1# image_receiver_mdk.h 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--SE: @liyang_bryan--> 6<!--TSE: @xchaosioda--> 7 8## Overview 9 10The file declares the APIs used to obtain image data from the native layer. 11 12**Library**: libimage_receiver_ndk.z.so 13 14**File to include**: <multimedia/image_framework/image_receiver_mdk.h> 15 16**System capability**: SystemCapability.Multimedia.Image 17 18**Since**: 10 19 20**Related module**: [Image](capi-image.md) 21 22## Summary 23 24### Structs 25 26| Name| typedef Keyword| Description| 27| -- | -- | -- | 28| [OhosImageReceiverInfo](capi-image-ohosimagereceiverinfo.md) | - | Describes the information about an image receiver.| 29| [ImageReceiverNative_](capi-image-imagereceivernative-.md) | ImageReceiverNative | Defines the data type name of the image receiver at the native layer.| 30 31### Functions 32 33| Name| typedef Keyword| Description| 34| -- | -- | -- | 35| [typedef void (\*OH_Image_Receiver_On_Callback)()](#oh_image_receiver_on_callback) | OH_Image_Receiver_On_Callback | Defines the callbacks for the image receiver at the native layer.| 36| [int32_t OH_Image_Receiver_CreateImageReceiver(napi_env env, struct OhosImageReceiverInfo info, napi_value* res)](#oh_image_receiver_createimagereceiver) | - | Creates an ImageReceiver object at the application layer.| 37| [ImageReceiverNative* OH_Image_Receiver_InitImageReceiverNative(napi_env env, napi_value source)](#oh_image_receiver_initimagereceivernative) | - | Initializes an [ImageReceiverNative](capi-image-imagereceivernative-.md) object through an ImageReceiver object.| 38| [int32_t OH_Image_Receiver_GetReceivingSurfaceId(const ImageReceiverNative* native, char* id, size_t len)](#oh_image_receiver_getreceivingsurfaceid) | - | Obtains the receiver ID through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object.| 39| [int32_t OH_Image_Receiver_ReadLatestImage(const ImageReceiverNative* native, napi_value* image)](#oh_image_receiver_readlatestimage) | - | Obtains the latest image through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object.| 40| [int32_t OH_Image_Receiver_ReadNextImage(const ImageReceiverNative* native, napi_value* image)](#oh_image_receiver_readnextimage) | - | Obtains the next image through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object.| 41| [int32_t OH_Image_Receiver_On(const ImageReceiverNative* native, OH_Image_Receiver_On_Callback callback)](#oh_image_receiver_on) | - | Registers an [OH_Image_Receiver_On_Callback](#oh_image_receiver_on_callback) callback. This callback is triggered whenever a new image is received.| 42| [int32_t OH_Image_Receiver_GetSize(const ImageReceiverNative* native, struct OhosImageSize* size)](#oh_image_receiver_getsize) | - | Obtains the size of the image receiver through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object.| 43| [int32_t OH_Image_Receiver_GetCapacity(const ImageReceiverNative* native, int32_t* capacity)](#oh_image_receiver_getcapacity) | - | Obtains the capacity of the image receiver through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object.| 44| [int32_t OH_Image_Receiver_GetFormat(const ImageReceiverNative* native, int32_t* format)](#oh_image_receiver_getformat) | - | Obtains the format of the image receiver through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object.| 45| [int32_t OH_Image_Receiver_Release(ImageReceiverNative* native)](#oh_image_receiver_release) | - | Releases an [ImageReceiverNative](capi-image-imagereceivernative-.md) object.<br>This function is not used to release an ImageReceiver object.| 46 47## Function Description 48 49### OH_Image_Receiver_On_Callback() 50 51``` 52typedef void (*OH_Image_Receiver_On_Callback)() 53``` 54 55**Description** 56 57Defines the callbacks for the image receiver at the native layer. 58 59**Since**: 10 60 61### OH_Image_Receiver_CreateImageReceiver() 62 63``` 64int32_t OH_Image_Receiver_CreateImageReceiver(napi_env env, struct OhosImageReceiverInfo info, napi_value* res) 65``` 66 67**Description** 68 69Creates an ImageReceiver object at the application layer. 70 71**Since**: 10 72 73 74**Parameters** 75 76| Name| Description| 77| -- | -- | 78| napi_env env | Pointer to the NAPI environment.| 79| struct [OhosImageReceiverInfo](capi-image-ohosimagereceiverinfo.md) info | Options for setting the ImageReceiver object.| 80| napi_value* res | Pointer to the ImageReceiver object at the application layer.| 81 82**Returns** 83 84| Type| Description| 85| -- | -- | 86| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br> **IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br> **IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br>**IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_INVALID_PARAMETER**: Obtaining parameters from the surface fails.<br> **IMAGE_RESULT_CREATE_SURFACE_FAILED**: The surface fails to be created.<br> **IMAGE_RESULT_SURFACE_GRALLOC_BUFFER_FAILED**: The buffer fails to be allocated to the surface.<br> **IMAGE_RESULT_GET_SURFACE_FAILED**: The surface fails to be obtained.<br> **IMAGE_RESULT_MEDIA_RTSP_SURFACE_UNSUPPORT**: The media RTSP surface is not supported.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.<br> **IMAGE_RESULT_MEDIA_DATA_UNSUPPORT**: The media type is not supported.| 87 88### OH_Image_Receiver_InitImageReceiverNative() 89 90``` 91ImageReceiverNative* OH_Image_Receiver_InitImageReceiverNative(napi_env env, napi_value source) 92``` 93 94**Description** 95 96Initializes an [ImageReceiverNative](capi-image-imagereceivernative-.md) object through an ImageReceiver object. 97 98**Since**: 10 99 100 101**Parameters** 102 103| Name| Description| 104| -- | -- | 105| napi_env env | Pointer to the NAPI environment.| 106| napi_value source | ImageReceiver object.| 107 108**Returns** 109 110| Type| Description| 111| -- | -- | 112| [ImageReceiverNative](capi-image-imagereceivernative-.md)* | Pointer to the ImageReceiverNative object obtained. If the operation fails, a null pointer is returned.| 113 114**See also** 115 116[OH_Image_Receiver_Release](#oh_image_receiver_release) 117 118### OH_Image_Receiver_GetReceivingSurfaceId() 119 120``` 121int32_t OH_Image_Receiver_GetReceivingSurfaceId(const ImageReceiverNative* native, char* id, size_t len) 122``` 123 124**Description** 125 126Obtains the receiver ID through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object. 127 128**Since**: 10 129 130 131**Parameters** 132 133| Name| Description| 134| -- | -- | 135| const [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 136| char* id | Pointer to the buffer that stores the ID string obtained.| 137| size_t len | Size of the buffer.| 138 139**Returns** 140 141| Type| Description| 142| -- | -- | 143| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br>**IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_INVALID_PARAMETER**: Obtaining parameters from the surface fails.<br> **IMAGE_RESULT_GET_SURFACE_FAILED**: The surface fails to be obtained.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.<br> **IMAGE_RESULT_MEDIA_DATA_UNSUPPORT**: The media type is not supported.| 144 145### OH_Image_Receiver_ReadLatestImage() 146 147``` 148int32_t OH_Image_Receiver_ReadLatestImage(const ImageReceiverNative* native, napi_value* image) 149``` 150 151**Description** 152 153Obtains the latest image through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object. 154 155This function can be called to receive data only after the [OH_Image_Receiver_On_Callback](#oh_image_receiver_on_callback) callback is triggered. When the [ImageNative](capi-image-imagenative-.md) object created by the Image object returned by this function is no longer needed, call [OH_Image_Release](capi-image-mdk-h.md#oh_image_release) to release the object. New data can be received only after the release. 156 157**Since**: 10 158 159 160**Parameters** 161 162| Name| Description| 163| -- | -- | 164| const [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 165| napi_value* image | Pointer to an Image object at the application layer.| 166 167**Returns** 168 169| Type| Description| 170| -- | -- | 171| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br>**IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_INVALID_PARAMETER**: Obtaining parameters from the surface fails.<br> **IMAGE_RESULT_CREATE_SURFACE_FAILED**: The surface fails to be created.<br> **IMAGE_RESULT_SURFACE_GRALLOC_BUFFER_FAILED**: The buffer fails to be allocated to the surface.<br> **IMAGE_RESULT_GET_SURFACE_FAILED**: The surface fails to be obtained.<br> **IMAGE_RESULT_MEDIA_RTSP_SURFACE_UNSUPPORT**: The media RTSP surface is not supported.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.<br> **IMAGE_RESULT_MEDIA_DATA_UNSUPPORT**: The media type is not supported.| 172 173### OH_Image_Receiver_ReadNextImage() 174 175``` 176int32_t OH_Image_Receiver_ReadNextImage(const ImageReceiverNative* native, napi_value* image) 177``` 178 179**Description** 180 181Obtains the next image through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object. 182 183This function can be called to receive data only after the [OH_Image_Receiver_On_Callback](#oh_image_receiver_on_callback) callback is triggered. When the [ImageNative](capi-image-imagenative-.md) object created by the Image object returned by this function is no longer needed, call [OH_Image_Release](capi-image-mdk-h.md#oh_image_release) to release the object. New data can be received only after the release. 184 185**Since**: 10 186 187 188**Parameters** 189 190| Name| Description| 191| -- | -- | 192| const [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 193| napi_value* image | Pointer to an Image object at the application layer.| 194 195**Returns** 196 197| Type| Description| 198| -- | -- | 199| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br>**IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_INVALID_PARAMETER**: Obtaining parameters from the surface fails.<br> **IMAGE_RESULT_CREATE_SURFACE_FAILED**: The surface fails to be created.<br> **IMAGE_RESULT_SURFACE_GRALLOC_BUFFER_FAILED**: The buffer fails to be allocated to the surface.<br> **IMAGE_RESULT_GET_SURFACE_FAILED**: The surface fails to be obtained.<br> **IMAGE_RESULT_MEDIA_RTSP_SURFACE_UNSUPPORT**: The media RTSP surface is not supported.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.<br> **IMAGE_RESULT_MEDIA_DATA_UNSUPPORT**: The media type is not supported.| 200 201### OH_Image_Receiver_On() 202 203``` 204int32_t OH_Image_Receiver_On(const ImageReceiverNative* native, OH_Image_Receiver_On_Callback callback) 205``` 206 207**Description** 208 209Registers an [OH_Image_Receiver_On_Callback](#oh_image_receiver_on_callback) callback. This callback is triggered whenever a new image is received. 210 211**Since**: 10 212 213 214**Parameters** 215 216| Name| Description| 217| -- | -- | 218| const [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 219| [OH_Image_Receiver_On_Callback](#oh_image_receiver_on_callback) callback | [OH_Image_Receiver_On_Callback](#oh_image_receiver_on_callback) callback to register.| 220 221**Returns** 222 223| Type| Description| 224| -- | -- | 225| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br>**IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_INVALID_PARAMETER**: Obtaining parameters from the surface fails.<br> **IMAGE_RESULT_GET_SURFACE_FAILED**: The surface fails to be obtained.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.<br> **IMAGE_RESULT_MEDIA_DATA_UNSUPPORT**: The media type is not supported.| 226 227### OH_Image_Receiver_GetSize() 228 229 230``` 231int32_t OH_Image_Receiver_GetSize(const ImageReceiverNative* native, struct OhosImageSize* size) 232``` 233 234**Description** 235 236Obtains the size of the image receiver through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object. 237 238**Since**: 10 239 240 241**Parameters** 242 243| Name| Description| 244| -- | -- | 245| const [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 246| struct [OhosImageSize](capi-image-ohosimagesize.md)* size | Pointer to the OhosImageSize object obtained.| 247 248**Returns** 249 250| Type| Description| 251| -- | -- | 252| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br>**IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.| 253 254### OH_Image_Receiver_GetCapacity() 255 256``` 257int32_t OH_Image_Receiver_GetCapacity(const ImageReceiverNative* native, int32_t* capacity) 258``` 259 260**Description** 261 262Obtains the capacity of the image receiver through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object. 263 264**Since**: 10 265 266 267**Parameters** 268 269| Name| Description| 270| -- | -- | 271| const [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 272| int32_t* capacity | Pointer to the capacity obtained.| 273 274**Returns** 275 276| Type| Description| 277| -- | -- | 278| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br>**IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.| 279 280### OH_Image_Receiver_GetFormat() 281 282``` 283int32_t OH_Image_Receiver_GetFormat(const ImageReceiverNative* native, int32_t* format) 284``` 285 286**Description** 287 288Obtains the format of the image receiver through an [ImageReceiverNative](capi-image-imagereceivernative-.md) object. 289 290**Since**: 10 291 292 293**Parameters** 294 295| Name| Description| 296| -- | -- | 297| const [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 298| int32_t* format | Pointer to the format obtained.| 299 300**Returns** 301 302| Type| Description| 303| -- | -- | 304| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br>**IMAGE_RESULT_JNI_ENV_ABNORMAL**: The JNI environment is abnormal.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.| 305 306### OH_Image_Receiver_Release() 307 308``` 309int32_t OH_Image_Receiver_Release(ImageReceiverNative* native) 310``` 311 312**Description** 313 314Releases an [ImageReceiverNative](capi-image-imagereceivernative-.md) object. 315 316This function is not used to release an ImageReceiver object. 317 318**Since**: 10 319 320 321**Parameters** 322 323| Name| Description| 324| -- | -- | 325| [ImageReceiverNative](capi-image-imagereceivernative-.md)* native | Pointer to an ImageReceiverNative object.| 326 327**Returns** 328 329| Type| Description| 330| -- | -- | 331| int32_t | Result code defined in [IRNdkErrCode](capi-image-mdk-common-h.md#irndkerrcode):<br>**IMAGE_RESULT_SUCCESS**: The operation is successful.<br> **IMAGE_RESULT_BAD_PARAMETER**: A parameter is incorrect.<br> **IMAGE_RESULT_INVALID_PARAMETER**: A parameter is invalid.<br> **IMAGE_RESULT_DATA_UNSUPPORT**: The image type is not supported.| 332