FilterMessages

PCAN-Basic

previous page next page

PCAN-Basic Documentation

FilterMessages

Configures the reception filter.

Syntax

Pascal OO

class function FilterMessages(
    Channel: TPCANHandle;
    FromID: LongWord;
    ToID: LongWord;
    Mode: TPCANMode
    ): TPCANStatus;

[DllImport("PCANBasic.dll", EntryPoint = "CAN_FilterMessages")]
public static extern TPCANStatus FilterMessages(
    [MarshalAs(UnmanagedType.U1)]
    TPCANHandle Channel,
    UInt32 FromID,
    UInt32 ToID,
    [MarshalAs(UnmanagedType.U1)]
    TPCANMode Mode);

C++ / CLR

[DllImport("PCANBasic.dll", EntryPoint = "CAN_FilterMessages")]
static TPCANStatus FilterMessages(
    [MarshalAs(UnmanagedType::U1)]
    TPCANHandle Channel,
    UInt32 FromID,
    UInt32 ToID,
    [MarshalAs(UnmanagedType::U1)]
    TPCANMode Mode);

Visual Basic

<DllImport("PCANBasic.dll", EntryPoint:="CAN_FilterMessages")> _
Public Shared Function FilterMessages( _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Channel As TPCANHandle, _
    ByVal FromID As UInt32, _
    ByVal ToID As UInt32, _
    <MarshalAs(UnmanagedType.U1)> _
    ByVal Mode As TPCANMode) As TPCANStatus
End Function

Python

def FilterMessages(
    self,
    Channel,
    FromID,
    ToID,
    Mode)

Parameters

Parameters	Description
Channel	The handle of a PCAN Channel (see TPCANHandle).
FromID	The lowest CAN ID wanted to be received.
ToID	The highest CAN ID wanted to be received.
Mode	The type of the filter being set (see TPCANMode).

Returns

The return value is a TPCANStatus code. 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.

Remarks

Note that after a PCAN Channel is initialized, the status of its filter is fully opened. According with the current filter status, calling this method causes the following behavior:

Filter 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] .
Filter status is PCAN_FILTER_CLOSE: The filter is set to the given range of IDs passed to this function [FromID, ToID] .
Filter 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 in account that configuring the message filter cause the CAN controller to enter the Reset state. This will affect other applications that communicate with the same PCAN hardware.

Notes:

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.
Multiple calls of FilterMessages expand the reception filter.
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".

Python Notes

Class-Method: Unlike the .NET Framework, under Python a variable has to be instantiated with an object of type PCANBasic in order to use the API functionality.
Python's first argument convention: Under Python, 'self' is a parameter that is automatically included within the call of this method, within a PCANBasic object and hasn't to be indicated in a method call. This parameter represents the calling object itself.

Example

The following example shows the use of the method FilterMessages 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;
StringBuilder strMsg;
UInt32 iBuffer;

strMsg = new StringBuilder(256);

// 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);
    MessageBox.Show(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);
        MessageBox.Show(strMsg.ToString());
    }
    else
        MessageBox.Show("Filter successfully configured for IDs 2,3,4 and 5");
}

C++/CLR:

TPCANStatus result;
StringBuilder^ strMsg;
UInt32 iBuffer;

strMsg = gcnew StringBuilder(256);

// 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, iBuffer, sizeof(iBuffer));
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    MessageBox::Show(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);
        MessageBox::Show(strMsg->ToString());
    }
    else
        MessageBox::Show("Filter successfully configured for IDs 2,3,4 and 5");
}

Visual Basic:

Dim result As TPCANStatus
Dim strMsg As StringBuilder
Dim iBuffer As UInt32

strMsg = New StringBuilder(256)

'  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, iBuffer, Convert.ToUInt32(Len(iBuffer)))
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    MessageBox.Show(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 Then
        ' An error occurred, get a text describing the error and show it
        '
        PCANBasic.GetErrorText(result, 0, strMsg)
        MessageBox.Show(strMsg.ToString)
    Else
        MessageBox.Show("Filter successfully configured for IDs 2,3,4 and 5")
    End If
End If

Pascal OO:

var
    result : TPCANStatus;
    strMsg: array [0..256] of Char;
    iBuffer: LongWord;
begin
    //  The message filter is closed first to ensure the reception of the new range of IDs.
    //
    iBuffer := TPCANBasic.PCAN_FILTER_CLOSE;
    result := TPCANBasic.SetValue(TPCANBasic.PCAN_USBBUS1,PCAN_MESSAGE_FILTER, PLongWord(@iBuffer), sizeof(iBuffer));
    If (result <> PCAN_ERROR_OK) Then
    begin
        // An error occurred, get a text describing the error and show it
        //
        TPCANBasic.GetErrorText(result, 0, strMsg);
        MessageBox(0, strMsg, 'Error',MB_OK);
    end
    else
    begin
        // The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
        //
        result := TPCANBasic.FilterMessages(TPCANBasic.PCAN_USBBUS1,2,5,PCAN_MODE_STANDARD);
        If (result <> PCAN_ERROR_OK) Then
        begin
            // An error occurred, get a text describing the error and show it
            //
            TPCANBasic.GetErrorText(result, 0, strMsg);
            MessageBox(0, strMsg, 'Error',MB_OK);
        end
        else
            MessageBox(0,'Filter successfully configured for IDs 2,3,4 and 5','Success', MB_OK);
    end;

Python:

#  The message filter is closed first to ensure the reception of the new range of IDs.
#
result = objPCAN.SetValue(PCAN_USBBUS1,PCAN_MESSAGE_FILTER,PCAN_FILTER_CLOSE)
if result != PCAN_ERROR_OK:
    # An error occurred, get a text describing the error and show it
    #
    result = objPCAN.GetErrorText(result)
    print result[1]
else:
    # The message filter is configured to receive the IDs 2,3,4 and 5 on the PCAN-USB, Channel 1
    #
    result = objPCAN.FilterMessages(PCAN_USBBUS1,2,5,PCAN_MODE_STANDARD)
    if result != PCAN_ERROR_OK:
        # An error occurred, get a text describing the error and show it
        #
        result = objPCAN.GetErrorText(result)
        print result[1]
    else:
        print "Filter successfully configured for IDs 2,3,4 and 5"