MessageFilter.h File Reference

Provides BMessageFilter class. More...

Classes
class	BMessageFilter
	Describes a message filter for BLooper and BHandler. More...

Typedefs
typedef filter_result(*	filter_hook) (BMessage *message, BHandler **target, BMessageFilter *filter)
	Prototype for a custom filter_hook for use in the BMessageFilter class. More...

Enumerations
enum	filter_result {   B_SKIP_MESSAGE,   B_DISPATCH_MESSAGE }
	Return Codes and Protocol of the filter_hook. More...
enum	message_delivery {   B_ANY_DELIVERY,   B_DROPPED_DELIVERY,   B_PROGRAMMED_DELIVERY }
	BMessageFilter filter criteria on how a message was delivered. More...
enum	message_source {   B_ANY_SOURCE,   B_REMOTE_SOURCE,   B_LOCAL_SOURCE }
	BMessageFilter filter criteria on the source of a message. More...

Detailed Description

Provides BMessageFilter class.

Typedef Documentation

filter_hook

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

Prototype for a custom filter_hook for use in the BMessageFilter class.

This hook can be used when you are constructing a new BMessageFilter object. It is a custom filter function you can use.

This hook should handle the following parameters:

Parameters

[in]	message	The message that needs to be verified.
[out]	target	If your filter hook is conscious about the available handlers, you can set a specific BHandler based on your filters requirements. You do not have to change this field, because there will always be a working default.
[in]	filter	A pointer to the filter from which this hook is called.

Returns

You should return B_SKIP_MESSAGE in case the message does not conform to the filter criteria, or B_DISPATCH_MESSAGE if the message passes these criteria.

See also

BMessageFilter(uint32, filter_hook)

BMessageFilter(message_delivery, message_source, filter_hook)

BMessageFilter(message_delivery, message_source, uint32, filter_hook)

Since

BeOS R3

Enumeration Type Documentation

filter_result

enum filter_result

Return Codes and Protocol of the filter_hook.

These return codes should be used in your own filter_hook function, or by your overridden BMessageFilter::Filter() method.

Since

BeOS R3

Enumerator
B_SKIP_MESSAGE	The message does not pass the filter criteria and should not be handled. Since BeOS R3
B_DISPATCH_MESSAGE	The message passes the filter criteria and should be dispatched to a BHandler. Since BeOS R3

message_delivery

enum message_delivery

BMessageFilter filter criteria on how a message was delivered.

Two constructors of the BMessageFilter class allow you to specify that it should filter based on how the message was delivered. There are two ways in which messages can be delivered within the Haiku API: by direct delivery using the BLooper::PostMessage() function, and by drag and drop in the GUI. With this filter you can, for example, specify that your handler only handles deliveries that were programmed by you, and not any random drag and drop actions initiated by the user.

Since

BeOS R3

Enumerator
B_ANY_DELIVERY	Accept both delivery methods. Since BeOS R3
B_DROPPED_DELIVERY	Only accept messages that were dropped by the user in the GUI. Since BeOS R3
B_PROGRAMMED_DELIVERY	Only accept messages that were delivered using the BLooper::PostMessage() method. Since BeOS R3

message_source

enum message_source

BMessageFilter filter criteria on the source of a message.

One of the key features of the messaging system of Haiku, is the ability to send messages between applications. However, your handler or looper might have been written in such a way that it would make no sense to try to process messages from an external source. Use these filter criteria to filter the unwanted messages out.

You use these constants in the constructors of the BMessageFilter class.

Warning

System messages, for example from the app_server, are considered remote messages. Keep this in mind when you want to set up criteria for your window and application loopers.

Since

BeOS R3

Enumerator
B_ANY_SOURCE	Accept both local and remote messages. Since BeOS R3
B_REMOTE_SOURCE	Only accept messages from a remote source, so from other applications. Since BeOS R3
B_LOCAL_SOURCE	Only accept messages from your own local application. Since BeOS R3