Interface (ImageReceiver)

The ImageReceiver class provides APIs to obtain the surface ID of a component, read the latest image, read the next image, and release the ImageReceiver instance. The ImageReceiver acts as the receiver and consumer of images. Its parameter properties do not actually affect the received images. The configuration of image properties should be done on the sending side (the producer), such as when creating a camera preview stream with createPreviewOutput.

Before calling any APIs in ImageReceiver, you must use image.createImageReceiver to create an ImageReceiver instance.

Since API version 23, you are advised to use image.createImageReceiver to create an ImageReceiver instance based on the passed ImageReceiverOptions.

Images occupy a large amount of memory. When you finish using an ImageReceiver instance, call release to free the memory promptly. Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

NOTE

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.

The initial APIs of this interface are supported since API version 9.

Modules to Import

import { image } from '@kit.ImageKit';

Properties

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Name	Type	Read Only	Optional	Description
size⁹⁺	Size	Yes	No	Image size. This parameter does not affect the size of the received image. The actual returned size is determined by the producer, for example, the camera.
capacity⁹⁺	number	Yes	No	Maximum number of images that can be accessed at the same time. This parameter is used only as an expected value. The actual capacity is determined by the device hardware.
format⁹⁺	ImageFormat	Yes	No	Image format. The value is an enum value of ImageFormat. (Currently, only ImageFormat:JPEG is supported. The format actually returned depends on the producer, for example, camera.)

getReceivingSurfaceId⁹⁺

getReceivingSurfaceId(callback: AsyncCallback<string>): void

Obtains a surface ID for the camera or other components. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<string>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the surface ID obtained. Otherwise, err is an error object.

Example

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

async function GetReceivingSurfaceId(receiver : image.ImageReceiver) {
  receiver.getReceivingSurfaceId((err: BusinessError, id: string) => {
    if (err) {
      console.error(`Failed to get the ReceivingSurfaceId.code ${err.code},message is ${err.message}`);
    } else {
      console.info('Succeeded in getting the ReceivingSurfaceId.');
    }
  });
}

getReceivingSurfaceId⁹⁺

getReceivingSurfaceId(): Promise<string>

Obtains a surface ID for the camera or other components. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Return value

Type	Description
Promise<string>	Promise used to return the surface ID.

Example

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

async function GetReceivingSurfaceId(receiver : image.ImageReceiver) {
  receiver.getReceivingSurfaceId().then((id: string) => { 
    console.info('Succeeded in getting the ReceivingSurfaceId.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to get the ReceivingSurfaceId.code ${error.code},message is ${error.message}`);
  })
}

readLatestImage⁹⁺

readLatestImage(callback: AsyncCallback<Image>): void

Reads the latest image from the ImageReceiver instance. This API uses an asynchronous callback to return the result.

NOTE This API can be called to receive data only after the on callback is triggered. When the Image object returned by this API is no longer needed, call release to release the object. New data can be received only after the release.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Image>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the latest image obtained; otherwise, err is an error object.

Example

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

async function ReadLatestImage(receiver : image.ImageReceiver) {
  receiver.readLatestImage((err: BusinessError, img: image.Image) => {
    if (err) {
      console.error(`Failed to read the latest Image.code ${err.code},message is ${err.message}`);
    } else {
      console.info('Succeeded in reading the latest Image.');
    }
  });
}

readLatestImage⁹⁺

readLatestImage(): Promise<Image>

Reads the latest image from the ImageReceiver instance. This API uses a promise to return the result.

NOTE This API can be called to receive data only after the on callback is triggered. When the Image object returned by this API is no longer needed, call release to release the object. New data can be received only after the release.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Return value

Type	Description
Promise<Image>	Promise used to return the latest image.

Example

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

async function ReadLatestImage(receiver : image.ImageReceiver) {
  receiver.readLatestImage().then((img: image.Image) => {
    console.info('Succeeded in reading the latest Image.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to read the latest Image.code ${error.code},message is ${error.message}`);
  });
}

readNextImage⁹⁺

readNextImage(callback: AsyncCallback<Image>): void

Reads the next image from the ImageReceiver instance. This API uses an asynchronous callback to return the result.

NOTE This API can be called to receive data only after the on callback is triggered. When the Image object returned by this API is no longer needed, call release to release the object. New data can be received only after the release.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Image>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the next image obtained. Otherwise, err is an error object.

Example

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

async function ReadNextImage(receiver : image.ImageReceiver) {
  receiver.readNextImage((err: BusinessError, img: image.Image) => {
    if (err) {
      console.error(`Failed to read the next Image.code ${err.code},message is ${err.message}`);
    } else {
      console.info('Succeeded in reading the next Image.');
    }
  });
}

readNextImage⁹⁺

readNextImage(): Promise<Image>

Reads the next image from the ImageReceiver instance. This API uses a promise to return the result.

NOTE This API can be called to receive data only after the on callback is triggered. When the Image object returned by this API is no longer needed, call release to release the object. New data can be received only after the release.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Return value

Type	Description
Promise<Image>	Promise used to return the next image.

Example

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

async function ReadNextImage(receiver : image.ImageReceiver) {
  receiver.readNextImage().then((img: image.Image) => {
    console.info('Succeeded in reading the next Image.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to read the next Image.code ${error.code},message is ${error.message}`);
  });
}

on⁹⁺

on(type: 'imageArrival', callback: AsyncCallback<void>): void

Listens for image arrival events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of event to listen for. The value is fixed at 'imageArrival'. This event is triggered when an image is received.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

async function On(receiver : image.ImageReceiver) {
  receiver.on('imageArrival', () => {
    // Implement the callback logic when an image is received.
  });
}

off¹³⁺

off(type: 'imageArrival', callback?: AsyncCallback<void>): void

Unregisters the callback function that is triggered when the buffer is released. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of event, which is 'imageArrival'.
callback	AsyncCallback<void>	No	Callback to unregister.

Example

async function Off(receiver : image.ImageReceiver) {
  let callbackFunc = ()=>{
      // Implement the callback logic.
  };
  receiver.on('imageArrival', callbackFunc);
  receiver.off('imageArrival', callbackFunc);
}

release⁹⁺

release(callback: AsyncCallback<void>): void

Releases this ImageReceiver instance. This API uses an asynchronous callback to return the result.

Images occupy a large amount of memory. When you finish using an ImageReceiver instance, call this API to free the memory promptly.

Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

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

async function Release(receiver : image.ImageReceiver) {
  receiver.release((err: BusinessError) => {
    if (err) {
      console.error(`Failed to release the receiver.code ${err.code},message is ${err.message}`);
    } else {
      console.info('Succeeded in releasing the receiver.');
    }
  })
}

release⁹⁺

release(): Promise<void>

Releases this ImageReceiver instance. This API uses a promise to return the result.

Images occupy a large amount of memory. When you finish using an ImageReceiver instance, call this API to free the memory promptly.

Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

System capability: SystemCapability.Multimedia.Image.ImageReceiver

Return value

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

Example

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

async function Release(receiver : image.ImageReceiver) {
  receiver.release().then(() => {
    console.info('Succeeded in releasing the receiver.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to release the receiver.code ${error.code},message is ${error.message}`);
  })
}