xbmc/messaging/IMessageTarget.h

   1 /*
   2  *  Copyright (C) 2005-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 namespace KODI
  12 {
  13 namespace MESSAGING
  14 {
  15 class ThreadMessage;
  16
  17 /*!
  18  * \class IMessageTarget IMessageTarget.h "messaging/IMessageTarget.h"
  19  * \brief A class wishing to receive messages should implement this
  20  *        and call \sa CApplicationMessenger::RegisterReceiver
  21  *        to start receiving messages
  22  */
  23 class IMessageTarget
  24 {
  25 public:
  26   virtual ~IMessageTarget() = default;
  27   /*!
  28    * \brief Should return the message mask that it wishes to receive
  29    *        messages for
  30    *
  31    * The message mask is defined in "messaging/ApplicationMessenger.h"
  32    * pick the next one available when creating a new
  33    */
  34   virtual int GetMessageMask() = 0;
  35
  36   /*!
  37    * \brief This gets called whenever a message matching the registered
  38    *        message mask is processed.
  39    *
  40    * There are no ordering guarantees here so implementations should never
  41    * rely on a certain ordering of messages.
  42    *
  43    * Cleaning up any pointers stored in the message payload is not specified
  44    * and is decided by the implementer of the message.
  45    * In general prefer to delete any data in this method to keep the callsites cleaner
  46    * and simpler but if data is to be passed back it's perfectly valid to handle it any way
  47    * that fits the situation as long as it's documented along with the message.
  48    *
  49    * To return a simple value the result parameter of \sa ThreadMessage can be used
  50    * as it will be used as the return value for \sa CApplicationMessenger::SendMsg.
  51    * It is up to the implementer to decide if this is to be used and it should be documented
  52    * along with any new message implemented.
  53    */
  54   virtual void OnApplicationMessage(ThreadMessage* msg) = 0;
  55 };
  56 }
  57 }