IXXAT - J1939 API V1.1 Documentation
|
C Wrapper for the J1939 API
The C wrapper provides the external pure C interface for the J1939Api, thus abstracting direct access of COM-like interfaces from the user. The C wrapper is provided to the user as collection of functions.
Types and Macros
J1939API_CWRAPPER_DECL
Import / Export declaration for API functions and handle
#ifdef _J1939API_CWRAPPER #define J1939API_CWRAPPER_DECL __declspec(dllexport) #else #define J1939API_CWRAPPER_DECL __declspec(dllimport) #endif
HJ1939API
Handle to the API instance.
typedef void * HJ1939API;
Functions
J1939Api_GetVersion()
J1939API_CWRAPPER_DECL int J1939Api_GetVersion( CHAR* pszProdVersion);
Description
Gets the product version of the J1939 API as string.
Parameter | Dir. | Description |
pszProdVersion | out | Pointer to char with at least 64 bytes to return product version. |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_POINTER | Invalid pointer received by function |
J1939Api_GetHRESULTString()
J1939API_CWRAPPER_DECL int J1939Api_GetHRESULTString( HRESULT hr , LPSTR* pszDescription);
Description
API functions in C return HRESULTs to indicate success or failure of the function. The function J1939Api_GetHRESULTString() returns a string describing a particular HRESULT.
Parameter | Dir. | Description |
hr | in | J1939 API HRESULT |
pszDescription | out | Pointer to description string |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_POINTER | Invalid pointer received by function |
J1939Api_GetErrorString()
J1939API_CWRAPPER_DECL int J1939Api_GetErrorString( UINT16 wErrCode , LPSTR* pszDescription);
Description
During the administration of an API instance, errors can occur independently from the calling of particular functions. These errors are then registered in the reception queue and delivered to the API as error messages. The error code part of the error message indicates the type of error and the location of the error occurrence. The J1939Api_GetErrorString() function returns a string describing the error code.
Parameter | Dir. | Description |
wErrCode | in | Error code from stack |
pszDescription | out | Pointer to description string |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_POINTER | Invalid pointer received by function |
J1939Api_GetBoardList()
J1939API_CWRAPPER_DECL int J1939Api_GetBoardList( J1939API_BOARDINFO* psBoardInfo , UINT16* pwBoardCount);
Description
A list of available boards can be retrieved as a listing of their descriptions and serial numbers using the function J1939Api_GetBoardList(). The memory for the board info list should be allocated by the user as a structure array or as allocated memory before the pointer to which is passed to the function. The board count argument should initially indicate the number of board information structures for which the memory is allocated. Upon successful completion of the function, the board count will indicate the amount of board info structures returned. Note: The number of possible board info structures returned is limited by the J1939API_MAX_BOARDS define in the file j1939api_types.h.
Parameter | Dir. | Description |
psBoardInfo | out | Pointer to list of J1939API_BOARDINFO structs |
pwBoardCount | in/out | Number of available board info entries / entries used |
Return Value | Description |
J1939API_S_OK | success |
J1939API_E_POINTER | NULL pointer passed to function |
J1939API_E_VCI_INIT | failure to initialize the VCI |
J1939API_E_VCI_GETBOARDLIST | failure to retrieve the VCI board list |
J1939API_E_OUTOFMEMORY | failure to allocate memory for list |
J1939Api_Create()
J1939API_CWRAPPER_DECL int J1939Api_Create( UINT8 bDeviceAddress, J1939API_NAME sDeviceName, UINT8 bBoardIndex, UINT8 bCanLine, LPCTSTR wszXmlModuleFile, HJ1939API* ph );
Description
The initialization includes the importation of the XML module file specified by the wszXmlModuleFile parameter for the mapping and demapping of the J1939 messages. The initialization also includes the initialization of the J1939 Stack software, which initializes and starts the CAN interface, starts J1939 address claiming and drives the reception and transmission of messages. The startup of the CAN interface will require some time. The active state of the instance can be checked using the function J1939Api_GetStackStatus().
See Also
Parameter | Dir. | Description |
bDeviceAddress | in | device address for J1939 stack |
sDeviceName | in | device name for J1939 stack in the form of a J1939API_NAME struct |
bBoardIndex | in | Index corresponding to the selected VCIV3 hardware (see J1939Api_GetBoardList()) |
bCanLine | in | can line of selected hardware |
wszXmlModuleFile | in | file path for XML file containing J1939 configuration data |
ph | in | Reference to a handle to the J1939API object, which is to be created (see HJ1939API) |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_OUTOFMEMORY | Failure to create new instance of class |
J1939API_E_FS_OPEN | Error opening module file |
J1939API_E_POINTER | Invalid pointer |
J1939API_E_TREE_IMPORT | Error importing J1939 tree from XML |
J1939API_E_INST_MAX | Instance count has reached the maximum |
J1939Api_Destroy()
J1939API_CWRAPPER_DECL void J1939Api_Destroy( HJ1939API h );
Description
Destroys HJ1939API instance, frees allocated memory and halts the stack task.
See Also
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
Return Value | Description |
- | None |
J1939Api_GetStackStatus()
J1939API_CWRAPPER_DECL int J1939Api_GetStackStatus( HJ1939API h, UINT8* pbStatus);
Description
Gets the status value of the J1939 Stack. Before the status is active, transmissions over the stack will fail.
See Also
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
pbStatus | out | Current stack status 1 = active (address claiming finished) 0 = inactive (address claiming not finished) |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939Api_Send()
J1939API_CWRAPPER_DECL int J1939Api_Send( HJ1939API h, UINT32 dwTimeout, J1939API_MSG* psMsg );
Description
Encodes and sends a J1939 message by copying the message into the stack internal transmission queue. Raw encoding can be performed by setting the message type of sMsg. The macro J1939API_MSG_DATABYTE() is available to support the assignment of individual data bytes in the 32-bit parameter array. Mapped messages return an error on the attempted transmission with an incorrect number of parameters. In the case of a full transmission queue, the J1939Api_Send() function will reattempt transmission until the timeout period has elapsed.
See Also
J1939Api_Receive(), J1939Api_GetStackStatus()
Remarks
Setting the message type to RAW in the msgtype field forces RAW encoding. Allocation and freeing of message data are handled by the API and the data is directly copied to the transmission queue, therefore memory management is not necessary by the user. The global bit of the J1939API_MSG is ignored for transmission. Specify global messages by setting the remote device to 0xFF.
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
dwTimeout | in | Transmit timeout in milliseconds (-1 for infinite) |
psMsg | in | Pointer to a J1939 message in the form of the J1939API_MSG struct |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_S_TIMEOUT | Timeout |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_INVALIDARG | Invalid argument received by function |
J1939API_E_TREE_GETSPLIST | Failure retrieving SP list for PGN |
J1939API_E_TREE_GETNODEDATA | Failure retrieving data for SP node |
J1939API_E_ENCODING | Failed to encode data, bad format |
J1939API_E_OUTOFMEMORY | Failed to allocate memory for message |
J1939API_E_STK_TX_NOTACTIVE | Stack is inactive |
J1939API_E_STK_TX_FAIL | General transmission failure |
J1939Api_Receive()
J1939API_CWRAPPER_DECL int J1939Api_Receive( HJ1939API h, UINT32 dwTimeout, PJ1939API_MSG psMsg );
Description
Decodes and returns a J1939 message or error message from the internal receive queue. The message type is stored in the least significant bits of the message status byte. Data PGNs will be decoded. Decoding is performed by the Codec unit using the information contained in the XML module file. If the received PGN is not included in the PGN table, the message will be decoded as raw, which copies the data from the data field byte for byte to the 32-bit parameters, and the raw message type in the message type byte will be set. The J1939Api_Receive() function will wait on an empty queue until the timeout period has elapsed.
See Also
J1939Api_Send(), J1939Api_GetRxQueueStatus()
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
dwTimeout | in | Receive timeout in milliseconds (-1 for infinite) |
psMsg | out | J1939 message in the form of the J1939API_MSG struct |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_S_TIMEOUT | Timeout (empty queue) |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_DECODING | Failed to decode data, bad format |
J1939API_E_TREE_GETSPLIST | Failure retrieving SP list for PGN |
J1939API_E_TREE_GETNODEDATA | Failure retrieving data for SP node |
J1939API_E_RX_TYPEUNKNOWN | Unknown message type found in queue |
J1939Api_GetRxQueueStatus()
J1939API_CWRAPPER_DECL int J1939Api_GetRxQueueStatus( HJ1939API h, UINT16* pwMsgCount );
Description
Gets the current reception queue status, by representing the current number of messages in the receive queue. The queue has a depth of 1024 messages.
See Also
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
pwMsgCount | out | Word representing the current number of messages waiting in the receive queue |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_POINTER | Invalid pointer received by function |
J1939Api_RegisterDataPgn()
J1939API_CWRAPPER_DECL int J1939Api_RegisterDataPgn( HJ1939API h, UINT32 dwPgn );
Description
Registers a data PGN for reception with the stack. PGNs not found in
PGN table indicate such with a return value of J1939API_S_RAWPGN.
Such messages will be decoded on reception as raw. The reception of an unregistered message directed to the API (not global) will cause an error message to be sent back to originating node. The reception of a registered data message will cause the message to be entered into the reception queue for retrieval by the user application.
See Also
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
dwPgn | in | PGN to be registered |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_S_RAWPGN | Success...registered as RAW |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_STK_REG_MAX | Too many PGNs registered |
J1939API_E_STK_REG_FAIL | General registration failure |
J1939Api_RegisterReqPgn()
J1939API_CWRAPPER_DECL int J1939Api_RegisterReqPgn( HJ1939API h, UINT32 dwPgn );
Description
Registers a request PGN for reception with the stack. The reception of an unregistered request message directed to the API (not global) will cause an error message to be sent back to originating node. The reception of a registered request message will cause the message to be entered into the reception queue as a request message for retrieval and handling by the user application.
See Also
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
dwPgn | in | PGN to be registered of the message to be requested |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_STK_REG_MAX | Too many PGNs registered |
J1939API_E_STK_REG_FAIL | General registration failure |
J1939Api_RegisterCycPgn()
J1939API_CWRAPPER_DECL int J1939Api_RegisterCycPgn( HJ1939API h, UINT32 dwPgn, UINT32 dwCycleTime );
Description
Registers a data Rx PGN for timeout supervision. The function uses the RegisterDataPgn() functionality to register the PGN for reception by the stack and in addition, registers it with a cyclical test array within the API. On the timeout of an actively registered cyclic message, the J1939API_USR_ERR_CYC_TIMEOUT error message is entered into the reception queue. Cyclical PGNs are deactivated for testing on timeout, to prevent jamming of the reception queue with timeout messages. Cyclical PGNs are activated by the reception of a corresponding message following the initial registration or a previous cycle timeout.
See Also
J1939Api_RegisterDataPgn(), J1939Api_ClearPgnList()
Remarks
The minimum resolution of the cycle time is 5 milliseconds. Cycle times will be rounded up to the next multiple of the timer resolution. The registration of cyclical PGNs also performs the registration of data PGNs.
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
dwPgn | in | PGN to be registered |
dwCycleTime | in | Required reception cycle time in milliseconds. See Remarks for more information regarding the cycle time. |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_S_RAWPGN | Success...registered as RAW |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_STK_REG_MAX | Too many PGNs registered |
J1939API_E_STK_REG_FAIL | General registration failure |
J1939Api_ClearPgnList()
J1939API_CWRAPPER_DECL int J1939Api_ClearPgnList( HJ1939API h );
Description
Removes all registered PGNs from the data, request and cyclic registration list.
See Also
J1939Api_RegisterDataPgn(), J1939Api_RegisterReqPgn(), J1939Api_RegisterCycPgn()
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939Api_ReadSpnList()
J1939API_CWRAPPER_DECL int J1939Api_ReadSpnList( HJ1939API h, J1939API_MSG* psMsg, UINT32* pdwSpns );
Description
Retrieves a list of SPNs within a given PG. The memory for the SPN list should be maintained by the user as a array of 32-bit unsigned integers or as allocated memory before the pointer to which is passed to the function. The count argument should initially indicate the number of SPNs for which the memory is allocated. Upon successful completion of the function, the count pointer will indicate the amount of SPNs returned. Note: The number of possible SPN structures returned is limited by the J1939API_MAX_PARAM_COUNT define in the file j1939api_types.h.
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
psMsg | in | Pointer to the received message |
pdwSpnList | out | Pointer to SPN list |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_POINTER | Invalid pointer received by function |
J1939API_E_TREE_GETPGNODE | Error retrieving PG node |
J1939API_E_TREE_GETSPLIST | Error retrieving SP list |
J1939API_E_TREE_GETNODEDATA | Error retrieving node data |
J1939Api_ReadSpnAttr()
J1939API_CWRAPPER_DECL int J1939Api_ReadSpnAttr( HJ1939API h, UINT32 dwSpn, PJ1939API_PARAMATTR psParamAttr );
Description
Retrieves the attributes corresponding to a specific SPN. The user is responsible for maintaining the memory of the parameter attribute, either by declaring a structure or allocating a memory buffer, before passing the pointer to the J1939Api_ReadSpnAttr() function.
See Also
Parameter | Dir. | Description |
h | in | Handle to the J1939API object, from which the function is called (see HJ1939API) |
dwSpn | in | SPN from which to retrieve the attributes |
psParamAttr | out | Pointer to SPN parameter structure (see J1939API_PARAMATTR in j1939api_types.h) |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_NOT_INITIALIZED | API not initialized |
J1939API_E_POINTER | Invalid pointer received by function |
J1939API_E_TREE_GETSPNODE | Error retrieving SP node |
Document generated by c2doc 3.26.00 Copyright © 2005-2013 by IXXAT Automation GmbH All rights reserved.