/*
 * Copyright 2007-2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Niels Sascha Reedijk, niels.reedijk@gmail.com
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/app/MessageFilter.h	hrev47355
 *		src/kits/app/MessageFilter.cpp	hrev47355
 */


/*!
	\file MessageFilter.h
	\ingroup app
	\ingroup libbe
	\brief Provides BMessageFilter class.
*/


/*!
	\enum filter_result
	\brief 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
*/


/*!
	\var B_SKIP_MESSAGE
	\brief The message does not pass the filter criteria and should not be
	       handled.

	\since BeOS R3
*/


/*!
	\var B_DISPATCH_MESSAGE
	\brief The message passes the filter criteria and should be dispatched to
	       a BHandler.

	\since BeOS R3
*/


/*!
	\typedef filter_result (*filter_hook) (BMessage* message,
		 BHandler** target, BMessageFilter* filter)
	\brief Prototype for a custom \c 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:

	\param[in] message The message that needs to be verified.
	\param[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.
	\param[in] filter A pointer to the filter from which this hook is called.

	\return 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 BMessageFilter(uint32, filter_hook)
	\see BMessageFilter(message_delivery, message_source, filter_hook)
	\see BMessageFilter(message_delivery, message_source, uint32, filter_hook)

	\since BeOS R3
*/


/*!
	\enum message_delivery
	\brief 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
*/


/*!
	\var B_ANY_DELIVERY
	\brief Accept both delivery methods.

	\since BeOS R3
*/


/*!
	\var B_DROPPED_DELIVERY
	\brief Only accept messages that were dropped by the user in the GUI.

	\since BeOS R3
*/


/*!
	\var B_PROGRAMMED_DELIVERY
	\brief Only accept messages that were delivered using the
	       BLooper::PostMessage() method.

	\since BeOS R3
*/


/*!
	\enum message_source
	\brief 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 \c 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
*/


/*!
	\var B_ANY_SOURCE
	\brief Accept both local and remote messages.

	\since BeOS R3
*/


/*!
	\var B_REMOTE_SOURCE
	\brief Only accept messages from a remote source, so from other
	       applications.

	\since BeOS R3
*/


/*!
	\var B_LOCAL_SOURCE
	\brief Only accept messages from your own local application.

	\since BeOS R3
*/


/*!
	\class BMessageFilter
	\ingroup app
	\ingroup libbe
	\brief 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 \c 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:
	-# 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.
	-# 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:
\code
// Our window does not handle drop events.
BMessageFilter *filter = new BMessageFilter(B_PROGRAMMED_DELIVERY, B_ANY_SOURCE);
window->AddCommonFilter(filter);
\endcode

	An example of a filter that only allows one type of message:
\code
BMessageFilter *filter = new BMessageFilter(kHappyMessages);
handler->AddFilter(filter);
\endcode

	An example of a #filter_hook:
\code
// 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);
\endcode

	The two classes that use BMessageFilter are BLooper and BHandler. In the
	general messaging introduction, there is also a section on 
	\ref app-messaging-receiving "handling messages".

	\since BeOS R3
*/



/*!
	\fn BMessageFilter::BMessageFilter(uint32 inWhat, filter_hook func)
	\brief 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 BMessageFilter(message_delivery, message_source, filter_hook)
	\see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)

	\since BeOS R3
*/


/*!
	\fn BMessageFilter::BMessageFilter(message_delivery delivery,
		 message_source source, filter_hook func)
	\brief 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 BMessageFilter(uint32 what,filter_hook)
	\see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)

	\since BeOS R3
*/


/*!
	\fn BMessageFilter::BMessageFilter(message_delivery delivery,
		message_source source, uint32 inWhat, filter_hook func)
	\brief 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 BMessageFilter(uint32 what,filter_hook)
	\see BMessageFilter(message_delivery, message_source, filter_hook)

	\since BeOS R3
*/


/*!
	\fn BMessageFilter::BMessageFilter(const BMessageFilter& filter)
	\brief Copy constructor. Copy the criteria from another object.

	\since BeOS R3
*/


/*!
	\fn BMessageFilter::BMessageFilter(const BMessageFilter* filter)
	\brief Create a new object based on criteria of another object.

	\since BeOS R3
*/


/*!
	\fn BMessageFilter::~BMessageFilter()
	\brief Destructor. Does nothing.

	\since BeOS R3
*/


/*!
	\fn BMessageFilter& BMessageFilter::operator=(const BMessageFilter& from)
	\brief Assignment operator. Copies criteria from another filter.

	\since BeOS R3
*/


/*!
	\fn filter_result BMessageFilter::Filter(BMessage* message,
		 BHandler** target)
	\brief Filter the message according to custom criteria.

	The default implementation of this method always returns
	\c B_DISPATCH_MESSAGE. You can override this method in subclasses to
	suit your own criteria. You receive two arguments.

	\param message The message that needs to be filtered.
	\param 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.

	\return You should return \c B_DISPATCH_MESSAGE in case the message passes
	        the tests, or \c B_SKIP_MESSAGE in case the message does not pass.

	\since BeOS R3
*/


/*!
	\fn message_delivery BMessageFilter::MessageDelivery() const
	\brief Return the message_delivery criterium of this filter.

	\since BeOS R3
*/


/*!
	\fn message_source BMessageFilter::MessageSource() const
	\brief Return the message_source criterium of this filter.

	\since BeOS R3
*/


/*!
	\fn uint32 BMessageFilter::Command() const
	\brief Return the accepted message constant.

	This method returns zero (0) in case this filter does not filter based on
	the message constant.

	\see FiltersAnyCommand() const

	\since BeOS R3
*/


/*!
	\fn bool BMessageFilter::FiltersAnyCommand() const
	\brief Return whether or not this filter has a message command criterium.

	\see Command() const

	\since BeOS R3
*/


/*!
	\fn BLooper* BMessageFilter::Looper() const
	\brief Return the looper this filter is associated with.

	\since BeOS R3
*/
