ndOpenDiagnosticOnIPStack

ndOpenDiagnosticOnIPStack

Purpose

Opens a diagnostic session on an IP port. Communication to the ECU is not yet started.

Format

int32_t ndOpenDiagnosticOnIPStack(
     LVBoolean *dynamicPort,
     uint8_t DoIPProtocolVersion,
     char xnetStackName[],
     char xnetLocalInterface[],
     TD1 *DiagRefOut);

Input

DoIPProtocolVersion

Defines the protocol version of the DoIP packets:

If protocol version is set to 2010, the protocol version byte of the Generic DoIP header is set to 1. If protocol version is set to 2012, the protocol version byte of the Generic DoIP header is set to 2. The default is 2010.

The protocol versions used by the ECU and Automotive Diagnostic Command Set applications must match or a Generic Header error will be issued.

dynamicPort

Defines whether the standard UDP port 13401 (UDP_TEST_EQUIPMENT_LISTEN) is used for communication (FALSE) or a dynamically assigned UDP port (UDP_TEST_EQUIPMENT_REQUEST) is opened (TRUE).

xnetStackName

Zero-terminated string that specifies the name of the XNET IP Stack to use for IP communication by this diagnostic session. This IP stack must be started beforehand; refer to NI-XNET Hardware and Software Help for information about configuring and creating an IP stack. This function will wait for the IP stack and all of its virtual interfaces to become ready. If this parameter is set to an empty string, the native operating system IP stack will be used.

xnetLocalInterface

Zero-terminated string that specifies the local interface to use for this diagnostic session on the specified XNET IP Stack; used when the XNET IP Stack contains multiple virtual interfaces.

This optional parameter can be omitted if the IP Stack has only one local interface. This property is ignored if the xnetStackName parameter is not set. Refer to NI-XNET Hardware and Software Help for more information on this parameter.

Output

DiagRefOut

A struct that contains all necessary information about the diagnostic session. Pass this struct as a handle to all subsequent diagnostic functions; always close it using ndCloseDiagnostic to disconnect from the ECU and close the diagnostic session's XNET IP Stack reference.

Return Value

The return value indicates the function call status as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.

Use the ndStatusToString function to obtain a descriptive string for the return value.

Description

ndOpenDiagnosticOnIPStack opens a Diagnostic over Internet Protocol (DoIP) communication channel to an ECU. The UDP port specified as input is initialized, and a handle to it is stored (among other internal data) in DiagRefOut, which serves as reference for further diagnostic functions.

Note that no communication to an ECU takes place at this point. To open a diagnostic session on an ECU, you can optionally call ndDoIPGetEntities to find out which DoIP entities (DoIP-capable ECUs) exist in the network. Then, open a TCP/IP connection to a DoIP entity using ndDoIPConnect. After that, you can execute diagnostic services on the TCP/IP connection.

This function replaces the standard (CAN-based) ndOpenDiagnosticOnCANFD, because the CAN parameters are no longer relevant for IP-based diagnostics.

In general, it is not necessary to manipulate the DiagRefOut cluster contents.