ApiReset Method

Discards all messages contained in the receive and transmit queues of a PCAN Channel.

Definition

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

public static PcanStatus Reset(
	PcanChannel channel
)

Public Shared Function Reset ( 
	channel As PcanChannel
) As PcanStatus

C++

public:
static PcanStatus Reset(
	PcanChannel channel
)

Parameters

channel PcanChannel: The handle of a PCAN Channel.

Return Value

PcanStatus

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

Initialize: Indicates that the channel cannot be used because it was not found in the list of reserved Channels of the calling application.
IllegalHandle: Indicates that the channel contains an invalid value.

Remarks

Calling this method ONLY clears the queues of a Channel. A reset of the CAN controller doesn't take place, unless the parameter HardResetStatus is active.

Normally a reset of the CAN Controller is desired when a bus-off occur. In this case 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 Reset(PcanChannel) method using the USB interface (first PCAN-USB hardware). This example assumes that there is communication taking place on the CAN bus.

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 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.
    // Since the message filter is open at connection time, the Channel is already receiving and placing messages
    // in the reception queue of this Channel.
    //
    Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.");

    // Wait some time to simulate any work in the application.                
    //
    System.Threading.Thread.Sleep(1000);

    // Before starting with the actual work, the queue is cleared
    //
    result = Api.Reset(channel);
    if (result != PcanStatus.OK)
    {
        // An error occurred
        //
        Api.GetErrorText(result, out var errorText);
        Console.WriteLine(errorText);
    }
    else
    {
        // A success message on reset is shown.
        //
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully reset.");

        // Wait some time to simulate any operation in the application...
        //
        System.Threading.Thread.Sleep(1000);

        // 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 bit rate (BTR0/BTR1 0x001C)
'
Dim result As PcanStatus = Api.Initialize(channel, Bitrate.Pcan500)
If (result <> PcanStatus.OK) Then
    ' An error occurred
    '
    Dim errorText As String = String.Empty
    Api.GetErrorText(result, errorText)
    Console.WriteLine(errorText)
Else
    ' A success message on connection Is shown.
    ' Since the message filter Is open at connection time, the Channel Is already receiving And placing messages
    ' in the reception queue of this Channel.
    '
    Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.")

    ' Wait some time to simulate any work in the application.                
    '
    System.Threading.Thread.Sleep(1000)

    ' Before starting with the actual work, the queue is cleared
    '
    result = Api.Reset(channel)
    If (result <> PcanStatus.OK) Then
        ' An error occurred
        '
        Dim errorText As String = String.Empty
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        ' A success message on reset is shown.
        '
        Console.WriteLine($"The hardware represented by the handle {channel} was successfully reset.")

        ' Wait some time to simulate any operation in the application...
        '
        System.Threading.Thread.Sleep(1000)

        ' 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
            '
            Dim errorText As String = String.Empty
            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 If

C++

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.
    // Since the message filter is open at connection time, the Channel is already receiving and placing messages
    // in the reception queue of this Channel.
    //
    Console::WriteLine("The hardware represented by the handle {0} was successfully initialized.", channel);

    // Wait some time to simulate any work in the application.                
    //
    System::Threading::Thread::Sleep(1000);

    // Before starting with the actual work, the queue is cleared
    //
    result = Api::Reset(channel);
    if (result != PcanStatus::OK)
    {
        // An error occurred
        //
        Api::GetErrorText(result, errorText);
        Console::WriteLine(errorText);
    }
    else
    {
        // A success message on reset is shown.
        //
        Console::WriteLine("The hardware represented by the handle {0} was successfully reset.", channel);

        // Wait some time to simulate any operation in the application...
        //
        System::Threading::Thread::Sleep(1000);

        // The connection to the hardware is finalized when it is no longer needed
        //
        result = Api::Uninitialize(channel);
        if (result != PcanStatus::OK)
        {
            // An error occurred
            //
            String^ errorText;
            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.