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
  29
  30 namespace Tizen { namespace Telephony
  31 {
  32 class _SimInfoImpl;
  33
  34 /**
  35  * @class       SimInfo
  36  * @brief       This class provides information of the currently inserted SIM card.
  37  * @since       2.0
  38  *
  39  * The %SimInfo class provides methods to get information from the SIM card such as MCC, MNC, SPN, ICC ID, the name of operator,
  40  * and whether the SIM card is available or not.
  41  *
  42  * The following example demonstrates how to use the %SimInfo class to get the SIM information.
  43  *
  44  * @code
  45  *
  46  *      result
  47  *      MyClass::GetSimInfo(void)
  48  *      {
  49  *              int mnc;
  50  *              int mcc;
  51  *              bool isAvailable;
  52  *              String spn;
  53  *              String iccId;
  54  *              String operatorName;
  55  *
  56  *              SimInfo* pSimInfo = new SimInfo();
  57  *
  58  *              result r = pSimInfo->Construct();
  59  *              if (IsFailed(r))
  60  *              {
  61  *                      delete pSimInfo;
  62  *                      return r;
  63  *              }
  64  *
  65  *              mnc = pSimInfo->GetMnc();
  66  *              mcc = pSimInfo->GetMcc();
  67  *              spn = pSimInfo->GetSpn();
  68  *              iccId = pSimInfo->GetIccId();
  69  *              operatorName = pSimInfo->GetOperatorName();
  70  *              isAvailable = pSimInfo->IsAvailable();
  71  *
  72  *              delete pSimInfo;
  73  *              return E_SUCCESS;
  74  *      }
  75  *
  76  * @endcode
  77  */
  78 class _OSP_EXPORT_ SimInfo
  79         : public Tizen::Base::Object
  80 {
  81 public:
  82         /**
  83      * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  84      *
  85      * @since   2.0
  86      */
  87         SimInfo(void);
  88
  89         /**
  90      * This destructor overrides Tizen::Base::Object::~Object().
  91      *
  92      * @since   2.0
  93      */
  94         virtual ~SimInfo(void);
  95
  96         /**
  97      * Initializes this instance of %SimInfo.
  98      *
  99      * @since   2.0
 100          *
 101      * @return  An error code
 102      * @exception       E_SUCCESS       The method is successful.
 103      * @exception       E_SYSTEM        A system error has occurred.
 104      * @exception       E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 105      */
 106         result Construct(void);
 107
 108         /**
 109      * Gets the Mobile Network Code (MNC) of the SIM International Mobile Subscriber Identity (IMSI) information.
 110      *
 111      * @since   2.0
 112          *
 113      * @privilege   %http://tizen.org/privilege/systeminfo
 114      *
 115      * @return      The MNC of the SIM card, @n
 116      *              else @c -1 if the method fails
 117      * @exception       E_SUCCESS       The method is successful.
 118      * @exception       E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 119      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 120      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 121      */
 122         int GetMnc(void) const;
 123
 124         /**
 125      * Gets the Mobile Country Code (MCC) of the SIM IMSI information.
 126      *
 127      * @since   2.0
 128          *
 129      * @privilege   %http://tizen.org/privilege/systeminfo
 130      *
 131      * @return      The MCC of the SIM card, @n
 132      *              else @c -1 if the method fails
 133      * @exception       E_SUCCESS       The method is successful.
 134      * @exception       E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 135      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 136      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 137      */
 138         int GetMcc(void) const;
 139
 140         /**
 141      * Gets the Service Provider Name (SPN) string of the SIM card.
 142      *
 143      * @since   2.0
 144          *
 145      * @privilege   %http://tizen.org/privilege/systeminfo
 146      *
 147      * @return      The SPN of the SIM card, @n
 148      *              else an empty string if there is no SIM card in the device, or if an SPN is not assigned to the SIM card
 149      * @exception   E_SUCCESS   The method is successful.
 150      * @exception   E_DEVICE_UNAVAILABLE        The operation has failed due to a missing SIM card.
 151      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 152      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 153      */
 154         Tizen::Base::String GetSpn(void) const;
 155
 156         /**
 157      * Gets the Integrated Circuit Card Identifier (ICCID) of the SIM card. @n
 158      * One useful case to detect the change of SIM cards is to store this value and compare it with the most recent value.
 159      * This method provides a unique identification number for the SIM card.
 160      *
 161      * @since   2.0
 162          *
 163      * @privilege   %http://tizen.org/privilege/systeminfo
 164      *
 165      * @return  The ICCID of the SIM card, @n
 166      *          else an empty string if the method fails
 167      * @exception   E_SUCCESS   The method is successful.
 168      * @exception   E_DEVICE_UNAVAILABLE        The operation has failed due to a missing SIM card.
 169      * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 170      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 171      */
 172         Tizen::Base::String GetIccId(void) const;
 173
 174     /**
 175      * Gets the operator name of Common PCN Handset Specification (CPHS) of the SIM card.
 176      *
 177      * @since   2.0
 178          *
 179      * @privilege   %http://tizen.org/privilege/systeminfo
 180      *
 181      * @return      The operator name of the SIM card, @n
 182      *              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
 183      * @exception       E_SUCCESS       The method is successful.
 184      * @exception       E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 185      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 186      * @remarks If this method has failed, then this method returns an empty string.
 187      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 188      */
 189         Tizen::Base::String GetOperatorName(void) const;
 190
 191         /**
 192      * Gets the phone number of the SIM card.
 193      *
 194      * @since   2.0
 195          *
 196      * @privilege   %http://tizen.org/privilege/systeminfo
 197      *
 198      * @return      The phone number of the SIM card, @n
 199      *              else an empty string if there is no SIM card in the device, or if a Mobile Station International Subscriber Directory Number
 200      *              (MSISDN) is not assigned to the SIM card
 201      * @exception       E_SUCCESS    The method is successful.
 202      * @exception       E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 203      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 204      * @exception       E_SYSTEM        A system error has occurred.
 205      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 206      */
 207         Tizen::Base::String GetPhoneNumber(void) const;
 208
 209         /**
 210      * @if VISPARTNER
 211      * Gets the International Mobile Subscriber Identity (IMSI) of the SIM card.
 212      *
 213      * @since   2.0
 214          *
 215      * @visibility  partner
 216      * @privilege   %http://tizen.org/privilege/useridentity
 217      *
 218      * @return      The IMSI of the SIM card, @n
 219      *              else an empty string if the method fails
 220      * @exception       E_SUCCESS       The method is successful.
 221      * @exception       E_DEVICE_UNAVAILABLE    The operation has failed due to a missing SIM card.
 222      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 223      * @exception       E_SYSTEM The method cannot proceed due to a severe system error.
 224      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 225      * @endif
 226      */
 227         Tizen::Base::String GetImsi(void) const;
 228
 229         /**
 230      * Checks whether a SIM card is present in the device or not.
 231      *
 232      * @since   2.0
 233          *
 234      * @privilege   %http://tizen.org/privilege/systeminfo
 235      *
 236      * @return  @c true if the SIM card is present in the device, @n
 237      *          else @c false
 238      * @exception       E_SUCCESS       The method is successful.
 239      * @exception       E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 240      * @remarks         The specific error code can be accessed using the GetLastResult() method.
 241      */
 242         bool IsAvailable(void) const;
 243
 244 private:
 245         /**
 246      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 247      *
 248      * @param[in]   rhs   An instance of %SimInfo
 249      */
 250         SimInfo(const SimInfo& rhs);
 251
 252         /**
 253      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 254      *
 255      * @param[in]   rhs An instance of %SimInfo
 256      */
 257         SimInfo& operator =(const SimInfo& rhs);
 258
 259 private:
 260         _SimInfoImpl* __pSimInfoImpl;
 261
 262         friend class _SimInfoImpl;
 263 }; // SimInfo
 264
 265 }} // Tizen::Telephony
 266 #endif // _FTEL_SIM_INFO_H_