@ohos.distributedsched.abilityConnectionManager (Cross-Device Connection Management) (System API)

The abilityConnectionManager module provides APIs for cross-device connection management. After successful networking between devices (login with the same account and enabling of Bluetooth on the devices), a system application and third-party application can start a UIAbility of the same application across the devices. After a connection is successfully established, data can be transmitted across the devices, including strings, ArrayBuffer byte streams, images, and transport streams.

NOTE

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

The APIs provided by this module are system APIs. The APIs of this module can be used only in the stage model.

Modules to Import

import { abilityConnectionManager } from '@kit.DistributedServiceKit';

abilityConnectionManager.on('collaborateEvent')

on(type: 'collaborateEvent', sessionId: number, callback: Callback<CollaborateEventInfo>): void

Registers a listener for the collaborateEvent events. 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.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is collaborateEvent. This event is triggered when collaborateEvent() is called.
sessionId	number	Yes	Collaboration session ID.
callback	Callback<CollaborateEventInfo>	Yes	Registered callback function, which returns collaboration event information.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let sessionId = 100;
abilityConnectionManager.on("collaborateEvent", sessionId, (callbackInfo) => {
  hilog.info(0x0000, 'testTag', 'session collaborateEvent, eventType is', callbackInfo.eventType);
});

abilityConnectionManager.on('receiveImage')

on(type: 'receiveImage', sessionId: number, callback: Callback<EventCallbackInfo>): void

Registers a listener for the receiveImage events.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is receiveImage. This event is triggered when sendImage() is called.
sessionId	number	Yes	Collaboration session ID.
callback	Callback<EventCallbackInfo>	Yes	Registered callback.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

abilityConnectionManager.on("receiveImage", sessionId, (callbackInfo) => {
  hilog.info(0x0000, 'testTag', 'session receiveImage, sessionId is', callbackInfo.sessionId);
});

abilityConnectionManager.off('collaborateEvent')

off(type: 'collaborateEvent', sessionId: number, callback?: Callback<CollaborateEventInfo>): void

Unregisters the listener for the collaborateEvent events.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is collaborateEvent.
sessionId	number	Yes	Collaboration session ID.
callback	Callback<CollaborateEventInfo>	No	Registered callback. If a value is passed in, listening will be disabled for the specified event callback. If no value is passed in, listening will be disabled for all event callbacks.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';

let sessionId = 100;
abilityConnectionManager.off("collaborateEvent", sessionId);

abilityConnectionManager.off('receiveImage')

off(type: 'receiveImage', sessionId: number, callback?: Callback<EventCallbackInfo>): void

Unregisters the listener for the receiveImage events.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is receiveImage.
sessionId	number	Yes	Collaboration session ID.
callback	Callback<EventCallbackInfo>	No	Registered callback. If a value is passed in, listening will be disabled for the specified event callback. If no value is passed in, listening will be disabled for all event callbacks.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';

let sessionId = 100;
abilityConnectionManager.off("receiveImage", sessionId);

abilityConnectionManager.sendImage

sendImage(sessionId: number, image: image.PixelMap, quality?: number): Promise<void>

Sends images from one device to another after a connection is successfully established. This method uses a promise to return the result asynchronously.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
sessionId	number	Yes	Collaboration session ID.
image	image.PixelMap	Yes	Image information.
quality	number	No	Image compression quality. The value ranges from 0 to 100. The default value is 30.

Return value

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

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { image } from '@kit.ImageKit';
import { fileIo } from '@kit.CoreFileKit';

try {
  let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
  photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
  photoSelectOptions.maxSelectNumber = 5;
  let photoPicker = new photoAccessHelper.PhotoViewPicker();
  photoPicker.select(photoSelectOptions).then((photoSelectResult) => {
    if (!photoSelectResult) {
      hilog.error(0x0000, 'testTag', 'photoSelectResult = null');
    return;
    }

    let file = fileIo.openSync(photoSelectResult.photoUris[0], fileIo.OpenMode.READ_ONLY);
    hilog.info(0x0000, 'testTag', 'file.fd:' + file.fd);

    let sessionId = 100;
    let imageSourceApi: image.ImageSource = image.createImageSource(file.fd);
    if (imageSourceApi) {
      imageSourceApi.createPixelMap().then((pixelMap) => {
        abilityConnectionManager.sendImage(sessionId, pixelMap)
      });
    } else {
      hilog.info(0x0000, 'testTag', 'imageSourceApi is undefined');
    }
  })
} catch (error) {
  hilog.error(0x0000, 'testTag', 'photoPicker failed with error: ' + JSON.stringify(error));
}

abilityConnectionManager.createStream

createStream(sessionId: number, param: StreamParam): Promise<number>

Creates transport streams to send images and videos from one device to another after a connection is successfully established. This API uses a promise to return the result.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
sessionId	number	Yes	Collaboration session ID.
param	StreamParam	Yes	Transport stream configuration.

Return value

Type	Description
Promise<number>	Promise used to return the result. The number in the promise indicates the creation result.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
32300001	Only one stream can be created for the current session.
32300003	Bitrate not supported.
32300004	Color space not supported.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

hilog.info(0x0000, 'testTag', 'startStream');
let sessionId = 100;
abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => {
  let surfaceParam: abilityConnectionManager.SurfaceParam = {
    width: 640,
    height: 480,
    format: 1
  }
  let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam);
  hilog.info(0x0000, 'testTag', 'surfaceId is'+surfaceId);
  AppStorage.setOrCreate<string>('surfaceId', surfaceId);
  abilityConnectionManager.startStream(streamId);
})

abilityConnectionManager.setSurfaceId

setSurfaceId(streamId: number, surfaceId: string, param: SurfaceParam): void

