include/telephony_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 #ifndef __CAPI_TELEPHONY_SIM_H__
  18 #define __CAPI_TELEPHONY_SIM_H__
  19
  20 #include "telephony_common.h"
  21
  22 #ifdef __cplusplus
  23  extern "C" {
  24 #endif
  25
  26 /**
  27  * @file telephony_sim.h
  28  * @brief This file contains the SIM APIs and related enumerations.
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_TELEPHONY_INFORMATION_SIM
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Enumeration for the state of SIM card.
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39  */
  40 typedef enum
  41 {
  42     TELEPHONY_SIM_STATE_UNAVAILABLE, /**< SIM is not available on this device */
  43     TELEPHONY_SIM_STATE_LOCKED,      /**< SIM is locked */
  44     TELEPHONY_SIM_STATE_AVAILABLE,   /**< SIM is available on this device */
  45     TELEPHONY_SIM_STATE_UNKNOWN,     /**< SIM is in transition between states */
  46 } telephony_sim_state_e;
  47
  48
  49 /**
  50  * @brief Enumeration for the type of SIM card .
  51  * @since_tizen 2.4
  52  */
  53 typedef enum {
  54         TELEPHONY_SIM_APP_TYPE_SIM = 0x01, /**< SIM(GSM) Application */
  55         TELEPHONY_SIM_APP_TYPE_USIM = 0x02, /**< USIM Application */
  56         TELEPHONY_SIM_APP_TYPE_CSIM = 0x04, /**< CDMA Application */
  57         TELEPHONY_SIM_APP_TYPE_ISIM = 0x08, /**< ISIM Application */
  58 } telephony_sim_application_type_e;
  59
  60
  61 /**
  62  * @brief Gets the Integrated Circuit Card IDentification (ICC-ID).
  63  * @details The Integrated Circuit Card Identification number internationally identifies SIM cards.
  64  *
  65  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  66  * @privlevel public
  67  * @privilege %http://tizen.org/privilege/telephony
  68  *
  69  * @remarks You must release @c icc_id using free().
  70  *
  71  * @param[in] handle The handle from telephony_init()
  72  * @param[out] icc_id The Integrated Circuit Card Identification
  73  *
  74  * @return @c 0 on success,
  75  *         otherwise a negative error value
  76  *
  77  * @retval #TELEPHONY_ERROR_NONE              Successful
  78  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
  79  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
  80  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
  81  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
  82  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
  83  *
  84  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
  85  *
  86  * @see telephony_sim_get_state()
  87  */
  88 int telephony_sim_get_icc_id(telephony_h handle, char **icc_id);
  89
  90 /**
  91  * @brief Gets the SIM Operator (MCC [3 digits] + MNC [2~3 digits]).
  92  * @details The Operator is embedded in the SIM card.
  93  *
  94  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  95  * @privlevel public
  96  * @privilege %http://tizen.org/privilege/telephony
  97  *
  98  * @remarks You must release @c sim_operator using free().
  99  *
 100  * @param[in] handle The handle from telephony_init()
 101  * @param[out] sim_operator The SIM Operator
 102  *
 103  * @return @c 0 on success,
 104  *         otherwise a negative error value
 105  *
 106  * @retval #TELEPHONY_ERROR_NONE              Successful
 107  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 108  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 109  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 110  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 111  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 112  *
 113  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 114  *
 115  * @see telephony_sim_get_state()
 116  */
 117 int telephony_sim_get_operator(telephony_h handle, char **sim_operator);
 118
 119 /**
 120  * @brief Gets the Mobile Subscription Identification Number (MSIN [9~10 digits]) of the SIM provider.
 121  * @details This function gets Mobile Subscription Identification Number embedded in the SIM card.
 122  *
 123  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 124  * @privlevel public
 125  * @privilege %http://tizen.org/privilege/telephony
 126  *
 127  * @remarks You must release @c msin using free().
 128  *
 129  * @param[in] handle The handle from telephony_init()
 130  * @param[out] msin The Mobile Subscription Identification Number
 131  *
 132  * @return @c 0 on success,
 133  *         otherwise a negative error value
 134  *
 135  * @retval #TELEPHONY_ERROR_NONE              Successful
 136  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 137  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 138  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 139  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 140  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 141  *
 142  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 143  *
 144  * @see telephony_sim_get_state()
 145  */
 146 int telephony_sim_get_msin(telephony_h handle, char **msin);
 147
 148 /**
 149  * @brief Gets the Service Provider Name (SPN) of the SIM card.
 150  * @details This function gets Service Provider Name embedded in the SIM card.
 151  *          If this value is not stored in SIM card,
 152  *          negative error returned and @c NULL will be stored in @c spn.
 153  *
 154  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 155  * @privlevel public
 156  * @privilege %http://tizen.org/privilege/telephony
 157  *
 158  * @remarks You must release @c spn using free().
 159  *
 160  * @param[in] handle The handle from telephony_init()
 161  * @param[out] spn The Service Provider Name
 162  *
 163  * @return @c 0 on success,
 164  *         otherwise a negative error value
 165  *
 166  * @retval #TELEPHONY_ERROR_NONE              Successful
 167  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 168  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 169  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 170  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 171  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 172  *
 173  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 174  *
 175  * @see telephony_sim_get_state()
 176  */
 177 int telephony_sim_get_spn(telephony_h handle, char **spn);
 178
 179 /**
 180  * @brief Checks whether the current SIM card is different from the previous SIM card.
 181  *
 182  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 183  * @privlevel public
 184  * @privilege %http://tizen.org/privilege/telephony
 185  *
 186  * @param[in] handle The handle from telephony_init()
 187  * @param[out] is_changed @c true if the current SIM card is different from the previous SIM card,
 188  *                        otherwise @c false if the SIM card is not changed
 189  *
 190  * @return @c 0 on success,
 191  *         otherwise a negative error value
 192  *
 193  * @retval #TELEPHONY_ERROR_NONE              Successful
 194  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 196  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 197  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 198  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 199  *
 200  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 201  *
 202  * @see telephony_sim_get_state()
 203  */
 204 int telephony_sim_is_changed(telephony_h handle, bool *is_changed);
 205
 206 /**
 207  * @brief Gets the state of the SIM.
 208  *
 209  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 210  * @privlevel public
 211  * @privilege %http://tizen.org/privilege/telephony
 212  *
 213  * @param[in] handle The handle from telephony_init()
 214  * @param[out] sim_state The current state of the SIM
 215  *
 216  * @return @c 0 on success,
 217  *         otherwise a negative error value
 218  *
 219  * @retval #TELEPHONY_ERROR_NONE              Successful
 220  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 221  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 222  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 223  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 224  */
 225 int telephony_sim_get_state(telephony_h handle, telephony_sim_state_e *sim_state);
 226
 227 /**
 228  * @brief Gets the list of application on UICC.
 229  *
 230  * @since_tizen 2.4
 231  * @privlevel public
 232  * @privilege %http://tizen.org/privilege/telephony
 233  *
 234  * @param[in] handle The handle from telephony_init()
 235  * @param[out] app_list The masking value for below values
 236  *                      #TELEPHONY_SIM_APP_TYPE_SIM 0x01 GSM Application
 237  *                      #TELEPHONY_SIM_APP_TYPE_USIM 0x02 USIM Application
 238  *                      #TELEPHONY_SIM_APP_TYPE_CSIM 0x04 CSIM Application
 239  *                      #TELEPHONY_SIM_APP_TYPE_ISIM 0x08 ISIM Application
 240  *
 241  * @return @c 0 on success,
 242  *         otherwise a negative error value
 243  *
 244  * @retval #TELEPHONY_ERROR_NONE              Successful
 245  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 246  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 247  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 248  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 249  */
 250 int telephony_sim_get_application_list(telephony_h handle, unsigned int *app_list);
 251
 252 /**
 253  * @brief Gets the SIM card subscriber number.
 254  * @details This function gets subscriber number embedded in the SIM card.
 255  *          This value contains MSISDN related to the subscriber.
 256  *          If this value is not stored in SIM card,
 257  *          negative error returned and @c NULL will be stored in @c subscriber_number.
 258  *
 259  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 260  * @privlevel public
 261  * @privilege %http://tizen.org/privilege/telephony
 262  *
 263  * @remarks You must release @c subscriber_number using free().
 264  *
 265  * @param[in] handle The handle from telephony_init()
 266  * @param[out] subscriber_number The subscriber number in the SIM
 267  *
 268  * @return @c 0 on success,
 269  *         otherwise a negative error value
 270  *
 271  * @retval #TELEPHONY_ERROR_NONE              Successful
 272  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 273  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 274  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 275  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 276  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 277  *
 278  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 279  *
 280  * @see telephony_sim_get_state()
 281  */
 282 int telephony_sim_get_subscriber_number(telephony_h handle, char **subscriber_number);
 283
 284 /**
 285  * @brief Gets the Subscriber ID.
 286  * @details This function gets subscriber ID encoded.
 287  *
 288  * @since_tizen 2.4
 289  * @privlevel public
 290  * @privilege %http://tizen.org/privilege/telephony
 291  *
 292  * @remarks You must release @c subscriber_id using free().
 293  *
 294  * @param[in] handle The handle from telephony_init()
 295  * @param[out] subscriber_id The subscriber ID
 296  *
 297  * @retval #TELEPHONY_ERROR_NONE              Successful
 298  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter
 299  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 300  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 301  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Operation failed
 302  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 303  *
 304  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 305  *
 306  * @see telephony_sim_get_state()
 307  */
 308 int telephony_sim_get_subscriber_id(telephony_h handle, char **subscriber_id);
 309
 310 /**
 311  * @}
 312  */
 313
 314 #ifdef __cplusplus
 315  }
 316 #endif
 317
 318 #endif // __CAPI_TELEPHONY_SIM_H__