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