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 methods to obtain the current network information.
  37  *
  38  * @since       2.0
  39  *
  40  * The %NetworkInfo class provides methods to obtain information, such as the MNC, the MCC, the PLMN, the cell ID, and the operator name, of the current network.
  41  *
  42  * The following example demonstrates how to use the %NetworkInfo class to obtain 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 to copy
 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 for PLMN.
 187      *
 188      * @section CompNetworkInfoGetPlmnPageSolutionSection Resolutions
 189          *                      The issue mentioned above is resolved in Tizen API version 2.1, and it is recommended to use Tizen API version 2.1. or above. @n
 190      *          -# The method returns a numeric name for PLMN-ID(MCC+MNC).
 191      *          To get the alphabetic name of PLMN, it is recommended to use Tizen::Telephony::GetOperatorName().
 192      */
 193
 194     /**
 195      * Gets the current cell ID.
 196      *
 197      * @since           2.0
 198      * @privlevel       public
 199      * @privilege   %http://tizen.org/privilege/telephony @n
 200      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 201      *
 202      * @return          The current cell ID
 203      * @exception       E_SUCCESS                       The method is successful.
 204      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 205      * @remarks
 206          *                              - The cell ID is provided using only the NetworkManager::GetNetworkInfo() method when connected to a network.
 207      *                          - The specific error code can be accessed using the GetLastResult() method.
 208      */
 209         int GetCellId(void) const;
 210
 211         /**
 212      * Gets the current Location Area Code (LAC).
 213      *
 214      * @since           2.0
 215      * @privlevel       public
 216      * @privilege   %http://tizen.org/privilege/telephony @n
 217      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 218      *
 219      * @return          The current LAC
 220      * @exception       E_SUCCESS                       The method is successful.
 221      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 222      * @remarks
 223          *                              - The LAC is provided using only the NetworkManager::GetNetworkInfo() method when connected to a network.
 224      *                          - The specific error code can be accessed using the GetLastResult() method.
 225      */
 226         int GetLac(void) const;
 227
 228     /**
 229      * Gets the operator name.
 230      *
 231      * @since           2.0
 232      * @privlevel       public
 233      * @privilege   %http://tizen.org/privilege/telephony @n
 234      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 235      *
 236      * @return      The operator name
 237      * @exception   E_SUCCESS                   The method is successful.
 238      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 239      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 240      */
 241     Tizen::Base::String GetOperatorName(void) const;
 242
 243     /**
 244      * Checks whether the specified instance of %NetworkInfo equals the current instance.
 245      *
 246      * @since   2.0
 247          *
 248      * @return          @c true if the specified instance equals the current instance, @n
 249      *                  else @c false
 250      * @param[in]   rhs         An instance of %NetworkInfo to check
 251      * @remarks     This method returns @c false if the specified object is not %NetworkInfo.
 252      */
 253         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 254
 255         /**
 256      * Gets the hash value of the current instance.
 257      *
 258      * @since   2.0
 259      *
 260      * @return  The hash value of the current instance
 261      */
 262         virtual int GetHashCode(void) const;
 263
 264         /**
 265      * Gets the received signal strength indication of the modem device.
 266      *
 267      * @since           2.0
 268      * @privlevel       public
 269      * @privilege   %http://tizen.org/privilege/telephony @n
 270      *                          (%http://tizen.org/privilege/systeminfo is deprecated.)
 271          * @feature             %http://tizen.org/feature/network.telephony
 272      * @return          The current RSSI @n
 273      *                  The possible RSSI values range from @c 0 to @c 100.
 274      * @exception   E_SUCCESS                            The method is successful.
 275      * @exception   E_PRIVILEGE_DENIED           The application does not have the privilege to call this method.
 276      * @exception   E_SYSTEM                             A system error has occurred.
 277          * @exception  E_UNSUPPORTED_OPERATION   The Emulator or target device does not support the required feature. @b Since: @b 2.1
 278          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 279          * @remarks
 280          *                      - The specific error code can be accessed using the GetLastResult() method.
 281          *                      - Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 282      */
 283         static int GetRssi(void);
 284
 285         /**
 286       * Copying of objects using this copy assignment operator is allowed.
 287       *
 288       * @since 2.0
 289       *
 290       * @return     A reference to this instance
 291       * @param[in]  rhs   An instance of %NetworkInfo to copy
 292       */
 293         NetworkInfo& operator=(const NetworkInfo& rhs);
 294
 295 private:
 296         _NetworkInfoImpl* __pNetworkInfoImpl;
 297
 298         friend class _NetworkInfoImpl;
 299 }; // NetworkInfo
 300
 301 }} //Tizen::Telephony
 302 #endif // _FTEL_NETWORK_INFO_H_