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