2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_TELEPHONY_SIM_H__
19 #define __TIZEN_TELEPHONY_SIM_H__
32 * @brief This file contains the SIM APIs and related enumeration.
36 * @addtogroup CAPI_TELEPHONY_SIM_MODULE
42 * @brief Enumeration of error code for sim card.
46 SIM_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
47 SIM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
48 SIM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
49 SIM_ERROR_OPERATION_FAILED = TIZEN_ERROR_TELEPHONY_CLASS | 0x3000, /**< Operation failed */
50 SIM_ERROR_NOT_AVAILABLE = TIZEN_ERROR_TELEPHONY_CLASS | 0x3001, /**< SIM is not available */
54 * @brief Enumeration of the state of SIM card.
59 SIM_STATE_UNAVAILABLE, /**< SIM is not available on this device */
60 SIM_STATE_LOCKED, /**< SIM is locked */
61 SIM_STATE_AVAILABLE, /**< SIM is available on this device */
62 SIM_STATE_UNKNOWN, /**< SIM is in transition between states */
67 * @brief Gets the Integrated Circuit Card IDentification (ICC-ID).
68 * @details The Integrated Circuit Card Identification number internationally identifies SIM cards.
69 * @remarks @c icc_id must be released with free() by you.
71 * @param[out] icc_id The Integrated Circuit Card IDentification
72 * @return 0 on success, otherwise a negative error value.
73 * @retval #SIM_ERROR_NONE Successful
74 * @retval #SIM_ERROR_OUT_OF_MEMORY Out of memory
75 * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
76 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
77 * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
78 * @pre The SIM state must be #SIM_STATE_AVAILABLE.
79 * @see sim_get_state()
82 int sim_get_icc_id(char **icc_id);
85 * @brief Gets the Mobile Country Code (MCC) of SIM provider.
86 * @details The Mobile Country Code is embedded in the SIM card.
88 * @remarks @c mcc must be released with free() by you.
90 * @param[out] mcc The Mobile Country Code
91 * @return 0 on success, otherwise a negative error value.
92 * @retval #SIM_ERROR_NONE Successful
93 * @retval #SIM_ERROR_OUT_OF_MEMORY Out of memory
94 * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
95 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
96 * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
97 * @pre The SIM state must be #SIM_STATE_AVAILABLE.
98 * @see sim_get_state()
101 int sim_get_mcc(char **mcc);
104 * @brief Gets the Mobile Network Code (MNC) of SIM provider.
105 * @details This function gets Mobile Network Code embedded in SIM card.
107 * @remarks @c mnc must be released with free() by you.
108 * @param[out] mnc The Mobile Network Code
109 * @return 0 on success, otherwise a negative error value.
110 * @retval #SIM_ERROR_NONE Successful
111 * @retval #SIM_ERROR_OUT_OF_MEMORY Out of memory
112 * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
113 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
114 * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
115 * @pre The SIM state must be #SIM_STATE_AVAILABLE.
116 * @see sim_get_state()
119 int sim_get_mnc(char **mnc);
122 * @brief Gets the Service Provider Name (SPN) of SIM card.
123 * @details This function gets Service Provider Name embedded in SIM card.
124 * If this value is not stored in SIM card, NULL will be returned.
125 * @remarks @c spn must be released with free() by you.
126 * @param[out] spn The Service Provider Name
127 * @return 0 on success, otherwise a negative error value.
128 * @retval #SIM_ERROR_NONE Successful
129 * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
130 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
131 * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
132 * @pre The SIM state must be #SIM_STATE_AVAILABLE.
133 * @see sim_get_state()
136 int sim_get_spn(char **spn);
139 * @brief Gets the state of SIM.
141 * @param[out] sim_state The current state of SIM
142 * @return 0 on success, otherwise a negative error value.
143 * @retval #SIM_ERROR_NONE Successful
144 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
145 * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
148 int sim_get_state(sim_state_e *sim_state);
151 * @brief Gets the SIM card subscriber number.
152 * @details This function gets subscriber number embedded in SIM card. This value contains MSISDN related to the subscriber. \n
153 * If this value is not stored in SIM card, NULL will be returned.
155 * @remarks @c subscriber_number must be released with free() by you.
157 * @param[out] subscriber_number The subscriber number in SIM
158 * @return 0 on success, otherwise a negative error value.
159 * @retval #SIM_ERROR_NONE Successful
160 * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
161 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
162 * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
163 * @pre The SIM state must be #SIM_STATE_AVAILABLE.
164 * @see sim_get_state()
167 int sim_get_subscriber_number(char **subscriber_number);
170 * @brief Called when sim card state changes.
171 * @param [in] state The status of sim
172 * @param [in] user_data The user data passed from the callback registration function
173 * @pre This callback function is invoked if you register this function using sim_set_state_changed_cb().
175 * @see sim_set_state_changed_cb()
176 * @see sim_unset_state_changed_cb()
178 typedef void(* sim_state_changed_cb)(sim_state_e state, void *user_data);
181 * @brief Registers a callback function to be invoked when sim card state changes.
183 * @remarks You can register several callback functions.
185 * @param [in] callback The callback function to register
186 * @param [in] user_data The user data to be passed to the callback function
187 * @param [out] id A callback ID
188 * @return 0 on success, otherwise a negative error value.
189 * @retval #SIM_ERROR_NONE Successful
190 * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
191 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
192 * @post sim_state_changed_cb() will be invoked.
193 * @see sim_state_changed_cb()
194 * @see sim_unset_state_changed_cb()
196 int sim_set_state_changed_cb(sim_state_changed_cb callback, void *user_data);
199 * @brief Unregisters the callback function.
201 * @param [in] id The callback ID
202 * @return 0 on success, otherwise a negative error value.
203 * @retval #SIM_ERROR_NONE Successful
204 * @retval #SIM_ERROR_OPERATION_FAILED Operation failed.
205 * @see sim_set_state_changed_cb()
208 int sim_unset_state_changed_cb();
220 #endif // __TIZEN_TELEPHONY_SIM_H__