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 the local Wi-Fi device management.
  40  *
  41  * @since   2.0
  42  *
  43  * The %WifiManager class provides methods for creating a %WifiManager instance, and managing the local Wi-Fi devices.
  44  * It also allows the listener to get the events from the 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.
 104          *
 105          * @since       2.0
 106          *
 107          * @remarks     After creating an instance of this class, the Construct() method must be called explicitly to
 108          *              initialize the instance.
 109          * @see         Construct()
 110          */
 111         WifiManager(void);
 112
 113         /**
 114          * This destructor overrides Tizen::Base::Object::~Object().
 115          *
 116          * @since       2.0
 117          */
 118         virtual ~WifiManager(void);
 119
 120         /**
 121          * Initializes this instance of %WifiManager with the specified listener.
 122          *
 123          * @since       2.0
 124          *
 125          * @feature     %http://tizen.org/feature/network.wifi
 126          *
 127          * @return      An error code
 128          * @param[in]   listener                A reference to the listener instance
 129          * @exception   E_SUCCESS               The method is successful.
 130          * @exception   E_SYSTEM                A system error has occurred.
 131          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 132          * @exception   E_UNSUPPORTED_OPERATION The device does not support the Wi-Fi feature.For more information, see
 133          *                                      <a href=”../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm”>
 134          *                                      Application Filtering</a>.
 135          * @remarks
 136          *            - The @c listener instance must not be deleted before destructing this instance.
 137          *            - Before calling this method, check whether the feature is supported by
 138          *              %Tizen::System::SystemInfo::GetValue() methods.
 139          */
 140         result Construct(IWifiManagerEventListener& listener);
 141
 142         /**
 143          * Activates the local Wi-Fi device.
 144          *
 145          * @since       2.0
 146          * @privlevel   public
 147          * @privilege   %http://tizen.org/privilege/wifi.admin
 148          *
 149          * @return      An error code
 150          * @exception   E_SUCCESS           The activation is successful.
 151          * @exception   E_FAILURE           The method has failed to activate.
 152          * @exception   E_IN_PROGRESS       The activate process is in progress.
 153          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
 154          *                                  For example, the Wi-Fi is already activated.
 155          * @exception   E_SYSTEM            A system error has occurred.
 156          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 157          * @see         IWifiManagerEventListener::OnWifiActivated()
 158          */
 159         result Activate(void) const;
 160
 161         /**
 162          * Deactivates the local Wi-Fi device.
 163          *
 164          * @since       2.0
 165          * @privlevel   public
 166          * @privilege   %http://tizen.org/privilege/wifi.admin
 167          *
 168          * @return      An error code
 169          * @exception   E_SUCCESS           The deactivation is successful.
 170          * @exception   E_FAILURE           The method has failed to deactivate.
 171          * @exception   E_IN_PROGRESS       The deactivate process is in progress.
 172          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
 173          *                                  For example, the Wi-Fi is already deactivated.
 174          * @exception   E_SYSTEM            A system error has occurred.
 175          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 176          * @see         IWifiManagerEventListener::OnWifiDeactivated()
 177          */
 178         result Deactivate(void) const;
 179
 180         /**
 181          * Gets the current power status of the local Wi-Fi device.
 182          *
 183          * @since       2.0
 184          *
 185          * @return      The current power status of the local Wi-Fi device
 186          */
 187         WifiPowerStatus GetPowerStatus(void) const;
 188
 189         /**
 190          * Gets the MAC address of the Wi-Fi device.
 191          *
 192          * @since       2.0
 193          *
 194          * @return      The MAC address in the form '00-00-00-00-00-00'
 195          * @remarks     This MAC address is different from the MAC address provided by the WifiDirectDevice class.
 196          */
 197         Tizen::Base::String GetMacAddress(void) const;
 198
 199         /**
 200          * Checks whether the local device is activated.
 201          *
 202          * @since       2.0
 203          *
 204          * @return      @c true if the local device is activated, @n
 205          *              else @c false
 206          */
 207         bool IsActivated(void) const;
 208
 209         /**
 210          * Checks whether the local device is connected with a remote Access Point(AP).
 211          *
 212          * @since       2.0
 213          *
 214          * @return      @c true if the local device is connected with a remote Access Point(AP), @n
 215          *              else @c false
 216          */
 217         bool IsConnected(void) const;
 218
 219         /**
 220          * Scans for a nearby BSS with both the infrastructure and independent modes.
 221          *
 222          * @since       2.0
 223          * @privlevel   public
 224          * @privilege   %http://tizen.org/privilege/wifi.read
 225          *
 226          * @return      An error code
 227          * @exception   E_SUCCESS           The method is successful.
 228          * @exception   E_FAILURE           The method has failed.
 229          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 230          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 231          * @remarks
 232          *              - Only active scan (probing for Access Points(APs) and ad hoc stations in the range) is supported.
 233          *              - This operation does not work while the Wi-Fi Direct scanning or connection is in progress.
 234          * @see         IWifiManagerEventListener::OnWifiScanCompletedN()
 235          */
 236         result Scan(void);
 237
 238         /**
 239          * Connects to a specific access point that is a BSS with an infrastructure mode.
 240          *
 241          * @since       2.0
 242          * @privlevel   public
 243          * @privilege   %http://tizen.org/privilege/wifi.admin
 244          *
 245          * @return      An error code
 246          * @param[in]   targetApInfo        A BSS information representing the target access point
 247          * @exception   E_SUCCESS           The method is successful.
 248          * @exception   E_FAILURE           The method has failed.
 249          * @exception   E_IN_PROGRESS       The previous request is in progress.
 250          * @exception   E_INVALID_ARG       The specified input parameter is invalid. @n
 251          *                                  For example, the BSS type is an independent mode.
 252          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 253          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 254          * @remarks     If a connection to another access point is already established, it will be disconnected and the new
 255          *              connection of this method will be established.
 256          * @see         IWifiManagerEventListener::OnWifiConnected()
 257          */
 258         result Connect(const WifiBssInfo& targetApInfo);
 259
 260         /**
 261          * Sets the behavior mode of the Wi-Fi background system about connection and background scanning.
 262          *
 263          * @since       2.0
 264          * @privlevel   platform
 265          * @privilege   %http://tizen.org/privilege/wifimanager
 266          *
 267          * @return      An error code
 268          * @param[in]   mode                A Wi-Fi background system mode
 269          * @exception   E_SUCCESS           The method is successful.
 270          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 271          * @exception   E_OPERATION_FAILED  The operation has failed.
 272          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 273          */
 274         result SetWifiSystemScanMode(WifiSystemScanMode mode);
 275
 276         /**
 277          * Adds the specified @c listener for receiving the notification when the state of current Wi-Fi connection is changed
 278          * or the result of Wi-Fi background scanning is updated.
 279          *
 280          * @since       2.0
 281          * @privlevel   platform
 282          * @privilege   %http://tizen.org/privilege/wifimanager
 283          *
 284          * @return      An error code
 285          * @param[in]   listener            The listener to add
 286          * @exception   E_SUCCESS           The method is successful.
 287          * @exception   E_OBJ_ALREADY_EXIST The listener is already added.
 288          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 289          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 290          */
 291         result AddSystemMonitoringEventListener(IWifiSystemMonitoringEventListener& listener);
 292
 293         /**
 294          * Removes the specified IWifiSystemMonitoringEventListener instance for receiving the notification. @n The removed listener
 295          * cannot listen to the events that are fired.
 296          *
 297          * @since       2.0
 298          * @privlevel   platform
 299          * @privilege   %http://tizen.org/privilege/wifimanager
 300          *
 301          * @return      An error code
 302          * @param[in]   listener            The listener to remove
 303          * @exception   E_SUCCESS           The method is successful.
 304          * @exception   E_OBJ_NOT_FOUND     The listener is not found.
 305          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 306          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 307          */
 308         result RemoveSystemMonitoringEventListener(IWifiSystemMonitoringEventListener& listener);
 309
 310         /**
 311          * Gets the state of current Wi-Fi connection.
 312          *
 313          * @since       2.0
 314          *
 315          * @return      The state of the current Wi-Fi connection
 316          */
 317         WifiConnectionState GetConnectionState(void) const;
 318
 319         /**
 320          * Gets the information of current Wi-Fi connection target which the local device is connecting or connected with.
 321          *
 322          * @since       2.0
 323          *
 324          * @return      A pointer to the WifiBssInfo instance representing the information of current Wi-Fi connection target, @n
 325          *              else @c null if GetConnectionState() is ::WIFI_CONN_STATE_NOT_CONNECTED
 326          */
 327         WifiBssInfo* GetConnectionTargetInfoN(void) const;
 328
 329         /**
 330          * Updates the Wi-Fi BSS information which is saved in the underlying Wi-Fi system.
 331          *
 332          * @since       2.0
 333          * @privlevel   platform
 334          * @privilege   %http://tizen.org/privilege/wifimanager
 335          *
 336          * @return      An error code
 337          * @param[in]   bssInfo             A BSS information representing the access point
 338          * @exception   E_SUCCESS           The method is successful.
 339          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 340          * @exception   E_OBJ_NOT_FOUND     The specified input parameter is not found.
 341          * @exception   E_OPERATION_FAILED  The operation has failed.
 342          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 343          *
 344          * @remarks     The updated information is deleted when Wi-Fi is turned off if the BSS has never been connected before.
 345          */
 346         result UpdateBssInfo(const WifiBssInfo& bssInfo);
 347
 348         /**
 349          * Gets a list of the latest search results which the underlying Wi-Fi system scan periodically on background.
 350          *
 351          * @since       2.0
 352          *
 353          * @return      A Tizen::Base::Collection::IList containing WifiBssInfo of existing Wi-Fi connections if successful, @n
 354          *              else @c null
 355          */
 356         Tizen::Base::Collection::IList* GetSystemScanResultN(void) const;
 357
 358 private:
 359         //
 360         // The implementation of this copy constructor is intentionally blank to prohibit copying of objects.
 361         //
 362         WifiManager(const WifiManager& value);
 363
 364         //
 365         // The implementation of this copy assignment operator is intentionally blank to prohibit copying of objects.
 366         //
 367         WifiManager& operator=(const WifiManager& rhs);
 368
 369 private:
 370         _WifiManagerImpl* __pWifiManagerImpl;
 371
 372         friend class _WifiManagerImpl;
 373 }; // WifiManager
 374
 375 } } } // Tizen::Net::Wifi
 376 #endif // _FNET_WIFI_WIFI_MANAGER_H_