PCANBasicRead(UInt16, TPCANMsg, TPCANTimestamp) Method

public static TPCANStatus Read(
	ushort Channel,
	out TPCANMsg MessageBuffer,
	out TPCANTimestamp TimestampBuffer
)

Public Shared Function Read ( 
	Channel As UShort,
	<OutAttribute> ByRef MessageBuffer As TPCANMsg,
	<OutAttribute> ByRef TimestampBuffer As TPCANTimestamp
) As TPCANStatus

public:
static TPCANStatus Read(
	unsigned short Channel, 
	[OutAttribute] TPCANMsg% MessageBuffer, 
	[OutAttribute] TPCANTimestamp% TimestampBuffer
)

Parameters

Channel  UInt16

The handle of a PCAN Channel (see PCAN Handle Definitions).

MessageBuffer  TPCANMsg

A buffer to store the CAN message.

TimestampBuffer  TPCANTimestamp

A buffer to store the reception time of the message.

Return Value

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

• PCAN_ERROR_INITIALIZE: Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
• PCAN_ERROR_ILLPARAMVAL: Indicates that one or more parameters passed to the method are invalid.
• PCAN_ERROR_ILLOPERATION: Indicates that the PCAN Channel passed to the method was not initialized using the Initialize method.
• PCAN_ERROR_ILLHANDLE: Indicates that the given PCAN Channel is not valid.
• PCAN_ERROR_BUSLIGHT: Indicates a bus error within the given PCAN Channel. The hardware is in bus-light status.

    Note

  MessageBuffer and TimestampBuffer are valid in this case.
• PCAN_ERROR_BUSHEAVY: Indicates a bus error within the given PCAN Channel. The hardware is in bus-heavy status.

    Note

  MessageBuffer and TimestampBuffer are valid in this case.
• PCAN_ERROR_BUSOFF: Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.

    Note

  MessageBuffer and TimestampBuffer are valid in this case.
• PCAN_ERROR_QRCVEMPTY: Indicates that the reception queue of the Channel is empty.
• PCAN_ERROR_ILLDATA: Indicates that the message that has been read is not permitted due to the current settings and has been discarded.

The Read method returns CAN frames from the reception queue. It is important to call Read repeatedly until the reception queue becomes empty. In case there are no more messages to retrieve, the error PCAN_ERROR_QRCVEMPTY is returned. The error PCAN_ERROR_QRCVEMPTY is also returned if the reception of messages, configurable through the PCAN_RECEIVE_STATUS parameter, is disabled.

The receive queue can contain up to 32768 messages.

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

• Time-Triggered Reading: Consists in periodically calls to the Read method. Typically, an application starts a timer that checks for messages every 50 or 100 milliseconds, calling the Read method in a loop until the error PCAN_ERROR_QRCVEMPTY 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 placed in its reception 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. Consider using the PCAN_BUSOFF_AUTORESET parameter, which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like bus-off, bus-heavy and bus-light:

• Performing an uninitialize / initialize cycle: This causes a hardware reset, but only when no more clients are connected to that channel.
• Using the parameter PCAN_HARD_RESET_STATUS: It instructs this method to explicitly perform a hardware reset regardless of whether other clients are connected to that channel.

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 flag PCAN_MESSAGE_ERRFRAME is set in the TPCANMsg.MSGTYPE field, the message is an Error Frame.

If the flag PCAN_MESSAGE_STATUS is set in the TPCANMsg.MSGTYPE field, the message is a PCAN Status Frame.

The following example shows the use of Read(UInt16, TPCANMsg, TPCANTimestamp) method 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.

TPCANStatus result;
System.Text.StringBuilder strMsg;
TPCANMsg msg;
TPCANTimestamp time;

strMsg = new System.Text.StringBuilder(256);

// ... channel is initialized and communication takes place ...

do
{
    // Check the reception queue for new frames
    //
    result = PCANBasic.Read(PCANBasic.PCAN_USBBUS1, out msg, out time);
    if (result != TPCANStatus.PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        Console.WriteLine("A message was received");
        ProcessMessage(msg, time);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        Console.WriteLine(strMsg.ToString());
        // 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 & TPCANStatus.PCAN_ERROR_QRCVEMPTY) != TPCANStatus.PCAN_ERROR_QRCVEMPTY);

Dim result As TPCANStatus
Dim strMsg As System.Text.StringBuilder
Dim msg As TPCANMsg = Nothing
Dim time As TPCANTimestamp

strMsg = New System.Text.StringBuilder(256)

' ... channel is initialized and communication takes place ...

Do
    ' Check the receive queue for new messages
    '
    result = PCANBasic.Read(PCANBasic.PCAN_USBBUS1, msg, time)
    If result <> TPCANStatus.PCAN_ERROR_QRCVEMPTY Then
        Console.WriteLine("A message was received")
        ProcessMessage(msg, time)
    Else
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        Console.WriteLine(strMsg.ToString())
        ' Here can be decided if the loop has to be  terminated (eg. the bus
        ' status is  bus-off)
        '
        HandleReadError(result)
    End If
    ' Try to read a message from the receive queue of the PCAN-USB, Channel 1,
    ' until the queue is empty
    '
Loop While ((result And TPCANStatus.PCAN_ERROR_QRCVEMPTY) <> TPCANStatus.PCAN_ERROR_QRCVEMPTY)

TPCANStatus result;
System::Text::StringBuilder^ strMsg;
TPCANMsg msg;
TPCANTimestamp time;

strMsg = gcnew System::Text::StringBuilder(256);

// ... channel is initialized and communication takes place ...

do
{
    // Check the receive queue for new messages
    //
    result = PCANBasic::Read(PCANBasic::PCAN_USBBUS1, msg, time);
    if (result != TPCANStatus::PCAN_ERROR_QRCVEMPTY)
    {
        // Process the received message
        //
        Console::WriteLine("A message was received");
        ProcessMessage(msg, time);
    }
    else
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic::GetErrorText(result, 0, strMsg);
        Console::WriteLine(strMsg->ToString());
        // 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 & TPCANStatus::PCAN_ERROR_QRCVEMPTY) != TPCANStatus::PCAN_ERROR_QRCVEMPTY);

Reference

Other Resources