Telephony
Telephony features include call, SIM, network, and modem information using the Telephony Service.
The main telephony features are:
-
Call information
Get the voice and video call states. You can use this information in call-related actions.
-
SIM information
Extract information stored on a SIM card without changing the information.
-
Network information
Access (without changing) information about the current cellular network and telephony service.
-
Modem information
Access (without changing) IMEI information.
The following figure illustrates the Telephony Service and APIs.
Figure: Telephony API and Telephony Service
Call Information
The Call API (in mobile and wearable applications) provides the following functions:
-
telephony_call_get_voice_call_state()
Determines whether the voice call is connecting, connected, or idle. It returns one of the telephony_call_state_e values.
-
telephony_call_get_video_call_state()
Determines whether the video call is connecting, connected, or idle. It returns one of the telephony_call_state_e values.
To get call state change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.
The following table defines the available notification IDs.
| Change in state | Notification ID |
|---|---|
| Voice call | TELEPHONY_NOTI_VOICE_CALL_STATE |
| Video call | TELEPHONY_NOTI_VIDEO_CALL_STATE |
SIM Information
The SIM API (in mobile and wearable applications) provides the following functions:
-
telephony_sim_get_icc_id()
Gets the Integrated Circuit Card IDentification (ICC-ID). You get the ICC-ID as a string, which needs to be freed by the application.
-
telephony_sim_get_operator()
Gets the SIM operator (MCC + MNC). You get the operator information as a string, which needs to be freed by the application.
-
telephony_sim_get_msin()
Gets the Mobile Subscription Identification Number (MSIN) of the SIM provider. You get the MSIN as a string, which needs to be freed by the application.
-
telephony_sim_get_spn()
Gets the Service Provider Name (SPN) of the SIM card. You get the SPN as a string, which needs to be freed by the application.
-
telephony_sim_get_cphs_operator_name()
Gets the Operator Name String (ONS) of the Common PCN Handset Specification (CPHS) in the SIM card. You get the CPHS as a string, which needs to be freed by the application.
-
telephony_sim_get_subscriber_number()
Gets the subscriber number embedded in the SIM card. This value contains the MSISDN related to the subscriber. You get the subscriber number as a string, which needs to be freed by the application.
-
telephony_sim_get_state()
Gets the state of the SIM. It returns one of the telephony_sim_state_e values.
-
telephony_sim_is_changed()
Checks whether the current SIM card differs from the previous SIM card.
To get SIM state change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.
The following table defines the available notification IDs.
| Change in state | Notification ID |
|---|---|
| SIM state | TELEPHONY_NOTI_SIM_STATUS |
| Note |
|---|
| Before retrieving information from the SIM card, you must retrieve the state of the SIM card. You can get SIM-related information only if the SIM state is TELEPHONY_SIM_STATE_AVAILABLE. |
Network Information
The Network API (in mobile and wearable applications) provides the following functions:
-
telephony_network_get_lac()
Gets the LAC (Location Area Code) of the current network.
-
telephony_network_get_cell_id()
Gets the cell identification number.
-
telephony_network_get_rssi()
Gets the RSSI (Received Signal Strength Indicator).
-
telephony_network_get_roaming_status()
Gets the roaming state (true = roaming and false = not roaming).
-
telephony_network_get_mcc()
Gets the MCC (Mobile Country Code) of the current registered network. You get the MCC as a string, which needs to be freed by the application.
-
telephony_network_get_mnc()
Gets the MNC (Mobile Network Code) of the current registered network. You get the MNC as a string, which needs to be freed by the application.
-
telephony_network_get_network_name()
Gets the name of the current registered network. You get the network name as a string, which needs to be freed by the application.
-
telephony_network_get_type()
Gets the network service type of the current registered network. It returns one of the telephony_network_type_e values.
-
telephony_network_get_service_state()
Gets the current network state of the telephony service. It returns one of the telephony_network_service_state_e values.
To get network-related information change notifications, the application must register for the notifications with the telephony_set_noti_cb() function, by specifying the notification ID.
The following table defines the available notification IDs.
| Change in state | Notification ID |
|---|---|
| Network service state | TELEPHONY_NOTI_NETWORK_SERVICE_STATE |
| Cell ID | TELEPHONY_NOTI_NETWORK_CELLID |
| Roaming status | TELEPHONY_NOTI_NETWORK_ROAMING_STATUS |
| Signal strength | TELEPHONY_NOTI_NETWORK_SIGNALSTRENGTH_LEVEL |
| Note |
|---|
| Before retrieving information from the network, you must retrieve the network service state. You can get network-related information only if the network service state is TELEPHONY_NETWORK_SERVICE_STATE_IN_SERVICE. |
Modem Information
The Modem API (in mobile and wearable applications) provides the following functions:
-
telephony_modem_get_imei()
Gets the IMEI (International Mobile Station Equipment Identity) of the mobile phone. You get the IMEI as a string, which needs to be freed by the application.
