ApiGetValue(PcanChannel, PcanParameter, PcanChannelInformation) Method

Retrieves an array of PcanChannelInformation with information about the hardware currently attached to the system.

Definition

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

public static PcanStatus GetValue(
	PcanChannel channel,
	PcanParameter parameter,
	PcanChannelInformation[] buffer
)

Public Shared Function GetValue ( 
	channel As PcanChannel,
	parameter As PcanParameter,
	buffer As PcanChannelInformation()
) As PcanStatus

C++

public:
static PcanStatus GetValue(
	PcanChannel channel, 
	PcanParameter parameter, 
	array<PcanChannelInformation^>^ buffer
)

Parameters

channel PcanChannel

The handle of a PCAN Channel.

parameter PcanParameter

The parameter whose value is to be retrieved.

buffer PcanChannelInformation

Contains the requested information.

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.
InvalidParameter: Indicates that the requested parameter value is not implemented or is not supported by the given PCAN Channel.

Remarks

Use GetValue(PcanChannel, PcanParameter, PcanChannelInformation) to get the values associated to the parameters AttachedChannelsInformation.

This method can only be called using the Channel None. Using any other Channel ends with an error.

See PcanChannelInformation for additional information on the retrieved data.

Example

The following example shows the use of the GetValue(PcanChannel, PcanParameter, PcanChannelInformation) method. The information about the attached Channels is requested and shown.

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.None;

// The amount of hardware currently attached to the system is retrieved
//
PcanStatus result = Api.GetValue(channel, PcanParameter.AttachedChannelsCount, out uint channelsCount);
if (result != PcanStatus.OK)
{
    // An error occurred
    //
    Api.GetErrorText(result, out var errorText);
    Console.WriteLine(errorText);
}
else
{
    // Information about the hardware currently attached to the system is retrieved
    //
    PcanChannelInformation[] channels = new PcanChannelInformation[channelsCount];
    result = Api.GetValue(channel, PcanParameter.AttachedChannelsInformation, channels);
    if (result != PcanStatus.OK)
    {
        // An error occurred
        //
        Api.GetErrorText(result, out var errorText);
        Console.WriteLine(errorText);
    }
    else
    {
        // The information about the channels is shown
        //
        Console.WriteLine($"There are {channelsCount} Channels attached to the system:");
        for (int i = 0; i < channelsCount; i++)
        {
            Console.WriteLine(" {0}) ---------------------------", i + 1);
            Console.WriteLine("    Name: {0}", channels[i].DeviceName);
            Console.WriteLine("    Handle: 0x{0:X}", channels[i].ChannelHandle);
            Console.WriteLine("    Controller: {0}", channels[i].ControllerNumber);
            Console.WriteLine("    Condition: {0}", channels[i].ChannelCondition);
        }
    }
}

Dim channel As PcanChannel = PcanChannel.None

' The amount of hardware currently attached to the system is retrieved
'
Dim channelsCount As UInteger = Nothing
Dim result As PcanStatus = Api.GetValue(channel, PcanParameter.AttachedChannelsCount, channelsCount)
' An error occurred
'
Dim errorText = Nothing
If result <> PcanStatus.OK Then
    Api.GetErrorText(result, errorText)
    Console.WriteLine(errorText)
Else
    ' Information about the hardware currently attached to the system is retrieved
    '
    Dim channels = New PcanChannelInformation(channelsCount - 1) {}
    result = Api.GetValue(channel, PcanParameter.AttachedChannelsInformation, channels)
    If result <> PcanStatus.OK Then
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        ' The information about the channels is shown
        '
        Console.WriteLine($"There are {channelsCount} Channels attached to the system:")
        For i As Integer = 0 To channelsCount - 1
            Console.WriteLine(" {0}) ---------------------------", i + 1)
            Console.WriteLine("    Name: {0}", channels(i).DeviceName)
            Console.WriteLine("    Handle: 0x{0:X}", channels(i).ChannelHandle)
            Console.WriteLine("    Controller: {0}", channels(i).ControllerNumber)
            Console.WriteLine("    Condition: {0}", channels(i).ChannelCondition)
        Next
    End If
End If

C++

PcanChannel channel = PcanChannel::None;
String^ errorText;
UInt32 channelsCount; 

// The amount of hardware currently attached to the system is retrieved
//
PcanStatus result = Api::GetValue(channel, PcanParameter::AttachedChannelsCount, channelsCount);
if (result != PcanStatus::OK)
{
    // An error occurred
    //
    Api::GetErrorText(result, errorText);
    Console::WriteLine(errorText);
}
else
{
    // Information about the hardware currently attached to the system is retrieved
    //
    array<PcanChannelInformation^>^ channels = gcnew array<PcanChannelInformation^>(channelsCount);
    result = Api::GetValue(channel, PcanParameter::AttachedChannelsInformation, channels);
    if (result != PcanStatus::OK)
    {
        // An error occurred
        //
        Api::GetErrorText(result, errorText);
        Console::WriteLine(errorText);
    }
    else
    {
        // The information about the channels is shown
        //
        Console::WriteLine("There are {0} Channels attached to the system:", channelsCount);
        for (int i = 0; i < channelsCount; i++)
        {
            Console::WriteLine(" {0}) ---------------------------", i + 1);
            Console::WriteLine("    Name: {0}", channels[i]->DeviceName);
            Console::WriteLine("    Handle: 0x{0:X}", channels[i]->ChannelHandle);
            Console::WriteLine("    Controller: {0}", channels[i]->ControllerNumber);
            Console::WriteLine("    Condition: {0}", channels[i]->ChannelCondition);
        }
    }
}

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.