PCANBasicFilterMessages Method

Configures the reception filter.

Definition

Namespace: Peak.Can.Basic.BackwardCompatibility
Assembly: PCANBasic.NET (in PCANBasic.NET.dll) Version: 4.9.0
C#
public static TPCANStatus FilterMessages(
	ushort Channel,
	uint FromID,
	uint ToID,
	TPCANMode Mode
)

Parameters

Channel  UInt16
The handle of a PCAN Channel (see PCAN Handle Definitions).
FromID  UInt32
The lowest CAN ID to be received.
ToID  UInt32
The highest CAN ID to be received.
Mode  TPCANMode
The kind of filter being set.

Return Value

TPCANStatus

The return value is a TPCANStatus value. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

  • PCAN_ERROR_INITIALIZE: Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
  • PCAN_ERROR_ILLHANDLE: Indicates that the given PCAN Channel is not valid.

Remarks

  Important

After a PCAN Channel is initialized, the status of its filter is fully opened.

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

  • Status is PCAN_FILTER_OPEN: The filter is automatically closed and then configured with the given range of IDs passed to this function [FromID, ToID].
  • Status is PCAN_FILTER_CLOSE: The filter is set to the given range of IDs passed to this function [FromID, ToID].
  • Status is PCAN_FILTER_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 the method FilterMessages. To do this, use the method SetValue

The parameter 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. It seems that the ID from a standard message uses the most significant 11 bits (bit 18 to 28) of the 29 bits. 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 FilterMessages(UInt16, UInt32, UInt32, TPCANMode) method on the channel PCAN_USBBUS1 to receive a custom range of IDs. 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.

  Note

It is assumed that the channel was already initialized.

C#
TPCANStatus result;
System.Text.StringBuilder strMsg;
UInt32 iBuffer;

strMsg = new System.Text.StringBuilder(256);

// ... channel is initialized ...

// The message filter is closed first to ensure the reception of the new range of IDs.
//
iBuffer = PCANBasic.PCAN_FILTER_CLOSE;
result = PCANBasic.SetValue(PCANBasic.PCAN_USBBUS1, TPCANParameter.PCAN_MESSAGE_FILTER, ref iBuffer, sizeof(UInt32));

if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    Console.WriteLine(strMsg.ToString());
}
else
{
    // The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
    //
    result = PCANBasic.FilterMessages(PCANBasic.PCAN_USBBUS1, 2, 5, TPCANMode.PCAN_MODE_STANDARD);
    if (result != TPCANStatus.PCAN_ERROR_OK)
    {
        // An error occurred, get a text describing the error and show it
        //
        PCANBasic.GetErrorText(result, 0, strMsg);
        Console.WriteLine(strMsg.ToString());
    }
    else
        Console.WriteLine("Filter successfully configured for IDs 2,3,4 and 5");
}

See Also