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 or %http://tizen.org/feature/network.telephony.mms
 179          *
 180          * @return      An error code
 181          * @param[in]   netAccountInfo         A NetAccountInfo instance containing network information to update an account
 182          * @exception   E_SUCCESS              The method is successful.
 183          * @exception   E_INVALID_ARG          The specified input parameter is invalid.
 184          * @exception   E_INVALID_ACCOUNT      The input account ID is invalid.
 185          * @exception   E_OPERATION_FAILED     This request operation has failed due to an internal error.
 186          * @exception   E_PRIVILEGE_DENIED     The application does not have the privilege to call this method.
 187          * @exception   E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 188          *                                      For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 189          * @remarks             Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 190          * @see         GetNetAccountInfoN()
 191          * @see                 UpdateNetAccount()
 192          */
 193         result UpdateSystemNetAccount(const NetAccountInfo& netAccountInfo);
 194
 195         /**
 196          * Gets the information on a network account.
 197          *
 198          * @since                       2.0
 199          *
 200          * @return                      A NetAccountInfo instance containing account information
 201          * @param[in]           netAccountId            The account ID whose information is required
 202          * @exception           E_SUCCESS                       The method is successful.
 203          * @exception           E_INVALID_ACCOUNT       The specified network account is invalid.
 204          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 205          * @exception           E_SYSTEM                        An internal error has occurred.
 206          * @exception           E_INVALID_OPERATION     This operation is not allowed on this network account instance.
 207          * @exception           E_INVALID_PROXY         The proxy address is invalid.
 208          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 209          * @remarks                     This method returns:
 210          *                                      - the NetAccountInfo instance for a PS account (NET_BEARER_PS) @n
 211          *                                      - the WifiNetAccountInfo instance for a WLAN account (NET_BEARER_WIFI) in the %NetAccountInfo type @n
 212          *                                      The Wi-Fi account info contains the default %NetAccountInfo and additional Wi-Fi specific information. @n
 213          *                                      To determine the type of instance returned, use the GetBearerType() method.
 214          *                                      The instance can then be cast down to %WifiNetAccountInfo and used in a NET_BEARER_WIFI case. If the
 215          *                                      application gets the last result by E_INVALID_PROXY, it must use a warning pop-up to notify the user.
 216          * @see                         CreateNetAccount()
 217          * @see                         UpdateNetAccount()
 218          * @see                         DeleteNetAccount()
 219          */
 220         NetAccountInfo* GetNetAccountInfoN(NetAccountId netAccountId) const;
 221
 222         /**
 223          * Gets a list of all the accounts in the registry.
 224          *
 225          * @since               2.0
 226          *
 227          * @return      A Tizen::Base::Collection::IList with NetAccoundIds, which are in the registry
 228          * @exception   E_SUCCESS                       The method is successful.
 229          * @exception   E_OBJ_NOT_FOUND         The NetAccountInfo is not found in the registry.
 230          * @exception   E_SYSTEM                        An internal error has occurred.
 231          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 232          */
 233         Tizen::Base::Collection::IListT <NetAccountId>* GetNetAccountIdsN(void) const;
 234
 235         /**
 236          * Gets a list of names of all the registered accounts.
 237          *
 238          * @since               2.0
 239          *
 240          * @return              A Tizen::Base::Collection::IList containing the indexes to the NetAccountInfos in the registry
 241          * @exception   E_SUCCESS                       The method is successful.
 242          * @exception   E_OBJ_NOT_FOUND         The NetAccountInfo is not found in the registry.
 243          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 244          * @exception   E_SYSTEM                        An internal error has occurred (baseband or system).
 245          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 246          */
 247         Tizen::Base::Collection::IList* GetNetAccountNamesN(void) const;
 248
 249         /**
 250          * Gets a network account, which has the specified name.
 251          *
 252          * @since               2.0
 253          *
 254          * @return              The NetAccountID with the specified name, @n
 255          *                              else @c INVALID_HANDLE in case of an error or if NetAccountInfo is not found
 256          * @param[in]   netAccountName          The network account name to search for
 257          * @exception   E_SUCCESS                       The method is successful.
 258          * @exception   E_INVALID_ARG           The specified @c netAccountName is invalid or NetAccountInfo with this name does not exist.
 259          * @exception   E_SYSTEM                        An internal error has occurred.
 260          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 261          */
 262         NetAccountId GetNetAccountId(const Tizen::Base::String& netAccountName) const;
 263
 264         /**
 265          * Gets a network account, which is set for the Tizen application on each bearer.
 266          *
 267          * @since               2.0
 268          *
 269          * @feature             %http://tizen.org/feature/network.telephony, %http://tizen.org/feature/network.telephony.mms, %http://tizen.org/feature/network.wifi, %http://tizen.org/feature/network.wifi.direct, or %http://tizen.org/feature/usb.host
 270          *
 271          * @return              The network account, @n
 272          *                              else INVALID_HANDLE in case of an error or if NetAccountInfo is not found
 273          * @param[in]   netBearerType           The network account type of bearer
 274          * @exception   E_SUCCESS                       The method is successful.
 275          * @exception   E_SYSTEM                        An internal error has occurred (baseband).
 276          * @exception   E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 277          *                                      For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 278          * @remarks
 279          *                              - The specific error code can be accessed using the GetLastResult() method.
 280          *                              - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 281          */
 282         NetAccountId GetNetAccountId(NetBearerType netBearerType = NET_BEARER_PS) const;
 283
 284         /**
 285          * Gets a network account, which is set for the application like email, IM, and so on.
 286          *
 287          * @since               2.0
 288          *
 289          * @privlevel   partner
 290          * @privilege   %http://tizen.org/privilege/customnetaccount
 291          * @feature             %http://tizen.org/feature/network.telephony or %http://tizen.org/feature/network.telephony.mms
 292          *
 293          * @return              The @c NetAccountID with the specified name, @n
 294          *                              else INVALID_HANDLE is returned in case of an error or if %NetAccountInfo is not found
 295          * @param[in]   netProfileName          The network profile name for an application such as email
 296          * @exception   E_SUCCESS                       The method is successful.
 297          * @exception   E_INVALID_ARG           The @c netAccountName is invalid or %NetAccountInfo with this name does not exist.
 298          * @exception   E_SYSTEM                        An internal error has occurred.
 299          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 300          * @exception   E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 301          *                                      For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 302          * @remarks
 303          *                              - The specific error code can be accessed using the GetLastResult() method.
 304          *                              - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 305          */
 306         NetAccountId GetAppNetAccountId(const Tizen::Base::String& netProfileName) const;
 307
 308         /**
 309          * Sets the application-wise default account ID to the one specified by the input argument value.
 310          *
 311          * @since           2.0
 312          *
 313          * @privlevel           partner
 314          * @privilege           %http://tizen.org/privilege/customnetaccount
 315          *
 316          * @return                      An error code
 317          * @param[in]           netAccountId            The network account ID
 318          * @exception           E_SUCCESS                       The method is successful.
 319          * @exception           E_INVALID_ARG           The specified @c netAccountId is invalid.
 320          * @exception           E_SYSTEM                        An internal error has occurred.
 321          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 322          */
 323         result SetNetAccountId(NetAccountId netAccountId);
 324
 325         /**
 326          * @if OSPDEPREC
 327          * Gets the preferred network.
 328          *
 329          * @brief <i> [Deprecated] </i>
 330          * @deprecated This method is deprecated because it is moved to the NetConnectionManager class.
 331          * @since               2.0
 332          *
 333          * @return              The preferred network, @n
 334          *                              else @c NET_WIFI_FIRST in case of an error or if the preferred network is not set
 335          * @exception   E_SUCCESS                       The method is successful.
 336          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 337          * @endif
 338          */
 339         NetPreferenceType GetNetPreference(void) const;
 340
 341         /**
 342          * @if OSPDEPREC
 343          * Sets the preferred network.
 344          *
 345          * @brief <i> [Deprecated] </i>
 346          * @deprecated          This method is deprecated because it is moved to the NetConnectionManager class.
 347          * @since                       2.0
 348          *
 349          * @privlevel           public
 350          * @privilege           %http://tizen.org/privilege/network.connection
 351          * @feature                     %http://tizen.org/feature/network.wifi or %http://tizen.org/feature/network.telephony
 352          *
 353          * @return                      An error code
 354          * @param[in]           netPreference           The preferred network
 355          * @exception           E_SUCCESS                       The method is successful.
 356          * @exception           E_INVALID_OPERATION     This operation is not allowed.
 357          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 358          * @exception           E_UNSUPPORTED_OPERATION The target device does not support the required feature. @b Since: @b 2.1
 359          *                                              For more information, see <a href=../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm>Application Filtering</a>.
 360          * @remarks
 361          *                                      - If this method is not used, the default connection works in the Wi-Fi first mode.
 362          *                                      - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 363          * @endif
 364          */
 365         result SetNetPreference(NetPreferenceType netPreference = NET_WIFI_FIRST);
 366
 367 private:
 368         /*
 369          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 370          *
 371          * @param[in]   rhs                     An instance of %NetAccountManager
 372          */
 373         NetAccountManager(const NetAccountManager& rhs);
 374
 375         /*
 376          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 377          *
 378          * @param[in]   rhs An instance of %NetAccountManager
 379          */
 380         NetAccountManager& operator =(const NetAccountManager& rhs);
 381
 382 private:
 383         _NetAccountManagerImpl* __pNetAccountManagerImpl;
 384
 385         friend class _NetAccountManagerImpl;
 386 }; // NetAccountManager
 387
 388 } } //Tizen::Net
 389 #endif // _FNET_NET_ACCOUNT_MANAGER_H_