inc/FTelNetworkManager.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        FTelNetworkManager.h
  19  * @brief       This is the header file for the %NetworkManager class.
  20  *
  21  * This header file contains the declarations of the %NetworkManager class.
  22  */
  23 #ifndef _FTEL_NETWORK_MANAGER_H_
  24 #define _FTEL_NETWORK_MANAGER_H_
  25
  26
  27 #include <FBase.h>
  28 #include <FTelNetworkInfo.h>
  29 #include <FTelNetworkStatus.h>
  30
  31
  32 namespace Tizen { namespace Telephony
  33 {
  34 class _NetworkManagerImpl;
  35 class ITelephonyNetworkEventListener;
  36 class ITelephonyNetworkSettingListener;
  37
  38 /**
  39  * @class       NetworkManager
  40  * @brief       This class provides information about the current active network.
  41  *
  42  * @since       2.0
  43  *
  44  * The %NetworkManager class is used to register listeners who monitor network status changes,
  45  * as well as get information about current active network.
  46  *
  47  * The following example demonstrates how to use the %NetworkManager class to get the network information.
  48  *
  49  * @code
  50  *
  51  *  #include <FBase.h>
  52  *  #include <FTelephony.h>
  53  *
  54  *   using namespace Tizen::Base;
  55  *   using namespace Tizen::Telephony;
  56  *
  57  *   class MyClass
  58  *       : public Object
  59  *       , public ITelephonyNetworkEventListener
  60  *   {
  61  *     public:
  62  *       MyClass(void) {}
  63  *       ~MyClass(void) {}
  64  *
  65  *       // ITelephonyNetworkEventListener
  66  *       void OnTelephonyNetworkStatusChanged(const NetworkStatus& networkStatus);
  67  *
  68  *       void GetNetworkManagerInfo(void);
  69  *   };
  70  *
  71  *   void
  72  *   MyClass::OnTelephonyNetworkStatusChanged(const NetworkStatus& networkStatus)
  73  *   {
  74  *       bool isCallAvailable = networkStatus.IsCallServiceAvailable();
  75  *       bool isDataAvailable = networkStatus.IsDataServiceAvailable();
  76  *       bool isRoaming = networkStatus.IsRoaming();
  77  *   }
  78  *
  79  *   void
  80  *   MyClass::GetNetworkManagerInfo(void)
  81  *   {
  82  *       NetworkStatus networkStatus;
  83  *       NetworkInfo networkInfo;
  84  *
  85  *       NetworkManager* pNetworkManager = new (std::nothrow) NetworkManager();
  86  *       result r = pNetworkManager->Construct(this);
  87  *       if (IsFailed(r))
  88  *       {
  89  *               delete pNetworkManager;
  90  *               return;
  91  *       }
  92  *
  93  *       r = pNetworkManager->GetNetworkStatus(networkStatus);
  94  *       if (IsFailed(r))
  95  *       {
  96  *               delete pNetworkManager;
  97  *               return;
  98  *       }
  99  *
 100  *       r = pNetworkManager->GetNetworkInfo(networkInfo);
 101  *       if (IsFailed(r))
 102  *       {
 103  *               delete pNetworkManager;
 104  *               return;
 105  *       }
 106  *
 107  *       delete pNetworkManager;
 108  *   }
 109  *
 110  * @endcode
 111  */
 112 class _OSP_EXPORT_ NetworkManager
 113         : public Tizen::Base::Object
 114 {
 115 public:
 116         /**
 117      * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 118      *
 119      * @since   2.0
 120      */
 121         NetworkManager(void);
 122
 123         /**
 124      *  This destructor overrides Tizen::Base::Object::~Object().
 125      *
 126      * @since   2.0
 127      */
 128         virtual ~NetworkManager(void);
 129
 130         /**
 131      *  Initializes a new instance of this class. @n
 132      *  This is the two phase construction.
 133          * If a @c null pointer is passed during the construction, then there
 134      *  is no listener for telephony network status change callbacks.
 135      *
 136      * @since           2.0
 137          * @feature     %http://tizen.org/feature/network.telephony
 138      * @return          An error code
 139          * @param[in]   pListener       The listener for change in status of a telephony network
 140      * @exception       E_SUCCESS               The method is successful.
 141      * @exception       E_SYSTEM                A system error has occurred.
 142          * @exception   E_UNSUPPORTED_OPERATION  The Emulator or target device does not support the required feature. @b Since: @b 2.1
 143          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 144          * @remarks     Before calling this method, check whether the feature is supported by
 145          *                      Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 146      */
 147         result Construct(ITelephonyNetworkEventListener* pListener);
 148
 149         /**
 150      * Gets the network status.
 151      *
 152      * @since           2.0
 153      * @privlevel       public
 154      * @privilege   %http://tizen.org/privilege/telephony @n
 155      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 156      *
 157      * @return          An error code
 158      * @param[out]      networkStatus   The network status
 159      * @exception       E_SUCCESS       The method is successful.
 160      * @exception       E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 161      * @exception       E_SERVICE_UNAVAILABLE   The operation has failed because the device is out of the coverage area or in the emergency mode.
 162      * @exception       E_SYSTEM        A system error has occurred.
 163      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 164      */
 165         result GetNetworkStatus(NetworkStatus& networkStatus) const;
 166
 167         /**
 168      * Gets the network information.
 169      *
 170      * @since   2.0
 171      * @privlevel       public
 172      * @privilege   %http://tizen.org/privilege/telephony @n
 173      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 174      *
 175      * @return  An error code
 176      * @param[out]      networkInfo     The network information
 177      * @exception       E_SUCCESS       The method is successful.
 178      * @exception       E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 179      * @exception       E_SERVICE_UNAVAILABLE   The operation has failed because the device is out of the coverage area or in the emergency mode.
 180      * @exception       E_SYSTEM        A system error has occurred.
 181      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 182      */
 183         result GetNetworkInfo(NetworkInfo& networkInfo) const;
 184
 185     /**
 186      * Sets the listener for receiving the responses of the search network and the network selection mode.
 187      *
 188      * @since 2.0
 189      *
 190      * @privlevel       platform
 191      * @privilege   %http://tizen.org/privilege/telephonymanager
 192      *
 193      * @return  An error code
 194      * @param[in]   pListener           An instance of ITelephonyNetworkSettingListener @n
 195      *                                  The parameter can be set to @c null to remove the listener.
 196      * @exception   E_SUCCESS           The method is successful.
 197      * @exception   E_SYSTEM            A system error has occurred.
 198      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 199      */
 200     result SetNetworkSettingListener(ITelephonyNetworkSettingListener* pListener);
 201
 202     /**
 203      * Gets the network selection mode.
 204      *
 205      * @since 2.0
 206      *
 207      * @privlevel       platform
 208      * @privilege   %http://tizen.org/privilege/telephonymanager
 209      *
 210      * @return  An error code
 211      * @exception   E_SUCCESS   The method is successful.
 212      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 213      * @exception   E_SYSTEM                A system error has occurred.
 214      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 215      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSelectionModeReceived()
 216      */
 217     result GetNetworkSelectionMode(void);
 218
 219     /**
 220      * Selects the manually searched network.
 221      *
 222      * @since 2.0
 223      *
 224      * @privlevel       platform
 225      * @privilege   %http://tizen.org/privilege/telephonymanager
 226      *
 227      * @return  An error code
 228      * @param[out]      networkInfo     The network information
 229      * @exception   E_SUCCESS   The method is successful.
 230      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 231      * @exception   E_SYSTEM                A system error has occurred.
 232      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 233      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSelectionCompleted()
 234      */
 235     result SelectNetwork(const NetworkInfo& networkInfo);
 236
 237     /**
 238      * Selects the network automatically.
 239      *
 240      * @since 2.0
 241      *
 242      * @privlevel       platform
 243      * @privilege   %http://tizen.org/privilege/telephonymanager
 244      *
 245      * @return  An error code
 246      * @exception   E_SUCCESS   The method is successful.
 247      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 248      * @exception   E_SYSTEM                A system error has occurred.
 249      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 250      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSelectionCompleted()
 251      */
 252     result SelectNetwork(void);
 253
 254     /**
 255      * Searches for an available network.
 256      *
 257      * @since 2.0
 258      *
 259      * @privlevel       platform
 260      * @privilege   %http://tizen.org/privilege/telephonymanager
 261      *
 262      * @return  An error code
 263      * @exception   E_SUCCESS   The method is successful.
 264      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 265      * @exception   E_SYSTEM                A system error has occurred.
 266      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 267      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSearchCompletedN()
 268      */
 269     result SearchNetwork(void);
 270
 271
 272 private:
 273         /**
 274      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 275      *
 276      * @param[in]       rhs     An instance of %NetworkManager
 277      */
 278         NetworkManager(const NetworkManager& rhs);
 279
 280         /**
 281      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 282      *
 283      * @param[in]       rhs     An instance of %NetworkManager
 284      */
 285         NetworkManager& operator =(const NetworkManager& rhs);
 286
 287 private:
 288         _NetworkManagerImpl * __pNetworkManagerImpl;
 289
 290         friend class _NetworkManagerImpl;
 291 }; // NetworkManager
 292
 293 }} // Tizen::Telephony
 294 #endif // _FTEL_NETWORK_MANAGER_H_