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