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