Tizen Native API
7.0
|
The SIM API provides functions to obtain information from the SIM card, as well as SIM status.
Required Header
#include <telephony.h>
Overview
The Telephony SIM API allows you to extract information stored on a SIM card, but not to change the information.
Related Features
This API is related with the following feature:
- http://tizen.org/feature/network.telephony
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Functions | |
int | telephony_sim_get_icc_id (telephony_h handle, char **icc_id) |
Gets the Integrated Circuit Card IDentification (ICC-ID). | |
int | telephony_sim_get_operator (telephony_h handle, char **sim_operator) |
Gets the SIM Operator (MCC [3 digits] + MNC [2~3 digits]). | |
int | telephony_sim_get_msin (telephony_h handle, char **msin) |
Gets the Mobile Subscription Identification Number (MSIN [9~10 digits]) of the SIM provider. | |
int | telephony_sim_get_spn (telephony_h handle, char **spn) |
Gets the Service Provider Name (SPN) of the SIM card. | |
int | telephony_sim_is_changed (telephony_h handle, bool *is_changed) |
Checks whether the current SIM card is different from the previous SIM card. | |
int | telephony_sim_get_state (telephony_h handle, telephony_sim_state_e *sim_state) |
Gets the state of the SIM. | |
int | telephony_sim_get_application_list (telephony_h handle, unsigned int *app_list) |
Gets the list of application on UICC. | |
int | telephony_sim_get_subscriber_number (telephony_h handle, char **subscriber_number) |
Gets the SIM card subscriber number. | |
int | telephony_sim_get_subscriber_id (telephony_h handle, char **subscriber_id) |
Gets the Subscriber ID. | |
int | telephony_sim_get_lock_state (telephony_h handle, telephony_sim_lock_state_e *lock_state) |
Gets the lock state of the SIM. | |
int | telephony_sim_get_group_id1 (telephony_h handle, char **gid1) |
Gets the GID1 (Group Identifier Level 1). | |
int | telephony_sim_get_call_forwarding_indicator_state (telephony_h handle, bool *state) |
Gets the call forwarding indicator state of the SIM. |
Enumeration Type Documentation
Enumeration for the lock state of SIM card.
- Since :
- 3.0
- Enumerator:
Enumeration for the state of SIM card.
- Since :
- 2.3
Function Documentation
int telephony_sim_get_application_list | ( | telephony_h | handle, |
unsigned int * | app_list | ||
) |
Gets the list of application on UICC.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Parameters:
-
[in] handle The handle from telephony_init() [out] app_list The masking value for below values TELEPHONY_SIM_APP_TYPE_SIM 0x01 GSM Application TELEPHONY_SIM_APP_TYPE_USIM 0x02 USIM Application TELEPHONY_SIM_APP_TYPE_CSIM 0x04 CSIM Application TELEPHONY_SIM_APP_TYPE_ISIM 0x08 ISIM Application
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_call_forwarding_indicator_state | ( | telephony_h | handle, |
bool * | state | ||
) |
Gets the call forwarding indicator state of the SIM.
If the state is true
, incoming call will be forwarded to the selected number. state
indicates the CFU (Call Forwarding Unconditional) indicator status - Voice. (3GPP TS 31.102 4.2.64 EF CFIS)
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Parameters:
-
[in] handle The handle from telephony_init() [out] state The value whether incoming call will be forwarded or not. ( true:
forwarded,false:
not forwarded)
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_group_id1 | ( | telephony_h | handle, |
char ** | gid1 | ||
) |
Gets the GID1 (Group Identifier Level 1).
This function gets Group Identifier Level 1(GID1) embedded in the SIM card. If this value is not stored in SIM card, NULL
will be returned.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Remarks:
- You must release
gid1
using free() on success case.
- Parameters:
-
[in] handle The handle from telephony_init() [out] gid1 The GID1
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_icc_id | ( | telephony_h | handle, |
char ** | icc_id | ||
) |
Gets the Integrated Circuit Card IDentification (ICC-ID).
- Warning:
- This is not for use by third-party applications.
The Integrated Circuit Card Identification number internationally identifies SIM cards.
- Since :
- 2.3
- Privilege Level:
- partner
- Privilege:
- http://tizen.org/privilege/securesysteminfo
- Remarks:
- You must release
icc_id
using free() on success case. - Since 5.5, this function requires partner level privilege.
- Before 5.5, this function required the http://tizen.org/privilege/telephony privilege. Since 5.5, it requires the http://tizen.org/privilege/securesysteminfo privilege.
- To avoid unexpected behavior of old version applications which have the http://tizen.org/privilege/telephony privilege, there is an exception in handling the 'permission denied' error.
- For an application with api-version 5.5 or higher, if the application doesn't have http://tizen.org/privilege/securesysteminfo privilege, this function returns TELEPHONY_ERROR_PERMISSION_DENIED.
- For an application with api-version lower than 5.5, if the application has http://tizen.org/privilege/telephony privilege, this function returns a pseudo value with TELEPHONY_ERROR_NONE instead of TELEPHONY_ERROR_PERMISSION_DENIED. The returned value is not reliable data, it can't confirm the device's identification.
- Parameters:
-
[in] handle The handle from telephony_init() [out] icc_id The Integrated Circuit Card Identification
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_lock_state | ( | telephony_h | handle, |
telephony_sim_lock_state_e * | lock_state | ||
) |
Gets the lock state of the SIM.
This function gets SIM card lock state. If SIM state is TELEPHONY_SIM_STATE_LOCKED, you can use this function to retrieve lock state.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Parameters:
-
[in] handle The handle from telephony_init() [out] lock_state The current lock state of the SIM
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_LOCKED.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_msin | ( | telephony_h | handle, |
char ** | msin | ||
) |
Gets the Mobile Subscription Identification Number (MSIN [9~10 digits]) of the SIM provider.
This function gets Mobile Subscription Identification Number embedded in the SIM card.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Remarks:
- You must release
msin
using free() on success case.
- Parameters:
-
[in] handle The handle from telephony_init() [out] msin The Mobile Subscription Identification Number
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_operator | ( | telephony_h | handle, |
char ** | sim_operator | ||
) |
Gets the SIM Operator (MCC [3 digits] + MNC [2~3 digits]).
The Operator is embedded in the SIM card.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Remarks:
- You must release
sim_operator
using free() on success case.
- Parameters:
-
[in] handle The handle from telephony_init() [out] sim_operator The SIM Operator
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_spn | ( | telephony_h | handle, |
char ** | spn | ||
) |
Gets the Service Provider Name (SPN) of the SIM card.
This function gets Service Provider Name embedded in the SIM card. If this value is not stored in SIM card, NULL
will be returned.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Remarks:
- You must release
spn
using free() on success case.
- Parameters:
-
[in] handle The handle from telephony_init() [out] spn The Service Provider Name
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_state | ( | telephony_h | handle, |
telephony_sim_state_e * | sim_state | ||
) |
Gets the state of the SIM.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Parameters:
-
[in] handle The handle from telephony_init() [out] sim_state The current state of the SIM
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed
int telephony_sim_get_subscriber_id | ( | telephony_h | handle, |
char ** | subscriber_id | ||
) |
Gets the Subscriber ID.
This function gets subscriber ID encoded.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Remarks:
- You must release
subscriber_id
using free() on success case.
- Parameters:
-
[in] handle The handle from telephony_init() [out] subscriber_id The subscriber ID
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_get_subscriber_number | ( | telephony_h | handle, |
char ** | subscriber_number | ||
) |
Gets the SIM card subscriber number.
This function gets subscriber number embedded in the SIM card. This value contains MSISDN related to the subscriber. If this value is not stored in SIM card, NULL
will be returned.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Remarks:
- You must release
subscriber_number
using free() on success case.
- Parameters:
-
[in] handle The handle from telephony_init() [out] subscriber_number The subscriber number in the SIM
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()
int telephony_sim_is_changed | ( | telephony_h | handle, |
bool * | is_changed | ||
) |
Checks whether the current SIM card is different from the previous SIM card.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/telephony
- Parameters:
-
[in] handle The handle from telephony_init() [out] is_changed true
if the current SIM card is different from the previous SIM card, otherwisefalse
if the SIM card is not changed
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
TELEPHONY_ERROR_NONE Successful TELEPHONY_ERROR_INVALID_PARAMETER Invalid parameter TELEPHONY_ERROR_PERMISSION_DENIED Permission denied TELEPHONY_ERROR_NOT_SUPPORTED Not supported TELEPHONY_ERROR_OPERATION_FAILED Operation failed TELEPHONY_ERROR_SIM_NOT_AVAILABLE SIM is not available
- Precondition:
- The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
- See also:
- telephony_sim_get_state()