ApiSetValue(PcanChannel, PcanParameter, UInt32) Method

Configures a 32-bit numeric parameter value of a PCAN Channel.

Definition

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

public static PcanStatus SetValue(
	PcanChannel channel,
	PcanParameter parameter,
	uint buffer
)

Public Shared Function SetValue ( 
	channel As PcanChannel,
	parameter As PcanParameter,
	buffer As UInteger
) As PcanStatus

C++

public:
static PcanStatus SetValue(
	PcanChannel channel, 
	PcanParameter parameter, 
	unsigned int buffer
)

Parameters

channel PcanChannel: The handle of a PCAN Channel.
parameter PcanParameter: The parameter whose value is to be configured.
buffer UInt32: Contains the 32-bit numeric value to be set.

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.
IllegalHardwareHandle: Indicates that the hardware represented by channel is currently not available (detached or disabled).
InvalidParameter: Indicates that the requested parameter value is not implemented or is not supported by the given PCAN Channel.
InvalidValue: Indicates that one or more of the values passed to the method are invalid.
InvalidOperation: Indicates that an action cannot be executed due to the state of the hardware. Possible causes are:
- The BitrateAdapting parameter is being configured on an initialized channel.

Remarks

Use SetValue(PcanChannel, PcanParameter, UInt32) to set the value of parameters like the DeviceId, and ReceiveStatus, among others.

Not all parameters are supported for all PCAN Channels. Using a parameter with a non-compatible Channel ends with an error.

Not all parameters have write access. Using a read-only parameter with SetValue ends with an error.

Except for a few parameters, the channel has to be initialized first, before being able to configure a value on it. For more information see the PcanParameter section.

Example

The following example shows the use of the SetValue(PcanChannel, PcanParameter, UInt32) method using the USB interface (first PCAN-USB hardware). The device ID of the channel is configured to be 7.

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;
ulong acceptanceFilter = 0x00001000_00000500;

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

    // Configure the acceptance filter of the device to allow receiving the messages with IDs 1100h, 1400h, and 1500h
    //
    result = Api.SetValue(channel, PcanParameter.AcceptanceFilter29Bit, acceptanceFilter);
    if (result != PcanStatus.OK)
    {
        // An error occurred
        //
        Api.GetErrorText(result, out var errorText);
        Console.WriteLine(errorText);
    }
    else
    {
        Console.WriteLine($"The 29-bit acceptance filter of the hardware represented by the handle {channel} was successfully set to {acceptanceFilter:X16}h.");
    }

    // 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
Dim acceptanceFilter As ULong = &H00001000_00000500

' 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
'
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.")

    ' Configure the acceptance filter of the device to allow receiving the messages with IDs 1100h, 1400h, and 1500h
    '
    result = Api.SetValue(channel, PcanParameter.AcceptanceFilter29Bit, acceptanceFilter)
    If result <> PcanStatus.OK Then
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        Console.WriteLine($"The 29-bit acceptance filter of the hardware represented by the handle {channel} was successfully set to {acceptanceFilter:X16}h.")
    End If

    ' 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++

PcanChannel channel = PcanChannel::Usb01;
String^ errorText;
UInt64 acceptanceFilter = 0x00001000'00000500;

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

    // Configure the acceptance filter of the device to allow receiving the messages with IDs 1100h, 1400h, and 1500h
    //
    result = Api::SetValue(channel, PcanParameter::AcceptanceFilter29Bit, acceptanceFilter);
    if (result != PcanStatus::OK)
    {
        // An error occurred
        //
        Api::GetErrorText(result, errorText);
        Console::WriteLine(errorText);
    }
    else
    {
        Console::WriteLine("The 29-bit acceptance filter of the hardware represented by the handle {0} was successfully set to {1:X16}h.", channel, acceptanceFilter);
    }

    // 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.