BMessageFilter Class Reference

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

Public Member Functions
	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.
	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 (uint32 what, filter_hook func=NULL)
	Construct a new object that filters on a message constant.
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.

Since

BeOS R3

Constructor & Destructor Documentation

BMessageFilter() [1/5]

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)

Since

BeOS R3

BMessageFilter() [2/5]

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)

Since

BeOS R3

BMessageFilter() [3/5]

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)

Since

BeOS R3

BMessageFilter() [4/5]

BMessageFilter::BMessageFilter

(

const BMessageFilter &

filter

)

Copy constructor. Copy the criteria from another object.

Since

BeOS R3

BMessageFilter() [5/5]

BMessageFilter::BMessageFilter

(

const BMessageFilter *

filter

)

Create a new object based on criteria of another object.

Since

BeOS R3

~BMessageFilter()

BMessageFilter::~BMessageFilter ( )

virtual

Destructor. Does nothing.

Since

BeOS R3

Member Function Documentation

Command()

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

Since

BeOS R3

Filter()

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.

Since

BeOS R3

FiltersAnyCommand()

bool BMessageFilter::FiltersAnyCommand

(

)

const

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

See also

Command() const

Since

BeOS R3

Looper()

BLooper * BMessageFilter::Looper

(

)

const

Return the looper this filter is associated with.

Since

BeOS R3

MessageDelivery()

message_delivery BMessageFilter::MessageDelivery

(

)

const

Return the message_delivery criterium of this filter.

Since

BeOS R3

MessageSource()

message_source BMessageFilter::MessageSource

(

)

const

Return the message_source criterium of this filter.

Since

BeOS R3

operator=()

BMessageFilter & BMessageFilter::operator=

(

const BMessageFilter &

from

)

Assignment operator. Copies criteria from another filter.

Since

BeOS R3