Public Member Functions | List of all members
BMessageFilter Class Reference

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

Inherited by _BMCFilter_.

Public Member Functions

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

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.
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
ScreenMessage(BMessage* message, BHandler** target, BMessageFilter* filter)
{
switch (message->what) {
case kTcpEvent:
target = &fTcpHandler;
case kUdpEvent:
target = &fUdpHandler;
}
}
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
messageThe message that needs to be filtered.
targetIf 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