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 Mobile Subscription Identification Number (MSIN) of SIM provider.
 123  * @details This function gets Mobile Subscription Identification Number embedded in SIM card.
 124  *
 125  * @remarks @c msin must be released with free() by you.
 126  * @param[out] msin The  Mobile Subscription Identification Number
 127  * @return 0 on success, otherwise a negative error value.
 128  * @retval #SIM_ERROR_NONE Successful
 129  * @retval #SIM_ERROR_OUT_OF_MEMORY Out of memory
 130  * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
 131  * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
 132  * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
 133  * @pre The SIM state must be #SIM_STATE_AVAILABLE.
 134  * @see sim_get_state()
 135  *
 136  */
 137 int sim_get_msin(char **msin);
 138
 139 /**
 140  * @brief Gets the Service Provider Name (SPN) of SIM card.
 141  * @details This function gets Service Provider Name embedded in SIM card.
 142  * If this value is not stored in SIM card, NULL will be returned.
 143  * @remarks @c spn must be released with free() by you.
 144  * @param[out] spn The Service Provider Name
 145  * @return 0 on success, otherwise a negative error value.
 146  * @retval #SIM_ERROR_NONE Successful
 147  * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
 148  * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
 149  * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
 150  * @pre The SIM state must be #SIM_STATE_AVAILABLE.
 151  * @see sim_get_state()
 152  *
 153  */
 154 int sim_get_spn(char **spn);
 155
 156 /**
 157  * @brief Gets the Operator Name String (ONS) of Common PCN Handset Specification (CPHS) in SIM card.
 158  * @details This function gets the full name and the short name of CPHS operator embedded in SIM card.
 159  * If this value is not stored in SIM card, NULL will be returned.
 160  * @remarks @c full_name and @c short_name must be released with free() by you.
 161  * @param[out] full_name The full name of CPHS operator
 162  * @param[out] short_name The short name of CPHS operator
 163  * @return 0 on success, otherwise a negative error value.
 164  * @retval #SIM_ERROR_NONE Successful
 165  * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
 167  * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
 168  * @pre The SIM state must be #SIM_STATE_AVAILABLE.
 169  * @see sim_get_state()
 170  *
 171  */
 172 int sim_get_cphs_operator_name(char** full_name, char** short_name);
 173
 174 /**
 175  * @brief Gets the state of SIM.
 176  *
 177  * @param[out] sim_state The current state of SIM
 178  * @return 0 on success, otherwise a negative error value.
 179  * @retval #SIM_ERROR_NONE Successful
 180  * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
 181  * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
 182  *
 183  */
 184 int sim_get_state(sim_state_e *sim_state);
 185
 186 /**
 187  * @brief Gets the SIM card subscriber number.
 188  * @details This function gets subscriber number embedded in SIM card. This value contains MSISDN related to the subscriber. \n
 189  * If this value is not stored in SIM card, NULL will be returned.
 190  *
 191  * @remarks @c subscriber_number must be released with free() by you.
 192  *
 193  * @param[out] subscriber_number The subscriber number in SIM
 194  * @return 0 on success, otherwise a negative error value.
 195  * @retval #SIM_ERROR_NONE Successful
 196  * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
 198  * @retval #SIM_ERROR_NOT_AVAILABLE SIM is not available
 199  * @pre The SIM state must be #SIM_STATE_AVAILABLE.
 200  * @see sim_get_state()
 201  *
 202  */
 203 int sim_get_subscriber_number(char **subscriber_number);
 204
 205 /**
 206  * @brief Called when sim card state changes.
 207  * @param [in] state The status of sim
 208  * @param [in] user_data The user data passed from the callback registration function
 209  * @pre This callback function is invoked if you register this function using sim_set_state_changed_cb().
 210  *
 211  * @see sim_set_state_changed_cb()
 212  * @see sim_unset_state_changed_cb()
 213  */
 214 typedef void(* sim_state_changed_cb)(sim_state_e state, void *user_data);
 215
 216 /**
 217  * @brief Registers a callback function to be invoked when sim card state changes.
 218  *
 219  * @remarks You can register several callback functions.
 220  *
 221  * @param [in] callback The callback function to register
 222  * @param [in] user_data The user data to be passed to the callback function
 223  * @param [out] id A callback ID
 224  * @return 0 on success, otherwise a negative error value.
 225  * @retval #SIM_ERROR_NONE Successful
 226  * @retval #SIM_ERROR_INVALID_PARAMETER Invalid parameter
 227  * @retval #SIM_ERROR_OPERATION_FAILED Operation failed
 228  * @post sim_state_changed_cb() will be invoked.
 229  * @see sim_state_changed_cb()
 230  * @see sim_unset_state_changed_cb()
 231  */
 232 int sim_set_state_changed_cb(sim_state_changed_cb callback, void *user_data);
 233
 234 /**
 235  * @brief Unregisters the callback function.
 236  *
 237  * @param [in] id The callback ID
 238  * @return 0 on success, otherwise a negative error value.
 239  * @retval #SIM_ERROR_NONE Successful
 240  * @retval #SIM_ERROR_OPERATION_FAILED Operation failed.
 241  * @see sim_set_state_changed_cb()
 242  *
 243  */
 244 int sim_unset_state_changed_cb();
 245
 246 /**
 247  * @}
 248  */
 249
 250
 251 #ifdef __cplusplus
 252  }
 253 #endif
 254
 255
 256 #endif // __TIZEN_TELEPHONY_SIM_H__
 257