Important
public bool AddFilter(
int queueIndex,
FilteringCriterion filter
)
Public Function AddFilter (
queueIndex As Integer,
filter As FilteringCriterion
) As Boolean
public:
bool AddFilter(
int queueIndex,
FilteringCriterion filter
)
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.
The following example shows how to configure the message filter of the second 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.
// Create the object using the default configuration
//
Worker myWorker = new Worker();
// Set the filter of the second receive queue (index 1) 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(1, 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}");
}
' Create the object using the default configuration
'
Dim myWorker As Worker = New Worker()
' Set the filter of the second receive queue (index 1) 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(1, 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
// Create the object using the default configuration
//
Worker^ myWorker = gcnew Worker();
// Set the filter of the second receive queue (index 1) to discard messages
// with extended IDs 0x00000010, 0x00000011, and 0x00000012
//
FilteringCriterion criterion;
criterion.SetIdRange(0x10, 0x12, FilterMode::Extended, FilterBehavior::Exclude);
if (!myWorker->AddFilter(1, 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);
}
IndexOutOfRangeException | The queueIndex parameter value is out of range. This must be in the range [0...ReceiveQueuesCount-1]. |