inc/FNetNetConnection.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 /**
  19  * @file                FNetNetConnection.h
  20  * @brief               This is the header file for the %NetConnection class.
  21  *
  22  * This header file contains the declarations of the %NetConnection class.
  23  */
  24 #ifndef _FNET_NET_CONNECTION_H_
  25 #define _FNET_NET_CONNECTION_H_
  26
  27 #include <FBase.h>
  28 #include <FNetNetTypes.h>
  29 #include <FNetNetConnectionInfo.h>
  30 #include <FNetINetConnectionEventListener.h>
  31
  32 namespace Tizen { namespace Net
  33 {
  34 class _NetConnectionImpl;
  35
  36 /**
  37  * @class       NetConnection
  38  * @brief       This class provides methods for all the network connections.
  39  *
  40  * @since       2.0
  41  *
  42  * The %NetConnection class provides methods for managing the connections for data communication.
  43  *
  44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/managing_network_connections.htm">Managing Network Connections</a>.
  45  *
  46  * The following example demonstrates how to use the %NetConnection class.
  47  *
  48  * @code
  49  *
  50  *      #include <FBase.h>
  51  *      #include <FNet.h>
  52  *
  53  *      using namespace Tizen::Base;
  54  *      using namespace Tizen::Net;
  55  *
  56  *      class MyClass
  57  *        : public Object
  58  *        , public INetConnectionEventListener
  59  *      {
  60  *         public:
  61  *                MyClass(void) {}
  62  *                ~MyClass(void) {}
  63  *
  64  *              void OnNetConnectionStarted(NetConnection& netConnection, result r)
  65  *              {
  66  *                      AppLog("OnStarted result=[%s]\n", GetErrorMessage(r));
  67  *              }
  68  *
  69  *              void OnNetConnectionStopped(NetConnection& netConnection, result r)
  70  *              {
  71  *                      AppLog("OnStopped\n");
  72  *              }
  73  *
  74  *              void OnNetConnectionSuspended(NetConnection& netConnection)
  75  *              {
  76  *                      AppLog("OnSuspended\n");
  77  *              }
  78  *
  79  *              void OnNetConnectionResumed(NetConnection& netConnection)
  80  *              {
  81  *                      AppLog("OnResumed\n");
  82  *              }
  83  *
  84  *              void StartNetConnection(void);
  85  *      };
  86  *
  87  *      void
  88  *      MyClass::StartNetConnection(void)
  89  *      {
  90  *              NetAccountManager netAccountManager;
  91  *              result r = netAccountManager.Construct();
  92  *              if (IsFailed(r))
  93  *              {
  94  *                      return;
  95  *              }
  96  *
  97  *              NetAccountId accountId = netAccountManager.GetNetAccountId(NET_BEARER_PS);
  98  *
  99  *              NetConnection* pNetConnection = new NetConnection();
 100  *              r = pNetConnection->Construct(accountId);
 101  *              if (IsFailed(r))
 102  *              {
 103  *                      delete pNetConnection;
 104  *                      return;
 105  *              }
 106  *
 107  *              r = pNetConnection->AddNetConnectionListener(*this);
 108  *              r = pNetConnection->Start();
 109  *
 110  *              // Wait OnNetConnectionStarted() event
 111  *
 112  *              delete pNetConnection;
 113  *      }
 114  *
 115  * @endcode
 116  */
 117 class _OSP_EXPORT_ NetConnection
 118         : public Tizen::Base::Object
 119 {
 120 public:
 121         /**
 122          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 123          *
 124          * @since               2.0
 125          *
 126          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 127          */
 128         NetConnection(void);
 129
 130         /**
 131          * This destructor overrides Tizen::Base::Object::~Object().
 132          *
 133          * @since       2.0
 134          */
 135         virtual ~NetConnection(void);
 136
 137         /**
 138          * Initializes this instance of %NetConnection with the specified parameter. @n
 139          * It automatically binds @c netAccountId with %NetConnection. This method registers an application for receiving the network connection events. @n
 140          * A network connection is based on a configured network account for starting the connection. In order to start the network connection, create a new
 141          * network account or obtain the information of an existing network account, and call the Start() method.
 142          *
 143          * @since                       2.0
 144          *
 145          * @return                      An error code
 146          * @param[in]           netAccountId            The index of the network account to which this %NetConnection is bound
 147          * @exception           E_SUCCESS                       The method is successful.
 148          * @exception           E_MAX_EXCEEDED          Unable to setup a new connection due to too many existing connections.
 149          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 150          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 151          * @exception           E_INVALID_ACCOUNT       The specified network account ID is invalid.
 152          * @exception           E_SYSTEM                        An internal error has occurred.
 153          * @exception           E_INVALID_PROXY         The proxy address is invalid.
 154          * @remarks                     If the application gets the last result by E_INVALID_PROXY, it must use a warning pop-up to notify the user.
 155          */
 156         result Construct(NetAccountId netAccountId);
 157
 158 public:
 159         /**
 160          * Adds a listener to %NetConnection. @n
 161          * The added listener can listen to events when they are fired.
 162          *
 163          * @since               2.0
 164          *
 165          * @param[in]   listener                                A reference to INetConnectionEventListener
 166          * @return              An error code
 167          * @exception   E_SUCCESS                               The method is successful.
 168          * @exception   E_INVALID_STATE                 This instance may be closed.
 169          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 170          * @exception   E_OBJ_ALREADY_EXIST             The listener is already added.
 171          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, @n
 172          *                                                                              because the caller thread is a worker thread.
 173          */
 174         result AddNetConnectionListener(INetConnectionEventListener& listener);
 175
 176         /**
 177          * Removes the specified INetConnectionEventListener instance.
 178          *
 179          * @since               2.0
 180          *
 181          * @param[in]   listener                                A reference to INetConnectionEventListener
 182          * @return              An error code
 183          * @exception   E_SUCCESS                               The method is successful.
 184          * @exception   E_INVALID_STATE                 This instance may be closed.
 185          * @exception   E_OBJ_NOT_FOUND                 The eventListener is not found.
 186          */
 187         result RemoveNetConnectionListener(INetConnectionEventListener& listener);
 188
 189         /**
 190          * Starts the network connection.
 191          *
 192          * @since               2.0
 193          *
 194          * @privlevel   public
 195          * @privilege   %http://tizen.org/privilege/network.connection
 196          *
 197          * @return              An error code
 198          * @exception   E_SUCCESS                               The method is successful.
 199          * @exception   E_INVALID_STATE                 This instance may be closed.
 200          * @exception   E_INVALID_ACCOUNT               The specified network account ID is invalid.
 201          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 202          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 203          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 204          * @exception   E_SERVICE_LIMITED               A connection is already active. Therefore, cannot setup a co-existing network connection.
 205          * @exception   E_SYSTEM                                An internal error has occurred.
 206          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 207          * @remarks             When the network is available, after calling this method, the INetConnectionEventListener::OnNetConnectionStarted() method of the registered
 208          *                              INetConnectionEventListener instance is called.
 209          * @see                 Stop()
 210          */
 211         result Start(void);
 212
 213         /**
 214          * Stops the network connection.
 215          *
 216          * @since               2.0
 217          *
 218          * @privlevel   public
 219          * @privilege   %http://tizen.org/privilege/network.connection
 220          *
 221          * @return              An error code
 222          * @exception   E_SUCCESS                               The method is successful.
 223          * @exception   E_INVALID_STATE                 This instance may be closed.
 224          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 225          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 226          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 227          * @exception   E_SYSTEM                                An internal error has occurred.
 228          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 229          * @remarks             This method stops the network connection of an application. Additionally, it does not ensure immediate disconnection of the network
 230          *                              service (for example, 3G data service or Wi-Fi). The network service remains active till all the applications stop using the network
 231          *                              connection. Once stopped, the network connection can be restarted using the Start() method.
 232          * @see                 Start()
 233          * @see                 Close()
 234          */
 235         result Stop(void);
 236
 237         /**
 238          * Closes the network connection. @n
 239          * All the resources associated with the network connection are freed. This is a forced operation. The Close() method disconnects the network connection
 240          * with a remote server or gateway.
 241          *
 242          * @since               2.0
 243          *
 244          * @privlevel   public
 245          * @privilege   %http://tizen.org/privilege/network.connection
 246          *
 247          * @return              An error code
 248          * @exception   E_SUCCESS                               The method is successful.
 249          * @exception   E_INVALID_STATE                 This instance may be closed.
 250          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 251          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 252          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 253          * @exception   E_SYSTEM                                An internal error has occurred.
 254          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 255          * @remarks             This method stops the network connection of an application. Additionally, it does not ensure immediate disconnection of the network
 256          *                              service (for example, 3G data service or Wi-Fi). The network service remains active till all the applications stop using the network
 257          *                              connection.
 258          * @see                 Stop()
 259          */
 260         result Close(void);
 261
 262         /**
 263          * Gets the network account ID of this instance. @n
 264          * This ID is used to establish a network connection with a remote server or gateway.
 265          *
 266          * @since               2.0
 267          *
 268          * @return              The NetAccountId of this %NetConnection which is bound at Construct(), @n
 269          *                              else @c INVALID_HANDLE if %NetConnection is invalid or not constructed
 270          * @exception   E_SUCCESS                       The method is successful.
 271          * @exception   E_INVALID_STATE         This instance may be closed.
 272          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 273          */
 274         NetAccountId GetNetAccountId(void) const;
 275
 276         /**
 277          * Gets the network connection information.
 278          *
 279          * @since               2.0
 280          *
 281          * @return              A NetConnectionInfo instance specifying information on this network connection
 282          * @exception   E_SUCCESS                               The method is successful.
 283          * @exception   E_INVALID_STATE                 This instance may be closed.
 284          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 285          * @exception   E_ILLEGAL_ACCESS                The access is denied.
 286          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 287          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 288          * @exception   E_SYSTEM                                An internal error has occurred.
 289          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 290          * @remarks             This method requires a NetConnectionInfo instance reference. The network connection information is only available when the network
 291          *                              connection is "Active". For other states, this method returns @c null.
 292          * @warning     Do not delete the returned NetConnectionInfo instance. This instance directly references the internal connection information of
 293          *                              %NetConnection.
 294          */
 295         const NetConnectionInfo* GetNetConnectionInfo(void) const;
 296
 297         /**
 298          * @if OSPDEPREC
 299          * Gets the connection information for the specified account.
 300          *
 301          * @brief <i> [Deprecated] </i>
 302          * @deprecated This method is deprecated because it is moved to the NetConnectionManager class.
 303          * @since       2.0
 304          *
 305          * @return              A NetConnectionInfo instance specifying information on this network connection, @n
 306          *                              else @c null in case of an error or if an active connection is not found
 307          * @param[in]   netAccountId            The network account
 308          * @exception   E_SUCCESS                       The method is successful.
 309          * @exception   E_INVALID_ACCOUNT       The specified network account ID is invalid.
 310          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 311          * @exception   E_SYSTEM                        An internal error has occurred.
 312          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 313          * @endif
 314          */
 315         static NetConnectionInfo* GetNetConnectionInfoN(NetAccountId netAccountId);
 316
 317         /**
 318          * @if OSPDEPREC
 319          * Gets a list of all the connection information used by the system.
 320          *
 321          * @brief <i> [Deprecated] </i>
 322          * @deprecated  This method is deprecated because it is moved to the NetConnectionManager class.
 323          * @since       2.0
 324          *
 325          * @return              A Tizen::Base::Collection::IList containing indexes to NetConnectionInfo in the network, @n
 326          *                              else @c null in case of an error or if an active connection is not found
 327          * @exception   E_SUCCESS                       The method is successful.
 328          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 329          * @exception   E_SYSTEM                        An internal error has occurred (baseband or system).
 330          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 331          * @endif
 332          */
 333         static Tizen::Base::Collection::IList* GetAllNetConnectionInfoN(void);
 334
 335
 336         /**
 337          * Gets the state of the network connection.
 338          *
 339          * @since               2.0
 340          *
 341          * @return              The state of the network connection
 342          * @exception   E_SUCCESS                               The method is successful.
 343          * @exception   E_INVALID_STATE                 This instance may be closed.
 344          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 345          */
 346         NetConnectionState GetConnectionState(void) const;
 347
 348 private:
 349         /**
 350          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 351          *
 352          * @param[in]   value                   An instance of %NetConnection
 353          */
 354         NetConnection(const NetConnection& rhs);
 355
 356         /**
 357          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 358          *
 359          * @param[in]   rhs                             An instance of %NetConnection
 360          */
 361         NetConnection& operator =(const NetConnection& rhs);
 362
 363 private:
 364         _NetConnectionImpl* __pNetConnectionImpl;
 365
 366         friend class _NetConnectionImpl;
 367 }; // NetConnection
 368
 369 } } //Tizen::Net
 370
 371 #endif // _FNET_NET_CONNECTION_H_