Merge "remove wrong link page" into tizen_2.1
[platform/framework/native/appfw.git] / inc / FIoClientChannel.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                FIoClientChannel.h
18  * @brief               This is the header file for the %ClientChannel class.
19  *
20  * This header file contains the declarations of the %ClientChannel class.
21  */
22 #ifndef _FIO_CLIENT_CHANNEL_H_
23 #define _FIO_CLIENT_CHANNEL_H_
24
25 #include <FBaseResult.h>
26 #include <FBaseObject.h>
27 #include <FBaseDataType.h>
28 #include <FAppTypes.h>
29 #include <FIoIChannelResponseEventListener.h>
30
31 namespace Tizen { namespace Io
32 {
33
34 /**
35 * @if OSPDEPREC
36 * @class    ClientChannel
37 * @brief    <i> [Deprecated] </i> This class provides methods for sending a request to another application.
38 *
39 * @deprecated   This class is deprecated. Instead of using this class, use LocalMessagePort, RemoteMessagePort, and MessagePortManager classes.
40 * @since    2.0
41 *
42 * @final        This class is not intended for extension.
43 *
44 * The %ClientChannel class provides methods for sending a request to another application's ServerChannel. To receive a response
45 * for the request, set the ChannelResponseEventListener interface. The instance of %ClientChannel can be retrieved
46 * using ClientChannel::GetInstance().
47 *
48 * The following example demonstrates how to use the %ClientChannel class.
49 *
50 * @code
51 *
52 * #include <FBase.h>
53 * #include <FIo.h>
54 *
55 * using namespace Tizen::Base;
56 * using namespace Tizen::Base::Collection;
57 * using namespace Tizen::Io;
58 * using namespace Tizen::App;
59 *
60 * class MyAppClass
61 *       : public Tizen::Io::IChannelResponseEventListener
62 * {
63 * public:
64 *       result Initialize(void);
65 *       void virtual OnChannelResponseReceivedN(RequestId reqId, Tizen::Io::ClientChannel& clientChannel
66 *                                                                                               , const Tizen::Base::String& serverChannelId
67 *                                                                                               , Tizen::Base::Collection::IList* pArgs);
68 *       void GetOnlineFriends(void);
69 * };
70 *
71 * void
72 * MyAppClass::Initialize(void)
73 * {
74 *       // Sets the channel response event listener.
75 *       ClientChannel::GetInstance()->SetChannelResponseEventListener(this);
76 * }
77 *
78 * void
79 * MyAppClass::OnChannelResponseReceivedN(RequestId reqId, ClientChannel& clientChannel
80 *                                                                               , const String& serverChannelId
81 *                                                                               , IList* pArgs)
82 * {
83 *       // Handles the channel response.
84 *       for(int i = 0; i < pArgs->GetCount(); i++)
85 *       {
86 *               AppLog("pData[%d]=%S", i, ((String*)(pArgs->GetAt(i)))->GetPointer());
87 *       }
88 *
89 *       // Cleans up the arguments.
90 *       pArgs->RemoveAll(true);
91 *       delete pArgs;
92 * }
93 *
94 * void
95 * MyAppClass::GetOnlineFriends(void)
96 * {
97 *       RequestId reqId = 0;
98 *
99 *       ArrayList* pDataList = new ArrayList();
100 *       pDataList->Construct();
101 *
102 *       String* pData = new String(L"GetList");
103 *       String* pData2 = new String(L"Friend");
104 *
105 *       pDataList->Add(*pData);
106 *       pDataList->Add(*pData2);
107 *
108 *       ClientChannel::GetInstance()->SendRequest(L"1234567890.ContactSvc", pDataList, reqId);
109 *
110 *       pDataList->RemoveAll(true);
111 *       delete pDataList;
112 * }
113 *
114 * @endcode
115 * @endif
116 */
117
118 class _OSP_EXPORT_ ClientChannel
119         : public Tizen::Base::Object
120 {
121 public:
122         /**
123         * Gets the default client channel of the application.
124         *
125         * @since 2.0
126         *
127         * @return       A pointer to the %ClientChannel instance, @n
128         *                       else @c null if it fails
129         * @exception    E_SUCCESS           The method is successful.
130         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
131         * @remarks       The specific error code can be accessed using the GetLastResult() method.
132         */
133         static ClientChannel* GetInstance(void);
134
135         /**
136         * Gets the specific client channel of the application.
137         *
138         * @since 2.0
139         *
140         * @return       A pointer to the %ClientChannel instance, @n
141         *                       else @c null if it fails
142         * @param[in]     channelName         The channel name
143         * @exception     E_SUCCESS           The method is successful.
144         * @exception     E_SYSTEM            The method cannot proceed due to a severe system error.
145         * @remarks       The specific error code can be accessed using the GetLastResult() method.
146         */
147         static ClientChannel* GetInstance(const Tizen::Base::String& channelName);
148
149         /**
150         * Sets the response event listener. @n
151         * The listener is called when a response is received. To reset the event listener, @c null must be passed.
152         *
153         * @since 2.0
154         *
155         * @param[in] pResponseListener    The response event listener
156         */
157         void SetChannelResponseEventListener(IChannelResponseEventListener* pResponseListener);
158
159         /**
160          * Sends a request to the specific server channel of an application specified by the serverChannelId.
161          *
162          * @since 2.0
163          *
164          * @return       An error code
165          * @param[in]     serverChannelId    The server channel ID which can be either application ID or appicationID.ChannelName
166          * @param[in]     pArgs               A pointer to an argument list of type String
167          * @param[out]    reqId               The request ID
168          * @exception     E_SUCCESS           The method is successful.
169          * @exception     E_OBJ_NOT_FOUND     The server channel is not found.
170          * @exception     E_SYSTEM            The method cannot proceed due to a severe system error.
171          */
172         result SendRequest(const Tizen::Base::String& serverChannelId, const Tizen::Base::Collection::IList* pArgs, RequestId& reqId);
173
174
175 private:
176         /**
177         * This default constructor is intentionally declared as private to implement the Singleton semantic.
178         */
179         ClientChannel(void);
180
181         /**
182         * This destructor is intentionally declared as private to implement the Singleton semantic.
183         */
184         virtual ~ClientChannel(void);
185
186         /**
187         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
188         */
189         ClientChannel(const ClientChannel& clientChannel);
190
191         /**
192         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
193         */
194         ClientChannel& operator =(const ClientChannel& clientChannel);
195
196         static void InitSingleton(void);
197
198         static void DestroySingleton(void);
199
200         static ClientChannel* __pClientChannelInstance;
201
202         friend class _ClientChannelImpl;
203
204         class _ClientChannelImpl* __pClientChannelImpl;
205
206 }; // ClientChannel
207
208 } } // Tizen::Io
209
210 #endif //_FIO_CLIENT_CHANNEL_H_