目录

manager (NearLink Enabling Capability)

This module provides basic NearLink management capabilities, including obtaining device information and subscribing to the status change event.

Since: 5.0.1(13)

Modules to Import

import { manager } from '@kit.NearLinkKit';

PairingState

type PairingState = constant.PairingState

Enumerated values of pairing statuses with a remote device.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Type Description
constant.PairingState Pairing status with a remote device.

ConnectionState

type ConnectionState = constant.ConnectionState

Enumerated values of connection statuses with a remote device.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Type Description
constant.ConnectionState Connection status with a remote device.

AcbState

type AcbState = constant.AcbState

Enumerated values of logical link connection statuses with a remote device.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.1.0(18)

Type Description
constant.AcbState Logical link connection status with a remote device.

getState

getState(): NearlinkState

Queries the NearLink status.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Returns:

Type Description
NearlinkState NearLink status.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let state: manager.NearlinkState = manager.getState();
  console.info('state:' + JSON.stringify(state));
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

isNearLinkSupported

isNearLinkSupported(): boolean

Checks whether the current device supports NearLink.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 6.1.0(23)

Returns:

Type Description
boolean true: The device supports NearLink. false: The device does not support NearLink.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let isSupported: boolean = manager.isNearLinkSupported();
  if (isSupported) {
    console.info('NearLink is supported on this device.');
  } else {
    console.info('NearLink is not supported on this device.');
  }
} catch (err) {
  console.error('Error occurred: ' + (err as BusinessError).code + ', ' + (err as BusinessError).message);
}

getLocalName

getLocalName(): string

Queries the NearLink name on the local device.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Returns:

Type Description
string Local name of the NearLink device. The value contains a maximum of 30 characters.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
1009700003 NearLink is off.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let name: string = manager.getLocalName();
  console.info('name:' + JSON.stringify(name));
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

getPairedDevices

getPairedDevices(): Array<string>

Obtains the list of devices paired with the current device.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 6.0.1(21)

Returns:

Type Description
Array<string> List of paired device addresses.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
1009700003 NearLink is off.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let pairedDevices: Array<string> = manager.getPairedDevices();
  if (pairedDevices.length > 0) {
        console.info('getPairedDevices return: ' + JSON.stringify(pairedDevices));
    } else {
        console.info('No Paired Devices found.');
    }
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

on( 'stateChange')

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

Subscribes to the NearLink status change event. This API uses an asynchronous callback to return the result.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Parameters:

Parameter Type Mandatory Description
type string Yes

Event type. The value 'stateChange' indicates a NearLink status change event.

