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 // Start the network connection.
  51 using namespace Tizen::Net;
  52
  53 void
  54 Test(void)
  55 {
  56         // Account ID
  57         NetAccountId accountId = INVALID_HANDLE;
  58         result r = E_SUCCESS;
  59
  60         // Account manager
  61         NetAccountManager netAccountManager;
  62         r = netAccountManager.Construct();
  63         accountId = netAccountManager.GetNetAccountId();
  64
  65         // Construct a listener.
  66         TestListener* pMyListener = new TestListener();
  67
  68         // NetConnection instance allocation.
  69         NetConnection* pNetConnection = new NetConnection;
  70
  71         // Construct NetConnection.
  72         r = pNetConnection->Construct(accountId);
  73
  74         // __NetConnectionEvent AddListener.
  75         r = pNetConnection->AddNetConnectionListener(pMyListener);
  76
  77         // NetConnection connect.
  78         r = pNetConnection->Start();
  79 }
  80  * @endcode
  81  */
  82 class _OSP_EXPORT_ NetConnection
  83         : public Tizen::Base::Object
  84 {
  85 public:
  86         /**
  87          * 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.
  88          *
  89          * @since               2.0
  90          *
  91          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
  92          */
  93         NetConnection(void);
  94
  95         /**
  96          * This destructor overrides Tizen::Base::Object::~Object().
  97          *
  98          * @since       2.0
  99          */
 100         virtual ~NetConnection(void);
 101
 102         /**
 103          * Initializes this instance of %NetConnection with the specified parameter. @n
 104          * It automatically binds @c netAccountId with %NetConnection. This method registers an application for receiving the network connection events. @n
 105          * A network connection is based on a configured network account for starting the connection. In order to start the network connection, create a new
 106          * network account or obtain the information of an existing network account, and call the Start() method.
 107          *
 108          * @since                       2.0
 109          *
 110          * @return                      An error code
 111          * @param[in]           netAccountId            The index of the network account to which this %NetConnection is bound
 112          * @exception           E_SUCCESS                       The method is successful.
 113          * @exception           E_MAX_EXCEEDED          Unable to setup a new connection due to too many existing connections.
 114          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 115          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 116          * @exception           E_INVALID_ACCOUNT       The specified network account ID is invalid.
 117          * @exception           E_SYSTEM                        An internal error has occurred.
 118          * @exception           E_INVALID_PROXY         The proxy address is invalid.
 119          * @remarks                     If the application gets the last result by E_INVALID_PROXY, it must use a warning pop-up to notify the user.
 120          */
 121         result Construct(NetAccountId netAccountId);
 122
 123 public:
 124         /**
 125          * Adds a listener to %NetConnection. @n
 126          * The added listener can listen to events when they are fired.
 127          *
 128          * @since               2.0
 129          *
 130          * @param[in]   listener                                A reference to INetConnectionEventListener
 131          * @return              An error code
 132          * @exception   E_SUCCESS                               The method is successful.
 133          * @exception   E_INVALID_STATE                 This instance may be closed.
 134          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 135          * @exception   E_OBJ_ALREADY_EXIST             The listener is already added.
 136          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, @n
 137          *                                                                              because the caller thread is a worker thread.
 138          */
 139         result AddNetConnectionListener(INetConnectionEventListener& listener);
 140
 141         /**
 142          * Removes the specified INetConnectionEventListener instance.
 143          *
 144          * @since               2.0
 145          *
 146          * @param[in]   listener                                A reference to INetConnectionEventListener
 147          * @return              An error code
 148          * @exception   E_SUCCESS                               The method is successful.
 149          * @exception   E_INVALID_STATE                 This instance may be closed.
 150          * @exception   E_OBJ_NOT_FOUND                 The eventListener is not found.
 151          */
 152         result RemoveNetConnectionListener(INetConnectionEventListener& listener);
 153
 154         /**
 155          * Starts the network connection.
 156          *
 157          * @since               2.0
 158          *
 159          * @privlevel   public
 160          * @privilege   http://tizen.org/privilege/network.connection
 161          *
 162          * @return              An error code
 163          * @exception   E_SUCCESS                               The method is successful.
 164          * @exception   E_INVALID_STATE                 This instance may be closed.
 165          * @exception   E_INVALID_ACCOUNT               The specified network account ID is invalid.
 166          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 167          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 168          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 169          * @exception   E_SERVICE_LIMITED               A connection is already active. Therefore, cannot setup a co-existing network connection.
 170          * @exception   E_SYSTEM                                An internal error has occurred.
 171          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 172          * @remarks             When the network is available, after calling this method, the OnNetConnectionStarted() method of the registered
 173          *                              INetConnectionEventListener instance is called.
 174          * @see                 Stop()
 175          */
 176         result Start(void);
 177
 178         /**
 179          * Stops the network connection.
 180          *
 181          * @since               2.0
 182          *
 183          * @privlevel   public
 184          * @privilege   http://tizen.org/privilege/network.connection
 185          *
 186          * @return              An error code
 187          * @exception   E_SUCCESS                               The method is successful.
 188          * @exception   E_INVALID_STATE                 This instance may be closed.
 189          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 190          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 191          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 192          * @exception   E_SYSTEM                                An internal error has occurred.
 193          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 194          * @remarks             This method stops the network connection of an application.  Additionally, it does not ensure immediate disconnection of the network
 195          *                              service (for example, 3G data service or Wi-Fi). The network service remains active till all the applications stop using the network
 196          *                              connection. Once stopped, the network connection can be restarted using the Start() method.
 197          * @see                 Start()
 198          * @see                 Close()
 199          */
 200         result Stop(void);
 201
 202         /**
 203          * Closes the network connection. @n
 204          * All the resources associated with the network connection are freed. This is a forced operation. The Close() method disconnects the network connection
 205          * with a remote server or gateway.
 206          *
 207          * @since               2.0
 208          *
 209          * @privlevel   public
 210          * @privilege   http://tizen.org/privilege/network.connection
 211          *
 212          * @return              An error code
 213          * @exception   E_SUCCESS                               The method is successful.
 214          * @exception   E_INVALID_STATE                 This instance may be closed.
 215          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 216          * @exception   E_ILLEGAL_ACCESS                Access is denied to the resources bound to this %NetConnection.
 217          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 218          * @exception   E_SYSTEM                                An internal error has occurred.
 219          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 220          * @remarks             This method stops the network connection of an application. Additionally, it does not ensure immediate disconnection of the network
 221          *                              service (for example, 3G data service or Wi-Fi). The network service remains active till all the applications stop using the network
 222          *                              connection.
 223          * @see                 Stop()
 224          */
 225         result Close(void);
 226
 227         /**
 228          * Gets the network account ID of this instance. @n
 229          * This ID is used to establish a network connection with a remote server or gateway.
 230          *
 231          * @since               2.0
 232          *
 233          * @return              The NetAccountId of this %NetConnection which is bound at Construct(), @n
 234          *                              else @c INVALID_HANDLE if %NetConnection is invalid or not constructed
 235          * @exception   E_SUCCESS                       The method is successful.
 236          * @exception   E_INVALID_STATE         This instance may be closed.
 237          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 238          */
 239         NetAccountId GetNetAccountId(void) const;
 240
 241         /**
 242          * Gets the network connection information.
 243          *
 244          * @since               2.0
 245          *
 246          * @return              A NetConnectionInfo instance specifying information on this network connection
 247          * @exception   E_SUCCESS                               The method is successful.
 248          * @exception   E_INVALID_STATE                 This instance may be closed.
 249          * @exception   E_INVALID_CONNECTION    The network connection is invalid.
 250          * @exception   E_ILLEGAL_ACCESS                The access is denied.
 251          * @exception   E_INVALID_CONTEXT               The context information associated with the network connection account is invalid.
 252          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 253          * @exception   E_SYSTEM                                An internal error has occurred.
 254          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 255          * @remarks             This method requires a NetConnectionInfo instance reference. The network connection information is only available when the network
 256          *                              connection is "Active". For other states, this method returns @c null.
 257          * @warning     Do not delete the returned NetConnectionInfo instance. This instance directly references the internal connection information of
 258          *                              %NetConnection.
 259          */
 260         const NetConnectionInfo* GetNetConnectionInfo(void) const;
 261
 262         /**
 263          * @if OSPDEPREC
 264          * Gets the connection information for the specified account.
 265          *
 266          * @brief <i> [Deprecated] </i>
 267          * @deprecated This method is deprecated because it is moved to the NetConnectionManager class.
 268          * @since       2.0
 269          *
 270          * @return              A NetConnectionInfo instance specifying information on this network connection, @n
 271          *                              else @c null in case of an error or if an active connection is not found
 272          * @param[in]   netAccountId            The network account
 273          * @exception   E_SUCCESS                       The method is successful.
 274          * @exception   E_INVALID_ACCOUNT       The specified network account ID is invalid.
 275          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 276          * @exception   E_SYSTEM                        An internal error has occurred.
 277          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 278          * @endif
 279          */
 280         static NetConnectionInfo* GetNetConnectionInfoN(NetAccountId netAccountId);
 281
 282         /**
 283          * @if OSPDEPREC
 284          * Gets a list of all the connection information used by the system.
 285          *
 286          * @brief <i> [Deprecated] </i>
 287          * @deprecated  This method is deprecated because it is moved to the NetConnectionManager class.
 288          * @since       2.0
 289          *
 290          * @return              An IList containing indexes to NetConnectionInfo in the network, @n
 291          *                              else @c null in case of an error or if an active connection is not found
 292          * @exception   E_SUCCESS                       The method is successful.
 293          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 294          * @exception   E_SYSTEM                        An internal error has occurred (baseband or system).
 295          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 296          * @endif
 297          */
 298         static Tizen::Base::Collection::IList* GetAllNetConnectionInfoN(void);
 299
 300
 301         /**
 302          * Gets the state of the network connection.
 303          *
 304          * @since               2.0
 305          *
 306          * @return              The state of the network connection
 307          * @exception   E_SUCCESS                               The method is successful.
 308          * @exception   E_INVALID_STATE                 This instance may be closed.
 309          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 310          */
 311         NetConnectionState GetConnectionState(void) const;
 312
 313 private:
 314         /**
 315          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 316          *
 317          * @param[in]   value                   An instance of %NetConnection
 318          */
 319         NetConnection(const NetConnection& rhs);
 320
 321         /**
 322          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 323          *
 324          * @param[in]   rhs                             An instance of %NetConnection
 325          */
 326         NetConnection& operator =(const NetConnection& rhs);
 327
 328 private:
 329         _NetConnectionImpl* __pNetConnectionImpl;
 330
 331         friend class _NetConnectionImpl;
 332 }; // NetConnection
 333
 334 } } //Tizen::Net
 335
 336 #endif // _FNET_NET_CONNECTION_H_