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