The Telephony provides call, modem, network, and SIM information.

Required Header

#include <telephony.h>

Overview

The Telephony provides call, modem, network, and SIM 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_set_noti_cb (telephony_h handle, telephony_noti_e noti_id, telephony_noti_cb cb, void *user_data)
	Sets a callback function to be invoked when the telephony state changes.
int	telephony_unset_noti_cb (telephony_h handle, telephony_noti_e noti_id)
	Unsets a callback function.
int	telephony_init (telephony_handle_list_s *list)
	Acquires the list of available handles to use the telephony API.
int	telephony_deinit (telephony_handle_list_s *list)
	Deinitializes the telephony handle list.
int	telephony_get_state (telephony_state_e *state)
	Acquires the telephony state value.
int	telephony_set_state_changed_cb (telephony_state_changed_cb callback, void *user_data)
	Sets a callback function to be invoked when the telephony state changes.
int	telephony_unset_state_changed_cb (telephony_state_changed_cb callback)
	Unsets a telephony state callback function.
Typedefs
typedef struct telephony_data *	telephony_h
	The Telephony API handle.
typedef void(*	telephony_noti_cb )(telephony_h handle, telephony_noti_e noti_id, void data, void user_data)
	Called when the telephony state changes.
typedef void(*	telephony_state_changed_cb )(telephony_state_e state, void *user_data)
	Called for the telephony state changes.

Typedef Documentation

typedef struct telephony_data* telephony_h

The Telephony API handle.

Since :: 2.3

typedef void(* telephony_noti_cb)(telephony_h handle, telephony_noti_e noti_id, void *data, void *user_data)

Called when the telephony state changes.

Since :: 2.3

typedef void(* telephony_state_changed_cb)(telephony_state_e state, void *user_data)

Called for the telephony state changes.

Since :: 2.4

Enumeration Type Documentation

enum telephony_error_e

Enumeration for Telephony error.

Since :: 2.3

Enumerator:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_OUT_OF_MEMORY	Out of memory
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

enum telephony_noti_e

Enumeration for Telephony notification.

Since :: 2.3

Enumerator:

