Merge from 2.2
[platform/framework/native/telephony.git] / 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_