ApiFilterMessages Method

Configures the acceptance filter for CAN messages within a PCAN Channel.

Definition

Namespace: Peak.Can.Basic
Assembly: PCANBasic.NET (in PCANBasic.NET.dll) Version: 4.9.0
C#
public static PcanStatus FilterMessages(
	PcanChannel channel,
	uint fromID,
	uint toID,
	FilterMode mode
)

Parameters

channel  PcanChannel
The handle of a PCAN Channel.
fromID  UInt32
The lower range value to accept and place messages in the receive queue.

The lowest value allowed is 0.The highest value allowed is 0x7FF if mode equals to Standard, and 0x1FFFFFFF if mode equals to Extended.

toID  UInt32
The upper range value to accept and place messages in the receive queue.

The lowest value allowed is 0. The highest value allowed is 0x7FF if mode equals to Standard, and 0x1FFFFFFF if mode equals to Extended.

mode  FilterMode
The kind of filter to be set. This parameter restricts the range of values valid for fromID and toID.

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.

Remarks

  Important

After a PCAN Channel is initialized, its filter is fully opened, causing any message received by the hardware to be placed in the receive queue of the Channel.

Based on the current state of the filter, calling this method results in the following behavior:

  • Status was Open: The filter is automatically closed and then configured with the given range of IDs passed to FilterMessages [fromID, toID].
  • Status was Close: The filter is set to the given range of IDs passed to FilterMessages [fromID, toID].
  • Status was Custom: The filter is expanded with the given range of Ids [fromID, toID]. If a smaller or different range is required than a range that has been configured before, the filter has to be closed first before calling FilterMessages again. To do this, use the method SetValue.

The mode indicates which kind of ID is being used to register the new filter range. There are two possible values, Standard (11-bit identifier) or Extended (29-bit identifier). Standard frames are using the bit positions 28 to 18 of the Acceptance Mask/Code registers in the SJA1000 CAN controller. Drivers for 82C200 CAN controllers have to shift the bits down to positions 10 to 0.

Take into account that configuring the message filter causes the CAN controller to enter the reset state. This will affect other applications that communicate with the same PCAN hardware.

  Important

  1. There is only one filter for standard and extended CAN messages. The ID from a standard message uses the most significant 11 bits (bit 18 to 28) of the 29 bits filter. I.e. the standard ID 400h is also received by indicating an extended ID 10000000h. For this reason, it is not recommended to mix standard and extended filters, since it can increase the risk of receiving unwanted messages.
  2. Multiple calls of FilterMessages expand the reception filter.
  3. It is not guaranteed that an application only receives CAN messages in the range of fromID to toID. This is caused by the operating principle of the SJA1000's acceptance filter. See also Philips Data Sheet "SJA1000 Stand-alone CAN-controller.

Example

The following example shows the use of the FilterMessages method using the USB interface (first PCAN-USB hardware). A Channel is initialized and its filter is configured to get only messages with ID 2,3,4 or 5.

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.

C#
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 message filter is fully open after initialization.
    // Configuring a custom acceptance range automatically closes the filter first.
    //  The messages with ID in the range [2,5] is configured.
    // 
    result = Api.FilterMessages(channel, 2, 5, FilterMode.Standard);
    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 message filter was successfully configured for IDs 2,3,4 and 5.");

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

Exceptions

DllNotFoundExceptionThe underlying PCANBasic.dll library could not be found.
PcanBasicExceptionThe 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.

See Also