Telephony Information

Telephony information features include call, SIM, network, and modem information using the Telephony Service.

The main telephony information 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 APIs and Telephony Service

Call Information

The Call API (in mobile and wearable applications) provides the following functions:

• telephony_call_get_preferred_voice_subscription()

  Gets the current value for the preferred voice call subscription. It returns one of the telephony_call_preferred_voice_subs_e values.

• telephony_call_get_call_list()

  Gets the list of the current call. It returns the current call count and the call handle.

• telephony_call_release_call_list()

  Releases the list allocated to the call handle. When the call handle is no longer needed, this function must be called to free the handle.

• telephony_call_get_handle_id()

  Gets the call handle ID.

• telephony_call_get_number()

  Gets the call number.

• telephony_call_get_type()

  Gets the call type. It returns one of the telephony_call_type_e values.

• telephony_call_get_status()

  Gets the call status. It returns one of the telephony_call_status_e values.

• telephony_call_get_direction()

  Gets the call direction: MO (Mobile Originated) or MT (Mobile Terminated). It returns one of the telephony_call_direction_e values.

• telephony_call_get_conference_status()

  Determines whether the call is conference call. It returns true for a conference call or false for a single call.

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.

Table: Call information notification IDs

Change in state	Notification ID
Voice status idle	TELEPHONY_NOTI_VOICE_CALL_STATUS_IDLE
Voice status active	TELEPHONY_NOTI_VOICE_CALL_STATUS_ACTIVE
Voice status held	TELEPHONY_NOTI_VOICE_CALL_STATUS_HELD
Voice status dialing	TELEPHONY_NOTI_VOICE_CALL_STATUS_DIALING
Voice status alerting	TELEPHONY_NOTI_VOICE_CALL_STATUS_ALERTING
Voice status incoming	TELEPHONY_NOTI_VOICE_CALL_STATUS_INCOMING
Video status idle	TELEPHONY_NOTI_VIDEO_CALL_STATUS_IDLE
Video status active	TELEPHONY_NOTI_VIDEO_CALL_STATUS_ACTIVE
Video status dialing	TELEPHONY_NOTI_VIDEO_CALL_STATUS_DIALING
Video status alerting	TELEPHONY_NOTI_VIDEO_CALL_STATUS_ALERTING
Video status incoming	TELEPHONY_NOTI_VIDEO_CALL_STATUS_INCOMING
Preferred voice subscription	TELEPHONY_NOTI_CALL_PREFERRED_VOICE_SUBSCRIPTION

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.

• telephony_sim_get_application_list()

  Gets the application list on the UICC. It returns one of the masking (telephony_sim_application_type_e) values.

• telephony_sim_get_subscriber_id()

  Gets the subscriber ID as a string, which needs to be freed by the application.

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.

Table: SIM information 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.

• telephony_network_get_ps_type()

  Gets the packet service type of the currently registered network. It returns one of the telephony_network_ps_type_e values.

• telephony_network_get_network_name_option()

  Gets the network name option of the currently registered network. It returns one of the telephony_network_name_option_e values.

• telephony_network_get_default_data_subscription()

  Gets the current default subscription for the data service (packet-switched). It returns one of the telephony_network_default_data_subs_e values.

• telephony_network_get_default_subscription()

  Gets the current default subscription for the voice service (circuit-switched). It returns one of the telephony_network_default_subs_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.

Table: Network information 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
Network name	TELEPHONY_NOTI_NETWORK_NETWORK_NAME
Packet-switched type	TELEPHONY_NOTI_NETWORK_PS_TYPE
Default data subscription	TELEPHONY_NOTI_NETWORK_DEFAULT_DATA_SUBSCRIPTION
Default subscription	TELEPHONY_NOTI_NETWORK_DEFAULT_SUBSCRIPTION

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.

• telephony_modem_get_power_status()

  Gets the power status of the modem. It returns one of the telephony_modem_power_status_e values.