1# Interface (ImageReceiver) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--SE: @liyang_bryan--> 6<!--TSE: @xchaosioda--> 7 8> **NOTE** 9> 10> - 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. 11> - The initial APIs of this interface are supported since API version 9. 12 13The **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](../apis-camera-kit/arkts-apis-camera-CameraManager.md#createpreviewoutput). 14 15Before calling any APIs in ImageReceiver, you must create an ImageReceiver instance. 16 17## Modules to Import 18 19```ts 20import { image } from '@kit.ImageKit'; 21``` 22 23## Properties 24 25**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 26 27| Name | Type | Read Only| Optional| Description | 28| -------- | ---------------------------- | ---- | ---- | ------------------ | 29| size<sup>9+</sup> | [Size](arkts-apis-image-i.md#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. | 30| capacity<sup>9+</sup> | 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.| 31| format<sup>9+</sup> | [ImageFormat](arkts-apis-image-e.md#imageformat9) | Yes | No | Image format, which is a constant of [ImageFormat](arkts-apis-image-e.md#imageformat9). (Currently, only **ImageFormat:JPEG** is supported. The format actually returned is determined by the producer, for example, camera.) | 32 33## getReceivingSurfaceId<sup>9+</sup> 34 35getReceivingSurfaceId(callback: AsyncCallback\<string>): void 36 37Obtains a surface ID for the camera or other components. This API uses an asynchronous callback to return the result. 38 39**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 40 41**Parameters** 42 43| Name | Type | Mandatory| Description | 44| -------- | ---------------------- | ---- | -------------------------- | 45| 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.| 46 47**Example** 48 49```ts 50import { BusinessError } from '@kit.BasicServicesKit'; 51 52receiver.getReceivingSurfaceId((err: BusinessError, id: string) => { 53 if (err) { 54 console.error(`Failed to get the ReceivingSurfaceId.code ${err.code},message is ${err.message}`); 55 } else { 56 console.info('Succeeded in getting the ReceivingSurfaceId.'); 57 } 58}); 59``` 60 61## getReceivingSurfaceId<sup>9+</sup> 62 63getReceivingSurfaceId(): Promise\<string> 64 65Obtains a surface ID for the camera or other components. This API uses a promise to return the result. 66 67**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 68 69**Return value** 70 71| Type | Description | 72| ---------------- | -------------------- | 73| Promise\<string> | Promise used to return the surface ID.| 74 75**Example** 76 77```ts 78import { BusinessError } from '@kit.BasicServicesKit'; 79 80receiver.getReceivingSurfaceId().then((id: string) => { 81 console.info('Succeeded in getting the ReceivingSurfaceId.'); 82}).catch((error: BusinessError) => { 83 console.error(`Failed to get the ReceivingSurfaceId.code ${error.code},message is ${error.message}`); 84}) 85``` 86 87## readLatestImage<sup>9+</sup> 88 89readLatestImage(callback: AsyncCallback\<Image>): void 90 91Reads the latest image from the ImageReceiver instance. This API uses an asynchronous callback to return the result. 92 93This API can be called to receive data only after the [on](#on9) callback is triggered. When the [Image](arkts-apis-image-Image.md) object returned by this API is no longer needed, call [release](arkts-apis-image-Image.md#release9) to release the object. New data can be received only after the release. 94 95**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 96 97**Parameters** 98 99| Name | Type | Mandatory| Description | 100| -------- | ------------------------------- | ---- | ------------------------ | 101| callback | AsyncCallback<[Image](arkts-apis-image-Image.md)> | 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. | 102 103**Example** 104 105```ts 106import { BusinessError } from '@kit.BasicServicesKit'; 107 108receiver.readLatestImage((err: BusinessError, img: image.Image) => { 109 if (err) { 110 console.error(`Failed to read the latest Image.code ${err.code},message is ${err.message}`); 111 } else { 112 console.info('Succeeded in reading the latest Image.'); 113 } 114}); 115``` 116 117## readLatestImage<sup>9+</sup> 118 119readLatestImage(): Promise\<Image> 120 121Reads the latest image from the ImageReceiver instance. This API uses a promise to return the result. 122 123This API can be called to receive data only after the [on](#on9) callback is triggered. When the [Image](arkts-apis-image-Image.md) object returned by this API is no longer needed, call [release](arkts-apis-image-Image.md#release9) to release the object. New data can be received only after the release. 124 125**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 126 127**Return value** 128 129| Type | Description | 130| ------------------------- | ------------------ | 131| Promise<[Image](arkts-apis-image-Image.md)> | Promise used to return the latest image.| 132 133**Example** 134 135```ts 136import { BusinessError } from '@kit.BasicServicesKit'; 137 138receiver.readLatestImage().then((img: image.Image) => { 139 console.info('Succeeded in reading the latest Image.'); 140}).catch((error: BusinessError) => { 141 console.error(`Failed to read the latest Image.code ${error.code},message is ${error.message}`); 142}) 143``` 144 145## readNextImage<sup>9+</sup> 146 147readNextImage(callback: AsyncCallback\<Image>): void 148 149Reads the next image from the ImageReceiver instance. This API uses an asynchronous callback to return the result. 150 151This API can be called to receive data only after the [on](#on9) callback is triggered. When the [Image](arkts-apis-image-Image.md) object returned by this API is no longer needed, call [release](arkts-apis-image-Image.md#release9) to release the object. New data can be received only after the release. 152 153**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 154 155**Parameters** 156 157| Name | Type | Mandatory| Description | 158| -------- | ------------------------------- | ---- | -------------------------- | 159| callback | AsyncCallback<[Image](arkts-apis-image-Image.md)> | 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. | 160 161**Example** 162 163```ts 164import { BusinessError } from '@kit.BasicServicesKit'; 165 166receiver.readNextImage((err: BusinessError, img: image.Image) => { 167 if (err) { 168 console.error(`Failed to read the next Image.code ${err.code},message is ${err.message}`); 169 } else { 170 console.info('Succeeded in reading the next Image.'); 171 } 172}); 173``` 174 175## readNextImage<sup>9+</sup> 176 177readNextImage(): Promise\<Image> 178 179Reads the next image from the ImageReceiver instance. This API uses a promise to return the result. 180 181This API can be called to receive data only after the [on](#on9) callback is triggered. When the [Image](arkts-apis-image-Image.md) object returned by this API is no longer needed, call [release](arkts-apis-image-Image.md#release9) to release the object. New data can be received only after the release. 182 183**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 184 185**Return value** 186 187| Type | Description | 188| ------------------------- | -------------------- | 189| Promise<[Image](arkts-apis-image-Image.md)> | Promise used to return the next image.| 190 191**Example** 192 193```ts 194import { BusinessError } from '@kit.BasicServicesKit'; 195 196receiver.readNextImage().then((img: image.Image) => { 197 console.info('Succeeded in reading the next Image.'); 198}).catch((error: BusinessError) => { 199 console.error(`Failed to read the next Image.code ${error.code},message is ${error.message}`); 200}) 201``` 202 203## on<sup>9+</sup> 204 205on(type: 'imageArrival', callback: AsyncCallback\<void>): void 206 207Listens for image arrival events. 208 209**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 210 211**Parameters** 212 213| Name | Type | Mandatory| Description | 214| -------- | -------------------- | ---- | ------------------------------------------------------ | 215| type | string | Yes | Type of event to listen for. The value is fixed at **'imageArrival'**, which is triggered when an image is received.| 216| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 217 218**Example** 219 220```ts 221receiver.on('imageArrival', () => { 222 // image arrival, do something. 223}) 224``` 225 226## off<sup>13+</sup> 227 228off(type: 'imageArrival', callback?: AsyncCallback\<void>): void 229 230Unregisters the callback function that is triggered when the buffer is released. 231 232**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 233 234**Parameters** 235 236| Name | Type | Mandatory| Description | 237| -------- | -------------------- |----|----------------------------------------| 238| type | string | Yes | Type of event, which is **'imageArrival'**.| 239| callback | AsyncCallback\<void> | No | Callback to unregister. | 240 241**Example** 242 243```ts 244let callbackFunc = ()=>{ 245 // do something. 246} 247receiver.on('imageArrival', callbackFunc) 248receiver.off('imageArrival', callbackFunc) 249``` 250 251## release<sup>9+</sup> 252 253release(callback: AsyncCallback\<void>): void 254 255Releases this ImageReceiver instance. This API uses an asynchronous callback to return the result. 256 257ArkTS supports memory reclamation. Even if the application does not call **release()**, the memory of the ImageReceiver object will be released by the system. However, images usually occupy a large amount of memory. Therefore, it is recommended that the application proactively call the API to release the memory when the object is no longer required. 258 259**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 260 261**Parameters** 262 263| Name | Type | Mandatory| Description | 264| -------- | -------------------- | ---- | ------------------------ | 265| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 266 267**Example** 268 269```ts 270import { BusinessError } from '@kit.BasicServicesKit'; 271 272receiver.release((err: BusinessError) => { 273 if (err) { 274 console.error(`Failed to release the receiver.code ${err.code},message is ${err.message}`); 275 } else { 276 console.info('Succeeded in releasing the receiver.'); 277 } 278}) 279``` 280 281## release<sup>9+</sup> 282 283release(): Promise\<void> 284 285Releases this ImageReceiver instance. This API uses a promise to return the result. 286 287ArkTS supports memory reclamation. Even if the application does not call **release()**, the memory of the ImageReceiver object will be released by the system. However, images usually occupy a large amount of memory. Therefore, it is recommended that the application proactively call the API to release the memory when the object is no longer required. 288 289**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 290 291**Return value** 292 293| Type | Description | 294| -------------- | ------------------ | 295| Promise\<void> | Promise that returns no value.| 296 297**Example** 298 299```ts 300import { BusinessError } from '@kit.BasicServicesKit'; 301 302receiver.release().then(() => { 303 console.info('Succeeded in releasing the receiver.'); 304}).catch((error: BusinessError) => { 305 console.error(`Failed to release the receiver.code ${error.code},message is ${error.message}`); 306}) 307``` 308