1 /* 2 * Copyright (C) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup image 18 * @{ 19 * 20 * @brief Provides APIs for obtaining image data from the native layer. 21 * 22 * @Syscap SystemCapability.Multimedia.Image 23 * @since 10 24 * @version 2.0 25 */ 26 27 /** 28 * @file image_receiver_mdk.h 29 * 30 * @brief Declares the APIs for obtaining image data from the native layer. 31 * Need link <b>libimagendk.z.so</b> and <b>libimage_receiverndk.z.so</b> 32 * 33 * @kit ImageKit 34 * @since 10 35 * @version 2.0 36 */ 37 38 #ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_RECEIVER_MDK_H_ 39 #define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_RECEIVER_MDK_H_ 40 #include "napi/native_api.h" 41 #include "image_mdk_common.h" 42 #include "image_mdk.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Defines an <b>ImageReceiver</b> object at the native layer. 50 * 51 * @since 10 52 * @version 2.0 53 */ 54 struct ImageReceiverNative_; 55 56 /** 57 * @brief Defines the data type name of a native image receiver. 58 * 59 * @since 10 60 * @version 2.0 61 */ 62 typedef struct ImageReceiverNative_ ImageReceiverNative; 63 64 /** 65 * @brief Defines the callbacks for images at the native layer. 66 * 67 * @since 10 68 * @version 2.0 69 */ 70 typedef void (*OH_Image_Receiver_On_Callback)(void); 71 72 /** 73 * @brief Defines the information about an image receiver. 74 * 75 * @since 10 76 * @version 2.0 77 */ 78 struct OhosImageReceiverInfo { 79 /* Default width of the image received by the consumer, in pixels. */ 80 int32_t width; 81 /* Default height of the image received by the consumer, in pixels. */ 82 int32_t height; 83 /* Image format {@link OHOS_IMAGE_FORMAT_JPEG} created by using the receiver. */ 84 int32_t format; 85 /* Maximum number of images that can be cached. */ 86 int32_t capicity; 87 }; 88 89 /** 90 * @brief Creates an <b>ImageReceiver</b> object at the application layer. 91 * 92 * @param env Indicates the NAPI environment pointer. 93 * @param info Indicates the options for setting the <b>ImageReceiver</b> object. 94 * @param res Indicates the pointer to the <b>ImageReceiver</b> object obtained. 95 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 96 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 97 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 98 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 99 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface. 100 * returns {@link IRNdkErrCode} IMAGE_RESULT_CREATE_SURFACE_FAILED - if create surface failed. 101 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GRALLOC_BUFFER_FAILED - if surface gralloc buffer failed. 102 * returns {@link IRNdkErrCode} IMAGE_RESULT_GET_SURFACE_FAILED - if get sufrace failed. 103 * returns {@link IRNdkErrCode} IMAGE_RESULT_MEDIA_RTSP_SURFACE_UNSUPPORT - if media rtsp surface not support. 104 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 105 * returns {@link IRNdkErrCode} IMAGE_RESULT_MEDIA_DATA_UNSUPPORT - if media type unsupported. 106 * @see OhosImageReceiverInfo 107 * @since 10 108 * @version 2.0 109 */ 110 int32_t OH_Image_Receiver_CreateImageReceiver(napi_env env, struct OhosImageReceiverInfo info, napi_value* res); 111 112 /** 113 * @brief Initializes an {@link ImageReceiverNative} object at the native layer 114 * through an <b>ImageReceiver</b> object at the application layer. 115 * 116 * @param env Indicates the NAPI environment pointer. 117 * @param source Indicates an <b>ImageReceiver</b> object. 118 * @return Returns the pointer to the {@link ImageReceiverNative} object obtained if the operation is successful; 119 * returns a null pointer otherwise. 120 * @see ImageReceiverNative, OH_Image_Receiver_Release 121 * @since 10 122 * @version 2.0 123 */ 124 ImageReceiverNative* OH_Image_Receiver_InitImageReceiverNative(napi_env env, napi_value source); 125 126 /** 127 * @brief Obtains the receiver ID through an {@link ImageReceiverNative} object. 128 * 129 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 130 * @param id Indicates the pointer to the buffer that stores the ID string obtained. 131 * @param len Indicates the size of the buffer. 132 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 133 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 134 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 135 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 136 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface. 137 * returns {@link IRNdkErrCode} IMAGE_RESULT_GET_SURFACE_FAILED - if get sufrace failed. 138 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 139 * returns {@link IRNdkErrCode} IMAGE_RESULT_MEDIA_DATA_UNSUPPORT - if media type unsupported. 140 * @see ImageReceiverNative 141 * @since 10 142 * @version 2.0 143 */ 144 int32_t OH_Image_Receiver_GetReceivingSurfaceId(const ImageReceiverNative* native, char* id, size_t len); 145 146 /** 147 * @brief Obtains the latest image through an {@link ImageReceiverNative} object. 148 * 149 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 150 * @param image Indicates the pointer to an <b>Image</b> object at the application layer. 151 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 152 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 153 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 154 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 155 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface. 156 * returns {@link IRNdkErrCode} IMAGE_RESULT_CREATE_SURFACE_FAILED - if create surface failed. 157 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GRALLOC_BUFFER_FAILED - if surface gralloc buffer failed. 158 * returns {@link IRNdkErrCode} IMAGE_RESULT_GET_SURFACE_FAILED - if get sufrace failed. 159 * returns {@link IRNdkErrCode} IMAGE_RESULT_MEDIA_RTSP_SURFACE_UNSUPPORT - if media rtsp surface not support. 160 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 161 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_REQUEST_BUFFER_FAILED - if request Buffer failed. 162 * @see ImageReceiverNative 163 * @since 10 164 * @version 2.0 165 */ 166 int32_t OH_Image_Receiver_ReadLatestImage(const ImageReceiverNative* native, napi_value* image); 167 168 /** 169 * @brief Obtains the next image through an {@link ImageReceiverNative} object. 170 * 171 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 172 * @param image Indicates the pointer to an <b>Image</b> object at the application layer. 173 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 174 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 175 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 176 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 177 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface. 178 * returns {@link IRNdkErrCode} IMAGE_RESULT_CREATE_SURFACE_FAILED - if create surface failed. 179 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GRALLOC_BUFFER_FAILED - if surface gralloc buffer failed. 180 * returns {@link IRNdkErrCode} IMAGE_RESULT_GET_SURFACE_FAILED - if get sufrace failed. 181 * returns {@link IRNdkErrCode} IMAGE_RESULT_MEDIA_RTSP_SURFACE_UNSUPPORT - if media rtsp surface not support. 182 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 183 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_REQUEST_BUFFER_FAILED - if request Buffer failed. 184 * @see ImageReceiverNative 185 * @since 10 186 * @version 2.0 187 */ 188 int32_t OH_Image_Receiver_ReadNextImage(const ImageReceiverNative* native, napi_value* image); 189 190 /** 191 * @brief Registers an {@link OH_Image_Receiver_On_Callback} callback event. 192 * 193 * This callback event is triggered whenever a new image is received. 194 * 195 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 196 * @param callback Indicates the {@link OH_Image_Receiver_On_Callback} callback event to register. 197 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 198 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 199 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 200 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 201 * returns {@link IRNdkErrCode} IMAGE_RESULT_GET_SURFACE_FAILED - if get sufrace failed. 202 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 203 * returns {@link IRNdkErrCode} IMAGE_RESULT_REGISTER_LISTENER_FAILED - if Failed to register listener. 204 * returns {@link IRNdkErrCode} IMAGE_RESULT_REGISTER_BUFFER_FAILED - if Failed to register buffer. 205 * @see ImageReceiverNative 206 * @since 10 207 * @version 2.0 208 */ 209 int32_t OH_Image_Receiver_On(const ImageReceiverNative* native, OH_Image_Receiver_On_Callback callback); 210 211 /** 212 * @brief Obtains the size of the image receiver through an {@link ImageReceiverNative} object. 213 * 214 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 215 * @param size Indicates the pointer to the {@link OhosImageSize} object obtained. 216 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 217 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 218 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 219 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 220 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 221 * @see ImageReceiverNative, OH_Image_Receiver_On_Callback 222 * @since 10 223 * @version 2.0 224 */ 225 int32_t OH_Image_Receiver_GetSize(const ImageReceiverNative* native, struct OhosImageSize* size); 226 227 /** 228 * @brief Obtains the capacity of the image receiver through an {@link ImageReceiverNative} object. 229 * 230 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 231 * @param capacity Indicates the pointer to the capacity obtained. 232 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 233 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 234 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 235 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 236 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 237 * @see ImageReceiverNative, OhosImageSize 238 * @since 10 239 * @version 2.0 240 */ 241 int32_t OH_Image_Receiver_GetCapacity(const ImageReceiverNative* native, int32_t* capacity); 242 243 /** 244 * @brief Obtains the format of the image receiver through an {@link ImageReceiverNative} object. 245 * 246 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 247 * @param format Indicates the pointer to the format obtained. 248 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 249 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 250 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 251 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 252 * returns {@link IRNdkErrCode} IMAGE_RESULT_DATA_UNSUPPORT - if image type unsupported. 253 * @see ImageReceiverNative 254 255 * @since 10 256 * @version 2.0 257 */ 258 int32_t OH_Image_Receiver_GetFormat(const ImageReceiverNative* native, int32_t* format); 259 260 /** 261 * @brief Releases an {@link ImageReceiverNative} object at the native layer. 262 * 263 * This API is not used to release an <b>ImageReceiver</b> object at the application layer. 264 * 265 * @param native Indicates the pointer to an {@link ImageReceiverNative} object at the native layer. 266 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful. 267 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter. 268 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment. 269 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter. 270 * @see ImageReceiverNative 271 * @since 10 272 * @version 2.0 273 */ 274 int32_t OH_Image_Receiver_Release(ImageReceiverNative* native); 275 #ifdef __cplusplus 276 }; 277 #endif 278 /** @} */ 279 280 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_RECEIVER_MDK_H_ 281