BMessageFilter Class Reference

Describes a message filter for BLooper and BHandler. More...

List of all members.

Public Member Functions
	BMessageFilter (uint32 what, filter_hook func=NULL)
	Construct a new object that filters on a message constant.
	BMessageFilter (message_delivery delivery, message_source source, filter_hook func=NULL)
	Construct a new object that filters on delivery method and message source.
	BMessageFilter (message_delivery delivery, message_source source, uint32 what, filter_hook func=NULL)
	Construct a new object that filters on delivery method, message source and specific message constants.
	BMessageFilter (const BMessageFilter &filter)
	Copy constructor. Copy the criteria from another object.
	BMessageFilter (const BMessageFilter *filter)
	Create a new object based on criteria of another object.
virtual	~BMessageFilter ()
	Destructor. Does nothing.
uint32	Command () const
	Return the accepted message constant.
virtual filter_result	Filter (BMessage *message, BHandler **_target)
	Filter the message according to custom criteria.
bool	FiltersAnyCommand () const
	Return whether or not this filter has a message command criterium.
BLooper *	Looper () const
	Return the looper this filter is associated with.
message_delivery	MessageDelivery () const
	Return the message_delivery criterium of this filter.
message_source	MessageSource () const
	Return the message_source criterium of this filter.
BMessageFilter &	operator= (const BMessageFilter &from)
	Assignment operator. Copies criteria from another filter.

---

Detailed Description

Describes a message filter for BLooper and BHandler.

Objects of this class serve as a description of properties that incoming messages should have in order to be processed by a handler or a looper. BMessageFilter provides three default filter criteria, the what constant, the message_source and the type of message_delivery, and an extendible filter_hook.

BMessageFilter's standard filter criteria can be extended in two ways:

1. Specify a filter_hook. This is a static function that takes a message and a pointer to a BHandler as arguments, and allows you to accept or reject the message, and even redirect it to a specific BHandler.
2. Subclass the BMessageFilter class and override the Filter() function. This has the same capabilities as using a filter_hook, but it allows cleaner code (in some cases).

Both methods have their merits, but please remember that you have to choose which one you want to use, since you can't use both. The order of processing the criteria is in this order: the source, the delivery method, the filter hook and then the overrided Filter() method. Additionally, if a filter_hook is registered, the Filter() method will not be called.

The BMessageFilter objects are used in two different classes. They can be associated with specific BHandlers. Using the BHandler::AddFilter() and the BHandler::SetFilterList() methods, you can add filters to the filter list. It is also possible to associate filters with BLoopers. In that case, all incoming messages of that looper are checked against the criteria. To perform filtering in loopers, have a look at the BLooper::AddCommonFilter() and the BLooper::SetCommonFilterList() methods.

An example of a filter that selects on the default criteria:

// Our window does not handle drop events.
BMessageFilter *filter = new BMessageFilter(B_PROGRAMMED_DELIVERY, B_ANY_SOURCE);
window->AddCommonFilter(filter);

An example of a filter that only allows one type of message:

BMessageFilter *filter = new BMessageFilter(kHappyMessages);
handler->AddFilter(filter);

An example of a filter_hook:

// The handler depends on the what code of a message
filter_result
ScreenMessage(BMessage* message, BHandler** target, BMessageFilter* filter)
{
    switch (message->what) {
        case kTcpEvent:
            target = &fTcpHandler;
            return B_DISPATCH_MESSAGE;
        case kUdpEvent:
            target = &fUdpHandler;
            return B_DISPATCH_MESSAGE;
    }
    
    return B_SKIP_MESSAGE;
}

BMessageFilter *filter = new BMessageFilter(B_ANY_DELIVERY, B_ANY_SOURCE, ScreenMessage);
looper->AddCommonFilter(filter);

The two classes that use BMessageFilter are BLooper and BHandler. In the general messaging introduction, there is also a section on handling messages.

---

Constructor & Destructor Documentation

BMessageFilter::BMessageFilter	(	uint32	inWhat,
		filter_hook	func = NULL
	)

Construct a new object that filters on a message constant.

You can also specify a filter_hook, if you want apply custom filter criteria.

See also:

BMessageFilter(message_delivery, message_source, filter_hook)

BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)

BMessageFilter::BMessageFilter	(	message_delivery	delivery,
		message_source	source,
		filter_hook	func = NULL
	)

Construct a new object that filters on delivery method and message source.

You can also specify a filter_hook, if you want to apply custom filter criteria.

See also:

BMessageFilter(uint32 what,filter_hook)

BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)

BMessageFilter::BMessageFilter	(	message_delivery	delivery,
		message_source	source,
		uint32	inWhat,
		filter_hook	func = NULL
	)

Construct a new object that filters on delivery method, message source and specific message constants.

You can also specify a filter_hook, if you want to apply custom filter criteria.

See also:

BMessageFilter(uint32 what,filter_hook)

BMessageFilter(message_delivery, message_source, filter_hook)

---

Member Function Documentation

uint32 BMessageFilter::Command

(

)

const

Return the accepted message constant.

This method returns zero (0) in case this filter does not filter based on the message constant.

See also:

FiltersAnyCommand() const

filter_result BMessageFilter::Filter	(	BMessage *	message,
		BHandler **	target
	)		[virtual]

Filter the message according to custom criteria.

The default implementation of this method always returns B_DISPATCH_MESSAGE. You can override this method in subclasses to suit your own criteria. You receive two arguments.

Parameters:

message	The message that needs to be filtered.
target	If you want to, you can specify a handler that should handle this message. Note that you do have to pass a handler that is associated with the looper that received the message.

Returns:

You should return B_DISPATCH_MESSAGE in case the message passes the tests, or B_SKIP_MESSAGE in case the message does not pass.

bool BMessageFilter::FiltersAnyCommand

(

)

const

Return whether or not this filter has a message command criterium.

See also:

Command() const