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_