inc/FIoRemoteMessagePort.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16 /**
  17  * @file                FIoRemoteMessagePort.h
  18  * @brief               This is the header file for the %RemoteMessagePort class.
  19  *
  20  * This header file contains declarations of the %RemoteMessagePort class.
  21  */
  22 #ifndef _FIO_REMOTE_MESSAGE_PORT_H_
  23 #define _FIO_REMOTE_MESSAGE_PORT_H_
  24
  25 #include <FBaseResult.h>
  26 #include <FBaseObject.h>
  27 #include <FBaseDataType.h>
  28 #include <FBaseColIMap.h>
  29 #include <FAppTypes.h>
  30
  31 namespace Tizen { namespace Io
  32 {
  33
  34 class LocalMessagePort;
  35
  36 /**
  37 * @class    RemoteMessagePort
  38 * @brief    This class provides methods for sending messages to message ports of another application.
  39 *
  40 * @since    2.0
  41 *
  42 * @final        This class is not intended for extension.
  43 *
  44 * The %RemoteMessagePort class provides methods for sending messages to message ports of another application.
  45 *
  46 * For more information on the class features,
  47 * see <a href="../org.tizen.native.appprogramming/html/guide/io/messageport.htm">Message Port Communication</a>.
  48 *
  49 * @see Tizen::Io::MessagePortManager
  50 * @see Tizen::Io::LocalMessagePort
  51 *
  52 * @code
  53 *
  54 * #include <FBase.h>
  55 * #include <FIo.h>
  56 *
  57 * using namespace Tizen::Base;
  58 * using namespace Tizen::Base::Collection;
  59 * using namespace Tizen::Io;
  60 *
  61 * class MyAppClass
  62 *               : public Tizen::Io::IMessagePortListener
  63 * {
  64 * public:
  65 *       void Initialize(void);
  66 *       virtual void OnMessageReceivedN(RemoteMessagePort* pRemoteMessagePort, IMap* pMessage);
  67 *       void GetOnlineFriends(void);
  68 *
  69 * private:
  70 *       LocalMessagePort* pLocalPort;
  71 *       RemoteMessagePort* pRemotePort;
  72 * };
  73 *
  74 * void
  75 * MyAppClass::Initialize(void)
  76 * {
  77 *       pLocalPort = MessagePortManager::RequestLocalMessagePort(L"PortA");
  78 *       pLocalPort->AddMessagePortListener(*this);
  79 *
  80 *       pRemotePort = MessagePortManager::RequestRemoteMessagePort(L"1234567890.RemoteApp", L"PortB");
  81 * }
  82 *
  83 * void
  84 * MyAppClass::OnMessageReceivedN(RemoteMessagePort* pRemoteMessagePort, IMap* pMessage)
  85 * {
  86 *   String* pValue = static_cast<String*>(pMessage->GetValue(String(L"Reply")));
  87 *
  88 *       AppLog("My friend's name is %ls", pValue->GetPointer());
  89 *
  90 *       delete pMessage;
  91 * }
  92 *
  93 * void
  94 * MyAppClass::GetOnlineFriends(void)
  95 * {
  96 *       HashMap* pMap = new HashMap(SingleObjectDeleter);
  97 *       pMap->Construct();
  98 *
  99 *       pMap->Add(new String(L"Request"), new String(L"Friend"));
 100 *
 101 *       pRemotePort->SendMessage(pLocalPort, pMap);
 102 *
 103 *       delete pMap;
 104 * }
 105 *
 106 * @endcode
 107 */
 108
 109 class _OSP_EXPORT_ RemoteMessagePort
 110         : public Tizen::Base::Object
 111 {
 112 public:
 113
 114         /**
 115         * Gets the name of a remote message port.
 116         *
 117         * @since    2.0
 118         *
 119         * @return               The name of a remote message port
 120         */
 121         Tizen::Base::String GetName(void) const;
 122
 123         /**
 124         * Gets the ID of a remote application.
 125         *
 126         * @since    2.0
 127         *
 128         * @return               The ID of a remote application
 129         */
 130         Tizen::App::AppId GetAppId(void) const;
 131
 132         /**
 133         * Checks whether an instance is a trusted message port or not.
 134         *
 135         * @since    2.0
 136         *
 137         * @return               @c true if the instance is a trusted message port, @n
 138         *                               else @c false
 139         */
 140         bool IsTrusted(void) const;
 141
 142         /**
 143          * Sends a message to the message port of a remote application. This method is used for the unidirectional communication.
 144          *
 145          * @since    2.0
 146          *
 147          * @return       An error code
 148          * @param[in]     pMessage            A pointer to an argument map of key (String) and value (String or ByteBuffer) pair @n
 149          *                                                                        The recommended message size is under 4KB.
 150          * @exception     E_SUCCESS           The method is successful.
 151          * @exception     E_INVALID_ARG       The message argument is not a map of key (String) and value (String or ByteBuffer) pair.
 152          * @exception     E_OBJ_NOT_FOUND     The message port of the target application is not found.
 153          * @exception     E_MAX_EXCEEDED      The size of @c pMessage has exceeded the maximum limit.
 154          * @exception     E_SYSTEM            The method has failed due to a severe system error.
 155          * @remarks       The recommended message size is under 4KB because severe system performance degradation may occur for large messages. @c E_MAX_EXCEEDED may be returned for messages over 4KB size.
 156          */
 157         result SendMessage(const Tizen::Base::Collection::IMap* pMessage);
 158
 159
 160         /**
 161          * Sends a message to the message port of a remote application. This method is used for the bidirectional communication.
 162          *
 163          * @since    2.0
 164          *
 165          * @return       An error code
 166          * @param[in]     pLocalMessagePort    The local message port
 167          * @param[in]     pMessage            A pointer to an argument map of key (String) and value (String or ByteBuffer) pair @n
 168          *                                                                        The recommended message size is under 4KB.
 169          * @exception     E_SUCCESS           The method is successful.
 170          * @exception     E_INVALID_ARG       Either of the following conditions has occurred: @n
 171          *                                                                        - The local message port is @c null. @n
 172          *                                                                        - The message argument is not a map of key (String) and value (String or ByteBuffer) pair.
 173          * @exception     E_OBJ_NOT_FOUND     The message port of the target application is not found.
 174          * @exception     E_MAX_EXCEEDED      The size of @c pMessage has exceeded the maximum limit.
 175          * @exception     E_SYSTEM            The method has failed due to a severe system error.
 176          * @remarks       The recommended message size is under 4KB because severe system performance degradation may occur for large messages. @c E_MAX_EXCEEDED may be returned for messages over 4KB size.
 177          */
 178         result SendMessage(const LocalMessagePort* pLocalMessagePort, const Tizen::Base::Collection::IMap* pMessage);
 179
 180 private:
 181         /**
 182         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 183         */
 184         RemoteMessagePort(void);
 185
 186         /**
 187         * This destructor is intentionally declared as private so that only the platform can delete an instance.
 188         */
 189         virtual ~RemoteMessagePort(void);
 190
 191         /**
 192         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 193         */
 194         RemoteMessagePort(const RemoteMessagePort& localMessagePort);
 195
 196         /**
 197         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 198         */
 199         RemoteMessagePort& operator =(const RemoteMessagePort& localMessagePort);
 200
 201
 202         friend class _RemoteMessagePortImpl;
 203
 204         class _RemoteMessagePortImpl * __pRemoteMessagePortImpl;
 205
 206 }; // RemoteMessagePort
 207
 208 } } // Tizen::Io
 209
 210 #endif //_FIO_REMOTE_MESSAGE_PORT_H_