inc/FTelNetworkInfo.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        FTelNetworkInfo.h
  19  * @brief       This is the header file for the %NetworkInfo class.
  20  *
  21  * This header file contains the declarations of the %NetworkInfo class.
  22  */
  23 #ifndef _FTEL_NETWORK_INFO_H_
  24 #define _FTEL_NETWORK_INFO_H_
  25
  26
  27 #include <FBase.h>
  28
  29
  30 namespace Tizen { namespace Telephony
  31 {
  32 class _NetworkInfoImpl;
  33
  34 /**
  35  * @class       NetworkInfo
  36  * @brief       This class provides information of the current network.
  37  *
  38  * @since       2.0
  39  *
  40  * The %NetworkInfo class provides methods to get information of the current network such as MNC, MCC, PLMN, cell ID, and operator name.
  41  *
  42  * The following example demonstrates how to use the %NetworkInfo class to get the network information.
  43  *
  44  * @code
  45  *
  46  *  #include <FBase.h>
  47  *  #include <FTelephony.h>
  48  *
  49  *  using namespace Tizen::Base;
  50  *  using namespace Tizen::Telephony;
  51  *
  52  *  class MyClass
  53  *      : public Object
  54  *  {
  55  *  public:
  56  *      MyClass(void) {}
  57  *      ~MyClass(void) {}
  58  *
  59  *      void GetNetworkInfo(void);
  60  *  };
  61  *
  62  *  void
  63  *  MyClass::GetNetworkInfo(void)
  64  *  {
  65  *      result r = E_SUCCESS;
  66  *      int mnc;
  67  *      int mcc;
  68  *      int cellId;
  69  *      int lac;
  70  *      String plmn;
  71  *      String operatorName;
  72  *
  73  *      NetworkInfo networkInfo;
  74  *      NetworkManager* pNetworkManager = new (std::nothrow) NetworkManager();
  75  *
  76  *      r = pNetworkManager->Construct(null);
  77  *      if (IsFailed(r))
  78  *      {
  79  *              delete pNetworkManager;
  80  *              return;
  81  *      }
  82  *
  83  *      r = pNetworkManager->GetNetworkInfo(networkInfo);
  84  *      if (IsFailed(r))
  85  *      {
  86  *              delete pNetworkManager;
  87  *              return;
  88  *      }
  89  *
  90  *      mnc = networkInfo.GetMnc();
  91  *      mcc = networkInfo.GetMcc();
  92  *      cellId = networkInfo.GetCellId();
  93  *      lac = networkInfo.GetLac();
  94  *      plmn = networkInfo.GetPlmn();
  95  *      operatorName = networkInfo.GetOperatorName();
  96  *
  97  *      delete pNetworkManager;
  98  *  }
  99  *
 100  * @endcode
 101  */
 102 class _OSP_EXPORT_ NetworkInfo
 103         : public Tizen::Base::Object
 104 {
 105 public:
 106         /**
 107      * This is the default constructor for this class.
 108      *
 109      * @since   2.0
 110      */
 111         NetworkInfo(void);
 112
 113         /**
 114      * Copying of objects using this copy constructor is allowed.
 115      *
 116      * @since 2.0
 117      *
 118      * @param[in]   rhs   An instance of %NetworkInfo
 119      */
 120         NetworkInfo(const NetworkInfo& rhs);
 121
 122         /**
 123      * This destructor overrides Tizen::Base::Object::~Object().
 124      *
 125      * @since   2.0
 126      */
 127         virtual ~NetworkInfo(void);
 128
 129         /**
 130      * Gets the Mobile Network Code (MNC) of the network.
 131      *
 132      * @since   2.0
 133      * @privlevel       public
 134      * @privilege   %http://tizen.org/privilege/telephony @n
 135      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 136      *
 137      * @return          The MNC of the network
 138      * @exception       E_SUCCESS       The method is successful.
 139      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 140      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 141      */
 142         int GetMnc(void) const;
 143
 144         /**
 145      * Gets the Mobile Country Code (MCC) of the network.
 146      *
 147      * @since   2.0
 148      * @privlevel       public
 149      * @privilege   %http://tizen.org/privilege/telephony @n
 150      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 151      *
 152      * @return          The MCC of the network
 153      * @exception       E_SUCCESS       The method is successful.
 154      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 155      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 156      */
 157         int GetMcc(void) const;
 158
 159     /**
 160      * Gets the Public Land Mobile Network (PLMN).
 161      *
 162      * @if OSPCOMPAT
 163      * @brief <i> [Compatibility] </i>
 164      * @endif
 165      * @since   2.0
 166      * @if OSPCOMPAT
 167      * @compatibility   This method has compatibility issues with OSP compatible applications. @n
 168      *                  For more information, see the issue description for @ref CompNetworkInfoGetPlmnPage "here".
 169      * @endif
 170      * @privlevel       public
 171      * @privilege   %http://tizen.org/privilege/telephony @n
 172      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 173      *
 174      * @return          The PLMN name
 175      * @exception       E_SUCCESS               The method is successful.
 176      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 177      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 178      */
 179         Tizen::Base::String GetPlmn(void) const;
 180
 181
 182     /**
 183      * @page    CompNetworkInfoGetPlmnPage Compatibility for GetPlmn()
 184      * @section CompNetworkInfoGetPlmnPageIssueSection Issues
 185      *          Implementation of this method in Tizen API versions prior to 2.1 has the following issue: @n
 186      *          -# The method returns an alphabetic name of PLMN.
 187      *
 188      * @section CompNetworkInfoGetPlmnPageSolutionSection Resolutions
 189      *          -# The method returns a numeric name of PLMN-ID(MCC+MNC).
 190      *           To get the alphabetic name of PLMN, it is recommended to use Tizen::Telephony::GetOperatorName().
 191      */
 192
 193     /**
 194      * Gets the current cell ID.
 195      *
 196      * @since   2.0
 197      * @privlevel       public
 198      * @privilege   %http://tizen.org/privilege/telephony @n
 199      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 200      *
 201      * @return          The current cell ID
 202      * @exception       E_SUCCESS       The method is successful.
 203      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 204      * @remarks     This cell ID is provided using only NetworkManager::GetNetworkInfo() when connected to a network.
 205      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 206      */
 207         int GetCellId(void) const;
 208
 209         /**
 210      * Gets the current Location Area Code (LAC).
 211      *
 212      * @since   2.0
 213      * @privlevel       public
 214      * @privilege   %http://tizen.org/privilege/telephony @n
 215      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 216      *
 217      * @return          The current LAC
 218      * @exception       E_SUCCESS       The method is successful.
 219      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 220      * @remarks     This LAC is provided using only NetworkManager::GetNetworkInfo() when connected to a network.
 221      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 222      */
 223         int GetLac(void) const;
 224
 225     /**
 226      * Gets the operator name.
 227      *
 228      * @since 2.0
 229      * @privlevel       public
 230      * @privilege   %http://tizen.org/privilege/telephony @n
 231      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 232      *
 233      * @return      The operator name
 234      * @exception   E_SUCCESS   The method is successful.
 235      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 236      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 237      */
 238     Tizen::Base::String GetOperatorName(void) const;
 239
 240     /**
 241      * Checks whether the specified instance of %NetworkInfo equals the current instance.
 242      *
 243      * @since   2.0
 244          *
 245      * @return  @c true if the specified instance equals the current instance, @n
 246      *          else @c false
 247      * @param[in]   rhs An instance of %NetworkInfo
 248      * @remarks     The method returns @c false if the specified object is not %NetworkInfo.
 249      */
 250         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 251
 252         /**
 253      * Gets the hash value of the current instance.
 254      *
 255      * @since   2.0
 256      *
 257      * @return  The hash value of the current instance
 258      */
 259         virtual int GetHashCode(void) const;
 260
 261         /**
 262      * Gets the received signal strength indication of a modem device.
 263      *
 264      * @since   2.0
 265      * @privlevel       public
 266      * @privilege   %http://tizen.org/privilege/telephony @n
 267      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 268          * @feature             %http://tizen.org/feature/network.telephony
 269      * @return  The current RSSI @n
 270      *          The possible RSSI value ranges from @c 0 to @c 100.
 271      * @exception   E_SUCCESS   The method is successful.
 272      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 273      * @exception   E_SYSTEM    A system error has occurred.
 274          * @exception  E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature. @b Since: @b 2.1
 275          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 276          * @remarks
 277          *                      - The specific error code can be accessed using the GetLastResult() method.
 278          *                      - Before calling this method, check whether the feature is supported by
 279          *                      Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 280      */
 281         static int GetRssi(void);
 282
 283         /**
 284       * Copying of objects using this copy assignment operator is allowed.
 285       *
 286       * @since 2.0
 287       *
 288       * @return     The reference of this instance
 289       * @param[in]  rhs   An instance of %NetworkInfo
 290       */
 291         NetworkInfo& operator=(const NetworkInfo& rhs);
 292
 293 private:
 294         _NetworkInfoImpl* __pNetworkInfoImpl;
 295
 296         friend class _NetworkInfoImpl;
 297 }; // NetworkInfo
 298
 299 }} //Tizen::Telephony
 300 #endif // _FTEL_NETWORK_INFO_H_