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

J1939Api_Destroy()


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

J1939Api_Create()


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

J1939Api_Send()


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

J1939Api_Receive()


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

J1939Api_ClearPgnList()


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

J1939Api_ClearPgnList()


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

J1939Api_ReadSpnList()


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.