Sets the binding relationship between transport streams and surfaces.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
streamId	number	Yes	Collaboration session ID.
surfaceId	string	Yes	Unique surface ID.
param	SurfaceParam	Yes	Surface configuration.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

hilog.info(0x0000, 'testTag', 'setSurfaceId');
let sessionId = 100;
abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => {
  let surfaceParam: abilityConnectionManager.SurfaceParam = {
    width: 640,
    height: 480,
    format: 1
  }
  let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam);
  abilityConnectionManager.setSurfaceId(streamId, surfaceId, surfaceParam);
})

abilityConnectionManager.getSurfaceId

getSurfaceId(streamId: number, param: SurfaceParam): string

Obtains the unique ID of the surface bound to the specified transport streams.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
streamId	number	Yes	Collaboration session ID.
param	SurfaceParam	Yes	Surface configuration.

Return value

Type	Description
string	Unique ID of the surface.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

hilog.info(0x0000, 'testTag', 'getSurfaceId');
let sessionId = 100;
abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => {
  let surfaceParam: abilityConnectionManager.SurfaceParam = {
    width: 640,
    height: 480,
    format: 1
  }
  let surfaceId = abilityConnectionManager.getSurfaceId(streamId, surfaceParam);
})

abilityConnectionManager.updateSurfaceParam

updateSurfaceParam(streamId: number, param: SurfaceParam): void

Updates the configuration of the surface bound to the specified transport streams.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
streamId	number	Yes	Collaboration session ID.
param	SurfaceParam	Yes	Surface configuration.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

hilog.info(0x0000, 'testTag', 'updateSurfaceParam');
let sessionId = 100;
abilityConnectionManager.createStream(sessionId ,{name: 'receive', role: 0}).then(async (streamId) => {
  let surfaceParam: abilityConnectionManager.SurfaceParam = {
    width: 640,
    height: 480,
    format: 1
  }
  abilityConnectionManager.updateSurfaceParam(streamId, surfaceParam);
})

abilityConnectionManager.destroyStream

destroyStream(streamId: number): void

Destroys the transport streams after the sending of images and videos is complete.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
streamId	number	Yes	Collaboration session ID.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let sessionId = 100;
hilog.info(0x0000, 'testTag', 'destroyStream called');
abilityConnectionManager.destroyStream(sessionId)

abilityConnectionManager.startStream

startStream(streamId: number): void

Starts transmission of the specified transport streams.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
streamId	number	Yes	Collaboration session ID.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
32300002	The stream at the receive end is not started.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let sessionId = 100;
hilog.info(0x0000, 'testTag', 'startStream called');
abilityConnectionManager.startStream(sessionId)

abilityConnectionManager.stopStream

stopStream(streamId: number): void

Stops transmission of the specified transport streams.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
streamId	number	Yes	Collaboration session ID.

Error codes

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

ID	Error Message
202	Not system App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let sessionId = 100;
hilog.info(0x0000, 'testTag', 'stopStream called');
abilityConnectionManager.stopStream(sessionId)

CollaborateEventInfo

Defines the collaboration event information.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Type	Read-Only	Optional	Description
eventType	CollaborateEventType	No	No	Collaboration event type.
eventMsg	string	No	Yes	Collaboration event message.

StreamParam

Defines stream transmission configuration parameters.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Type	Read-Only	Optional	Description
name	string	No	No	Stream name. It must be the same on the TX end and RX end.
role	StreamRole	No	No	Stream role, which can be TX stream or RX stream.
bitrate	number	No	Yes	Video bit rate. It is valid only for the TX end. The default value is 80000.
colorSpaceConversionTarget	colorSpaceManager.ColorSpace	No	Yes	Target color space.

SurfaceParam

Defines the surface configuration.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Type	Read-Only	Optional	Description
width	number	No	No	Encoding width. Set this parameter prior to stream transmission. Once stream transmission starts, the setting cannot be updated until the stream transmission ends. If you need to update the setting, stop stream transmission first.
height	number	No	No	Encoding length. Set this parameter prior to stream transmission. Once stream transmission starts, the setting cannot be updated until the stream transmission ends. If you need to update the setting, stop stream transmission first.
format	VideoPixelFormat	No	Yes	Video pixel format (valid only at the TX end).
rotation	number	No	Yes	Rotation angle of the video. The value range is {0, 90, 180, 270}. The default value is 0.
flip	FlipOptions	No	Yes	Video flip option.

CollaborateEventType

Enumerates collaboration event types.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Value	Description
SEND_FAILURE	0	Task sending failure.
COLOR_SPACE_CONVERSION_FAILURE	1	Color space conversion failure.

FlipOptions

Enumerates video flip options.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Value	Description
HORIZONTAL	0	Horizontal flip.
VERTICAL	1	Vertical flip.

StreamRole

Enumerates stream transmission modes.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Value	Description
SOURCE	0	TX stream.
SINK	1	RX stream.

VideoPixelFormat

Enumerates video pixel formats.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Value	Description
UNKNOWN	-1	Unknown pixel format.
NV12	0	NV12, YUV420 semi-planar format.
NV21	1	NV21, YUV420 semi-planar format.

ConnectOptions

Defines the connection options for the application.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Type	Read-Only	Optional	Description
needSendStream	boolean	No	Yes	Whether to send streams. The value true means to send streams, and the value false means the opposite.
needReceiveStream	boolean	No	Yes	Whether to receive streams. The value true means to receive streams, and the value false means the opposite.

EventCallbackInfo

Defines the event callback information.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Type	Read-Only	Optional	Description
image	image.PixelMap	No	Yes	Received image.

StartOptionParams

Enumerates application start options.

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

System capability: SystemCapability.DistributedSched.AppCollaboration

Name	Value	Description
START_IN_BACKGROUND	1	Start of the peer application in the background.