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