inc/FNetWifiWifiManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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  * @file    FNetWifiWifiManager.h
  19  * @brief   This is the header file for the %WifiManager class.
  20  *
  21  * This header file contains the declarations of the %WifiManager class.
  22  */
  23 #ifndef _FNET_WIFI_WIFI_MANAGER_H_
  24 #define _FNET_WIFI_WIFI_MANAGER_H_
  25
  26 #include <FBaseTypes.h>
  27 #include <FBaseResult.h>
  28 #include <FNetWifiWifiTypes.h>
  29 #include <FNetWifiIWifiManagerEventListener.h>
  30
  31 namespace Tizen { namespace Net { namespace Wifi
  32 {
  33 class WifiBssInfo;
  34 class _WifiManagerImpl;
  35 class IWifiSystemMonitoringEventListener;
  36
  37 /**
  38  * @class   WifiManager
  39  * @brief   This class provides methods for local Wi-Fi device management.
  40  *
  41  * @since   2.0
  42  *
  43  * The %WifiManager class provides methods for creating a %WifiManager instance, and managing local Wi-Fi devices.
  44  * It also allows the listener to get events from local Wi-Fi devices.
  45  *
  46  * For more information on the class features, see
  47  * <a href="../org.tizen.native.appprogramming/html/guide/net/wi-fi_connectivity.htm">Wi-Fi Connectivity</a>.
  48  *
  49  * The following example demonstrates how to use the %WifiManager class.
  50  *
  51  * @code
  52  *
  53  * using namespace Tizen::Net::Wifi;
  54  *
  55  * result
  56  * MyClass::WifiManagerSample(void)
  57  * {
  58  *      WifiManager wifiMgr;            // Creates an instance of WifiManager
  59  *      MyListenerClass wifiListener;   // Creates a listener for WifiManager
  60  *      result r;
  61  *
  62  *      // Initializes wifiMgr using the Construct method
  63  *      r = wifiMgr.Construct(wifiListener);
  64  *      if (IsFailed(r))
  65  *      {
  66  *              goto CATCH;
  67  *      }
  68  *
  69  *      // Activates the local Wi-Fi device
  70  *      r = wifiMgr.Activate();
  71  *      if (IsFailed(r))
  72  *      {
  73  *              goto CATCH;
  74  *      }
  75  *
  76  *      // Checks the current connection status
  77  *      if (!wifiMgr.IsConnected())
  78  *      {
  79  *              // Deactivates the local Wi-Fi device
  80  *              r = wifiMgr.Deactivate();
  81  *              if (IsFailed(r))
  82  *              {
  83  *                      goto CATCH;
  84  *              }
  85  *      }
  86  *
  87  *      return r;
  88  *
  89  * CATCH:
  90  *      // Do some exception handling.
  91  *      return r;
  92  * }
  93  *
  94  * @endcode
  95  *
  96  */
  97
  98 class _OSP_EXPORT_ WifiManager
  99         : public Tizen::Base::Object
 100 {
 101 public:
 102         /**
 103          * This is the default constructor for this class. @n
 104          * After creating an instance of this class, the Construct() method must be called explicitly to initialize the instance.
 105          *
 106          * @since       2.0
 107          */
 108         WifiManager(void);
 109
 110         /**
 111          * This destructor overrides Tizen::Base::Object::~Object().
 112          *
 113          * @since       2.0
 114          */
 115         virtual ~WifiManager(void);
 116
 117         /**
 118          * Initializes this instance of %WifiManager with the specified listener.
 119          *
 120          * @since       2.0
 121          *
 122          * @feature     %http://tizen.org/feature/network.wifi
 123          *
 124          * @return      An error code
 125          * @param[in]   listener                A reference to the listener instance
 126          * @exception   E_SUCCESS               The method is successful.
 127          * @exception   E_SYSTEM                A system error has occurred.
 128          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 129          * @exception   E_UNSUPPORTED_OPERATION The device does not support the Wi-Fi feature.For more information, see
 130          *                                      <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">
 131          *                                      Application Filtering</a>.
 132          * @remarks
 133          *                      - The @c listener instance must not be deleted before destructing this instance.
 134          *                      - Before calling this method, check whether the feature is supported by
 135          *                      Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 136          */
 137         result Construct(IWifiManagerEventListener& listener);
 138
 139         /**
 140          * Activates a local Wi-Fi device.
 141          *
 142          * @since       2.0
 143          * @privlevel   public
 144          * @privilege   %http://tizen.org/privilege/wifi.admin
 145          *
 146          * @return      An error code
 147          * @exception   E_SUCCESS           The activation is successful.
 148          * @exception   E_FAILURE           The method has failed to activate.
 149          * @exception   E_IN_PROGRESS       The activation process is in progress.
 150          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
 151          *                                  For example, the Wi-Fi is already activated.
 152          * @exception   E_SYSTEM            A system error has occurred.
 153          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 154          * @see         IWifiManagerEventListener::OnWifiActivated()
 155          */
 156         result Activate(void) const;
 157
 158         /**
 159          * Deactivates a local Wi-Fi device.
 160          *
 161          * @since       2.0
 162          * @privlevel   public
 163          * @privilege   %http://tizen.org/privilege/wifi.admin
 164          *
 165          * @return      An error code
 166          * @exception   E_SUCCESS           The deactivation is successful.
 167          * @exception   E_FAILURE           The method has failed to deactivate.
 168          * @exception   E_IN_PROGRESS       The deactivation process is in progress.
 169          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
 170          *                                  For example, the Wi-Fi is already deactivated.
 171          * @exception   E_SYSTEM            A system error has occurred.
 172          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 173          * @see         IWifiManagerEventListener::OnWifiDeactivated()
 174          */
 175         result Deactivate(void) const;
 176
 177         /**
 178          * Gets the current power status of a local Wi-Fi device.
 179          *
 180          * @since       2.0
 181          *
 182          * @return      The current power status of the local Wi-Fi device
 183          */
 184         WifiPowerStatus GetPowerStatus(void) const;
 185
 186         /**
 187          * Gets the MAC address of a Wi-Fi device.
 188          *
 189          * @since       2.0
 190          *
 191          * @return      The MAC address in the form '00-00-00-00-00-00'
 192          * @remarks     This MAC address is different from the MAC address provided by the WifiDirectDevice class.
 193          */
 194         Tizen::Base::String GetMacAddress(void) const;
 195
 196         /**
 197          * Checks whether the local device is activated.
 198          *
 199          * @since       2.0
 200          *
 201          * @return      @c true if the local device is activated, @n
 202          *              else @c false
 203          */
 204         bool IsActivated(void) const;
 205
 206         /**
 207          * Checks whether the local device is connected to a remote Access Point(AP).
 208          *
 209          * @since       2.0
 210          *
 211          * @return      @c true if the local device is connected to a remote Access Point(AP), @n
 212          *              else @c false
 213          */
 214         bool IsConnected(void) const;
 215
 216         /**
 217          * Scans for a nearby BSS with both the infrastructure and independent modes.
 218          *
 219          * @since       2.0
 220          * @privlevel   public
 221          * @privilege   %http://tizen.org/privilege/wifi.read
 222          *
 223          * @return      An error code
 224          * @exception   E_SUCCESS           The method is successful.
 225          * @exception   E_FAILURE           The method has failed.
 226          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 227          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 228          * @remarks
 229          *                      - Only an active scan (probing for Access Points(APs) and ad hoc stations in the range) is supported.
 230          *                      - This operation does not work while a Wi-Fi Direct scanning or connection is in progress.
 231          * @see         IWifiManagerEventListener::OnWifiScanCompletedN()
 232          */
 233         result Scan(void);
 234
 235         /**
 236          * Connects to a specific access point that is a BSS with an infrastructure mode.
 237          *
 238          * @since       2.0
 239          * @privlevel   public
 240          * @privilege   %http://tizen.org/privilege/wifi.admin
 241          *
 242          * @return      An error code
 243          * @param[in]   targetApInfo        The BSS information that represents the target access point
 244          * @exception   E_SUCCESS           The method is successful.
 245          * @exception   E_FAILURE           The method has failed.
 246          * @exception   E_IN_PROGRESS       A previous request is in progress.
 247          * @exception   E_INVALID_ARG       The specified input parameter is invalid. @n
 248          *                                  For example, the BSS type is an independent mode.
 249          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 250          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 251          * @remarks     If a connection to another access point is already established, it is disconnected and a new
 252          *              connection of this method is established.
 253          * @see         IWifiManagerEventListener::OnWifiConnected()
 254          */
 255         result Connect(const WifiBssInfo& targetApInfo);
 256
 257         /**
 258          * Sets the behavior mode of the Wi-Fi background system for connection and background scanning.
 259          *
 260          * @since       2.0
 261          * @privlevel   platform
 262          * @privilege   %http://tizen.org/privilege/wifimanager
 263          *
 264          * @return      An error code
 265          * @param[in]   mode                The Wi-Fi background system mode
 266          * @exception   E_SUCCESS           The method is successful.
 267          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 268          * @exception   E_OPERATION_FAILED  The operation has failed.
 269          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 270          */
 271         result SetWifiSystemScanMode(WifiSystemScanMode mode);
 272
 273         /**
 274          * Adds the specified @c listener for receiving a notification when the state of a current Wi-Fi connection is changed
 275          * or the result of Wi-Fi background scanning is updated.
 276          *
 277          * @since       2.0
 278          * @privlevel   platform
 279          * @privilege   %http://tizen.org/privilege/wifimanager
 280          *
 281          * @return      An error code
 282          * @param[in]   listener            The listener to add
 283          * @exception   E_SUCCESS           The method is successful.
 284          * @exception   E_OBJ_ALREADY_EXIST The listener is already added.
 285          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 286          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 287          */
 288         result AddSystemMonitoringEventListener(IWifiSystemMonitoringEventListener& listener);
 289
 290         /**
 291          * Removes the specified IWifiSystemMonitoringEventListener instance used for receiving a notification. @n The removed listener
 292          * cannot listen to the events that are fired.
 293          *
 294          * @since       2.0
 295          * @privlevel   platform
 296          * @privilege   %http://tizen.org/privilege/wifimanager
 297          *
 298          * @return      An error code
 299          * @param[in]   listener            The listener to remove
 300          * @exception   E_SUCCESS           The method is successful.
 301          * @exception   E_OBJ_NOT_FOUND     The listener is not found.
 302          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 303          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 304          */
 305         result RemoveSystemMonitoringEventListener(IWifiSystemMonitoringEventListener& listener);
 306
 307         /**
 308          * Gets the state of a current Wi-Fi connection.
 309          *
 310          * @since       2.0
 311          *
 312          * @return      The state of the current Wi-Fi connection
 313          */
 314         WifiConnectionState GetConnectionState(void) const;
 315
 316         /**
 317          * Gets the information of a current Wi-Fi connection target to which the local device is connecting or is connected with.
 318          *
 319          * @since       2.0
 320          *
 321          * @return      A pointer to the WifiBssInfo instance that represents the information of the current Wi-Fi connection target, @n
 322          *              else @c null if GetConnectionState() is ::WIFI_CONN_STATE_NOT_CONNECTED
 323          */
 324         WifiBssInfo* GetConnectionTargetInfoN(void) const;
 325
 326         /**
 327          * Updates the Wi-Fi BSS information which is saved in the underlying Wi-Fi system.
 328          *
 329          * @since       2.0
 330          * @privlevel   platform
 331          * @privilege   %http://tizen.org/privilege/wifimanager
 332          *
 333          * @return      An error code
 334          * @param[in]   bssInfo             The BSS information that represents the access point
 335          * @exception   E_SUCCESS           The method is successful.
 336          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 337          * @exception   E_OBJ_NOT_FOUND     The specified input parameter is not found.
 338          * @exception   E_OPERATION_FAILED  The operation has failed.
 339          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 340          *
 341          * @remarks     The updated information is deleted when Wi-Fi is turned off if the BSS has never been connected before.
 342          */
 343         result UpdateBssInfo(const WifiBssInfo& bssInfo);
 344
 345         /**
 346          * Gets the list of the latest search results which the underlying Wi-Fi system scans periodically in the background.
 347          *
 348          * @since       2.0
 349          *
 350          * @return      A Tizen::Base::Collection::IList that contains WifiBssInfo of the existing Wi-Fi connections, @n
 351          *              else @c null if it fails
 352          */
 353         Tizen::Base::Collection::IList* GetSystemScanResultN(void) const;
 354
 355 private:
 356         /**
 357          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 358          *
 359          * @param[in]   value               An instance of %WifiManager
 360          */
 361         WifiManager(const WifiManager& value);
 362
 363         /**
 364          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit
 365          * copying of objects.
 366          *
 367          * @param[in]   rhs                 An instance of %WifiManager
 368          */
 369         WifiManager& operator=(const WifiManager& rhs);
 370
 371 private:
 372         _WifiManagerImpl* __pWifiManagerImpl;
 373
 374         friend class _WifiManagerImpl;
 375 }; // WifiManager
 376
 377 } } } // Tizen::Net::Wifi
 378 #endif // _FNET_WIFI_WIFI_MANAGER_H_