e1b9c37f4d7ff0608b3c8bbe7f77b43a9421b988
[platform/framework/native/appfw.git] / 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_