CAN_Read

TPCANStatus __stdcall CAN_Read(
        TPCANHandle Channel,
        TPCANMsg* MessageBuffer,
        TPCANTimestamp* TimestampBuffer
);

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

Specifying the value of NULL for the parameter TimetampBuffer causes reading a message without timestamp, when the reception time is not desired. An "Illegal Parameter Value" error will be returned when the MessageBuffer is wrong or the TimestampBuffer contains a value different than NULL and provokes an internal error, eg. accessing its memory. 

The use of CAN_Read and CAN_ReadFD are mutually exclusive. The PCAN Channel passed to this function must be initialized using CAN_Initialize (class-method: Initialize). Otherwise the error PCAN_ERROR_ILLOPERATION is returned. 

The CAN_Read function returns received messages or status messages from the receive queue. It is important to call CAN_Read repeatedly until the queue is empty. In case there are no more messages in queue, the value PCAN_ERROR_QRCVEMPTY is returned. The error code PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages is disabled. See Receive Status Parameter for more information. 

The receive queue can contain up to 32767 messages. 

There are two possibilities for reading messages from the receive queue of a Channel: 

Time-Triggered Reading: Consists in periodically calls to the CAN_Read function. Typically, an application start a timer that every 50 or 100 milliseconds check for messages, calling the CAN_Read function in a loop until the value of PCAN_ERROR_QRCVEMTY or another error condition is reached. 

Event-Triggered Reading: Consists in reacting to a notification sent by the PCAN driver to a registered application, when a message is received and inserted in its receive queue. See Using Events to obtain more information about reading with events. 

About bus errors / Status messages 

If a bus-off error occur, an application cannot use the channel to communicate anymore, until the CAN controller is reset. With PCAN-Basic it is not possible to reset the CAN controller through a function directly. Consider using the PCAN-Basic property PCAN_BUSOFF_AUTORESET which instructs the API to automatically reset the CAN controller when a bus-off state is detected. 

Another way to reset errors like BUSOFF, BUSHEAVY, and BUSLIGTH, is to uninitialize and initialise again the channel used. This causes a hardware reset. 

The message type (see TPCANMessageType) of a CAN message indicates if the message is a 11-bit, 29-bit, RTR, Error, or Status message. This value should be checked every time a message has been read successfully. 

If the bit PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error frame (see Error Frames). 

If the bit PCAN_MESSAGE_STATUS is set in the TPCANMsg.MSGTYPE field, the message is a Status message. The ID and LEN fields do not contain valid data. The first 4 data bytes of the message contain the Error Code. The MSB of the Error Code is in data byte 0, the LSB is in data byte 3. If a status message was read the return value of CAN_Read is also the error code. 

Examples:

The following example shows the use of CAN_Read on the channel PCAN_USBBUS1. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user. 

Note: It is assumed that the channel was already initialized and that the following code is an OnTimer event handler function. 

C++:  

TPCANMsg msg;
TPCANTimestamp timestamp;
TPCANStatus result;
char strMsg[256];

do
{
    // Check the receive queue for new messages
    //
    result = CAN_Read(PCAN_USBBUS1,&msg,&timestamp);
    if(result != PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        MessageBox("A message was received");
        ProcessMessage(msg)
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        // and handle the error
        //
        CAN_GetErrorText(result, 0, strMsg);
        MessageBox(strMsg);
        // Here can be decided if the loop has to be  terminated (eg. the bus
        // status is  bus-off)
        //
        HandleReadError(result);
    }
// Try to read a message from the receive queue of the PCAN-USB, Channel 1,
// until the queue is empty
//
}while((result & PCAN_ERROR_QRCVEMPTY) != PCAN_ERROR_QRCVEMPTY);

CAN_Write 

Using Events 

Error Frames 

Class-method Version: Read