Note
MessageBuffer is valid in this case.
public static TPCANStatus Read(
ushort Channel,
out TPCANMsg MessageBuffer
)
Public Shared Function Read (
Channel As UShort,
<OutAttribute> ByRef MessageBuffer As TPCANMsg
) As TPCANStatus
public:
static TPCANStatus Read(
unsigned short Channel,
[OutAttribute] TPCANMsg% MessageBuffer
)
The return value is a TPCANStatus value. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:
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:
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:
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) 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;
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, out msg);
if (result != TPCANStatus.PCAN_ERROR_QRCVEMPTY)
{
// Process the received message
//
Console.WriteLine("A message was received");
ProcessMessage(msg);
}
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
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)
If result <> TPCANStatus.PCAN_ERROR_QRCVEMPTY Then
Console.WriteLine("A message was received")
ProcessMessage(msg)
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;
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);
if (result != TPCANStatus::PCAN_ERROR_QRCVEMPTY)
{
// Process the received message
//
Console::WriteLine("A message was received");
ProcessMessage(msg);
}
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);