/** 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 byyour overridden BMessageFilter::Filter() method.\since BeOS R3*//*!\var B_SKIP_MESSAGE\brief The message does not pass the filter criteria and should not behandled.\since BeOS R3*//*!\var B_DISPATCH_MESSAGE\brief The message passes the filter criteria and should be dispatched toa 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 BMessageFilterclass.This hook can be used when you are constructing a new BMessageFilterobject. 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 availablehandlers, you can set a specific BHandler based on your filtersrequirements. You do not have to change this field, becausethere 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 notconform to the filter criteria, or #B_DISPATCH_MESSAGE if themessage 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 itshould filter based on how the message was delivered. There are two ways inwhich messages can be delivered within the Haiku API: by direct deliveryusing the BLooper::PostMessage() function, and by drag and drop in the GUI.With this filter you can, for example, specify that your handler onlyhandles deliveries that were programmed by you, and not any random drag anddrop 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 theBLooper::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 abilityto send messages between applications. However, your handler or loopermight have been written in such a way that it would make no sense to tryto process messages from an external source. Use these filter criteria tofilter 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, areconsidered remote messages. Keep this in mind when you wantto 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 otherapplications.\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 incomingmessages should have in order to be processed by a handler or a looper.BMessageFilter provides three default filter criteria, the \c whatconstant, 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 messageand a pointer to a BHandler as arguments, and allows you to accept orreject 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 allowscleaner code (in some cases).Both methods have their merits, but please remember that you have to choosewhich one you want to use, since you can't use both. The order ofprocessing 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 beassociated with specific BHandlers. Using the BHandler::AddFilter()and the BHandler::SetFilterList() methods, you can add filters to thefilter list. It is also possible to associate filters with BLoopers. Inthat case, all incoming messages of that looper are checked against thecriteria. To perform filtering in loopers, have a look at theBLooper::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);\endcodeAn example of a filter that only allows one type of message:\codeBMessageFilter *filter = new BMessageFilter(kHappyMessages);handler->AddFilter(filter);\endcodeAn example of a #filter_hook:\code// The handler depends on the what code of a messagefilter_resultScreenMessage(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);\endcodeThe two classes that use BMessageFilter are BLooper and BHandler. In thegeneral 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 filtercriteria.\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 messagesource.You can also specify a #filter_hook, if you want to apply custom filtercriteria.\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, messagesource and specific message constants.You can also specify a #filter_hook, if you want to apply custom filtercriteria.\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 tosuit 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 handlethis message. Note that you do have to pass a handler that isassociated with the looper that received the message.\return You should return \c B_DISPATCH_MESSAGE in case the message passesthe 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 onthe 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*/