inc/FIoRemoteMessagePort.h

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