目录

@ohos.telephony.observer (Telephony Status Observer)

The observer module provides event subscription management functions. You can register or unregister an observer that listens for the following events: network status change, signal status change, call status change, cellular data connection status, uplink and downlink data flow status of cellular data services, and SIM status change.

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { observer } from '@kit.TelephonyKit';

NetworkState

type NetworkState = radio.NetworkState

Defines the network status.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
radio.NetworkState Network status.

SignalInformation

type SignalInformation = radio.SignalInformation

Defines the signal strength.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
radio.SignalInformation Signal strength.

DataConnectState

type DataConnectState = data.DataConnectState

Describes the connection status of a cellular data link.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
data.DataConnectState Connection status of a cellular data link.

RatType

type RatType = radio.RadioTechnology

Enumerates the radio access technologies.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
radio.RadioTechnology Radio access technology.

DataFlowType

type DataFlowType = data.DataFlowType

Defines the cellular data flow type.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
data.DataFlowType Cellular data flow type.

CallState

type CallState = call.CallState

Enumerates call states.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
call.CallState Call state. (Only the CALL_STATE_OFFHOOK state is reported during an outgoing call.)

CCallState23+

type CCallState = call.CCallState

Enumerates carrier call states.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
call.CCallState Call state (of the carrier).

CardType

type CardType = sim.CardType

Enumerates SIM card types.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
sim.CardType SIM card type.

SimState

type SimState = sim.SimState

SIM card state.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
sim.SimState SIM card state.

TelCallState21+

type TelCallState = call.TelCallState

Enumerates call states.

System capability: SystemCapability.Telephony.StateRegistry

Type Description
call.TelCallState Call state. (TEL_CALL_STATE_OFFHOOK and TEL_CALL_STATE_CONNECTED are used to report the dialed number status and the call connection status respectively during an outgoing call.)

observer.on('networkStateChange')

on(type: 'networkStateChange', callback: Callback<NetworkState>): void

Registers an observer for network status change events. This API uses an asynchronous callback to return the execution result.

Required permissions: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Network status change event. This field has a fixed value of networkStateChange.
callback Callback<NetworkState> Yes Callback used to return the network status object. For details, see NetworkState.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

try {
    observer.on('networkStateChange', (data: observer.NetworkState) => {
        console.info("on networkStateChange, data:" + JSON.stringify(data));
    });
} catch (err) {
    console.error(`observer.on networkStateChange failed: ${JSON.stringify(err)}`);
}

observer.on('networkStateChange')

on(type: 'networkStateChange', options: ObserverOptions, callback: Callback<NetworkState>): void

Registers an observer for network status change events of the SIM card in the specified slot. This API uses an asynchronous callback to return the execution result.

Required permissions: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Network status change event. This field has a fixed value of networkStateChange.
options ObserverOptions Yes Event subscription parameters.
callback Callback<NetworkState> Yes Callback used to return the network status object. For details, see NetworkState.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

// Set the subscription parameters and specify the card slot ID as 0 (card slot 1).
let options: observer.ObserverOptions = {
    slotId: 0
}
// Register an observer for network status change events of the SIM card in the specified slot.
observer.on('networkStateChange', options, (data: observer.NetworkState) => {
    console.info("on networkStateChange, data:" + JSON.stringify(data));
});

observer.off('networkStateChange')

off(type: 'networkStateChange', callback?: Callback<NetworkState>): void

