ApiRead(PcanChannel, PcanMessage) Method

Reads a CAN message from the receive queue of a PCAN Channel.

Definition

Namespace: Peak.Can.Basic
Assembly: PCANBasic.NET (in PCANBasic.NET.dll) Version: 4.9.0

public static PcanStatus Read(
	PcanChannel channel,
	out PcanMessage msg
)

Public Shared Function Read ( 
	channel As PcanChannel,
	<OutAttribute> ByRef msg As PcanMessage
) As PcanStatus

C++

public:
static PcanStatus Read(
	PcanChannel channel, 
	[OutAttribute] PcanMessage^% msg
)

Parameters

channel PcanChannel

The handle of a PCAN Channel.

msg PcanMessage

Contains the next available CAN frame stored in the FIFO receive queue of channel.

The content of msg is only valid if the returned value of this method is OK.

Return Value

PcanStatus

OK is returned on success. The typical errors in case of failure are:

IllegalHandle: Indicates that the channel contains an invalid value.
Initialize: Indicates that the channel cannot be used because it was not found in the list of reserved Channels of the calling application.
InvalidValue: Indicates that one or more of the values passed to the method are invalid.
ReceiveQueueEmpty: Indicates that there are no more messages in the receive queue of the Channel.
IllegalData: Indicates that the message that has been read is not permitted due to the current settings and has been discarded.

Remarks

Note

If the timestamp of message reception is required, use the Read(PcanChannel, PcanMessage, UInt64) method instead.

The Read method returns CAN frames from the receive queue. It is important to call Read repeatedly until the receive queue becomes empty. In case there are no more messages to retrieve, the error ReceiveQueueEmpty is returned. The ReceiveQueueEmpty error is also returned if the reception of messages, configurable through the ReceiveStatus 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 ReceiveQueueEmpty error 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 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. Consider using the BusOffAutoReset parameter, which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset bus errors like BusOff, BusPassive, and others:

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

The MsgType of a PcanMessage object indicates the kind of CAN frame it describes. This value should be checked every time a message has been read successfully.

If the MsgType of a PcanMessage contains the value Error, then the message is an Error Frame.

If the MsgType of a PcanMessage contains the value Status, then the message is a Status Frame.

Example

The following example shows the use of the Read(PcanChannel, PcanMessage) method using the USB interface (first PCAN-USB hardware). A Channel is initialized and used to read messages within 1 second.

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.

private static void ReadExample()
{            
    PcanChannel channel = PcanChannel.Usb01;

    // The hardware represented by the given handle is initialized with 500 kBit/s bit rate (BTR0/BTR1 0x001C)
    //
    PcanStatus result = Api.Initialize(channel, Bitrate.Pcan500);
    if (result != PcanStatus.OK)
    {
        // An error occurred
        //
        Api.GetErrorText(result, out var errorText);
        Console.WriteLine(errorText);
    }
    else
    {
        // A success message on connection is shown.
        //
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.");

        // Wait some time to get messages stored in the reception queue of the Channel
        //
        Console.WriteLine("The reception queue will be read out after 1 second...");
        System.Threading.Thread.Sleep(1000);

        // Messages are read and processed until the reception queue is empty
        //
        PcanMessage msg;
        do
        {                    
            result = Api.Read(channel, out msg);
            if (result == PcanStatus.OK)
            {
                // Process the received message
                // 
                ProcessMessage(msg);
            }
            else
            {
                if ((result & PcanStatus.ReceiveQueueEmpty) != PcanStatus.ReceiveQueueEmpty)
                {
                    // An unexpected error occurred
                    //
                    Api.GetErrorText(result, out var errorText);
                    Console.WriteLine("Reading process canceled due to unexpected error: " + errorText);
                    break;
                }
            }

        } while ((result & PcanStatus.ReceiveQueueEmpty) != PcanStatus.ReceiveQueueEmpty);

        // The connection to the hardware is finalized when it is no longer needed
        //
        result = Api.Uninitialize(channel);
        if (result != PcanStatus.OK)
        {
            // An error occurred
            //
            Api.GetErrorText(result, out var errorText);
            Console.WriteLine(errorText);
        }
        else
            Console.WriteLine($"The hardware represented by the handle {channel} was successfully finalized.");
    }
}

// Formats a CAN frame as string and writes it to the console output
//
private static void ProcessMessage(PcanMessage msg)
{
    string msgText = $"Type: {msg.MsgType} | ";
    if((msg.MsgType & MessageType.Extended) == MessageType.Extended)
        msgText += $"ID: {msg.ID:X8} | ";
    else
        msgText += $"ID: {msg.ID:X4} | ";
    msgText += $"Length: {msg.Length} | ";
    msgText += $"Data: ";
    for (int i = 0; i < msg.Length; i++)                
        msgText += $"{msg.Data[i]} ";

    Console.WriteLine(msgText);
}

