include/sim.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17
  18 #ifndef __TIZEN_TELEPHONY_SIM_H__
  19 #define __TIZEN_TELEPHONY_SIM_H__
  20
  21
  22 #include <tizen.h>
  23
  24
  25 #ifdef __cplusplus
  26  extern "C" {
  27 #endif
  28
  29
  30 /**
  31  * @file sim.h
  32  * @brief This file contains the SIM APIs and related enumeration.
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_TELEPHONY_SIM_MODULE
  37  * @{
  38  */
  39
  40
  41 /**
  42  * @brief Enumeration of error code for sim card.
  43  */
  44 typedef enum
  45 {
  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 */
  51 } sim_error_e;
  52
  53 /**
  54  * @brief Enumeration of the state of SIM card.
  55  *
  56  */
  57 typedef enum
  58 {
  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 */
  63 } sim_state_e;
  64
  65
  66 /**
  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.
  70  *
  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()
  80  *
  81  */
  82 int sim_get_icc_id(char **icc_id);
  83
  84 /**
  85  * @brief Gets the Mobile Country Code (MCC) of SIM provider.
  86  * @details The Mobile Country Code is embedded in the SIM card.
  87  *
  88  * @remarks @c mcc must be released with free() by you.
  89  *
  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()
  99  *
 100  */
 101 int sim_get_mcc(char **mcc);
 102
 103 /**
 104  * @brief Gets the Mobile Network Code (MNC) of SIM provider.
 105  * @details This function gets Mobile Network Code embedded in SIM card.
 106  *
 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()
 117  *
 118  */
 119 int sim_get_mnc(char **mnc);
 120
 121 /**
 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()
 134  *
 135  */
 136 int sim_get_spn(char **spn);
 137
 138 /**
 139  * @brief Gets the state of SIM.
 140  *
 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
 146  *
 147  */
 148 int sim_get_state(sim_state_e *sim_state);
 149
 150 /**
 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.
 154  *
 155  * @remarks @c subscriber_number must be released with free() by you.
 156  *
 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()
 165  *
 166  */
 167 int sim_get_subscriber_number(char **subscriber_number);
 168
 169 /**
 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().
 174  *
 175  * @see sim_set_state_changed_cb()
 176  * @see sim_unset_state_changed_cb()
 177  */
 178 typedef void(* sim_state_changed_cb)(sim_state_e state, void *user_data);
 179
 180 /**
 181  * @brief Registers a callback function to be invoked when sim card state changes.
 182  *
 183  * @remarks You can register several callback functions.
 184  *
 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()
 195  */
 196 int sim_set_state_changed_cb(sim_state_changed_cb callback, void *user_data);
 197
 198 /**
 199  * @brief Unregisters the callback function.
 200  *
 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()
 206  *
 207  */
 208 int sim_unset_state_changed_cb();
 209
 210 /**
 211  * @}
 212  */
 213
 214
 215 #ifdef __cplusplus
 216  }
 217 #endif
 218
 219
 220 #endif // __TIZEN_TELEPHONY_SIM_H__
 221