Tizen Native API  5.5

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 type of SIM card.

Since :
3.0
Enumerator:
TELEPHONY_SIM_APP_TYPE_SIM 

SIM(GSM) Application

TELEPHONY_SIM_APP_TYPE_USIM 

USIM Application

TELEPHONY_SIM_APP_TYPE_CSIM 

CDMA Application

TELEPHONY_SIM_APP_TYPE_ISIM 

ISIM Application

Enumeration for the lock state of SIM card.

Since :
3.0
Enumerator:
TELEPHONY_SIM_LOCK_STATE_UNKNOWN 

SIM is not in lock

TELEPHONY_SIM_LOCK_STATE_PIN_REQUIRED 

SIM is PIN(Personal Identification Number) locked

TELEPHONY_SIM_LOCK_STATE_PUK_REQUIRED 

SIM is PUK(Personal Unblocking Code) locked

TELEPHONY_SIM_LOCK_STATE_PERM_LOCKED 

SIM is permanently blocked(All the attempts for PIN/PUK failed)

TELEPHONY_SIM_LOCK_STATE_NCK_REQUIRED 

SIM is NCK(Network Control Key) locked

Enumeration for the state of SIM card.

Since :
2.3.1
Enumerator:
TELEPHONY_SIM_STATE_UNAVAILABLE 

SIM is not available on this device

TELEPHONY_SIM_STATE_LOCKED 

SIM is locked

TELEPHONY_SIM_STATE_AVAILABLE 

SIM is available on this device (SIM is not locked)

TELEPHONY_SIM_STATE_UNKNOWN 

SIM is in transition between states


Function Documentation

int telephony_sim_get_application_list ( telephony_h  handle,
unsigned int *  app_list 
)

Gets the list of application on UICC.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Parameters:
[in]handleThe handle from telephony_init()
[out]app_listThe 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_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM is not available
Precondition:
The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
See also:
telephony_sim_get_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]handleThe handle from telephony_init()
[out]stateThe 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_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM 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]handleThe handle from telephony_init()
[out]gid1The GID1
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM 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.1
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]handleThe handle from telephony_init()
[out]icc_idThe Integrated Circuit Card Identification
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM is not available
Precondition:
The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
See also:
telephony_sim_get_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]handleThe handle from telephony_init()
[out]lock_stateThe current lock state of the SIM
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation 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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Remarks:
You must release msin using free() on success case.
Parameters:
[in]handleThe handle from telephony_init()
[out]msinThe Mobile Subscription Identification Number
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM 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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Remarks:
You must release sim_operator using free() on success case.
Parameters:
[in]handleThe handle from telephony_init()
[out]sim_operatorThe SIM Operator
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM 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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Remarks:
You must release spn using free() on success case.
Parameters:
[in]handleThe handle from telephony_init()
[out]spnThe Service Provider Name
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM 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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Parameters:
[in]handleThe handle from telephony_init()
[out]sim_stateThe current state of the SIM
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
int telephony_sim_get_subscriber_id ( telephony_h  handle,
char **  subscriber_id 
)

Gets the Subscriber ID.

This function gets subscriber ID encoded.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Remarks:
You must release subscriber_id using free() on success case.
Parameters:
[in]handleThe handle from telephony_init()
[out]subscriber_idThe subscriber ID
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM 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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Remarks:
You must release subscriber_number using free() on success case.
Parameters:
[in]handleThe handle from telephony_init()
[out]subscriber_numberThe subscriber number in the SIM
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM 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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/telephony
Parameters:
[in]handleThe handle from telephony_init()
[out]is_changedtrue if the current SIM card is different from the previous SIM card, otherwise false if the SIM card is not changed
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_PERMISSION_DENIEDPermission denied
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
TELEPHONY_ERROR_SIM_NOT_AVAILABLESIM is not available
Precondition:
The SIM state must be TELEPHONY_SIM_STATE_AVAILABLE.
See also:
telephony_sim_get_state()