目录

dataTransfer (NearLink Data Transfer Capability)

This module provides the NearLink data transfer capability.

Since: 5.1.0(18)

Modules to Import

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

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.1.0(18)

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

createPort

createPort(uuid: string): void

Registers a port channel.

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
uuid string Yes Set this parameter to a 16-byte UUID or a 2-byte UUID of a standard NearLink service that supports data transfer. For details about the UUID format, please refer to UUID Format for a Standard NearLink Service.

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.
1009700020 The UUID is already registered.
1009700021 The number of ports exceeds the upper limit.
1009700099 Operation failed.

Example:

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

try {
  let uuid: string = 'FFFFFFFF-FC70-11EA-B720-000078951234'; // NearLink service UUID.
  dataTransfer.createPort(uuid);
  console.info('create port success');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

destroyPort

destroyPort(uuid: string): void

Destroys a port channel.

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
uuid string Yes Set this parameter to a 16-byte UUID or a 2-byte UUID of a standard NearLink service that supports data transfer. For details about the UUID format, please refer to UUID Format for a Standard NearLink Service.

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.
1009700022 The UUID is not registered.
1009700099 Operation failed.

Example:

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

try {
  let uuid: string = 'FFFFFFFF-FC70-11EA-B720-000078951234'; // NearLink service UUID.
  dataTransfer.destroyPort(uuid);
  console.info('destroy port success');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connect

connect(params: ConnectionParams): Promise<void>

Connects to a remote device and establishes a port channel. 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.1.0(18)

Parameters:

Parameter Type Mandatory Description
params ConnectionParams Yes Connection parameters of the port.

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

try {
  // Construct parameters for establishing a port channel.
  let connectionParams:dataTransfer.ConnectionParams = {
    address: '01:02:03:04:05:06', // Address of the remote NearLink device.
    uuid: '37BEA880-FC70-11EA-B720-00000000060D', // NearLink service UUID.
    mtu: 1024 // Size of the data packet expected to be sent, in bytes. This parameter is optional.
  };
  dataTransfer.connect(connectionParams).then(()=>{
    console.info('connect 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);
}

disconnect

disconnect(params: ConnectionParams): Promise<void>

Disconnects from a remote device and destroys a port channel. 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.1.0(18)

Parameters:

Parameter Type Mandatory Description
params ConnectionParams Yes Connection parameters of the port.

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

try {
  // Construct parameters for establishing a port channel.
  let connectionParams:dataTransfer.ConnectionParams = {
    address: '01:02:03:04:05:06', // Address of the remote NearLink device.
    uuid: '37BEA880-FC70-11EA-B720-00000000060D', // NearLink service UUID.
    mtu: 1024 // Size of the data packet expected to be sent, in bytes. This parameter is optional.
  };
  dataTransfer.disconnect(connectionParams).then(()=>{
    console.info('disconnect 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('connectionStateChanged')

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

Subscribes to the port channel 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 'connectionStateChanged' indicates a connection status change event.

This event is triggered when the connection status of the port channel changes.

For example, the connection status may change when dataTransfer.connect or dataTransfer.disconnect is called.
callback Callback<ConnectionResult> Yes Callback used to return the result of port connection parameter negotiation with a remote device.

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

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

off('connectionStateChanged')

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

Unsubscribes from the port channel 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 'connectionStateChanged' indicates a data transfer connection status change event.
callback Callback<ConnectionResult> No

Callback used to return the result of port connection parameter negotiation with a remote device.

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

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

getConnectionState

getConnectionState(params: ConnectionStateParams): ConnectionState

Obtains the connection status of the port channel between a local device and a remote 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.1.0(18)

Parameters:

Parameter Type Mandatory Description
params ConnectionStateParams Yes Connection parameters of the port.

Returns:

Type Description
ConnectionState NearLink port channel connection status with a remote device.

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

Example:

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

try {
  let connectionStateParams:dataTransfer.ConnectionStateParams = {
    address: '01:02:03:04:05:06', // Address of the remote device obtained through scanning.
    uuid: 'FFFFFFFF-FC70-11EA-B720-000078951234' // NearLink service UUID.
  };
  let state:dataTransfer.ConnectionState = dataTransfer.getConnectionState(connectionStateParams);
  console.info('state:' + JSON.stringify(state));
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

writeData

writeData(params: DataParams): Promise<void>

Sends data to a remote device using the device address and UUID. 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.1.0(18)

Parameters:

Parameter Type Mandatory Description
params DataParams Yes Parameters for data sending, including the remote device address, service UUID, and data packet to be sent.

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.
1009700023 The data writing process is congested.
1009700099 Operation failed.

Example:

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

try {
  // Construct parameters for data sending.
  let transferValueBuffer: Uint8Array = new Uint8Array(4);
  transferValueBuffer[0] = 1;
  transferValueBuffer[1] = 2;
  transferValueBuffer[2] = 3;
  transferValueBuffer[3] = 4;
  let dataParams: dataTransfer.DataParams = {
    address: '01:02:03:04:05:06', // Address of the remote NearLink device.
    uuid: '37BEA880-FC70-11EA-B720-00000000060D', // NearLink service UUID.
    data: transferValueBuffer.buffer // Data to be transferred between NearLink devices.
  };
  dataTransfer.writeData(dataParams).then(() => {
    console.info('writeData 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('readData')

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

Subscribes to the port channel data receiving 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 'readData' indicates the port channel data receiving event.

This event is triggered when port data is received from the remote device.
callback Callback<DataParams> Yes Callback used to return the parameters for port data sending and receiving.

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

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

off('readData')

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

Unsubscribes from the port channel data receiving 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 'readData' indicates the port channel data receiving event.
callback Callback<DataParams> No

Callback used to return the parameters for port data sending and receiving.

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

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

ConnectionParams

Parameters for initiating a port connection.

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 Address of a remote NearLink device. The address format is 11:22:33:AA:BB:FF.
uuid string No No NearLink service UUID, for example, 37bea880-fc70-11ea-b720-000000004386. For details about the UUID format, please refer to UUID Format for a Standard NearLink Service.
mtu number No Yes Expected length of the data packet to be sent, in bytes. The value range is [0, 65535]. The default value is 512.
transferMode TransferMode No Yes Data transfer mode with a remote device. The default value is BASIC.

DataParams

Parameters for port data sending and receiving.

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 Address of a remote NearLink device. The address format is 11:22:33:AA:BB:FF.
uuid string No No NearLink service UUID, for example, 37bea880-fc70-11ea-b720-000000004386. For details about the UUID format, please refer to UUID Format for a Standard NearLink Service.
data ArrayBuffer No No Data packet to be sent.

ConnectionResult

Result of port connection parameter negotiation 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)

Name Type Read-Only Optional Description
address string No No Address of a remote NearLink device. The address format is 11:22:33:AA:BB:FF.
uuid string No No NearLink service UUID, for example, 37bea880-fc70-11ea-b720-000000004386. For details about the UUID format, please refer to UUID Format for a Standard NearLink Service.
mtu number No No Negotiated length of the sent and received data packets, in bytes. The value range is [0, 65535].
state ConnectionState No No Connection status with a remote device.

ConnectionStateParams

Parameters for obtaining port channel connection statuses.

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 Address of a remote NearLink device. The address format is 11:22:33:AA:BB:FF.
uuid string No No NearLink service UUID, for example, 37bea880-fc70-11ea-b720-000000004386. For details about the UUID format, please refer to UUID Format for a Standard NearLink Service.

TransferMode

Enumerated values of data transfer modes 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)

Name Value Description
BASIC 0 Basic mode, without a data retransfer mechanism.
RELIABLE 1 Reliable mode, with a data retransfer mechanism.