Purpose

Returns a table of all DoIP entities (vehicles) on the local subnet, possibly restricted to EID or VIN.

Format 

        long ndDoIPGetEntities(
       TD1 *diagRef,
       unsigned short DoIPOpenType,
       char VINOrEID[],
       unsigned char *DoIPEntities,
       unsigned long *len);

Input

diagRef

Specifies the handle for the diagnostic session, obtained from ndOpenDiagnosticOnIPStack and passed to subsequent diagnostic functions. Normally, it is not necessary to manually manipulate the elements of this struct.

DoIPOpenType

Defines which DoIP entities this command queries and lists. Allowed values are:

0 VIN (VIN is specified in VINorEID)
1 EID (EID is specified in VINorEID)
2 All (VINorEID is ignored)

Other values are reserved.

VINOrEID

Depends on DoIPOpenType:

DoIPOpenType VINOrEID Value
0 A 17-character Vehicle Identification Number. Only DoIP entities for this VIN are listed.
1 An Entity ID (usually a MAC address). Only the DoIP entity with this ID is listed. Specify the EID as xx-xx-xx-xx-xx-xx, where each x stands for a hexadecimal digit.
2 Ignored.

Output

DoIPEntities

Returns an array of C structs, each of which describe a DoIP entity: 

           typedef struct
   {
         char           VIN[18];
         unsigned short Address;
         unsigned char  EID[6];
         unsigned char  GID[6];
         char           IP_Address[16];
   }
   DOIP_ENTITY;
VIN Contains the Vehicle Identification Number assigned to the DoIP entity. Could be empty if not assigned.
Address The logical (Target) DoIP Address of the DoIP Entity.
EID Contains the Entity ID (usually the Hardware MAC address) assigned to the DoIP entity. Could be empty (0) if not assigned.
GID Contains the Group ID assigned to the DoIP entity. Could be empty(0) if not assigned.
IP_Address Contains the DoIP Entity IP Address (in a.b.c.d notation).

len

Returns the size of the DoIPEntities array in bytes. Must be initialized with the size (in bytes) of the buffer provided for DoIPEntities.

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

ndDoIPGetEntities uses a UDP broadcast to identify all DoIP entities in the local subnet matching a certain condition. The entities responding are returned in the DoIPEntities cluster array.

The conditions are either a common VIN or EID or simply all entities connected. Refer to the description of DoIPOpenType and VINOrEID.

To specify a different broadcast address than the local subnet on the default Network Interface Controller, use the ndDoIPGetEntitiesEx function.