ApiWrite Method

Places a CAN message in the transmit queue of a PCAN Channel.

Definition

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

public static PcanStatus Write(
	PcanChannel channel,
	PcanMessage msg
)

Public Shared Function Write ( 
	channel As PcanChannel,
	msg As PcanMessage
) As PcanStatus

C++

public:
static PcanStatus Write(
	PcanChannel channel, 
	PcanMessage^ msg
)

Parameters

channel PcanChannel: The handle of a PCAN Channel.
msg PcanMessage: Represents the CAN message to be transmitted through the channel.

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.
InvalidOperation: Indicates that the channel was not initialized using the Initialize method.
InvalidValue: Indicates that one or more of the values passed to the method are invalid.
BusOff: Indicates a bus error within the given PCAN Channel. The CAN controller is in bus-off state.
TransmitQueueFull: Indicates that the transmit queue of the Channel is full.

Remarks

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.

Example

The following example shows the use of the Write(PcanChannel, PcanMessage) method using the USB interface (first PCAN-USB hardware). A Channel is initialized and used to write 10 messages.

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.

PcanChannel channel = PcanChannel.Usb01;

// The hardware represented by the given handle is initialized with 500 kBit/s nominal and 4 MBit/s data bit rate (SAE J2284-4)
//
PcanStatus result = Api.Initialize(channel, (BitrateFD)BitrateFD.BitrateSaeJ2284_4);
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.");

    // Define the message to send
    //
    PcanMessage msg = new PcanMessage(0x100, MessageType.Extended | MessageType.FlexibleDataRate | MessageType.BitRateSwitch, 15, null, true);              
    for (int i = 0; i < msg.Length; i++)
        msg.Data[i] = (byte)(64 - i);

    // Send 10 messages
    //
    for (byte i = 1; i <= 10; i++)
    {
        result = Api.Write(channel, msg);
        if (result != PcanStatus.OK)
        {
            // An error occurred
            //
            Api.GetErrorText(result, out var errorText);
            Console.WriteLine(errorText);
            Console.WriteLine($"Application terminated.");
            return;
        }
        else
        {
            // A success message on reset is shown.
            //
            Console.WriteLine($"Message {i} was successfully sent.");
        }
    }

    // Give the driver some time to send the messages...
    //
    System.Threading.Thread.Sleep(50);

    // 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.");
}

Dim channel As PcanChannel = PcanChannel.Usb01

' The hardware represented by the given handle is initialized with 500 kBit/s nominal and 4 MBit/s data bit rate (SAE J2284-4)
'
Dim result As PcanStatus = Api.Initialize(channel, CType(BitrateFD.BitrateSaeJ2284_4, BitrateFD))
' An 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.")

    ' Define the message to send
    '
    Dim msg As PcanMessage = New PcanMessage(&H100, MessageType.Extended Or MessageType.FlexibleDataRate Or MessageType.BitRateSwitch, 15, Nothing, True)
    For i As Integer = 0 To msg.Length - 1
        msg.Data(i) = 64 - i
    Next

    ' Send 10 messages
    '
    For i As Byte = 1 To 10
        result = Api.Write(channel, msg)
        If result <> PcanStatus.OK Then
            Api.GetErrorText(result, errorText)
            Console.WriteLine(errorText)
            Console.WriteLine($"Application terminated.")
            Return
        Else
            ' A success message on reset is shown.
            '
            Console.WriteLine($"Message {i} was successfully sent.")
        End If
    Next

    ' Give the driver some time to send the messages...
    '
    Threading.Thread.Sleep(50)

    ' The connection to the hardware is finalized when it is no longer needed
    '
    result = Api.Uninitialize(channel)
    If result <> PcanStatus.OK Then
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully finalized.")
    End If
End If

C++

String^ errorText;
PcanChannel channel = PcanChannel::Usb01;

// The hardware represented by the given handle is initialized with 500 kBit/s nominal and 4 MBit/s data bit rate (SAE J2284-4)
//
PcanStatus result = Api::Initialize(channel, (BitrateFD^)BitrateFD::BitrateSaeJ2284_4);
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);


    // Define the message to send
    //
    PcanMessage^ msg = gcnew PcanMessage(0x100, MessageType::Extended | MessageType::FlexibleDataRate | MessageType::BitRateSwitch, 15, nullptr, true);
    for (int i = 0; i < msg->Length; i++)
        msg->Data[i] = (Byte)(64 - i);

    // Send 10 messages
    //
    for (Byte i = 1; i <= 10; i++)
    {
        result = Api::Write(channel, msg);
        if (result != PcanStatus::OK)
        {
            // An error occurred
            //
            Api::GetErrorText(result, errorText);
            Console::WriteLine(errorText);
            Console::WriteLine("Application terminated.");
            return;
        }
        else
        {
            // A success message on reset is shown.
            //
            Console::WriteLine("Message {0} was successfully sent.", i);
        }
    }

    // Give the driver some time to send the messages...
    //
    System::Threading::Thread::Sleep(50);

    // 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);
}

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.