This event is triggered when NearLink is enabled or disabled.
callback Callback<NearlinkState> Yes Callback used to return the NearLink status.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Invalid parameter.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let callback: Callback<manager.NearlinkState> = (data: manager.NearlinkState) => {
  if (data === manager.NearlinkState.STATE_TURNING_ON) {
    console.info('nearlink STATE_TURNING_ON');
  } else if (data === manager.NearlinkState.STATE_ON) {
    console.info('nearlink STATE_ON');
  } else if (data === manager.NearlinkState.STATE_TURNING_OFF) {
    console.info('nearlink STATE_TURNING_OFF');
  } else if (data === manager.NearlinkState.STATE_OFF) {
    console.info('nearlink STATE_OFF');
  }
};
try {
  manager.on('stateChange', callback);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

off( 'stateChange')

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

Unsubscribes from the NearLink status change event. This API uses an asynchronous callback to return the result.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Parameters:

Parameter Type Mandatory Description
type string Yes Event type. The value 'stateChange' indicates a NearLink status change event.
callback Callback<NearlinkState> No

Callback used to return the NearLink status.

If this parameter is set, the current callback subscription is canceled. If this parameter is not set, all callbacks corresponding to the type are unsubscribed.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Invalid parameter.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  manager.off('stateChange');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

on( 'pairingStateChange')

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

Subscribes to pairing status change events. This API uses an asynchronous callback to return the result.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Parameters:

Parameter Type Mandatory Description
type string Yes

Event type. The value 'pairingStateChange' indicates a pairing status change event.

This event is triggered when remoteDevice.startPairing is called to initiate pairing or the local device receives a pairing request from another device.
callback Callback<PairingStateParam> Yes Callback used to return the subscribed pairing status change result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let onPairingStateEvent:(data: manager.PairingStateParam) => void = (data: manager.PairingStateParam) => {
  console.info('onPairStateChange addr: ' + data.address + ', state: ' + data.state);
};
try {
  manager.on('pairingStateChange', onPairingStateEvent);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

off( 'pairingStateChange')

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

Unsubscribes from pairing status change events. This API uses an asynchronous callback to return the result.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Parameters:

Parameter Type Mandatory Description
type string Yes Event type. The value 'pairingStateChange' indicates a pairing status change event.
callback Callback<PairingStateParam> No

Callback used to return the subscribed pairing status change result.

If this parameter is set, the current callback subscription is canceled. If this parameter is not set, all callbacks corresponding to the type are unsubscribed.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  manager.off('pairingStateChange');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

on( 'connectionStateChange')

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

Subscribes to the connection status change event. This API uses an asynchronous callback to return the result.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Parameters:

Parameter Type Mandatory Description
type string Yes

Event type. The value 'connectionStateChange' indicates a connection status change event.

This event is triggered when the connection status with the remote device changes.
callback Callback<ConnectionStateParam> Yes Callback used to return the result of the connection status change event.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let callback: Callback<manager.ConnectionStateParam> = (data: manager.ConnectionStateParam) => {
  console.info('data:' + JSON.stringify(data));
};
try {
  manager.on('connectionStateChange', callback);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

off( 'connectionStateChange')

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

Unsubscribes from the connection status change event. This API uses an asynchronous callback to return the result.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Parameters:

Parameter Type Mandatory Description
type string Yes Event type. The value 'connectionStateChange' indicates a connection status change event.
callback Callback<ConnectionStateParam> No

Callback used to return the result of the connection status change event.

If this parameter is set, the current callback subscription is canceled. If this parameter is not set, all callbacks corresponding to the type are unsubscribed.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  manager.off('connectionStateChange');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

on('acbStateChange')

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

Subscribes to the logical link connection status change event. This API uses an asynchronous callback to return the result.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.1.0(18)

Parameters:

Parameter Type Mandatory Description
type string Yes

Event type. The value 'acbStateChange' indicates a logical link connection status change event.

This event is triggered when the logical link connection status with the remote device changes.
callback Callback<AcbStateParam> Yes Callback used to return the result of the logical link connection status change event.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let callback: Callback<manager.AcbStateParam> = (data: manager.AcbStateParam) => {
  console.info('data:' + JSON.stringify(data));
};
try {
  manager.on('acbStateChange', callback);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

off( 'acbStateChange')

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

Unsubscribes from the logical link connection status change event. This API uses an asynchronous callback to return the result.

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

Required permissions: ohos.permission.ACCESS_NEARLINK

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.1.0(18)

Parameters:

Parameter Type Mandatory Description
type string Yes Event type. The value 'acbStateChange' indicates a logical link connection status change event.
callback Callback<AcbStateParam> No

Callback used to return the result of the logical link connection status change event.

If this parameter is set, the current callback subscription is canceled. If this parameter is not set, all callbacks corresponding to the type are unsubscribed.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801 Capability not supported.
1009700099 Operation failed.

Example:

import { manager } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  manager.off('acbStateChange');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

PairingStateParam

Result of the pairing status change event.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Name Type Read-Only Optional Description
address string No No Device address, indicating that the pairing status with the device changes. The address format is 11:22:33:AA:BB:FF.
preState PairingState No No Pairing status before this report.
state PairingState No No Current pairing status.
reason PairingReason No No Cause value.
reasonMsg string No Yes

Reason details. This field is used only for log information and is not used for logic processing.

Since: 26.0.0

PairingRequestParam

Result of the pairing request event.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Name Type Read-Only Optional Description
address string No No Device address, indicating that the pairing request from the device is received. The address format is 11:22:33:AA:BB:FF.
passkey string No No Code for pairing interaction, which is displayed to you for confirmation. The value is a string of six digits.
pairingType PairingType No No Pairing type.

ConnectionStateParam

Result of the connection status change event.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Name Type Read-Only Optional Description
address string No No Device address, indicating that the connection status with the device changes. The address format is 11:22:33:AA:BB:FF.
preState ConnectionState No No Connection status before this report.
state ConnectionState No No Current connection status.
connectionReason ConnectionReason No No Cause value.
reasonMsg string No Yes

Reason details. This field is used only for log information and is not used for logic processing.

Since: 26.0.0

NearlinkState

Enumerated values of NearLink statuses.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Name Value Description
STATE_TURNING_ON 0 NearLink is being turned on.
STATE_ON 1 NearLink has been turned on.
STATE_TURNING_OFF 2 NearLink is being turned off.
STATE_OFF 3 NearLink has been turned off.

PairingReason

Enumerated values of causes of the NearLink pairing status change result.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Name Value Description
PAIRING_REASON_SUCCESS 0 The pairing is successful.
PAIRING_REASON_FAILURE 1 The pairing fails.
PAIRING_REASON_PROFILE_UNSUPPORTED 2

The pairing fails because the remote device does not support the service.

Since: 5.1.0(18)
PAIRING_REASON_EXCEED_ACB_MAX 3

The pairing fails because the number of connected devices has reached the upper limit.

Since: 5.1.0(18)
PAIRING_REASON_REMOTE_CANCELED 4

The pairing fails because the remote device cancels the pairing.

Since: 5.1.0(18)
PAIRING_REASON_LOCAL_CANCELED 5

The pairing fails because the local device cancels the pairing.

Since: 5.1.0(18)

PairingType

Enumerated values of NearLink pairing types.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Name Value Description
NO_PASSKEY_CONFIRMATION 0 Pairing type that does not require a passkey. You do not need to check the pairing code.
PAIRING_TYPE_PASSCODE 1

Pairing type with passcode authentication. You need to enter the pairing code displayed on one device into the other device.

Since: 5.1.0(18)
PAIRING_TYPE_NUMBER_COMPARE 2

Pairing type with number comparison authentication. You must ensure that the pairing codes on both devices are the same.

Since: 5.1.0(18)

ConnectionReason

Cause values of the result of a NearLink connection status change.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.0.1(13)

Name Value Description
CONNECTION_SUCCESS 0 The connection is successful.
CONNECTION_FAILURE 1 The connection fails.

AcbStateParam

Result of the logical link connection status change event.

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

System capability: SystemCapability.Communication.NearLink.Core

Since: 5.1.0(18)

Name Type Read-Only Optional Description
address string No No Device address, indicating that the logical link connection status with the device changes. The address format is 11:22:33:AA:BB:FF.
state AcbState No No Current logical link connection status.