inc/FNetNetAccountManager.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                FNetNetAccountManager.h
  20  * @brief               This is the header file for the %NetAccountManager class.
  21  *
  22  * This header file contains the declarations of the %NetAccountManager class.
  23  */
  24 #ifndef _FNET_NET_ACCOUNT_MANAGER_H_
  25 #define _FNET_NET_ACCOUNT_MANAGER_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseObject.h>
  29 #include <FBaseResult.h>
  30 #include <FBaseColIList.h>
  31 #include <FBaseColArrayList.h>
  32 #include <FBaseColArrayListT.h>
  33 #include <FNetNetTypes.h>
  34 #include <FNetNetAccountInfo.h>
  35
  36 namespace Tizen { namespace Net
  37 {
  38 class _NetAccountManagerImpl;
  39
  40 /**
  41  * @class       NetAccountManager
  42  * @brief       This class provides methods for creating, deleting, and administering network accounts in the system.
  43  *
  44  * @since       2.0
  45  *
  46  * The %NetAccountManager class provides methods for creating, deleting, and administering components that can be used for configuring the
  47  * network accounts. These accounts can then be used for connecting to the network.
  48  *
  49  * For more information on the class features, see
  50  * <a href="../org.tizen.native.appprogramming/html/guide/net/network_accounts.htm">Network Accounts</a>.
  51  */
  52 class _OSP_EXPORT_ NetAccountManager
  53         : public Tizen::Base::Object
  54 {
  55 public:
  56         /**
  57          * 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.
  58          *
  59          * @since               2.0
  60          *
  61          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
  62          */
  63         NetAccountManager(void);
  64
  65         /**
  66          * This destructor overrides Tizen::Base::Object::~Object().
  67          *
  68          * @since               2.0
  69          */
  70         virtual ~NetAccountManager(void);
  71
  72         /**
  73          * Initializes this instance of %NetAccountManager.
  74          *
  75          * @since               2.0
  76          *
  77          * @return              An error code
  78          * @exception   E_SUCCESS                       The method is successful.
  79          * @exception   E_SYSTEM                        An internal initialization procedure has failed.
  80          */
  81         result Construct(void);
  82
  83 public:
  84         /**
  85          * Creates a new network account.
  86          *
  87          * @since                       2.0
  88          *
  89          * @privlevel           public
  90          * @privilege           http://tizen.org/privilege/network.account
  91          *
  92          * @return                      The @c NetAccountId assigned by the creation of a new network account, @n
  93          *                                      else @c INVALID_HANDLE if an error occurs
  94          * @param[in,out]       netAccountInfo          A NetAccountInfo instance containing network information to create an account
  95          * @exception           E_SUCCESS                       The method is successful.
  96          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
  97          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
  98          * @exception           E_MAX_EXCEEDED          The registry is full. @n Cannot create a new network account.
  99          * @exception           E_SYSTEM                        An internal error has occurred.
 100          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 101          * @remarks                     This method creates a new network account and returns a @c NetAccountId value that can be used in method calls later to operate on the
 102          *                                      account. If @c INVALID_HANDLE is returned, the specific error code can be accessed using the GetLastResult() method. A Wi-Fi account
 103          *                                      cannot be created using %NetAccountManager.
 104          * @see                         GetNetAccountInfoN()
 105          * @see                         UpdateNetAccount()
 106          * @see                         DeleteNetAccount()
 107          */
 108         NetAccountId CreateNetAccount(NetAccountInfo& netAccountInfo);
 109
 110         /**
 111          * Deletes a network account from the registry. @n
 112          * If the account is read-only or in service, the deletion fails. The Wi-Fi accounts cannot be deleted by %NetAccountManager.
 113          *
 114          * @since               2.0
 115          *
 116          * @privlevel   public
 117          * @privilege   http://tizen.org/privilege/network.account
 118          *
 119          * @return              An error code
 120          * @param[in]   netAccountId            A NetAccountId instance containing valid account information
 121          * @exception   E_SUCCESS                       The method is successful.
 122          * @exception   E_INVALID_ACCOUNT       The specified network account is invalid.
 123          * @exception   E_INVALID_OPERATION     This operation is not allowed on this network account instance.
 124          * @exception   E_SYSTEM                        An internal error has occurred.
 125          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 126          * @remarks             If the network account is created by another application, this method fails.
 127          *                              This method must use a warning pop-up to notify the user.
 128          * @see                 CreateNetAccount()
 129          * @see                 GetNetAccountInfoN()
 130          * @see                 UpdateNetAccount()
 131          */
 132         result DeleteNetAccount(NetAccountId netAccountId);
 133
 134         /**
 135          * Updates an existing network account.
 136          *
 137          * @since                       2.0
 138          *
 139          * @privlevel           public
 140          * @privilege           http://tizen.org/privilege/network.account
 141          *
 142          * @return                      An error code
 143          * @param[in]           netAccountInfo          A NetAccountInfo instance containing network information to update an account
 144          * @exception           E_SUCCESS                       The method is successful.
 145          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 146          * @exception           E_INVALID_ACCOUNT       The input is invalid.
 147          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 148          * @exception           E_SYSTEM                        An internal error has occurred.
 149          * @exception           E_INVALID_OPERATION     This operation is not allowed on this network account instance.
 150          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 151          * @remarks                     This method fails if the network account is read-only, in service, or created by another application.
 152          *                                      A Wi-Fi account cannot be updated using %NetAccountManager.
 153          *                                      Before calling this method, the user must call GetNetAccountInfoN() to get the latest information in the registry
 154          *                                      and change the desired fields of that information.
 155          *                                      This method must use a warning pop-up to notify the user.
 156          * @see                         CreateNetAccount()
 157          * @see                         GetNetAccountInfoN()
 158          * @see                         UpdateNetAccount()
 159          * @see                         DeleteNetAccount()
 160          */
 161         result UpdateNetAccount(const NetAccountInfo& netAccountInfo);
 162
 163         /**
 164          * Updates an existing system network account.
 165          *
 166          * @since       2.0
 167          *
 168          * @privlevel   platform
 169          * @privilege   http://tizen.org/privilege/networkmanager
 170          *
 171          * @return      An error code
 172          * @param[in]   netAccountInfo         A NetAccountInfo instance containing network information to update an account
 173          * @exception   E_SUCCESS              The method is successful.
 174          * @exception   E_INVALID_ARG          The specified input parameter is invalid.
 175          * @exception   E_INVALID_ACCOUNT      The input account ID is invalid.
 176          * @exception   E_OPERATION_FAILED     This request operation has failed due to an internal error.
 177          * @exception   E_PRIVILEGE_DENIED     The application does not have the privilege to call this method.
 178          * @see         GetNetAccountInfoN()
 179          * @see                 UpdateNetAccount()
 180          */
 181         result UpdateSystemNetAccount(const NetAccountInfo& netAccountInfo);
 182
 183         /**
 184          * Gets the information on a network account.
 185          *
 186          * @since                       2.0
 187          *
 188          * @return                      A NetAccountInfo instance containing account information
 189          * @param[in]           netAccountId            The account ID whose information is required
 190          * @exception           E_SUCCESS                       The method is successful.
 191          * @exception           E_INVALID_ACCOUNT       The specified network account is invalid.
 192          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 193          * @exception           E_SYSTEM                        An internal error has occurred.
 194          * @exception           E_INVALID_OPERATION     This operation is not allowed on this network account instance.
 195          * @exception           E_INVALID_PROXY         The proxy address is invalid.
 196          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 197          * @remarks                     This method returns:
 198          *                                      - the NetAccountInfo instance for a PS account (NET_BEARER_PS) @n
 199          *                                      - the WifiNetAccountInfo instance for a WLAN account (NET_BEARER_WIFI) in the %NetAccountInfo type @n
 200          *                                      The Wi-Fi account info contains the default %NetAccountInfo and additional Wi-Fi specific information. @n
 201          *                                      To determine the type of instance returned, use the GetBearerType() method.
 202          *                                      The instance can then be cast down to %WifiNetAccountInfo and used in a NET_BEARER_WIFI case. If the
 203          *                                      application gets the last result by E_INVALID_PROXY, it must use a warning pop-up to notify the user.
 204          * @see                         CreateNetAccount()
 205          * @see                         UpdateNetAccount()
 206          * @see                         DeleteNetAccount()
 207          */
 208         NetAccountInfo* GetNetAccountInfoN(NetAccountId netAccountId) const;
 209
 210         /**
 211          * Gets a list of all the accounts in the registry.
 212          *
 213          * @since               2.0
 214          *
 215          * @return      An IList with NetAccoundIds, which are in the registry
 216          * @exception   E_SUCCESS                       The method is successful.
 217          * @exception   E_OBJ_NOT_FOUND         The NetAccountInfo is not found in the registry.
 218          * @exception   E_SYSTEM                        An internal error has occurred.
 219          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 220          */
 221         Tizen::Base::Collection::IListT <NetAccountId>* GetNetAccountIdsN(void) const;
 222
 223         /**
 224          * Gets a list of names of all the registered accounts.
 225          *
 226          * @since               2.0
 227          *
 228          * @return              An IList containing the indexes to the NetAccountInfos in the registry
 229          * @exception   E_SUCCESS                       The method is successful.
 230          * @exception   E_OBJ_NOT_FOUND         The NetAccountInfo is not found in the registry.
 231          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 232          * @exception   E_SYSTEM                        An internal error has occurred (baseband or system).
 233          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 234          */
 235         Tizen::Base::Collection::IList* GetNetAccountNamesN(void) const;
 236
 237         /**
 238          * Gets a network account, which has the specified name.
 239          *
 240          * @since               2.0
 241          *
 242          * @return              The NetAccountID with the specified name, @n
 243          *                              else @c INVALID_HANDLE in case of an error or if NetAccountInfo is not found
 244          * @param[in]   netAccountName          The network account name to search for
 245          * @exception   E_SUCCESS                       The method is successful.
 246          * @exception   E_INVALID_ARG           The specified @c netAccountName is invalid or NetAccountInfo with this name does not exist.
 247          * @exception   E_SYSTEM                        An internal error has occurred.
 248          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 249          */
 250         NetAccountId GetNetAccountId(const Tizen::Base::String& netAccountName) const;
 251
 252         /**
 253          * Gets a network account, which is set for the Tizen application on each bearer.
 254          *
 255          * @since               2.0
 256          *
 257          * @return              The network account, @n
 258          *                              else INVALID_HANDLE in case of an error or if NetAccountInfo is not found
 259          * @param[in]   netBearerType           The network account type of bearer
 260          * @exception   E_SUCCESS                       The method is successful.
 261          * @exception   E_SYSTEM                        An internal error has occurred (baseband).
 262          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 263          *                              If INVALID_HANDLE is returned but the last result shows success, @n
 264          *              show a pop-up that asks the user to select the network profile in the Settings menu.
 265          */
 266         NetAccountId GetNetAccountId(NetBearerType netBearerType = NET_BEARER_PS) const;
 267
 268         /**
 269          * Gets a network account, which is set for the application like email, IM, and so on.
 270          *
 271          * @since               2.0
 272          *
 273          * @privlevel   partner
 274          * @privilege   http://tizen.org/privilege/customnetaccount
 275          *
 276          * @return              The @c NetAccountID with the specified name, @n
 277          *                              else INVALID_HANDLE is returned in case of an error or if %NetAccountInfo is not found
 278          * @param[in]   netProfileName          The network profile name for an application such as email
 279          * @exception   E_SUCCESS                       The method is successful.
 280          * @exception   E_INVALID_ARG           The @c netAccountName is invalid or %NetAccountInfo with this name does not exist.
 281          * @exception   E_SYSTEM                        An internal error has occurred.
 282          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 283          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 284          */
 285         NetAccountId GetAppNetAccountId(const Tizen::Base::String& netProfileName) const;
 286
 287         /**
 288          * Sets the application-wise default account ID to the one specified by the input argument value.
 289          *
 290          * @since           2.0
 291          *
 292          * @privlevel           partner
 293          * @privilege           http://tizen.org/privilege/customnetaccount
 294          *
 295          * @return                      An error code
 296          * @param[in]           netAccountId            The network account ID
 297          * @exception           E_SUCCESS                       The method is successful.
 298          * @exception           E_INVALID_ARG           The specified @c netAccountId is invalid.
 299          * @exception           E_SYSTEM                        An internal error has occurred.
 300          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 301          */
 302         result SetNetAccountId(NetAccountId netAccountId);
 303
 304         /**
 305          * @if OSPDEPREC
 306          * Gets the preferred network.
 307          *
 308          * @brief <i> [Deprecated] </i>
 309          * @deprecated This method is deprecated because it is moved to the NetConnectionManager class.
 310          * @since               2.0
 311          *
 312          * @return              The preferred network, @n
 313          *                              else @c NET_WIFI_FIRST in case of an error or if the preferred network is not set
 314          * @exception   E_SUCCESS                       The method is successful.
 315          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 316          * @endif
 317          */
 318         NetPreferenceType GetNetPreference(void) const;
 319
 320         /**
 321          * @if OSPDEPREC
 322          * Sets the preferred network.
 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          * @privlevel           public
 329          * @privilege           http://tizen.org/privilege/network.connection
 330          *
 331          * @return                      An error code
 332          * @param[in]           netPreference           The preferred network
 333          * @exception           E_SUCCESS                       The method is successful.
 334          * @exception           E_INVALID_OPERATION     This operation is not allowed.
 335          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 336          * @remarks                     This preference is not changed during the application life-cycle.
 337          *                                      If this method is not used, the default connection works in the Wi-Fi first mode.
 338          * @endif
 339          */
 340         result SetNetPreference(NetPreferenceType netPreference = NET_WIFI_FIRST);
 341
 342 private:
 343         /*
 344          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 345          *
 346          * @param[in]   rhs                     An instance of %NetAccountManager
 347          */
 348         NetAccountManager(const NetAccountManager& rhs);
 349
 350         /*
 351          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 352          *
 353          * @param[in]   rhs An instance of %NetAccountManager
 354          */
 355         NetAccountManager& operator =(const NetAccountManager& rhs);
 356
 357 private:
 358         _NetAccountManagerImpl* __pNetAccountManagerImpl;
 359
 360         friend class _NetAccountManagerImpl;
 361 }; // NetAccountManager
 362
 363 } } //Tizen::Net
 364 #endif // _FNET_NET_ACCOUNT_MANAGER_H_