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

enum telephony_sim_application_type_e

Enumeration for the type of SIM card.

Since :: 2.4

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

enum telephony_sim_lock_state_e

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

enum telephony_sim_state_e

Enumeration for the state of SIM card.

Since :: 2.3

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 :: 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, otherwise `false` 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()

Required Header

Overview

Related Features

Functions

Enumeration Type Documentation

Function Documentation