This document describes the BMessageFilter interface and some basics of how it is implemented. +The document has the following sections:
+ + + +The BMessageFilter class is a simple class for processing incoming BMessage's before +they are dispatched to a BLooper. The best source of information for the BMessageFilter interface +can be found +here in the Be Book. +
+ +The following use cases cover the BMessageFilter functionality:
+ +Construction 1: A BMessageFilter can be created by specifying a message_delivery +option, a message_source option, a command code and an optional filter function. These +options are used to determine the messages on which the filter will act and the filter itself +(see the "Filter" use cases).
Construction 2: A BMessageFilter can be created by specifying a message_delivery +option, a message_source option and an optional filter function. These options are used to +determine the messages on which the filter will act and the filter itself (see the "Filter" use +cases).
Construction 3: A BMessageFilter can be created by specifying a command code +and an optional filter function. These options are used to determine the messages on which the +filter will act and the filter itself (see the "Filter" use cases).
Construction 4: A BMessageFilter can be constructed by use of a copy constructor +which can take a reference to or a pointer to another BMessageFilter. The new BMessageFilter +will have all the options of the source BMessageFilter when that source filter was constructed. +Any other state of the source BMessageFilter that it has accumulated after construction is not +copied to the new filter.
Assignment: A BMessageFilter can be assigned the attributes of a source +BMessageFilter by the use of the assignment operator. The target BMessageFilter will have all +the options of the source BMessageFilter when that source filter was constructed. Any other +state of the source BMessageFilter that it has accumulated after construction is not copied +to the new filter.
Destruction: When a BMessageFilter is deconstructed, the BMessageFilter releases +any shared resources it may have allocated.
Command: When Command() is used on a BMessageFilter, the command code specified +at construction time for this filter is returned. If a BMessageFilter was not constructed +with a specific command code, this member function does not return a valid result.
FiltersAnyCommand: When FiltersAnyCommand() is called on a BMessageFilter, it +returns true if a command code was not specified at construction time for this filter. It +returns false if a command code was specified at construction time. The Command() member +function (see above use case) is only valid when FiltersAnyCommand() returns false.
Looper: The Looper() member function returns a pointer to the BLooper (or BHandler) +to which this filter has been added. If the filter has not been added to a BLooper, NULL is +returned. The member functions BLooper::AddCommonFilter() or BHandler::AddFilter() can be +used to add the filter to a looper (see use cases for BLooper and BHandler for details about +adding a filter).
MessageDelivery: The MessageDelivery() member function returns the message delivery +value that was specified at construction time for this filter. The possible values are +B_DROPPED_DELIVERY, B_PROGRAMMED_DELIVERY and B_ANY_DELIVERY. If no message delivery value +was specified at construction time, B_ANY_DELIVERY is returned.
MessageSource: The MessageSource() member function returns the message source +value that was specified at construction time for this filter. The possible values are +B_LOCAL_SOURCE, B_REMOTE_SOURCE and B_ANY_SOURCE. If no message source value +was specified at construction time, B_ANY_SOURCE is returned.
Filter 1: The filter can be applied for a message by passing the message and the +target BHandler which has received that message to the Filter() member function. This member +function returns B_DISPATCH_MESSAGE or B_SKIP_MESSAGE to the caller. The actual impact +of these filter results is dependent on the BLooper and BHandler behaviour (see the use cases for +these classes for more details).
Filter 2: If a filter function was not supplied on construction of the +BMessageFilter, then the Filter() member function determines the result of the filter. If the +Filter() member has been overridden in a derived class, the result depends on the behaviour of +this derived class. If the class has not been overridden and no filter function was provided +on construction, the B_DISPATCH_MESSAGE is returned. If a filter function was provided on +construction, then the filter function will be called and the Filter() member will return what +this filter function returns.
The implementation of the BMessageFilter is pretty simple. It is mainly a container for +properties of the filter itself and a few simple methods for getting and setting these +properties.
+ +The actual act of dispatching or skipping the message as dictated by the filter is implemented +in BLooper or BHandler. The BMessageFilter just provides a mechanism for these classes to +determine which to do. Also the BLooper or BHandler decide whether to pass the message through +the filter on their own. The filter does not look at every message to see whether the source +and delivery of this message is such that it should pass through the filter. Instead, BLooper or +BHandler look at the filter, check the source and delivery options of the filter against the +message itself and call the filter if appropriate. So, the filter is really just a container for +these options and doesn't take action based on them.
+ + +