ApiGetValue(PcanChannel, PcanParameter, UInt32) Method

Retrieves a 32-bit numeric parameter value from a PCAN Channel.

Definition

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

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

Public Shared Function GetValue ( 
	channel As PcanChannel,
	parameter As PcanParameter,
	<OutAttribute> ByRef buffer As UInteger
) As PcanStatus

C++

public:
static PcanStatus GetValue(
	PcanChannel channel, 
	PcanParameter parameter, 
	[OutAttribute] unsigned int% buffer
)

Parameters

channel PcanChannel

The handle of a PCAN Channel.

parameter PcanParameter

The parameter whose value is to be retrieved.

buffer UInt32

Contains the requested 32-bit numeric value.

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

Remarks

Use GetValue(PcanChannel, PcanParameter, UInt32) to get the value of parameters like the DeviceId, and ControllerNumber, 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 read access. Using a write-only parameter with GetValue ends with an error.

The value of some parameters can only be retrieved if the channel is initialized. For more information see the PcanParameter section.

According to the value being retrieved, the type of the value can be treated as an enumeration value. For more information see the PcanParameter section.

Example

The following example shows the use of the GetValue(PcanChannel, PcanParameter, UInt32) method using the USB interface (first PCAN-USB hardware). The device ID is requested on a not initialized Channel.

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.
    //
    Console.WriteLine($"The hardware represented by the handle {channel} was successfully initialized.");

    // The acceptance filter is retrieved
    //
    result = Api.GetValue(channel, PcanParameter.AcceptanceFilter11Bit, out ulong acceptanceFilter);
    if (result != PcanStatus.OK)
    {
        // An error occurred, get a text describing the error and show it
        // 
        Api.GetErrorText(result, out var errorText);
        Console.WriteLine(errorText);
    }
    else
    {
        Console.WriteLine("The 11-bit acceptance filter is configured as follow:");
        // The acceptance code is coded in the most significant 4 bytes
        Console.WriteLine("   Acceptance code: {0:X8}", acceptanceFilter >> 32);
        // The acceptance mask is coded in the less significant 4 bytes
        Console.WriteLine("   Acceptance mask: {0:X8}", acceptanceFilter & 0xFFFFFFFF);
    }

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

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

    ' The acceptance filter Is retrieved
    '
    Dim acceptanceFilter As UInt64
    result = Api.GetValue(channel, PcanParameter.AcceptanceFilter11Bit, acceptanceFilter)
    If result <> PcanStatus.OK Then
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        Console.WriteLine("The 11-bit acceptance filter is configured as follow:")
        ' The acceptance code is coded in the most significant 4 bytes
        Console.WriteLine("   Acceptance code: {0:X8}", acceptanceFilter >> 32)
        ' The acceptance mask is coded in the less significant 4 bytes
        Console.WriteLine("   Acceptance mask: {0:X8}", acceptanceFilter And &HFFFFFFFFUI)
    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;

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

    // The acceptance filter is retrieved
    //
    UInt64 acceptanceFilter;
    result = Api::GetValue(channel, PcanParameter::AcceptanceFilter11Bit, acceptanceFilter);
    if (result != PcanStatus::OK)
    {
        // An error occurred, get a text describing the error and show it
        // 
        Api::GetErrorText(result, errorText);
        Console::WriteLine(errorText);
    }
    else
    {
        Console::WriteLine("The 11-bit acceptance filter is configured as follow:");
        // The acceptance code is coded in the most significant 4 bytes
        Console::WriteLine("   Acceptance code: {0:X8}", acceptanceFilter >> 32);
        // The acceptance mask is coded in the less significant 4 bytes
        Console::WriteLine("   Acceptance mask: {0:X8}", acceptanceFilter & 0xFFFFFFFF);
    }

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