BMessageFilter

Derived from: none
Declared in:  be/app/MessageFilter.h
Library: libbe.so
Allocation: Constructor only
more...

A BMessageFilter is a message-screening function that you "attach" to a BLooper or BHandler. The message filter sees messages just before they're dispatched (i.e. just before BLooper::DispatchMessage()), and can modify or reject the message, change the message's designated handler, or whatever else it wants to do—the implementation of the filter function isn't restricted.

To define a message filter, you have to provide a message-filtering function. You do this by implementing the Filter() hook function in a BMessageFilter subclass, or by supplying a filter_hook function to the BMessageFilter constructor. Only one filter function per object is called. If you implement Filter() and provide a filter_hook function, the filter_hook will win.

To attach a message filter to a looper, call BLooper::AddCommonFilter(). To add it to a handler, call BHandler::AddFilter(). Looper filters see all incoming messages; handler filters see only those messages that are targetted for that particular handler.

A BLooper or BHandler can have more than one message filter. Furthermore, a looper can have two sets of filters: a looper set and a handler set (keep in mind that BLooper is derived from BHandler). Looper filters are applied before handler filters.

A BMessageFilter object can be assigned to only one BHandler or BLooper at a time.

The BMessageFilter class is intended to be used as part of the system-defined messaging system. If you try to use one outside this system, your results may not be what you expect.

Hook Functions

Filter()

Constructor and Destructor

BMessageFilter()

BMessageFilter(message_delivery delivery,       message_source source,       uint32 command,       filter_hook filter = NULL) BMessageFilter(message_delivery delivery,       message_source source,       filter_hook filter = NULL) BMessageFilter(uint32 command,       filter_hook filter = NULL) BMessageFilter(const BMessageFilter &object) BMessageFilter(const BMessageFilter *object)

Creates and returns a new BMessageFilter. The first three arguments define the types of messages that the object wants to see:

• delivery specifies how the message must arrive: drag-and-drop (B_DROPPED_DELIVERY), programmatically (B_PROGRAMMED_DELIVERY), or either (B_ANY_DELIVERY). The default is B_ANY_DELIVERY.

• source specifes whether the sender of the message must be local vis-a-vis this app (B_LOCAL_SOURCE), remote (B_REMOTE_SOURCE), or either (B_ANY_SOURCE). The default is B_ANY_SOURCE.

• command is a command constant. If supplied, the what value of the incoming message must match this value.

Messages that don't fit the definition won't be sent to the object's filter function.

The filter argument is a pointer to a filter_hook function. This is the function that's invoked when a message needs to be examined (see filter_hook for the protocol). You don't have to supply a filter_hook function; instead, you can implement BMessageFilter's Filter() function in a subclass.

For more information, refer to the description of the member Filter() function.

~BMessageFilter()

virtual ~BMessageFilter()

Does nothing.

Member Functions

Command() , FiltersAnyCommand()

uint32 Command(void) const bool FiltersAnyCommand(void) const

Command() returns the command constant (the BMessage what value) that an arriving message must match for the filter to apply. FiltersAnyCommand() returns true if the filter applies to all messages, and false if it's limited to a specific command.

Because all command constants are valid, including negative numbers and 0, Command() returns a reliable result only if FiltersAnyCommand() returns false.

Filter()

virtual filter_result Filter(BMessage *message, BHandler **target)

Implemented by derived classes to examine an arriving message just before it's dispatched. The first two arguments are the message that's being considered, and the proposed BHandler target. You can alter the contents of the message, and alter or even replace the handler. If you replace the handler, the new handler must belong to the same looper as the original. The new handler is given an opportunity to filter the message before it's dispatched.

The return value must be one of these two values:

• B_DISPATCH_MESSAGE. The message and handler are passed (by the caller) to the looper's DispatchMessage() function.

• B_SKIP_MESSAGE. The message goes no further—it's immediately thrown away by the caller.

The default version of this function returns B_DISPATCH_MESSAGE.

It's possible to call your Filter() function yourself (i.e. outside the message-passing mechanism), but keep in mind that it's the caller's responsibility to interpret the return value.

Rather than implement the Filter() function, you can supply the BMessageFilter with a filter_hook callback when you construct the object. If you do both, the filter_hook (and not Filter()) will be invoked when the object is asked to examine a message.

FiltersAny  see Command()

Looper()

BLooper *Looper(void) const

Returns the BLooper whose messages this object filters, or NULL if the BMessageFilter hasn't yet been assigned to a BHandler or BLooper. To attach a BMessageFilter to a looper or handler, use BLooper::AddCommonFilter() or BHandler::AddFilter().

MessageDelivery() , MessageSource()

message_delivery MessageDelivery(void) const message_source MessageSource(void) const

These functions return constants, set when the BMessageFilter object was constructed, that describe the categories of messages that can be filtered. MessageDelivery() returns a constant that specifies how the message must be delivered (B_DROPPED_DELIVERY, B_PROGRAMMED_DELIVERY, or B_ANY_DELIVERY). MessageSource() returns how the source of the message is constrained (B_LOCAL_SOURCE, B_REMOTE_SOURCE, or B_ANY_SOURCE).

Operators

= (copy)

BMessageFilter &operator=(const BMessageFilter&)

Copies the filtering criteria and filter_hook pointer (if any) from the right-side object into the left-side object.

Constants and Defined Types

filter_hook

filter_result (*filter_hook)(BMessage *message,       BHandler **target,       BMessageFilter *messageFilter)

filter_hook defines the protocol for message-filtering functions. The first two arguments are the message that's being considered, and the proposed BHandler target. You can alter the contents of the message, and alter or even replace the handler. If you replace the handler, the new handler must belong to the same looper as the original. The new handler is given an opportunity to filter the message before it's dispatched.

messageFilter is a pointer to the object on whose behalf this function is being called; you mustn't delete this object. More than one BMessageFilter can use the same filter_hook function.

The return value must be one of these two values:

• B_DISPATCH_MESSAGE. The message and handler are passed (by the caller) to the looper's DispatchMessage() function.

• B_SKIP_MESSAGE. The message goes no further—it's immediately thrown away by the caller.

It's possible to call your filter function yourself (i.e. outside the message-passing mechanism), but keep in mind that it's the caller's responsibility to interpret the return value.

You supply a BMessageFilter with a filter_hook function when you constuct the object. Alternatively, you can subclass BMessageFilter and provide an implementation of Filter(). If you do both, the filter_hook (and not Filter()) will be invoked when the object is asked to examine a message.

message_source

message_delivery

filter_result