Unregisters the observer for network status change events. This API uses an asynchronous callback to return the execution result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Network status change event. This field has a fixed value of networkStateChange.
callback Callback<NetworkState> No Callback used to return the network status object. For details, see NetworkState.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let callback: (data: observer.NetworkState) => void = (data: observer.NetworkState) => {
    console.info("on networkStateChange, data:" + JSON.stringify(data));
}
observer.on('networkStateChange', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('networkStateChange', callback);
observer.off('networkStateChange');

observer.on('signalInfoChange')

on(type: 'signalInfoChange', callback: Callback<Array<SignalInformation>>): void

Registers an observer for signal status change events. This API uses an asynchronous callback to return the execution result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Signal status change event. This field has a fixed value of signalInfoChange.
callback Callback<Array<SignalInformation>> Yes Callback used to return the signal strength object. For details, see SignalInformation.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { radio } from '@kit.TelephonyKit';

observer.on('signalInfoChange', (data: Array<radio.SignalInformation>) => {
    console.info("on signalInfoChange, data:" + JSON.stringify(data));
});

observer.on('signalInfoChange')

on(type: 'signalInfoChange', options: ObserverOptions, callback: Callback<Array<SignalInformation>>): void

Registers an observer for signal status change events of the SIM card in the specified slot. This API uses an asynchronous callback to return the execution result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Signal status change event. This field has a fixed value of signalInfoChange.
options ObserverOptions Yes Event subscription parameters.
callback Callback<Array<SignalInformation>> Yes Callback used to return the signal strength object. For details, see SignalInformation.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { radio } from '@kit.TelephonyKit';

let options: observer.ObserverOptions = {
    slotId: 0
}
observer.on('signalInfoChange', options, (data: Array<radio.SignalInformation>) => {
    console.info("on signalInfoChange, data:" + JSON.stringify(data));
});

observer.off('signalInfoChange')

off(type: 'signalInfoChange', callback?: Callback<Array<SignalInformation>>): void

Unregisters the observer for signal status change events. This API uses an asynchronous callback to return the execution result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Signal status change event. This field has a fixed value of signalInfoChange.
callback Callback<Array<SignalInformation>> No Callback used to return the signal strength object. For details, see SignalInformation.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { radio } from '@kit.TelephonyKit';

let callback: (data: Array<radio.SignalInformation>) => void = (data: Array<radio.SignalInformation>) => {
    console.info("on signalInfoChange, data:" + JSON.stringify(data));
}
observer.on('signalInfoChange', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('signalInfoChange', callback);
observer.off('signalInfoChange');

observer.on('callStateChange')

on(type: 'callStateChange', callback: Callback<CallStateInfo>): void

Registers an observer for call status change events. This API uses an asynchronous callback to return the execution result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Call status change event. This field has a fixed value of callStateChange.
callback Callback<CallStateInfo> Yes

Callback used to return the result,

which is the CallStateInfo object. In this object:

- Only state is accessible to third-party applications. - number is only accessible to system applications.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

observer.on('callStateChange', (data: observer.CallStateInfo) => {
    console.info("on callStateChange, data:" + JSON.stringify(data));
});

observer.on('callStateChange')

on(type: 'callStateChange', options: ObserverOptions, callback: Callback<CallStateInfo>): void

Registers an observer for call status change events. This API uses an asynchronous callback to return the execution result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of callStateChange.
options ObserverOptions Yes Event subscription parameters.
callback Callback<CallStateInfo> Yes

Callback used to return the result,

which is the CallStateInfo object. In this object:

- Only state is accessible to third-party applications. - number is only accessible to system applications.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let options: observer.ObserverOptions = {
    slotId: 0
}
observer.on('callStateChange', options, (data: observer.CallStateInfo) => {
    console.info("on callStateChange, data:" + JSON.stringify(data));
});

observer.off('callStateChange')

off(type: 'callStateChange', callback?: Callback<CallStateInfo>): void

Unregisters the observer for call status change events. This API uses an asynchronous callback to return the execution result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of callStateChange.
callback Callback<CallStateInfo> No

Callback used to return the result,

- Only state is accessible to third-party applications. - number is only accessible to system applications.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let callback: (data: observer.CallStateInfo) => void = (data: observer.CallStateInfo) => {
    console.info("on callStateChange, data:" + JSON.stringify(data));
}
observer.on('callStateChange', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('callStateChange', callback);
observer.off('callStateChange');

observer.on('callStateChangeEx')21+

on(type: 'callStateChangeEx', callback: Callback<TelCallState>, options?: ObserverOptions): void

Registers an observer for extended call status change events. This API uses an asynchronous callback to return the execution result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of callStateChangeEx.
callback Callback<TelCallState> Yes

Callback used to return the call status information object.

The application can obtain TelCallState.
options ObserverOptions No Observer options. This parameter specifies the slot ID for event subscription. The default value is the ID of the default data card slot.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
8800001 Invalid parameter value.
8800002 Service connection failed.
8800003 System internal error.
8800999 Unknown error.

Example

import { call } from '@kit.TelephonyKit';

// Define the callback for extended call status change events.
let callback: (data: call.TelCallState) => void = (data: call.TelCallState) => {
    console.info("on callStateChangeEx, data:" + JSON.stringify(data));
}
// Set the subscription parameters and specify the card slot ID.
let options: observer.ObserverOptions = {
    slotId: 0
}

try {
    // Subscribe to extended call status change events (for a specified card slot).
    observer.on('callStateChangeEx', callback, options);
    // Subscribe to extended call status change events (for all card slots).
    observer.on('callStateChangeEx', callback);
} catch (err) {
    console.error(`observer.on callStateChangeEx failed: ${JSON.stringify(err)}`);
}

observer.off('callStateChangeEx')21+

off(type: 'callStateChangeEx', callback?: Callback<TelCallState>): void

Unregisters the observer for extended call status change events. This API uses an asynchronous callback to return the execution result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Extended call status change event. This field has a fixed value of callStateChangeEx.
callback Callback<TelCallState> No

Callback used to return the call status information object. For details, see TelCallState in call.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
8800001 Invalid parameter value.
8800002 Service connection failed.
8800003 System internal error.
8800999 Unknown error.

Example

import { call } from '@kit.TelephonyKit';
let callback: (data: call.TelCallState) => void = (data: call.TelCallState) => {
    console.info("on callStateChangeEx, data:" + JSON.stringify(data));
}
observer.on('callStateChangeEx', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('callStateChangeEx', callback);
observer.off('callStateChangeEx');

observer.on('cellularDataConnectionStateChange')7+

on(type: 'cellularDataConnectionStateChange', callback: Callback<DataConnectionStateInfo>): void

Registers an observer for connection status change events of the cellular data link. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Cellular data connection status event. This field has a fixed value of cellularDataConnectionStateChange.
callback Callback<DataConnectionStateInfo> Yes Callback used to return the cellular data connection status information object. For details, see DataConnectState of data and RadioTechnology of radio.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

observer.on('cellularDataConnectionStateChange', (data: observer.DataConnectionStateInfo) => {
    console.info("on cellularDataConnectionStateChange, data:" + JSON.stringify(data));
});

observer.on('cellularDataConnectionStateChange')7+

on(type: 'cellularDataConnectionStateChange', options: ObserverOptions, callback: Callback<DataConnectionStateInfo>): void

Registers an observer for connection status change events of the cellular data link over the SIM card in the specified slot. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Cellular data connection status event. This field has a fixed value of cellularDataConnectionStateChange.
options ObserverOptions Yes Event subscription parameters.
callback Callback<DataConnectionStateInfo> Yes Callback used to return the cellular data connection status information object. For details, see DataConnectState of data and RadioTechnology of radio.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let options: observer.ObserverOptions = {
    slotId: 0
}
observer.on('cellularDataConnectionStateChange', options, (data: observer.DataConnectionStateInfo) => {
    console.info("on cellularDataConnectionStateChange, data:" + JSON.stringify(data));
});

observer.off('cellularDataConnectionStateChange')7+

off(type: 'cellularDataConnectionStateChange', callback?: Callback<DataConnectionStateInfo>): void

Unregisters the observer for connection status change events of the cellular data link. This API uses an asynchronous callback to return the result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Cellular data connection status event. This field has a fixed value of cellularDataConnectionStateChange.
callback Callback<DataConnectionStateInfo> No Callback used to return the cellular data connection status information object. For details, see DataConnectState of data and RadioTechnology of radio.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let callback: (data: observer.DataConnectionStateInfo) => void = (data: observer.DataConnectionStateInfo) => {
    console.info("on cellularDataConnectionStateChange, data:" + JSON.stringify(data));
}
observer.on('cellularDataConnectionStateChange', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('cellularDataConnectionStateChange', callback);
observer.off('cellularDataConnectionStateChange');

observer.on('cellularDataFlowChange')7+

on(type: 'cellularDataFlowChange', callback: Callback<DataFlowType>): void

Registers an observer for the uplink and downlink data flow status change events of the cellular data service. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Cellular data flow change event. This field has a fixed value of cellularDataFlowChange.
callback Callback<DataFlowType> Yes Callback used to return the data flow status object. For details, see DataFlowType in data.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { data } from '@kit.TelephonyKit';

observer.on('cellularDataFlowChange', (data: data.DataFlowType) => {
    console.info("on cellularDataFlowChange, data:" + JSON.stringify(data));
});

observer.on('cellularDataFlowChange')7+

on(type: 'cellularDataFlowChange', options: ObserverOptions, callback: Callback<DataFlowType>): void

Registers an observer for the uplink and downlink data flow status change events of the cellular data service on the SIM card in the specified slot. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Cellular data flow change event. This field has a fixed value of cellularDataFlowChange.
options ObserverOptions Yes Event subscription parameters.
callback Callback<DataFlowType> Yes Callback used to return the data flow status object. For details, see DataFlowType in data.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { data } from '@kit.TelephonyKit';

let options: observer.ObserverOptions = {
    slotId: 0
}
observer.on('cellularDataFlowChange', options, (data: data.DataFlowType) => {
    console.info("on cellularDataFlowChange, data:" + JSON.stringify(data));
});

observer.off('cellularDataFlowChange')7+

off(type: 'cellularDataFlowChange', callback?: Callback<DataFlowType>): void

Unregisters the observer for the uplink and downlink data flow status change events of the cellular data service. This API uses an asynchronous callback to return the result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Cellular data flow change event. This field has a fixed value of cellularDataFlowChange.
callback Callback<DataFlowType> No Callback used to return the data flow status object. For details, see DataFlowType in data.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { data } from '@kit.TelephonyKit';

let callback: (data: data.DataFlowType) => void = (data: data.DataFlowType) => {
    console.info("on cellularDataFlowChange, data:" + JSON.stringify(data));
}
observer.on('cellularDataFlowChange', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('cellularDataFlowChange', callback);
observer.off('cellularDataFlowChange');

observer.on('simStateChange')7+

on(type: 'simStateChange', callback: Callback<SimStateData>): void

Registers an observer for SIM card status change events. This API uses an asynchronous callback to return the result.

The return result of this API does not contain the activation status of the SIM card. For details, see sim.isSimActive.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of simStateChange.
callback Callback<SimStateData> Yes Callback used to return the SIM status data object.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

observer.on('simStateChange', (data: observer.SimStateData) => {
    console.info("on simStateChange, data:" + JSON.stringify(data));
});

observer.on('simStateChange')7+

on(type: 'simStateChange', options: ObserverOptions, callback: Callback<SimStateData>): void

Registers an observer for status change events of the SIM card in the specified slot. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of simStateChange.
options ObserverOptions Yes Event subscription parameters.
callback Callback<SimStateData> Yes Callback used to return the SIM status data object.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let options: observer.ObserverOptions = {
    slotId: 0
}
observer.on('simStateChange', options, (data: observer.SimStateData) => {
    console.info("on simStateChange, data:" + JSON.stringify(data));
});

observer.off('simStateChange')7+

off(type: 'simStateChange', callback?: Callback<SimStateData>): void

Unregisters the observer for SIM card status change events. This API uses an asynchronous callback to return the result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of simStateChange.
callback Callback<SimStateData> No Callback used to return the SIM status data object.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let callback: (data: observer.SimStateData) => void = (data: observer.SimStateData) => {
    console.info("on simStateChange, data:" + JSON.stringify(data));
}
observer.on('simStateChange', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('simStateChange', callback);
observer.off('simStateChange');

observer.on('iccAccountInfoChange')10+

on(type: 'iccAccountInfoChange', callback: Callback<void>): void

Registers an observer for account information change events of the SIM card. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of iccAccountInfoChange.
callback Callback<void> Yes Callback used to return the result. This callback is triggered when the card account changes.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

observer.on('iccAccountInfoChange', () => {
    console.info("on iccAccountInfoChange success");
});

observer.off('iccAccountInfoChange')10+

off(type: 'iccAccountInfoChange', callback?: Callback<void>): void

Unregisters the observer for account information change events of the SIM card. This API uses an asynchronous callback to return the result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
type string Yes Event type. This field has a fixed value of iccAccountInfoChange.
callback Callback<void> No Callback used to return the result. This callback is triggered when the card account changes.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

let callback: () => void = () => {
    console.info("on iccAccountInfoChange success");
}
observer.on('iccAccountInfoChange', callback);
// You can pass the callback of the on method to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
observer.off('iccAccountInfoChange', callback);
observer.off('iccAccountInfoChange');

observer.onGetSimActiveState23+

onGetSimActiveState(slotId: number, callback: Callback<boolean>): void

Registers an observer for SIM card activation state changes. This API uses an asynchronous callback to return the execution result.

Required permissions: ohos.permission.GET_TELEPHONY_STATE

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
slotId number Yes

Card slot ID.

- 0: card slot 1.

- 1: card slot 2.
callback Callback<boolean> Yes

Callback used to return whether the SIM card is activated.

- true: activated.

- false: not activated.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { sim } from '@kit.TelephonyKit';

let sislotId = 0;
let simActiveState: Callback<boolean> = (isSimActive: boolean) => {
    console.info(`simActiveState slotId ${JSON.stringify(isSimActive)}`);
}
observer.onGetSimActiveState(sislotId, simActiveState);

observer.offGetSimActiveState23+

offGetSimActiveState(callback?: Callback<boolean>): void

Unregisters an observer for SIM card activation state changes. This API uses an asynchronous callback to return the execution result.

Required permissions: ohos.permission.GET_TELEPHONY_STATE

System capability: SystemCapability.Telephony.StateRegistry

Parameters

Name Type Mandatory Description
callback Callback<boolean> No

Callback used to return whether the SIM card is activated.

- true: activated.

- false: not activated.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { sim } from '@kit.TelephonyKit';

let simActiveState: Callback<boolean> = (isSimActive: boolean) => {
    console.info(`simActiveState slotId ${JSON.stringify(isSimActive)}`);
}
observer.offGetSimActiveState(simActiveState);

observer.onCCallStateChange23+

onCCallStateChange(callback: Callback<CCallStateInfo>, options?: ObserverOptions): void

Registers an observer for carrier call status change events and obtains the call number. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.StateRegistry

Required permissions: ohos.permission.MANAGE_CALL_FOR_DEVICES

Parameters

Name Type Mandatory Description
callback Callback<CCallStateInfo> Yes

Callback used to return the result,

which is the CCallStateInfo object.
options ObserverOptions No Observer options. This parameter specifies the slot ID for event subscription. The default value is the ID of the default data card slot.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied
8800001 Invalid parameter value.
8800002 Service connection failed.
8800003 System internal error.
8800999 Unknown error.

Example

import { call, observer } from '@kit.TelephonyKit';

// Define the callback for carrier call status changes.
let callback: (data: observer.CCallStateInfo) => void = (data: observer.CCallStateInfo) => {
    console.info("onCCallStateChange, data:" + JSON.stringify(data));
};
// Set the subscription parameters and specify the card slot ID.
let options: observer.ObserverOptions = {
    slotId: 0
};

try {
    // Listen for the carrier call status (with the card slot specified).
    observer.onCCallStateChange(callback, options);
    // Listen for the carrier call status (without specifying the card slot).
    observer.onCCallStateChange(callback);
} catch (err) {
    console.error(`observer.onCCallStateChange failed: ${JSON.stringify(err)}`);
}

observer.offCCallStateChange23+

offCCallStateChange(callback?: Callback<CCallStateInfo>): void

Unregisters the observer for carrier call status change events and obtains the call number. This API uses an asynchronous callback to return the result.

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Telephony.StateRegistry

Required permissions: ohos.permission.MANAGE_CALL_FOR_DEVICES

Parameters

Name Type Mandatory Description
callback Callback<CCallStateInfo> No

Callback used to return the result,

which is the CCallStateInfo object.

If this parameter is not passed, the listening for the call status of all carriers is canceled.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied
8800001 Invalid parameter value.
8800002 Service connection failed.
8800003 System internal error.
8800999 Unknown error.

Example

import { observer } from '@kit.TelephonyKit';

let callback: (data: observer.CCallStateInfo) => void = (data: observer.CCallStateInfo) => {
    console.info("onCCallStateChange, data:" + JSON.stringify(data));
}

observer.offCCallStateChange(callback);
observer.offCCallStateChange();

observer.onCommunicationStateChange

onCommunicationStateChange(callback: Callback<boolean>, options?:ObserverOptions): void

Registers an observer for 5A network status change events. This API uses an asynchronous callback to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.StateRegistry

Required permissions: ohos.permission.GET_NETWORK_INFO

Parameters

Name Type Mandatory Description
callback Callback<boolean> Yes Callback used to return the result. The value true indicates that the 5A status is enabled, and the value false indicates that the 5A status is disabled.
options ObserverOptions No Observer options. This parameter specifies the slot ID for event subscription. The default value is the ID of the default data card slot.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.

Example

// Set the subscription parameters and specify the card slot ID.
let options: observer.ObserverOptions = {
    slotId: 0
}
// Define the callback for 5A network status changes.
let callback: Callback<boolean> = (isCommunicationStateOn: boolean) => {
    console.info(`communicationStateChanged ${JSON.stringify(isCommunicationStateOn)}`);
}
try {
    // Register an observer for 5A network status change events.
    observer.onCommunicationStateChange(callback, options);
} catch (err) {
    console.error(`observer.onCommunicationStateChange failed: ${JSON.stringify(err)}`);
}

observer.offCommunicationStateChange

offCommunicationStateChange(callback: Callback<boolean>, options?:ObserverOptions): void

Unregisters the observer for 5A network status change events. This API uses an asynchronous callback to return the execution result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.StateRegistry

Required permissions: ohos.permission.GET_NETWORK_INFO

Parameters

Name Type Mandatory Description
callback Callback<boolean> Yes Callback used to return the result. The value true indicates that the 5A status is enabled, and the value false indicates that the 5A status is disabled.
options ObserverOptions No Observer options. This parameter specifies the slot ID for event subscription. The default value is the ID of the default data card slot.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.

Example

let options: observer.ObserverOptions = {
    slotId: 0
}
let callback: Callback<boolean> = (isCommunicationStateOn: boolean) => {
    console.info(`communicationStateChanged ${JSON.stringify(isCommunicationStateOn)}`);
}
observer.onCommunicationStateChange(callback, options);
observer.offCommunicationStateChange(callback, options);

LockReason8+

Enumerates SIM card lock types.

System capability: SystemCapability.Telephony.StateRegistry

Name Value Description
SIM_NONE 0 No lock.
SIM_PIN 1 PIN lock.
SIM_PUK 2 PUK lock.
SIM_PN_PIN 3 Network PIN lock.
SIM_PN_PUK 4 Network PUK lock.
SIM_PU_PIN 5 Subnet PIN lock.
SIM_PU_PUK 6 Subnet PUK lock.
SIM_PP_PIN 7 Service provider PIN lock.
SIM_PP_PUK 8 Service provider PUK lock.
SIM_PC_PIN 9 Organization PIN lock.
SIM_PC_PUK 10 Organization PUK lock.
SIM_SIM_PIN 11 SIM PIN lock.
SIM_SIM_PUK 12 SIM PUK lock.

SimStateData7+

Enumerates SIM card types and states.

System capability: SystemCapability.Telephony.StateRegistry

Name Type Read-Only Optional Description
type CardType No No SIM card type.
state SimState No No SIM card state.
reason8+ LockReason No No SIM card lock type.

CallStateInfo11+

Defines information about the call status.

System capability: SystemCapability.Telephony.StateRegistry

Name Type Read-Only Optional Description
state CallState No No Call state.
number string No No Phone number. This parameter is only accessible to system apps. Third-party apps cannot obtain this parameter.

CCallStateInfo23+

Defines information about the call status.

System capability: SystemCapability.Telephony.StateRegistry

Name Type Read-Only Optional Description
state CCallState No No Call state.
teleNumber string No No Phone number.

DataConnectionStateInfo11+

Defines information about the data connection status.

System capability: SystemCapability.Telephony.StateRegistry

Name Type Read-Only Optional Description
state DataConnectState No No Data connection status.
network RatType No No Network type.

ObserverOptions11+

Defines event subscription parameters.

System capability: SystemCapability.Telephony.StateRegistry

Name Type Read-Only Optional Description
slotId number No No

Card slot ID.

- 0: card slot 1

- 1: card slot 2