WorkerAddFilter(FilteringCriterion) Method

Includes an additional filtering criterion to the message filter of the default receive queue (index 0).

Definition

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

C#

public bool AddFilter(
	FilteringCriterion filter
)

VB

Public Function AddFilter ( 
	filter As FilteringCriterion
) As Boolean

C++

public:
bool AddFilter(
	FilteringCriterion filter
)

Parameters

filter FilteringCriterion: A FilteringCriterion value representing a filter criterion.

Return Value

Boolean
A value indicating whether the filtering criterion was successfully added or not.

Remarks

The Worker registers 'ReceiveQueuesCount' receive queues. These are 0-indexed. The first queue (index 0) is open by default when the object is created, meaning, its message filter is set to PassForAll. All other queues remain closed, that is, their filters are configured as BlockForAll. The methods associated with a receive queue are overloaded, allowing either the direct use of the default queue (index 0) without specifying an index, or the use of a specific queue by passing an index.

To allow a message filter to apply filtering criteria, the status of it must be Inspect.

Duplicate filter criteria are not allowed. Attempting to include an item that already exists causes this method to fail.

Important

Each time a filtering criterion is added using AddFilter the state of the message filter of the associated receive queue is automatically set to Inspect.

Note

Filtering criteria with Behavior equals to Exclude are validated first. If there is no match, those with Behavior equals to Include are validated. The criteria are validated in the same order as they were registered, the oldest registered criterion is validated first, the newest one is validated last.

Important

If only exclusive filter criteria are used, messages that do not match any of them will be accepted and placed in the receive queue.

Example

The following example shows how to configure the message filter of the default receive queue to avoid receiving messages with extended IDs 0x00000010, 0x00000011, and 0x00000012.

In case of failure, an error messages is written to the console output using English as output language.

C#

// Create the object using the default configuration
//
Worker myWorker = new Worker();

// Set the filter of the default receive queue to discard messages
// with extended IDs 0x00000010, 0x00000011, and 0x00000012
//
FilteringCriterion criterion = new FilteringCriterion();
criterion.SetIdRange(0x10, 0x12, FilterMode.Extended, FilterBehavior.Exclude);
if(!myWorker.AddFilter(criterion))
    Console.WriteLine($"The given filter is already registered.");
else
    Console.WriteLine($"Filter configured successfully.");

try
{ 
    // Activate the worker object
    //
    myWorker.Start();
    Console.WriteLine("The Worker object was activated successfully - Messages with extended ID 10h, 11h, and 12h are being ignored.");

    // Deactivate the worker object, when it is no longer needed
    //
    myWorker.Stop();
    Console.WriteLine("The Worker object was deactivated.");
}
catch(Exception ex)
{
    Console.WriteLine($"An exception occurred by activating the Worker object. {ex.Message}");
}

VB

' Create the object using the default configuration
'
Dim myWorker As Worker = New Worker()

' Set the filter of the default receive queue to discard messages
' with extended IDs 0x00000010, 0x00000011, and 0x00000012
'
Dim criterion As FilteringCriterion = New FilteringCriterion()
criterion.SetIdRange(&H10, &H12, FilterMode.Extended, FilterBehavior.Exclude)
If Not myWorker.AddFilter(criterion) Then
    Console.WriteLine($"The given filter is already registered.")
Else
    Console.WriteLine($"Filter configured successfully.")
End If

Try
    ' Activate the worker object
    '
    myWorker.Start()
    Console.WriteLine("The Worker object was activated successfully - Messages with extended ID 10h, 11h, and 12h are being ignored.")

    ' Deactivate the worker object, when it is no longer needed
    '
    myWorker.[Stop]()
    Console.WriteLine("The Worker object was deactivated.")
Catch ex As Exception
    Console.WriteLine($"An exception occurred by activating the Worker object. {ex.Message}")
End Try

C++

// Create the object using the default configuration
//
Worker^ myWorker = gcnew Worker();

// Set the filter of the default receive queue to discard messages
// with extended IDs 0x00000010, 0x00000011, and 0x00000012
//
FilteringCriterion criterion;
criterion.SetIdRange(0x10, 0x12, FilterMode::Extended, FilterBehavior::Exclude);
if (!myWorker->AddFilter(criterion))
    Console::WriteLine("The given filter is already registered.");
else
    Console::WriteLine("Filter configured successfully.");

try
{
    // Activate the worker object
    //
    myWorker->Start(false, false, false);
    Console::WriteLine("The Worker object was activated successfully - Two receive queues are used.");

    // Deactivate the worker object, when it is no longer needed
    //
    myWorker->Stop(false, false, false);
    Console::WriteLine("The Worker object was deactivated.");
}
catch (Exception^ ex)
{
    Console::WriteLine("An exception occurred by activating the Worker object. {0}", ex->Message);
}