目录

scan (NearLink Scanning Capability)

This module provides NearLink scanning functions.

Since: 5.0.1(13)

Modules to Import

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

startScan

startScan(filters: Array<ScanFilters>, options?: ScanOptions): Promise<void>

Initiates NearLink scanning with a specified filter. This API uses a promise 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
filters Array<ScanFilters> Yes

Scan filters, which are used to configure information such as the name and address of the device to be scanned.

All fields in ScanFilters are optional. If all of these fields are not configured, ScanFilters indicates a set of empty filters and is considered invalid, which will be ignored.

Fields in ScanFilters of filters cannot all be empty. Otherwise, error code 401 is returned.
options ScanOptions No Scan options. The low power consumption mode is used by default.

Returns:

Type Description
Promise<void> Promise that returns no value.

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.
1009700003 NearLink is off.
1009700099 Operation failed.

Example:

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

let scanFilter: scan.ScanFilters = {
  address: '11:22:33:44:AA:FF', // Address of the peripheral device that is expected to be scanned.
  deviceName: 'device name' // Name of the peripheral device that is expected to be scanned.
};
let scanOptions: scan.ScanOptions = {
  scanMode: scan.ScanMode.SCAN_MODE_LOW_POWER
};
try {
  scan.startScan([scanFilter], scanOptions).then(() => {
    console.info('start scan success');
  }).catch ((err: BusinessError) => {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

startScan

startScan(filters: Array<ScanFilters> | null, options?: ScanOptions): Promise<void>

Starts NearLink scanning and allows the filter parameter to be set to null. This API uses a promise 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: 26.0.0

Parameters:

Parameter Type Mandatory Description
filters Array<ScanFilters> | null Yes

Filter criteria for NearLink advertising. Devices that meet the filter criteria will be reported. If the filter is not enabled, null is passed.

If this parameter is set to null, all discoverable NearLink devices nearby will be scanned. However, this method is not recommended as it may pick up unexpected devices and increase power consumption.
options ScanOptions No Scan options. The low power consumption mode is used by default.

Returns:

Type Description
Promise<void> Promise that returns no value.

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 { scan } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Perform a scanning without using a filter.
try {
  scan.startScan(null).then(() => {
    console.info('start scan without filter success');
  }).catch ((err: BusinessError) => {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

// Perform a scanning using a filter.
let scanFilter: scan.ScanFilters = {
  address: '11:22:33:44:AA:FF',
  deviceName: 'device name'
};
try {
  scan.startScan([scanFilter]).then(() => {
    console.info('start scan with filter success');
  }).catch ((err: BusinessError) => {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

stopScan

stopScan(): Promise<void>

Stops NearLink scanning. This API uses a promise 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)

Returns:

Type Description
Promise<void> Promise that returns no value.

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 { scan } from '@kit.NearLinkKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  scan.stopScan().then(() => {
    console.info('stop scan success');
  }).catch ((err: BusinessError) => {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

on( 'deviceFound')

on(type: 'deviceFound', callback: Callback<Array<ScanResults>>): void

Subscribes to NearLink scanning results. 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 'deviceFound' indicates the event of the NearLink device scanning result.

A NearLink scan starts when scan.startScan is called. This event is triggered when a NearLink device is discovered.
callback Callback‌<‌Array‌<‌ScanResults‌>‌> Yes Callback used to return the NearLink scanning result array object. The random address of a remote device is carried in the scanning 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.

Example:

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

let onReceiveEvent:(data: Array<scan.ScanResults>) => void = (data: Array<scan.ScanResults>) => {
  console.info('scan result addr:' + data[0].address + 'name:' + data[0].deviceName);
};
try {
  scan.on('deviceFound', onReceiveEvent);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

off( 'deviceFound')

off(type: 'deviceFound', callback?: Callback<Array<ScanResults>>): void

Unsubscribes from NearLink scanning results. 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 'deviceFound' indicates the event of the NearLink device scanning result.
callback Callback<Array<‌ScanResults‌>> No

Callback used to return the NearLink scanning result array object.

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.

Example:

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

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

ScanResults

Scanning results.

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 Address of a scanned device. The address format is 11:22:33:AA:BB:FF.
rssi number No No RSSI of the device discovered. The value range is [–128, +127], in dBm. The value 127 indicates an invalid value.
data ArrayBuffer No No Advertising packet data.
deviceName string No No Name of the device discovered. The value contains 0 to 30 characters.
isConnectable boolean No No Indicates whether a discovered device is connectable. The value true indicates yes, and the value false indicates no.
deviceClass constant.DeviceClass No Yes

Type of the device discovered.

Since: 5.1.0(18)

ScanFilters

Scan filters.

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 Yes Device address. By default, this field is not used if it is not set. The address format is 11:22:33:AA:BB:FF.
deviceName string No Yes Device name. The value contains 0 to 30 characters. By default, this field is not used if it is not set.
manufacturerId number No Yes Manufacturer ID. The value range is [1, 65535]. By default, this field is not used if it is not set.
manufacturerData ArrayBuffer No Yes Manufacturer data. By default, this field is not used if it is not set. manufacturerId must be set along with the field.
manufacturerDataMask ArrayBuffer No Yes Manufacturer data mask. By default, this field is not used if it is not set. This field must be set along with manufacturerData, and the lengths of the two fields must be the same.
rssi number No Yes

RSSI threshold, in dBm. The value range is [–128, 127]. Broadcast packets whose RSSI is greater than or equal to this threshold will be filtered out. You are advised to set the threshold within the range of [–90, 20].

Since: 26.0.0

ScanOptions

Scan options.

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
scanMode ScanMode No Yes Scan mode. The default value is 'SCAN_MODE_LOW_POWER'.
duration number No Yes Scan duration, in seconds. The value range is [10, 60]. Full-time scanning is used by default.

ScanMode

Enumerated values of scan modes.

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
SCAN_MODE_LOW_POWER 0 Low power consumption scan mode. The scan frequency and power consumption are low. This value is used by default.
SCAN_MODE_BALANCED 1 Balanced scan mode. The scan frequency and power consumption are medium.