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