inc/FTelSimInfo.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        FTelSimInfo.h
  19  * @brief       This is the header file for the %SimInfo class.
  20  *
  21  * This header file contains the declarations of the %SimInfo class.
  22  */
  23 #ifndef _FTEL_SIM_INFO_H_
  24 #define _FTEL_SIM_INFO_H_
  25
  26
  27 #include <FBase.h>
  28 #include <FTelTypes.h>
  29
  30
  31 namespace Tizen { namespace Telephony
  32 {
  33 class _SimInfoImpl;
  34
  35
  36 /**
  37  * @class       SimInfo
  38  * @brief       This class provides information of the currently inserted SIM card.
  39  * @since       2.0
  40  *
  41  * The %SimInfo class provides methods to get information from the SIM card such as MCC, MNC, SPN, ICC ID, the name of operator,
  42  * and whether the SIM card is available or not.
  43  *
  44  * The following example demonstrates how to use the %SimInfo class to get the SIM information.
  45  *
  46  * @code
  47  *
  48  *      result
  49  *      MyClass::GetSimInfo(void)
  50  *      {
  51  *              int mnc;
  52  *              int mcc;
  53  *              bool isAvailable;
  54  *              String spn;
  55  *              String iccId;
  56  *              String operatorName;
  57  *              SimType simType;
  58  *
  59  *              SimStateManager simStateManager;
  60  *              SimInfo simInfo;
  61  *
  62  *              result r = simStateManager.Construct();
  63  *              if (IsFailed(r))
  64  *              {
  65  *                      return r;
  66  *              }
  67  *
  68  *              r = simStateManager.GetSimInfo(simInfo);
  69  *              if (IsFailed(r))
  70  *              {
  71  *                      return r;
  72  *              }
  73  *
  74  *              mnc = simInfo.GetMnc();
  75  *              mcc = simInfo.GetMcc();
  76  *              spn = simInfo.GetSpn();
  77  *              iccId = simInfo.GetIccId();
  78  *              operatorName = simInfo.GetOperatorName();
  79  *              isAvailable = simInfo.IsAvailable();
  80  *              simType = simInfo.GetSimType();
  81  *
  82  *              return E_SUCCESS;
  83  *      }
  84  *
  85  * @endcode
  86  */
  87 class _OSP_EXPORT_ SimInfo
  88         : public Tizen::Base::Object
  89 {
  90 public:
  91         /**
  92          * This is the default constructor for this class.
  93          *
  94          * @since               2.0
  95          */
  96         SimInfo(void);
  97
  98         /**
  99          * Copying of objects using this copy constructor is allowed.
 100          *
 101          * @since       2.1
 102          *
 103          * @param[in]   rhs   An instance of %SimInfo
 104          */
 105         SimInfo(const SimInfo& rhs);
 106
 107         /**
 108          * This destructor overrides Tizen::Base::Object::~Object().
 109          *
 110          * @since       2.0
 111          */
 112         virtual ~SimInfo(void);
 113
 114         /**
 115          * Initializes this instance of %SimInfo.
 116          *
 117          * @brief   <i> [Deprecated] </i>
 118          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use the SimStateManager::GetSimInfo() method to get the initialized %SimInfo instance.
 119          *
 120          * @since               2.0
 121          * @feature %http://tizen.org/feature/network.telephony
 122          * @return              An error code
 123          * @exception   E_SUCCESS       The method is successful.
 124          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 125          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 126          * @exception   E_UNSUPPORTED_OPERATION  The Emulator or target device does not support the required feature. @b Since: @b 2.1
 127          *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/manifest_features.htm">Application Filtering</a>.
 128          * @remarks     Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 129          */
 130         result Construct(void);
 131
 132         /**
 133          * Gets the Mobile Network Code (MNC) of the SIM International Mobile Subscriber Identity (IMSI) information.
 134          *
 135          * @since       2.0
 136          *
 137          * @privlevel   public
 138          * @privilege   %http://tizen.org/privilege/telephony
 139          *
 140          * @return      The MNC of the SIM card, @n
 141          *              else @c -1 if the method fails
 142          * @exception   E_SUCCESS       The method is successful.
 143          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 144          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 145          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 146          */
 147         int GetMnc(void) const;
 148
 149         /**
 150          * Gets the Mobile Country Code (MCC) of the SIM IMSI information.
 151          *
 152          * @since       2.0
 153          *
 154          * @privlevel   public
 155          * @privilege   %http://tizen.org/privilege/telephony
 156          *
 157          * @return      The MCC of the SIM card, @n
 158          *              else @c -1 if the method fails
 159          * @exception   E_SUCCESS       The method is successful.
 160          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 161          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 162          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 163          */
 164         int GetMcc(void) const;
 165
 166         /**
 167          * Gets the Service Provider Name (SPN) string of the SIM card.
 168          *
 169          * @since       2.0
 170          *
 171          * @privlevel   public
 172          * @privilege   %http://tizen.org/privilege/telephony
 173          *
 174          * @return      The SPN of the SIM card, @n
 175          *              else an empty string if there is no SIM card in the device, or if an SPN is not assigned to the SIM card
 176          * @exception   E_SUCCESS       The method is successful.
 177          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 178          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 179          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 180          */
 181         Tizen::Base::String GetSpn(void) const;
 182
 183         /**
 184          * Gets the Integrated Circuit Card Identifier (ICCID) of the SIM card. @n
 185          * One useful case to detect the change of SIM cards is to store this value and compare it with the most recent value.
 186          * The %GetIccId() method provides a unique identification number for the SIM card.
 187          *
 188          * @since       2.0
 189          *
 190          * @privlevel   public
 191          * @privilege   %http://tizen.org/privilege/telephony
 192          *
 193          * @return  The ICCID of the SIM card, @n
 194          *          else an empty string if the method fails
 195          * @exception   E_SUCCESS       The method is successful.
 196          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 197          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 198          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 199          */
 200         Tizen::Base::String GetIccId(void) const;
 201
 202     /**
 203          * Gets the operator name of Common PCN Handset Specification (CPHS) of the SIM card.
 204          *
 205          * @since       2.0
 206          *
 207          * @privlevel   public
 208          * @privilege   %http://tizen.org/privilege/telephony
 209          *
 210          * @return      The operator name of the SIM card, @n
 211          *              else an empty string if there is no SIM card in the device, or if an operator name is not assigned to the SIM card
 212          * @exception   E_SUCCESS       The method is successful.
 213          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 214          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 215          * @remarks If this method has failed, then this method returns an empty string.
 216          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 217          */
 218         Tizen::Base::String GetOperatorName(void) const;
 219
 220         /**
 221          * Gets the phone number of the SIM card.
 222          *
 223          * @since       2.0
 224          *
 225          * @privlevel   public
 226          * @privilege   %http://tizen.org/privilege/telephony
 227          *
 228          * @return      The phone number of the SIM card, @n
 229          *              else an empty string if there is no SIM card in the device, or if a Mobile Station International Subscriber Directory Number
 230          *              (MSISDN) is not assigned to the SIM card
 231          * @exception   E_SUCCESS    The method is successful.
 232          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 233          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 234          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 235          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 236          */
 237         Tizen::Base::String GetPhoneNumber(void) const;
 238
 239         /**
 240          * Gets the International Mobile Subscriber Identity (IMSI) of the SIM card.
 241          *
 242          * @since       2.0
 243          *
 244          * @privlevel  partner
 245          * @privilege   %http://tizen.org/privilege/useridentity
 246          *
 247          * @return      The IMSI of the SIM card, @n
 248          *              else an empty string if the method fails
 249          * @exception   E_SUCCESS       The method is successful.
 250          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 251          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 252          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 253          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 254          */
 255         Tizen::Base::String GetImsi(void) const;
 256
 257         /**
 258          * Gets the type of SIM card.
 259          *
 260          * @since       2.1
 261          *
 262          * @privlevel   public
 263          * @privilege   %http://tizen.org/privilege/telephony
 264          *
 265          * @return              The type of SIM card
 266          *
 267          * @exception   E_SUCCESS       The method is successful.
 268          * @exception   E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 269          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 270          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 271          * @remarks             The specified error code can be accessed using the GetLastResult() method.
 272          */
 273         SimType GetSimType(void) const;
 274
 275         /**
 276          * Checks whether a SIM card is present in the device or not.
 277          *
 278          * @since       2.0
 279          *
 280          * @privlevel   public
 281          * @privilege   %http://tizen.org/privilege/telephony
 282          *
 283          * @return  @c true if the SIM card is present in the device, @n
 284          *          else @c false
 285          * @exception   E_SUCCESS       The method is successful.
 286          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 287          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 288          */
 289         bool IsAvailable(void) const;
 290
 291         /**
 292          * Copying of objects using this copy assignment operator is allowed.
 293          *
 294          * @since               2.1
 295          *
 296          * @param[in]   rhs An instance of %SimInfo
 297          */
 298         SimInfo& operator =(const SimInfo& rhs);
 299
 300         /**
 301          * Compares the specified instance of %SimInfo with the calling instance.
 302          *
 303          * @since               2.0
 304          *
 305          * @return              @c true if the values match, @n
 306          *                              else @c false
 307          * @param[in]   rhs     The other Tizen::Base::Object to compare
 308          * @see                 Tizen::Base::Object::Equals()
 309          */
 310         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 311
 312         /**
 313          * Gets the hash value of the current instance.
 314          *
 315          * @since               2.0
 316          *
 317          * @return      The hash value of the current instance
 318          */
 319         virtual int GetHashCode(void) const;
 320
 321 private:
 322         _SimInfoImpl* __pSimInfoImpl;
 323
 324         friend class _SimInfoImpl;
 325 }; // SimInfo
 326
 327 }} // Tizen::Telephony
 328
 329 #endif // _FTEL_SIM_INFO_H_