TELEPHONY_NOTI_SIM_STATUS	Notification to be invoked when the SIM card state changes. 'telephony_sim_state_e' will be delivered in notification data Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_SIM_CALL_FORWARDING_INDICATOR_STATE	Notification to be invoked when the SIM call forwarding indicator state changes. 'state(bool)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_SERVICE_STATE	Notification to be invoked when the network service state changes. 'telephony_network_service_state_e' will be delivered in notification data Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_CELLID	Notification to be invoked when the cell ID changes. 'cell_id(int)' will be delivered in notification data Privilege : http://tizen.org/privilege/location.coarse (Since: 3.0) http://tizen.org/privilege/telephony privilege is no longer required since 3.0.
TELEPHONY_NOTI_NETWORK_ROAMING_STATUS	Notification to be invoked when the roaming status changes. 'roaming_status(bool)' will be delivered in notification data Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_SIGNALSTRENGTH_LEVEL	Notification to be invoked when the signal strength changes. 'telephony_network_rssi_e' will be delivered in notification data Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_NETWORK_NAME	Notification to be invoked when the network name changes. 'network_name(char )' wil be delivered in notification data (Since:* 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_PS_TYPE	Notification to be invoked when the ps type changes. 'telephony_network_ps_type_e' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_DEFAULT_DATA_SUBSCRIPTION	Notification to be invoked when the default data subscription changes. 'telephony_network_default_data_subs_e' wil be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_DEFAULT_SUBSCRIPTION	Notification to be invoked when the default subscription changes. 'telephony_network_default_subs_e' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_NETWORK_LAC	Notification to be invoked when the LAC (Location Area Code) changes. 'lac(int)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/location.coarse
TELEPHONY_NOTI_NETWORK_TAC	Notification to be invoked when the TAC (Tracking Area Code) changes. 'tac(int)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/location.coarse
TELEPHONY_NOTI_NETWORK_SYSTEM_ID	Notification to be invoked when the system ID changes. 'sid(int)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/location.coarse
TELEPHONY_NOTI_NETWORK_NETWORK_ID	Notification to be invoked when the network ID changes. 'nid(int)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/location.coarse
TELEPHONY_NOTI_NETWORK_BS_ID	Notification to be invoked when the base station ID changes. 'bs_id(int)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/location.coarse
TELEPHONY_NOTI_NETWORK_BS_LATITUDE	Notification to be invoked when the base station latitude changes. 'bs_latitude(int)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/location.coarse
TELEPHONY_NOTI_NETWORK_BS_LONGITUDE	Notification to be invoked when the base station longitude changes. 'bs_longitue(int)' will be delivered in notification data (Since: 3.0) Privilege : http://tizen.org/privilege/location.coarse
TELEPHONY_NOTI_VOICE_CALL_STATE	Notification to be invoked when the voice call state changes. 'telephony_call_state_e' will be delivered in notification data (Deprecated Since 2.4. Use TELEPHONY_NOTI_VOICE_CALL_STATUS_XXX instead.) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VIDEO_CALL_STATE	Notification to be invoked when the video call state changes. 'telephony_call_state_e' will be delivered in notification data (Deprecated Since 2.4. Use TELEPHONY_NOTI_VIDEO_CALL_STATUS_XXX instead.) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VOICE_CALL_STATUS_IDLE	Notification to be invoked when a voice call is in idle status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VOICE_CALL_STATUS_ACTIVE	Notification to be invoked when a voice call is in active status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VOICE_CALL_STATUS_HELD	Notification to be invoked when a voice call is in held status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VOICE_CALL_STATUS_DIALING	Notification to be invoked when a voice call is in dialing status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VOICE_CALL_STATUS_ALERTING	Notification to be invoked when a voice call is in alertingstatus. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VOICE_CALL_STATUS_INCOMING	Notification to be invoked when a voice call is in incoming status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VIDEO_CALL_STATUS_IDLE	Notification to be invoked when a video call is in idle status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VIDEO_CALL_STATUS_ACTIVE	Notification to be invoked when a video call is in active status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VIDEO_CALL_STATUS_DIALING	Notification to be invoked when a video call is in dialing status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VIDEO_CALL_STATUS_ALERTING	Notification to be invoked when a video call is in alerting status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_VIDEO_CALL_STATUS_INCOMING	Notification to be invoked when a video call is in incoming status. 'handle_id(unsigned int)' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony
TELEPHONY_NOTI_CALL_PREFERRED_VOICE_SUBSCRIPTION	Notification to be invoked when the preferred voice subscription changes. 'telephony_call_preferred_voice_subs_e' will be delivered in notification data (Since: 2.4) Privilege : http://tizen.org/privilege/telephony

enum telephony_state_e

Enumeration for the telephony state.

Since :: 2.4

Enumerator:

TELEPHONY_STATE_NOT_READY	Telephony state is not ready
TELEPHONY_STATE_READY	Telephony state is ready

Function Documentation

int telephony_deinit ( telephony_handle_list_s * list )

Deinitializes the telephony handle list.

Since :: 2.3

Parameters:

[in] list The handle list to be deinitialized

Returns:: 0 on success, otherwise a negative error value

Return values:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_INVALID_PARAMETER	Invalid parameter
TELEPHONY_ERROR_NOT_SUPPORTED	Not supported
TELEPHONY_ERROR_OPERATION_FAILED	Operation failed

See also:: telephony_init()

int telephony_get_state ( telephony_state_e * state )

Acquires the telephony state value.

Since :: 2.4

Parameters:

[out] state The state value of telephony

Returns:: 0 on success, otherwise a negative error value

Return values:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_INVALID_PARAMETER	Invalid parameter
TELEPHONY_ERROR_NOT_SUPPORTED	Not supported
TELEPHONY_ERROR_OPERATION_FAILED	Operation failed

See also:: telephony_set_state_changed_cb(); telephony_unset_state_changed_cb()

int telephony_init ( telephony_handle_list_s * list )

Acquires the list of available handles to use the telephony API.

Since :: 2.3

Remarks:: You will get two handles in case of dual SIM device.
In this case, handle[0] means Primary SIM and handle[1] means Secondary SIM.

Parameters:

[out] list The list contains the number of available handles and array of handles

Returns:: 0 on success, otherwise a negative error value

Return values:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_OUT_OF_MEMORY	Out of memory
TELEPHONY_ERROR_INVALID_PARAMETER	Invalid parameter
TELEPHONY_ERROR_NOT_SUPPORTED	Not supported
TELEPHONY_ERROR_OPERATION_FAILED	Operation failed

See also:: telephony_deinit()

int telephony_set_noti_cb	(	telephony_h	handle,
		telephony_noti_e	noti_id,
		telephony_noti_cb	cb,
		void *	user_data
	)

Sets a callback function to be invoked when the telephony state changes.

Since :: 2.3

Remarks:: An application should have the privilege corresponding to each notificaiton ID.
Please see the telephony_noti_e to know the privilege.
If an application has no proper privilege, callback will not be invoked although API returns success.

Parameters:

[in]	handle	The handle to use the telephony API
[in]	noti_id	The notification ID to set the callback
[in]	cb	The callback to be invoked when the telephony state changes
[in]	user_data	The user data passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_INVALID_PARAMETER	Invalid parameter
TELEPHONY_ERROR_NOT_SUPPORTED	Not supported
TELEPHONY_ERROR_OPERATION_FAILED	Operation failed

Postcondition:: telephony_noti_cb() will be invoked.

See also:: telephony_unset_noti_cb()

int telephony_set_state_changed_cb	(	telephony_state_changed_cb	callback,
		void *	user_data
	)

Sets a callback function to be invoked when the telephony state changes.

Since :: 2.4

Parameters:

[in]	callback	The callback to be invoked when the telephony state changes
[in]	user_data	The user data passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_INVALID_PARAMETER	Invalid parameter
TELEPHONY_ERROR_NOT_SUPPORTED	Not supported
TELEPHONY_ERROR_OPERATION_FAILED	Operation failed

Postcondition:: telephony_state_changed_cb() will be invoked.

See also:: telephony_unset_state_changed_cb()

int telephony_unset_noti_cb	(	telephony_h	handle,
		telephony_noti_e	noti_id
	)

Unsets a callback function.

Since :: 2.3

Parameters:

[in]	handle	The handle to use the telephony API
[in]	noti_id	The notification ID to unset a callback

Returns:: 0 on success, otherwise a negative error value

Return values:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_INVALID_PARAMETER	Invalid parameter
TELEPHONY_ERROR_NOT_SUPPORTED	Not supported
TELEPHONY_ERROR_OPERATION_FAILED	Operation failed

See also:: telephony_set_noti_cb()

int telephony_unset_state_changed_cb ( telephony_state_changed_cb callback )

Unsets a telephony state callback function.

Since :: 2.4

Parameters:

[in] callback The callback to unset when the telephony state changes

Returns:: 0 on success, otherwise a negative error value

Return values:

TELEPHONY_ERROR_NONE	Successful
TELEPHONY_ERROR_INVALID_PARAMETER	Invalid parameter
TELEPHONY_ERROR_NOT_SUPPORTED	Not supported
TELEPHONY_ERROR_OPERATION_FAILED	Operation failed

See also:: telephony_set_state_changed_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation