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
 135      *
 136      * @return          The MNC of the network
 137      * @exception       E_SUCCESS       The method is successful.
 138      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 139      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 140      */
 141         int GetMnc(void) const;
 142
 143         /**
 144      * Gets the Mobile Country Code (MCC) of the network.
 145      *
 146      * @since   2.0
 147      * @privlevel       public
 148      * @privilege   %http://tizen.org/privilege/telephony
 149      *
 150      * @return          The MCC of the network
 151      * @exception       E_SUCCESS       The method is successful.
 152      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 153      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 154      */
 155         int GetMcc(void) const;
 156
 157     /**
 158      * Gets the Public Land Mobile Network (PLMN).
 159      *
 160      * @if OSPCOMPAT
 161      * @brief <i> [Compatibility] </i>
 162      * @endif
 163      * @since   2.0
 164      * @if OSPCOMPAT
 165      * @compatibility   This method has compatibility issues with OSP compatible applications. @n
 166      *                  For more information, see the issue description for @ref CompNetworkInfoGetPlmnPage "here".
 167      * @endif
 168      * @privlevel       public
 169      * @privilege   %http://tizen.org/privilege/telephony
 170      *
 171      * @return          The PLMN name
 172      * @exception       E_SUCCESS               The method is successful.
 173      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 174      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 175      */
 176         Tizen::Base::String GetPlmn(void) const;
 177
 178
 179     /**
 180      * @page    CompNetworkInfoGetPlmnPage Compatibility for GetPlmn()
 181      * @section CompNetworkInfoGetPlmnPageIssueSection Issues
 182      *          Implementation of this method in Tizen API versions prior to 2.1 has the following issue: @n
 183      *          -# The method returns an alphabetic name of PLMN.
 184      *
 185      * @section CompNetworkInfoGetPlmnPageSolutionSection Resolutions
 186      *          -# The method returns a numeric name of PLMN-ID(MCC+MNC).
 187      *           To get the alphabetic name of PLMN, it is recommended to use Tizen::Telephony::GetOperatorName().
 188      */
 189
 190     /**
 191      * Gets the current cell ID.
 192      *
 193      * @since   2.0
 194      * @privlevel       public
 195      * @privilege   %http://tizen.org/privilege/telephony
 196      *
 197      * @return          The current cell ID
 198      * @exception       E_SUCCESS       The method is successful.
 199      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 200      * @remarks     This cell ID is provided using only NetworkManager::GetNetworkInfo() when connected to a network.
 201      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 202      */
 203         int GetCellId(void) const;
 204
 205         /**
 206      * Gets the current Location Area Code (LAC).
 207      *
 208      * @since   2.0
 209      * @privlevel       public
 210      * @privilege   %http://tizen.org/privilege/telephony
 211      *
 212      * @return          The current LAC
 213      * @exception       E_SUCCESS       The method is successful.
 214      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 215      * @remarks     This LAC is provided using only NetworkManager::GetNetworkInfo() when connected to a network.
 216      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 217      */
 218         int GetLac(void) const;
 219
 220     /**
 221      * Gets the operator name.
 222      *
 223      * @since 2.0
 224      * @privlevel       public
 225      * @privilege   %http://tizen.org/privilege/telephony
 226      *
 227      * @return      The operator name
 228      * @exception   E_SUCCESS   The method is successful.
 229      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 230      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 231      */
 232     Tizen::Base::String GetOperatorName(void) const;
 233
 234     /**
 235      * Checks whether the specified instance of %NetworkInfo equals the current instance.
 236      *
 237      * @since   2.0
 238          *
 239      * @return  @c true if the specified instance equals the current instance, @n
 240      *          else @c false
 241      * @param[in]   rhs An instance of %NetworkInfo
 242      * @remarks     The method returns @c false if the specified object is not %NetworkInfo.
 243      */
 244         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 245
 246         /**
 247      * Gets the hash value of the current instance.
 248      *
 249      * @since   2.0
 250      *
 251      * @return  The hash value of the current instance
 252      */
 253         virtual int GetHashCode(void) const;
 254
 255         /**
 256      * Gets the received signal strength indication of a modem device.
 257      *
 258      * @since   2.0
 259      * @privlevel       public
 260      * @privilege   %http://tizen.org/privilege/telephony
 261          * @feature             %http://tizen.org/feature/network.telephony
 262      * @return  The current RSSI @n
 263      *          The possible RSSI value ranges from @c 0 to @c 100.
 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_SYSTEM    A system error has occurred.
 267          * @exception  E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature. @b Since: @b 2.1
 268          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 269          * @remarks
 270          *                      - The specific error code can be accessed using the GetLastResult() method.
 271          *                      - Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 272      */
 273         static int GetRssi(void);
 274
 275         /**
 276       * Copying of objects using this copy assignment operator is allowed.
 277       *
 278       * @since 2.0
 279       *
 280       * @return     The reference of this instance
 281       * @param[in]  rhs   An instance of %NetworkInfo
 282       */
 283         NetworkInfo& operator=(const NetworkInfo& rhs);
 284
 285 private:
 286         _NetworkInfoImpl* __pNetworkInfoImpl;
 287
 288         friend class _NetworkInfoImpl;
 289 }; // NetworkInfo
 290
 291 }} //Tizen::Telephony
 292 #endif // _FTEL_NETWORK_INFO_H_