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  * @brief Gets the Integrated Circuit Card IDentification (ICC-ID).
  50  * @details The Integrated Circuit Card Identification number internationally identifies SIM cards.
  51  *
  52  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  53  * @privlevel public
  54  * @privilege %http://tizen.org/privilege/telephony
  55  *
  56  * @remarks You must release @c icc_id using free().
  57  *
  58  * @param[in] handle The handle from telephony_init()
  59  * @param[out] icc_id The Integrated Circuit Card Identification
  60  *
  61  * @return @c 0 on success,
  62  *         otherwise a negative error value
  63  *
  64  * @retval #TELEPHONY_ERROR_NONE              Successful
  65  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Out of memory
  66  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
  67  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
  68  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Invalid parameter
  69  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
  70  *
  71  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
  72  *
  73  * @see telephony_sim_get_state()
  74  */
  75 int telephony_sim_get_icc_id(telephony_h handle, char **icc_id);
  76
  77 /**
  78  * @brief Gets the SIM Operator (MCC [3 digits] + MNC [2~3 digits]).
  79  * @details The Operator is embedded in the SIM card.
  80  *
  81  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  82  * @privlevel public
  83  * @privilege %http://tizen.org/privilege/telephony
  84  *
  85  * @remarks You must release @c sim_operator using free().
  86  *
  87  * @param[in] handle The handle from telephony_init()
  88  * @param[out] sim_operator The SIM Operator
  89  *
  90  * @return @c 0 on success,
  91  *         otherwise a negative error value
  92  *
  93  * @retval #TELEPHONY_ERROR_NONE              Successful
  94  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Out of memory
  95  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
  96  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
  97  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Invalid parameter
  98  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
  99  *
 100  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 101  *
 102  * @see telephony_sim_get_state()
 103  */
 104 int telephony_sim_get_operator(telephony_h handle, char **sim_operator);
 105
 106 /**
 107  * @brief Gets the Mobile Subscription Identification Number (MSIN [9~10 digits]) of the SIM provider.
 108  * @details This function gets Mobile Subscription Identification Number embedded in the SIM card.
 109  *
 110  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 111  * @privlevel public
 112  * @privilege %http://tizen.org/privilege/telephony
 113  *
 114  * @remarks You must release @c msin using free().
 115  *
 116  * @param[in] handle The handle from telephony_init()
 117  * @param[out] msin The Mobile Subscription Identification Number
 118  *
 119  * @return @c 0 on success,
 120  *         otherwise a negative error value
 121  *
 122  * @retval #TELEPHONY_ERROR_NONE              Successful
 123  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Out of memory
 124  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 125  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 126  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Invalid parameter
 127  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 128  *
 129  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 130  *
 131  * @see telephony_sim_get_state()
 132  */
 133 int telephony_sim_get_msin(telephony_h handle, char **msin);
 134
 135 /**
 136  * @brief Gets the Service Provider Name (SPN) of the SIM card.
 137  * @details This function gets Service Provider Name embedded in the SIM card.
 138  *          If this value is not stored in SIM card, @c NULL will be returned.
 139  *
 140  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 141  * @privlevel public
 142  * @privilege %http://tizen.org/privilege/telephony
 143  *
 144  * @remarks You must release @c spn using free().
 145  *
 146  * @param[in] handle The handle from telephony_init()
 147  * @param[out] spn The Service Provider Name
 148  *
 149  * @return @c 0 on success,
 150  *         otherwise a negative error value
 151  *
 152  * @retval #TELEPHONY_ERROR_NONE              Successful
 153  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Out of memory
 154  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 155  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 156  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Invalid parameter
 157  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 158  *
 159  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 160  *
 161  * @see telephony_sim_get_state()
 162  */
 163 int telephony_sim_get_spn(telephony_h handle, char **spn);
 164
 165 /**
 166  * @brief Checks whether the current SIM card is different from the previous SIM card.
 167  *
 168  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 169  * @privlevel public
 170  * @privilege %http://tizen.org/privilege/telephony
 171  *
 172  * @param[in] handle The handle from telephony_init()
 173  * @param[out] is_changed @c true if the current SIM card is different from the previous SIM card,
 174  *                        otherwise @c false if the SIM card is not changed
 175  *
 176  * @return @c 0 on success,
 177  *         otherwise a negative error value
 178  *
 179  * @retval #TELEPHONY_ERROR_NONE              Successful
 180  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Out of memory
 181  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 182  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 183  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Invalid parameter
 184  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 185  *
 186  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 187  *
 188  * @see telephony_sim_get_state()
 189  */
 190 int telephony_sim_is_changed(telephony_h handle, bool *is_changed);
 191
 192 /**
 193  * @brief Gets the state of the SIM.
 194  *
 195  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 196  * @privlevel public
 197  * @privilege %http://tizen.org/privilege/telephony
 198  *
 199  * @param[in] handle The handle from telephony_init()
 200  * @param[out] sim_state The current state of the SIM
 201  *
 202  * @return @c 0 on success,
 203  *         otherwise a negative error value
 204  *
 205  * @retval #TELEPHONY_ERROR_NONE              Successful
 206  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Out of memory
 207  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 208  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 209  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Invalid parameter
 210  */
 211 int telephony_sim_get_state(telephony_h handle, telephony_sim_state_e *sim_state);
 212
 213 /**
 214  * @brief Gets the SIM card subscriber number.
 215  * @details This function gets subscriber number embedded in the SIM card.
 216  *          This value contains MSISDN related to the subscriber.
 217  *          If this value is not stored in SIM card, @c NULL will be returned.
 218  *
 219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 220  * @privlevel public
 221  * @privilege %http://tizen.org/privilege/telephony
 222  *
 223  * @remarks You must release @c subscriber_number using free().
 224  *
 225  * @param[in] handle The handle from telephony_init()
 226  * @param[out] subscriber_number The subscriber number in the SIM
 227  *
 228  * @return @c 0 on success,
 229  *         otherwise a negative error value
 230  *
 231  * @retval #TELEPHONY_ERROR_NONE              Successful
 232  * @retval #TELEPHONY_ERROR_INVALID_PARAMETER Out of memory
 233  * @retval #TELEPHONY_ERROR_PERMISSION_DENIED Permission denied
 234  * @retval #TELEPHONY_ERROR_NOT_SUPPORTED     Not supported
 235  * @retval #TELEPHONY_ERROR_OPERATION_FAILED  Invalid parameter
 236  * @retval #TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
 237  *
 238  * @pre The SIM state must be #TELEPHONY_SIM_STATE_AVAILABLE.
 239  *
 240  * @see telephony_sim_get_state()
 241  */
 242 int telephony_sim_get_subscriber_number(telephony_h handle, char **subscriber_number);
 243
 244 /**
 245  * @}
 246  */
 247
 248 #ifdef __cplusplus
 249  }
 250 #endif
 251
 252 #endif // __CAPI_TELEPHONY_SIM_H__