Tizen Native API  5.0
Telephony Information

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.1
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.1
typedef void(* telephony_state_changed_cb)(telephony_state_e state, void *user_data)

Called for the telephony state changes.

Since :
3.0

Enumeration Type Documentation

Enumeration for Telephony error.

Since :
2.3.1
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

Enumeration for Telephony notification.

Since :
2.3.1
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 *)' will be delivered in notification data (Since: 3.0)
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: 3.0)
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' will be delivered in notification data (Since: 3.0)
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: 3.0)
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_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: 3.0)
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: 3.0)
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: 3.0)
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: 3.0)
Privilege : http://tizen.org/privilege/telephony

TELEPHONY_NOTI_VOICE_CALL_STATUS_ALERTING 

Notification to be invoked when a voice call is in alerting status.
'handle_id(unsigned int)' will be delivered in notification data (Since: 3.0)
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: 3.0)
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: 3.0)
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: 3.0)
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: 3.0)
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: 3.0)
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: 3.0)
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: 3.0)
Privilege : http://tizen.org/privilege/telephony

TELEPHONY_NOTI_MODEM_POWER_STATUS 

Notification to be invoked when the modem power status changes.
'telephony_modem_power_status_e' will be delivered in notification data (Since: 4.0)
Privilege : http://tizen.org/privilege/telephony

Enumeration for the telephony state.

Since :
3.0
Enumerator:
TELEPHONY_STATE_NOT_READY 

Telephony state is not ready

TELEPHONY_STATE_READY 

Telephony state is ready


Function Documentation

Deinitializes the telephony handle list.

Since :
2.3.1
Parameters:
[in]listThe handle list to be deinitialized
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
See also:
telephony_init()

Acquires the telephony state value.

Since :
3.0
Parameters:
[out]stateThe state value of telephony
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
See also:
telephony_set_state_changed_cb()
telephony_unset_state_changed_cb()

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

Since :
2.3.1
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]listThe list contains the number of available handles and array of handles
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_OUT_OF_MEMORYOut of memory
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation 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.1
Remarks:
An application should have the privilege corresponding to each notification 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]handleThe handle to use the telephony API
[in]noti_idThe notification ID to set the callback
[in]cbThe callback to be invoked when the telephony state changes
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation 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 :
3.0
Parameters:
[in]callbackThe callback to be invoked when the telephony state changes
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation 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.1
Parameters:
[in]handleThe handle to use the telephony API
[in]noti_idThe notification ID to unset a callback
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
See also:
telephony_set_noti_cb()

Unsets a telephony state callback function.

Since :
3.0
Parameters:
[in]callbackThe callback to unset when the telephony state changes
Returns:
0 on success, otherwise a negative error value
Return values:
TELEPHONY_ERROR_NONESuccessful
TELEPHONY_ERROR_INVALID_PARAMETERInvalid parameter
TELEPHONY_ERROR_NOT_SUPPORTEDNot supported
TELEPHONY_ERROR_OPERATION_FAILEDOperation failed
See also:
telephony_set_state_changed_cb()