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          * @feature                     %http://tizen.org/feature/network.telephony
  92          *
  93          * @return                      The @c NetAccountId assigned by the creation of a new network account, @n
  94          *                                      else @c INVALID_HANDLE if an error occurs
  95          * @param[in,out]       netAccountInfo          A NetAccountInfo instance containing network information to create an account
  96          * @exception           E_SUCCESS                       The method is successful.
  97          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
  98          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
  99          * @exception           E_MAX_EXCEEDED          The registry is full. @n Cannot create a new network account.
 100          * @exception           E_SYSTEM                        An internal error has occurred.
 101          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 102          * @exception           E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 103          *                                              For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 104          * @remarks
 105          *                                      - 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
 106          *                                              account. If @c INVALID_HANDLE is returned, the specific error code can be accessed using the GetLastResult() method. A Wi-Fi account
 107          *                                              cannot be created using %NetAccountManager.
 108          *                                      - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 109          * @see                         GetNetAccountInfoN()
 110          * @see                         UpdateNetAccount()
 111          * @see                         DeleteNetAccount()
 112          */
 113         NetAccountId CreateNetAccount(NetAccountInfo& netAccountInfo);
 114
 115         /**
 116          * Deletes a network account from the registry. @n
 117          * If the account is read-only or in service, the deletion fails. The Wi-Fi accounts cannot be deleted by %NetAccountManager.
 118          *
 119          * @since               2.0
 120          *
 121          * @privlevel   public
 122          * @privilege   %http://tizen.org/privilege/network.account
 123          *
 124          * @return              An error code
 125          * @param[in]   netAccountId            A NetAccountId instance containing valid account information
 126          * @exception   E_SUCCESS                       The method is successful.
 127          * @exception   E_INVALID_ACCOUNT       The specified network account is invalid.
 128          * @exception   E_INVALID_OPERATION     This operation is not allowed on this network account instance.
 129          * @exception   E_SYSTEM                        An internal error has occurred.
 130          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 131          * @remarks             If the network account is created by another application, this method fails.
 132          *                              This method must use a warning pop-up to notify the user.
 133          * @see                 CreateNetAccount()
 134          * @see                 GetNetAccountInfoN()
 135          * @see                 UpdateNetAccount()
 136          */
 137         result DeleteNetAccount(NetAccountId netAccountId);
 138
 139         /**
 140          * Updates an existing network account.
 141          *
 142          * @since                       2.0
 143          *
 144          * @privlevel           public
 145          * @privilege           %http://tizen.org/privilege/network.account
 146          * @feature                     %http://tizen.org/feature/network.telephony
 147          *
 148          * @return                      An error code
 149          * @param[in]           netAccountInfo          A NetAccountInfo instance containing network information to update an account
 150          * @exception           E_SUCCESS                       The method is successful.
 151          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 152          * @exception           E_INVALID_ACCOUNT       The input is invalid.
 153          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 154          * @exception           E_SYSTEM                        An internal error has occurred.
 155          * @exception           E_INVALID_OPERATION     This operation is not allowed on this network account instance.
 156          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 157          * @exception           E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 158          *                                              For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 159          * @remarks
 160          *                                      - This method fails if the network account is read-only, in service, or created by another application.
 161          *                                              A Wi-Fi account cannot be updated using %NetAccountManager.
 162          *                                              This method must use a warning pop-up to notify the user.
 163          *                                      - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 164          * @see                         CreateNetAccount()
 165          * @see                         GetNetAccountInfoN()
 166          * @see                         UpdateNetAccount()
 167          * @see                         DeleteNetAccount()
 168          */
 169         result UpdateNetAccount(const NetAccountInfo& netAccountInfo);
 170
 171         /**
 172          * Updates an existing system network account.
 173          *
 174          * @since       2.0
 175          *
 176          * @privlevel   platform
 177          * @privilege   %http://tizen.org/privilege/networkmanager
 178          * @feature             %http://tizen.org/feature/network.telephony for the NET_BEARER_PS value and @n
 179          *                              %http://tizen.org/feature/network.telephony.mms for the NET_BEARER_MMS value of @c netAccountInfo.GetBearerType()
 180          *
 181          * @return      An error code
 182          * @param[in]   netAccountInfo         A NetAccountInfo instance containing network information to update an account
 183          * @exception   E_SUCCESS              The method is successful.
 184          * @exception   E_INVALID_ARG          The specified input parameter is invalid.
 185          * @exception   E_INVALID_ACCOUNT      The input account ID is invalid.
 186          * @exception   E_OPERATION_FAILED     This request operation has failed due to an internal error.
 187          * @exception   E_PRIVILEGE_DENIED     The application does not have the privilege to call this method.
 188          * @exception   E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 189          *                                      For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 190          * @remarks             Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 191          * @see         GetNetAccountInfoN()
 192          * @see                 UpdateNetAccount()
 193          */
 194         result UpdateSystemNetAccount(const NetAccountInfo& netAccountInfo);
 195
 196         /**
 197          * Gets the information on a network account.
 198          *
 199          * @since                       2.0
 200          *
 201          * @return                      A NetAccountInfo instance containing account information
 202          * @param[in]           netAccountId            The account ID whose information is required
 203          * @exception           E_SUCCESS                       The method is successful.
 204          * @exception           E_INVALID_ACCOUNT       The specified network account is invalid.
 205          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 206          * @exception           E_SYSTEM                        An internal error has occurred.
 207          * @exception           E_INVALID_OPERATION     This operation is not allowed on this network account instance.
 208          * @exception           E_INVALID_PROXY         The proxy address is invalid.
 209          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 210          * @remarks                     This method returns:
 211          *                                      - the NetAccountInfo instance for a PS account (NET_BEARER_PS) @n
 212          *                                      - the WifiNetAccountInfo instance for a WLAN account (NET_BEARER_WIFI) in the %NetAccountInfo type @n
 213          *                                      The Wi-Fi account info contains the default %NetAccountInfo and additional Wi-Fi specific information. @n
 214          *                                      To determine the type of instance returned, use the GetBearerType() method.
 215          *                                      The instance can then be cast down to %WifiNetAccountInfo and used in a NET_BEARER_WIFI case. If the
 216          *                                      application gets the last result by E_INVALID_PROXY, it must use a warning pop-up to notify the user.
 217          * @see                         CreateNetAccount()
 218          * @see                         UpdateNetAccount()
 219          * @see                         DeleteNetAccount()
 220          */
 221         NetAccountInfo* GetNetAccountInfoN(NetAccountId netAccountId) const;
 222
 223         /**
 224          * Gets a list of all the accounts in the registry.
 225          *
 226          * @since               2.0
 227          *
 228          * @return      A Tizen::Base::Collection::IList with NetAccoundIds, which are 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_SYSTEM                        An internal error has occurred.
 232          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 233          */
 234         Tizen::Base::Collection::IListT <NetAccountId>* GetNetAccountIdsN(void) const;
 235
 236         /**
 237          * Gets a list of names of all the registered accounts.
 238          *
 239          * @since               2.0
 240          *
 241          * @return              A Tizen::Base::Collection::IList containing the indexes to the NetAccountInfos in the registry
 242          * @exception   E_SUCCESS                       The method is successful.
 243          * @exception   E_OBJ_NOT_FOUND         The NetAccountInfo is not found in the registry.
 244          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 245          * @exception   E_SYSTEM                        An internal error has occurred (baseband or system).
 246          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 247          */
 248         Tizen::Base::Collection::IList* GetNetAccountNamesN(void) const;
 249
 250         /**
 251          * Gets a network account, which has the specified name.
 252          *
 253          * @since               2.0
 254          *
 255          * @return              The NetAccountID with the specified name, @n
 256          *                              else @c INVALID_HANDLE in case of an error or if NetAccountInfo is not found
 257          * @param[in]   netAccountName          The network account name to search for
 258          * @exception   E_SUCCESS                       The method is successful.
 259          * @exception   E_INVALID_ARG           The specified @c netAccountName is invalid or NetAccountInfo with this name does not exist.
 260          * @exception   E_SYSTEM                        An internal error has occurred.
 261          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 262          */
 263         NetAccountId GetNetAccountId(const Tizen::Base::String& netAccountName) const;
 264
 265         /**
 266          * Gets a network account, which is set for the Tizen application on each bearer.
 267          *
 268          * @since               2.0
 269          *
 270          * @feature             %http://tizen.org/feature/network.telephony for the NET_BEARER_PS value and @n
 271          *                              %http://tizen.org/feature/network.wifi for the NET_BEARER_WIFI value and @n
 272          *                              %http://tizen.org/feature/network.wifi,direct for the NET_BEARER_WIFI_DIRECT value and @n
 273          *                              %http://tizen.org/feature/usb.host for the NET_BEARER_USB value and @n
 274          *                              %http://tizen.org/feature/network.telephony.mms for the NET_BEARER_MMS value of @c netBearerType
 275          *
 276          * @return              The network account, @n
 277          *                              else INVALID_HANDLE in case of an error or if NetAccountInfo is not found
 278          * @param[in]   netBearerType           The network account type of bearer
 279          * @exception   E_SUCCESS                       The method is successful.
 280          * @exception   E_SYSTEM                        An internal error has occurred (baseband).
 281          * @exception   E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 282          *                                      For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 283          * @remarks
 284          *                              - The specific error code can be accessed using the GetLastResult() method.
 285          *                              - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 286          */
 287         NetAccountId GetNetAccountId(NetBearerType netBearerType = NET_BEARER_PS) const;
 288
 289         /**
 290          * Gets a network account, which is set for the application like email, IM, and so on.
 291          *
 292          * @since               2.0
 293          *
 294          * @privlevel   partner
 295          * @privilege   %http://tizen.org/privilege/customnetaccount
 296          * @feature             %http://tizen.org/feature/network.telephony for the L"Internet" value and @n
 297          *                              %http://tizen.org/feature/network.telephony.mms for the L"Mms" value of @c netProfileName
 298          *
 299          * @return              The @c NetAccountID with the specified name, @n
 300          *                              else INVALID_HANDLE is returned in case of an error or if %NetAccountInfo is not found
 301          * @param[in]   netProfileName          The network profile name for an application such as email
 302          * @exception   E_SUCCESS                       The method is successful.
 303          * @exception   E_INVALID_ARG           The @c netAccountName is invalid or %NetAccountInfo with this name does not exist.
 304          * @exception   E_SYSTEM                        An internal error has occurred.
 305          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 306          * @exception   E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 307          *                                      For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 308          * @remarks
 309          *                              - The specific error code can be accessed using the GetLastResult() method.
 310          *                              - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 311          */
 312         NetAccountId GetAppNetAccountId(const Tizen::Base::String& netProfileName) const;
 313
 314         /**
 315          * Sets the application-wise default account ID to the one specified by the input argument value.
 316          *
 317          * @since           2.0
 318          *
 319          * @privlevel           partner
 320          * @privilege           %http://tizen.org/privilege/customnetaccount
 321          *
 322          * @return                      An error code
 323          * @param[in]           netAccountId            The network account ID
 324          * @exception           E_SUCCESS                       The method is successful.
 325          * @exception           E_INVALID_ARG           The specified @c netAccountId is invalid.
 326          * @exception           E_SYSTEM                        An internal error has occurred.
 327          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 328          */
 329         result SetNetAccountId(NetAccountId netAccountId);
 330
 331         /**
 332          * @if OSPDEPREC
 333          * Gets the preferred network.
 334          *
 335          * @brief <i> [Deprecated] </i>
 336          * @deprecated This method is deprecated because it is moved to the NetConnectionManager class.
 337          * @since               2.0
 338          *
 339          * @return              The preferred network, @n
 340          *                              else @c NET_WIFI_FIRST in case of an error or if the preferred network is not set
 341          * @exception   E_SUCCESS                       The method is successful.
 342          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 343          * @endif
 344          */
 345         NetPreferenceType GetNetPreference(void) const;
 346
 347         /**
 348          * @if OSPDEPREC
 349          * Sets the preferred network.
 350          *
 351          * @brief <i> [Deprecated] </i>
 352          * @deprecated          This method is deprecated because it is moved to the NetConnectionManager class.
 353          * @since                       2.0
 354          *
 355          * @privlevel           public
 356          * @privilege           %http://tizen.org/privilege/network.connection
 357          * @feature                     %http://tizen.org/feature/network.wifi for the NET_WIFI_ONLY value and @n
 358          *                                      %http://tizen.org/feature/network.telephony for the NET_PS_ONLY value of @c netPreference
 359          *
 360          * @return                      An error code
 361          * @param[in]           netPreference           The preferred network
 362          * @exception           E_SUCCESS                       The method is successful.
 363          * @exception           E_INVALID_OPERATION     This operation is not allowed.
 364          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 365          * @exception           E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 366          *                                              For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 367          * @remarks
 368          *                                      - If this method is not used, the default connection works in the Wi-Fi first mode.
 369          *                                      - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 370          * @endif
 371          */
 372         result SetNetPreference(NetPreferenceType netPreference = NET_WIFI_FIRST);
 373
 374 private:
 375         /*
 376          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 377          *
 378          * @param[in]   rhs                     An instance of %NetAccountManager
 379          */
 380         NetAccountManager(const NetAccountManager& rhs);
 381
 382         /*
 383          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 384          *
 385          * @param[in]   rhs An instance of %NetAccountManager
 386          */
 387         NetAccountManager& operator =(const NetAccountManager& rhs);
 388
 389 private:
 390         _NetAccountManagerImpl* __pNetAccountManagerImpl;
 391
 392         friend class _NetAccountManagerImpl;
 393 }; // NetAccountManager
 394
 395 } } //Tizen::Net
 396 #endif // _FNET_NET_ACCOUNT_MANAGER_H_