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  *      result
  52  *      MyClass::GetNetworkManagerInfo(void)
  53  *      {
  54  *              NetworkStatus networkStatus;
  55  *              NetworkInfo networkInfo;
  56  *
  57  *              NetworkManager* pNetworkManager = new NetworkManager();
  58  *
  59  *              result r = pNetworkManager->Construct(this);
  60  *              if (IsFailed(r))
  61  *              {
  62  *                      delete pNetworkManager;
  63  *                      return r;
  64  *              }
  65  *
  66  *              r = pNetworkManager->GetNetworkStatus(networkStatus);
  67  *              if (IsFailed(r))
  68  *              {
  69  *                      delete pNetworkManager;
  70  *                      return r;
  71  *              }
  72  *
  73  *              r = pNetworkManager->GetNetworkInfo(networkInfo);
  74  *              if (IsFailed(r))
  75  *              {
  76  *                      delete pNetworkManager;
  77  *                      return r;
  78  *              }
  79  *
  80  *              delete pNetworkManager;
  81  *              return E_SUCCESS;
  82  *      }
  83  *
  84  *      void
  85  *      MyClass::OnTelephonyNetworkStatusChanged(const NetworkStatus& networkStatus)
  86  *      {
  87  *              bool isCallAvail = networkStatus.IsCallServiceAvailable();
  88  *              bool isDataAvail = networkStatus.IsDataServiceAvailable();
  89  *              bool isRoaming = networkStatus.IsRoaming();
  90  *      }
  91  *
  92  * @endcode
  93  */
  94 class _OSP_EXPORT_ NetworkManager
  95         : public Tizen::Base::Object
  96 {
  97 public:
  98         /**
  99      * 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.
 100      *
 101      * @since   2.0
 102      */
 103         NetworkManager(void);
 104
 105         /**
 106      *  This destructor overrides Tizen::Base::Object::~Object().
 107      *
 108      * @since   2.0
 109      */
 110         virtual ~NetworkManager(void);
 111
 112         /**
 113      *  Initializes a new instance of this class. @n
 114      *  This is the two phase construction.
 115          * If a @c null pointer is passed during the construction, then there
 116      *  is no listener for telephony network status change callbacks.
 117      *
 118      * @since           2.0
 119          *
 120      * @return          An error code
 121          * @param[in]   pListener       The listener for change in status of a telephony network
 122      * @exception       E_SUCCESS               The method is successful.
 123      * @exception       E_SYSTEM                A system error has occurred.
 124      */
 125         result Construct(ITelephonyNetworkEventListener* pListener);
 126
 127         /**
 128      * Gets the network status.
 129      *
 130      * @since           2.0
 131      * @privilege   %http://tizen.org/privilege/systeminfo
 132      *
 133      * @return          An error code
 134      * @param[out]      networkStatus   The network status
 135      * @exception       E_SUCCESS       The method is successful.
 136      * @exception       E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 137      * @exception       E_SERVICE_UNAVAILABLE   The operation has failed because the device is out of the coverage area or in the emergency mode.
 138      * @exception       E_SYSTEM        A system error has occurred.
 139      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 140      */
 141         result GetNetworkStatus(NetworkStatus& networkStatus) const;
 142
 143         /**
 144      * Gets the network information.
 145      *
 146      * @since   2.0
 147      * @privilege   %http://tizen.org/privilege/systeminfo
 148      *
 149      * @return  An error code
 150      * @param[out]      networkInfo     The network information
 151      * @exception       E_SUCCESS       The method is successful.
 152      * @exception       E_NETWORK_UNAVAILABLE   The operation has failed because the device is in the offline mode.
 153      * @exception       E_SERVICE_UNAVAILABLE   The operation has failed because the device is out of the coverage area or in the emergency mode.
 154      * @exception       E_SYSTEM        A system error has occurred.
 155      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 156      */
 157         result GetNetworkInfo(NetworkInfo& networkInfo) const;
 158
 159     /**
 160      * @if VISPARTNER-MANUFACTURER
 161      * Sets the listener for receiving the responses of the search network and the network selection mode.
 162      *
 163      * @since 2.0
 164      *
 165      * @visibility  partner-manufacturer
 166      * @privilege   %http://tizen.org/privilege/telephonymanager
 167      *
 168      * @return  An error code
 169      * @param[in]   pListener           An instance of ITelephonyNetworkSettingListener @n
 170      *                                  The parameter can be set to @c null to remove the listener.
 171      * @exception   E_SUCCESS           The method is successful.
 172      * @exception   E_SYSTEM            A system error has occurred.
 173      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 174      *
 175      * @endif
 176      */
 177     result SetNetworkSettingListener(ITelephonyNetworkSettingListener* pListener);
 178
 179     /**
 180      * @if VISPARTNER-MANUFACTURER
 181      * Gets the network selection mode.
 182      *
 183      * @since 2.0
 184      *
 185      * @visibility  partner-manufacturer
 186      * @privilege   %http://tizen.org/privilege/telephonymanager
 187      *
 188      * @return  An error code
 189      * @exception   E_SUCCESS   The method is successful.
 190      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 191      * @exception   E_SYSTEM                A system error has occurred.
 192      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 193      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSelectionModeReceived()
 194      *
 195      * @endif
 196      */
 197     result GetNetworkSelectionMode(void);
 198
 199     /**
 200      * @if VISPARTNER-MANUFACTURER
 201      * Selects the manually searched network.
 202      *
 203      * @since 2.0
 204      *
 205      * @visibility  partner-manufacturer
 206      * @privilege   %http://tizen.org/privilege/telephonymanager
 207      *
 208      * @return  An error code
 209      * @param[out]      networkInfo     The network information
 210      * @exception   E_SUCCESS   The method is successful.
 211      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 212      * @exception   E_SYSTEM                A system error has occurred.
 213      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 214      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSelectionCompleted()
 215      *
 216      * @endif
 217      */
 218     result SelectNetwork(const NetworkInfo& networkInfo);
 219
 220     /**
 221      * @if VISPARTNER-MANUFACTURER
 222      * Selects the network automatically.
 223      *
 224      * @since 2.0
 225      *
 226      * @visibility  partner-manufacturer
 227      * @privilege   %http://tizen.org/privilege/telephonymanager
 228      *
 229      * @return  An error code
 230      * @exception   E_SUCCESS   The method is successful.
 231      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 232      * @exception   E_SYSTEM                A system error has occurred.
 233      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 234      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSelectionCompleted()
 235      *
 236      * @endif
 237      */
 238     result SelectNetwork(void);
 239
 240     /**
 241      * @if VISPARTNER-MANUFACTURER
 242      * Searches for an available network.
 243      *
 244      * @since 2.0
 245      *
 246      * @visibility  partner-manufacturer
 247      * @privilege   %http://tizen.org/privilege/telephonymanager
 248      *
 249      * @return  An error code
 250      * @exception   E_SUCCESS   The method is successful.
 251      * @exception   E_OPERATION_FAILED      This request operation has failed due to an internal error.
 252      * @exception   E_SYSTEM                A system error has occurred.
 253      * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 254      * @see ITelephonyNetworkSettingListener::OnTelephonyNetworkSearchCompletedN()
 255      *
 256      * @endif
 257      */
 258     result SearchNetwork(void);
 259
 260
 261 private:
 262         /**
 263      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 264      *
 265      * @param[in]       rhs     An instance of %NetworkManager
 266      */
 267         NetworkManager(const NetworkManager& rhs);
 268
 269         /**
 270      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 271      *
 272      * @param[in]       rhs     An instance of %NetworkManager
 273      */
 274         NetworkManager& operator =(const NetworkManager& rhs);
 275
 276 private:
 277         _NetworkManagerImpl * __pNetworkManagerImpl;
 278
 279         friend class _NetworkManagerImpl;
 280 }; // NetworkManager
 281
 282 }} // Tizen::Telephony
 283 #endif // _FTEL_NETWORK_MANAGER_H_