IXXAT - J1939 API V1.1 Documentation
|
C++ Wrapper for the J1939 API
The C++ Wrapper provides the external C++ interface for the J1939Api. It is provided to the user as a class object.
Types and Macros
J1939API_CPPWRAPPER_DECL
Import / Export declaration for API class
#ifdef _J1939API_CPPWRAPPER #define J1939API_CPPWRAPPER_DECL __declspec(dllexport) #else #define J1939API_CPPWRAPPER_DECL __declspec(dllimport) #endif
Functions
GetVersion()
static int J1939Api::GetVersion(CHAR* pszProdVersion);
Description
Gets the product version number of the J1939 API.
Remarks
****************
Parameter | Dir. | Description |
pszProdVersion | out | Pointer to char with at least 64 bytes to return product version. |
Return Value | Description |
HRESULT | code |
GetHRESULTString()
static int GetHRESULTString( HRESULT hr , LPSTR* pszDescription);
Description
API functions in C++ return HRESULTs to indicate success or failure of the function. The function 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 |
GetErrorString()
static int 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 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 |
GetBoardList()
static int 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 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 |
Initialize()
int Initialize ( UINT8 bDeviceAddress , J1939API_NAME sDeviceName , UINT8 bBoardIndex , UINT8 bCanLine , LPCTSTR wszXmlModuleFile );
Description
Initializes an instance of IJ1939Api. 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 start-up of the CAN interface will require some time. The active state of the instance can be checked using the function GetStackStatus().
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 GetBoardList()) |
bCanLine | in | can line of selected hardware |
wszXmlModuleFile | in | file path for XML file containing J1939 configuration data |
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 |
GetStackStatus()
int GetStackStatus ( 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 |
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 |
Send()
int Send ( 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 Send() function will reattempt transmission until the timeout period has elapsed.
See Also
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 |
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 |
Receive()
int Receive ( 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 Receive() function will wait on an empty queue until the timeout period has elapsed.
See Also
Parameter | Dir. | Description |
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 |
GetRxQueueStatus()
int GetRxQueueStatus ( 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 |
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 |
RegisterDataPgn()
int RegisterDataPgn ( 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 |
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 |
RegisterReqPgn()
int RegisterReqPgn ( 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 |
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 |
RegisterCycPgn()
int RegisterCycPgn ( 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
RegisterDataPgn(), 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 |
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 |
ClearPgnList()
int ClearPgnList ( void );
Description
Removes all registered PGNs from the data, request and cyclic registration list.
See Also
RegisterDataPgn(), RegisterReqPgn(), RegisterCycPgn()
Parameter | Dir. | Description |
- | - | - |
Return Value | Description |
J1939API_S_OK | Success |
J1939API_E_NOT_INITIALIZED | API not initialized |
ReadSpnList()
int ReadSpnList( 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 |
psMsg | in | Pointer to the received message |
pdwSpns | 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 |
ReadSpnAttr()
int ReadSpnAttr( 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 ReadSpnAttr() function.
See Also
Parameter | Dir. | Description |
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.