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.1 (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. @n
 123          * For full construction, the Construct() method must be called right after calling this constructor.
 124          *
 125          * @since               2.0
 126          */
 127         NetConnection(void);
 128
 129         /**
 130          * This destructor overrides Tizen::Base::Object::~Object().
 131          *
 132          * @since       2.0
 133          */
 134         virtual ~NetConnection(void);
 135
 136         /**
 137          * Initializes this instance of %NetConnection with the specified parameter. @n
 138          * It automatically binds @c netAccountId with %NetConnection. This method registers an application for receiving the network connection events. @n
 139          * A network connection is based on a configured network account for starting the connection. In order to start the network connection, create a new
 140          * network account or obtain the information of an existing network account, and call the Start() method.
 141          *
 142          * @since                       2.0
 143          *
 144          * @return                      An error code
 145          * @param[in]           netAccountId            The index of the network account to which this %NetConnection is bound
 146          * @exception           E_SUCCESS                       The method is successful.
 147          * @exception           E_MAX_EXCEEDED          Unable to setup a new connection due to too many existing connections.
 148          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 149          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 150          * @exception           E_INVALID_ACCOUNT       The specified network account ID is invalid.
 151          * @exception           E_SYSTEM                        An internal error has occurred.
 152          * @exception           E_INVALID_PROXY         The proxy address is invalid.
 153          * @remarks             If the application gets the last result by @c E_INVALID_PROXY, it must use a warning pop-up to notify the user.
 154          */
 155         result Construct(NetAccountId netAccountId);
 156
 157 public:
 158         /**
 159          * Adds a listener to %NetConnection. @n
 160          * The added listener can listen to events when they are fired.
 161          *
 162          * @since               2.0
 163          *
 164          * @param[in]   listener                                A reference to INetConnectionEventListener
 165          * @return              An error code
 166          * @exception   E_SUCCESS                               The method is successful.
 167          * @exception   E_INVALID_STATE                 This instance may be closed.
 168          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 169          * @exception   E_OBJ_ALREADY_EXIST             The listener is already added.
 170          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, @n
 171          *                                                                      because the caller thread is a worker thread.
 172          */
 173         result AddNetConnectionListener(INetConnectionEventListener& listener);
 174
 175         /**
 176          * Removes the specified INetConnectionEventListener instance.
 177          *
 178          * @since               2.0
 179          *
 180          * @param[in]   listener                                A reference to INetConnectionEventListener
 181          * @return              An error code
 182          * @exception   E_SUCCESS                               The method is successful.
 183          * @exception   E_INVALID_STATE                 This instance may be closed.
 184          * @exception   E_OBJ_NOT_FOUND                 The eventListener is not found.
 185          */
 186         result RemoveNetConnectionListener(INetConnectionEventListener& listener);
 187
 188         /**
 189          * Starts the network connection.
 190          *
 191          * @since               2.0
 192          *
 193          * @privlevel   public
 194          * @privilege   %http://tizen.org/privilege/network.connection
 195          *
 196          * @return              An error code
 197          * @exception   E_SUCCESS                               The method is successful.
 198          * @exception   E_INVALID_STATE                 This instance may be closed.
 199          * @exception   E_INVALID_ACCOUNT               The specified network account ID is invalid.
 200          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 201          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 202          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 203          * @exception   E_SERVICE_LIMITED               A connection is already active. Therefore, cannot setup a co-existing network connection.
 204          * @exception   E_SYSTEM                                An internal error has occurred.
 205          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 206          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 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          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 230          * @remarks             This method stops the network connection of an application. Additionally, it does not ensure immediate disconnection of the network
 231          *                              service (for example, 3G data service or Wi-Fi). The network service remains active till all the applications stop using the network
 232          *                              connection. Once stopped, the network connection can be restarted using the Start() method.
 233          * @see                 Start()
 234          * @see                 Close()
 235          */
 236         result Stop(void);
 237
 238         /**
 239          * Closes the network connection. @n
 240          * All the resources associated with the network connection are freed. This is a forced operation. The Close() method disconnects the network connection
 241          * with a remote server or gateway.
 242          *
 243          * @since               2.0
 244          *
 245          * @privlevel   public
 246          * @privilege   %http://tizen.org/privilege/network.connection
 247          *
 248          * @return              An error code
 249          * @exception   E_SUCCESS                               The method is successful.
 250          * @exception   E_INVALID_STATE                 This instance may be closed.
 251          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 252          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 253          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 254          * @exception   E_SYSTEM                                An internal error has occurred.
 255          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 256          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 257          * @remarks             This method stops the network connection of an application. Additionally, it does not ensure immediate disconnection of the network
 258          *                              service (for example, 3G data service or Wi-Fi). The network service remains active till all the applications stop using the network
 259          *                              connection.
 260          * @see                 Stop()
 261          */
 262         result Close(void);
 263
 264         /**
 265          * Gets the network account ID of this instance. @n
 266          * This ID is used to establish a network connection with a remote server or gateway.
 267          *
 268          * @since               2.0
 269          *
 270          * @return              The NetAccountId of this %NetConnection which is bound at Construct(), @n
 271          *                              else @c INVALID_HANDLE if %NetConnection is invalid or not constructed
 272          * @exception   E_SUCCESS                       The method is successful.
 273          * @exception   E_INVALID_STATE         This instance may be closed.
 274          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 275          */
 276         NetAccountId GetNetAccountId(void) const;
 277
 278         /**
 279          * Gets the network connection information.
 280          *
 281          * @since               2.0
 282          *
 283          * @return              A NetConnectionInfo instance specifying information on this network connection
 284          * @exception   E_SUCCESS                               The method is successful.
 285          * @exception   E_INVALID_STATE                 This instance may be closed.
 286          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 287          * @exception   E_ILLEGAL_ACCESS                The access is denied.
 288          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 289          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 290          * @exception   E_SYSTEM                                An internal error has occurred.
 291          * @remarks
 292          *                      - The specific error code can be accessed using the GetLastResult() method.
 293          *                      - This method requires a NetConnectionInfo instance reference. The network connection information is only available when the network
 294          *                      connection is "Active". For other states, this method returns @c null.
 295          * @warning     Do not delete the returned NetConnectionInfo instance. This instance directly references the internal connection information of
 296          *                              %NetConnection.
 297          */
 298         const NetConnectionInfo* GetNetConnectionInfo(void) const;
 299
 300         /**
 301          * @if OSPDEPREC
 302          * Gets the connection information for the specified account.
 303          *
 304          * @brief <i> [Deprecated] </i>
 305          * @deprecated This method is deprecated because it is moved to the NetConnectionManager class.
 306          * @since       2.0
 307          *
 308          * @return              A NetConnectionInfo instance specifying information on this network connection, @n
 309          *                              else @c null in case of an error or if an active connection is not found
 310          * @param[in]   netAccountId            The network account
 311          * @exception   E_SUCCESS                       The method is successful.
 312          * @exception   E_INVALID_ACCOUNT       The specified network account ID is invalid.
 313          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 314          * @exception   E_SYSTEM                        An internal error has occurred.
 315          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 316          * @endif
 317          */
 318         static NetConnectionInfo* GetNetConnectionInfoN(NetAccountId netAccountId);
 319
 320         /**
 321          * @if OSPDEPREC
 322          * Gets a list of all the connection information used by the system.
 323          *
 324          * @brief <i> [Deprecated] </i>
 325          * @deprecated  This method is deprecated because it is moved to the NetConnectionManager class.
 326          * @since       2.0
 327          *
 328          * @return              A Tizen::Base::Collection::IList containing indexes to NetConnectionInfo in the network, @n
 329          *                              else @c null in case of an error or if an active connection is not found
 330          * @exception   E_SUCCESS                       The method is successful.
 331          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 332          * @exception   E_SYSTEM                        An internal error has occurred (baseband or system).
 333          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 334          * @endif
 335          */
 336         static Tizen::Base::Collection::IList* GetAllNetConnectionInfoN(void);
 337
 338
 339         /**
 340          * Gets the state of the network connection.
 341          *
 342          * @since               2.0
 343          *
 344          * @return              The state of the network connection
 345          * @exception   E_SUCCESS                               The method is successful.
 346          * @exception   E_INVALID_STATE                 This instance may be closed.
 347          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 348          */
 349         NetConnectionState GetConnectionState(void) const;
 350
 351 private:
 352         /**
 353          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 354          *
 355          * @param[in]   value                   An instance of %NetConnection
 356          */
 357         NetConnection(const NetConnection& rhs);
 358
 359         /**
 360          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 361          *
 362          * @param[in]   rhs                             An instance of %NetConnection
 363          */
 364         NetConnection& operator =(const NetConnection& rhs);
 365
 366 private:
 367         _NetConnectionImpl* __pNetConnectionImpl;
 368
 369         friend class _NetConnectionImpl;
 370 }; // NetConnection
 371
 372 } } //Tizen::Net
 373
 374 #endif // _FNET_NET_CONNECTION_H_