Private Sub ReadExample()
    Dim channel As PcanChannel = PcanChannel.Usb01

    ' The hardware represented by the given handle is initialized with 500 kBit/s bit rate (BTR0/BTR1 0x001C)
    '
    Dim result As PcanStatus = Api.Initialize(channel, Bitrate.Pcan500)
    ' An error occurred
    '
    ' An unexpected error occurred
    '
    Dim errorText = Nothing
    If result <> PcanStatus.OK Then
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        ' A success message on connection is shown.
        '
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.")

        ' Wait some time to get messages stored in the reception queue of the Channel
        '
        Console.WriteLine("The reception queue will be read out after 1 second...")
        System.Threading.Thread.Sleep(1000)

        ' Messages are read and processed until the reception queue is empty
        '
        Dim msg As PcanMessage = Nothing
        Do
            result = Api.Read(channel, msg)
            If result = PcanStatus.OK Then
                ' Process the received message
                ' 
                ProcessMessage(msg)
            Else
                If (result And PcanStatus.ReceiveQueueEmpty) <> PcanStatus.ReceiveQueueEmpty Then
                    Api.GetErrorText(result, errorText)
                    Console.WriteLine("Reading process canceled due to unexpected error: " & errorText)
                    Exit Do
                End If
            End If

        Loop While (result And PcanStatus.ReceiveQueueEmpty) <> PcanStatus.ReceiveQueueEmpty

        ' The connection to the hardware is finalized when it is no longer needed
        '
        result = Api.Uninitialize(channel)

        If result <> PcanStatus.OK Then
            ' An error occurred
            '
            Api.GetErrorText(result, errorText)
            Console.WriteLine(errorText)
        Else
            Console.WriteLine($"The hardware represented by the handle {channel} was successfully finalized.")
        End If
    End If
End Sub

' Formats a CAN frame as string and writes it to the console output
'
Private Sub ProcessMessage(ByVal msg As PcanMessage)
    Dim msgText = $"Type: {msg.MsgType} | "
    If (msg.MsgType And MessageType.Extended) = MessageType.Extended Then
        msgText += $"ID: {msg.ID:X8} | "
    Else
        msgText += $"ID: {msg.ID:X4} | "
    End If
    msgText += $"Length: {msg.Length} | "
    msgText += $"Data: "
    For i As Integer = 0 To msg.Length - 1
        msgText += $"{msg.Data(i)} "
    Next

    Console.WriteLine(msgText)
End Sub

C++

void ReadExample()
{
    String^ errorText;
    PcanChannel channel = PcanChannel::Usb01;

    // The hardware represented by the given handle is initialized with 500 kBit/s bit rate (BTR0/BTR1 0x001C)
    //
    PcanStatus result = Api::Initialize(channel, Bitrate::Pcan500);
    if (result != PcanStatus::OK)
    {
        // An error occurred
        //
        Api::GetErrorText(result, errorText);
        Console::WriteLine(errorText);
    }
    else
    {
        // A success message on connection is shown.
        //
        Console::WriteLine("The hardware represented by the handle {0} was successfully initialized.", channel);

        // Wait some time to get messages stored in the reception queue of the Channel
        //
        Console::WriteLine("The reception queue will be read out after 1 second...");
        System::Threading::Thread::Sleep(1000);

        // Messages are read and processed until the reception queue is empty
        //
        PcanMessage^ msg;
        do
        {
            result = Api::Read(channel, msg);
            if (result == PcanStatus::OK)
            {
                // Process the received message
                // 
                ProcessMessage(msg);
            }
            else
            {
                if ((result & PcanStatus::ReceiveQueueEmpty) != PcanStatus::ReceiveQueueEmpty)
                {
                    // An unexpected error occurred
                    //
                    Api::GetErrorText(result, errorText);
                    Console::WriteLine("Reading process canceled due to unexpected error: {0}", errorText);
                    break;
                }
            }

        } while ((result & PcanStatus::ReceiveQueueEmpty) != PcanStatus::ReceiveQueueEmpty);

        // The connection to the hardware is finalized when it is no longer needed
        //
        result = Api::Uninitialize(channel);
        if (result != PcanStatus::OK)
        {
            // An error occurred
            //
            Api::GetErrorText(result, errorText);
            Console::WriteLine(errorText);
        }
        else
            Console::WriteLine("The hardware represented by the handle {0} was successfully finalized.", channel);
    }
}

// Formats a CAN frame as string and writes it to the console output
//
void ProcessMessage(PcanMessage^ msg)
{
    String^ msgText = String::Format("Type: {0} | ", msg->MsgType);
    if ((msg->MsgType & MessageType::Extended) == MessageType::Extended)
        msgText += String::Format("ID: {0:X8} | ", msg->ID);
    else
        msgText += String::Format("ID: {0:X4} | ", msg->ID);
    msgText += String::Format("Length: {0} | ", msg->Length);
    msgText += "Data: ";
    for (int i = 0; i < msg->Length; i++)
        msgText += String::Format("{0:X2} ", msg->Data[i]);

    Console::WriteLine(msgText);
}

Exceptions

DllNotFoundException	The underlying PCANBasic.dll library could not be found.
PcanBasicException	The execution of a PCAN-Basic related check operation ended with an unexpected result. Typically, this exception is triggered when a device driver is not installed or is not up to date.