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

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.

Does nothing.

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:

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 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.

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.

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().

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).

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

These constants distinguish the delivery criterion for filtering a BMessage.

See also: The BMessageFilter constructor

These constants list the possible constraints that a BMessageFilter might impose on the source of the messages it filters.

See also: The BMessageFilter constructor

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:

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.

typedef enum { . . . } filter_result

This type distinguishes between the B_SKIP_MESSAGE and B_DISPATCH_MESSAGE return values for a filter function.

See also: BMessageFilter::Filter()

typedef enum { . . . } message_delivery

This type enumerates the delivery criteria for filtering a message.

See also: The BMessageFilter constructor

typedef enum { . . . } message_source

This type enumerates the source criteria for filtering a message.

See also: The BMessageFilter constructor