1 /* 2 * Copyright (C) 2024 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. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file image_receiver_native.h 27 * 28 * @brief Declares the APIs for obtaining image data. 29 * @library libimage_receiver.so 30 * @kit ImageKit 31 * @syscap SystemCapability.Multimedia.Image.ImageReceiver 32 * @since 12 33 */ 34 35 #ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_RECEIVER_NATIVE_H 36 #define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_RECEIVER_NATIVE_H 37 38 #include "image_native.h" 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @brief Defines an <b>OH_ImageReceiverNative</b> object. 46 * 47 * @since 12 48 */ 49 struct OH_ImageReceiverNative; 50 51 /** 52 * @brief Defines the data type name of a native image receiver. 53 * 54 * @since 12 55 */ 56 typedef struct OH_ImageReceiverNative OH_ImageReceiverNative; 57 58 /** 59 * @brief Defines an image receiver options object. 60 * 61 * @since 12 62 */ 63 struct OH_ImageReceiverOptions; 64 65 /** 66 * @brief Defines the data type name of a native image receiver info. 67 * 68 * @since 12 69 */ 70 typedef struct OH_ImageReceiverOptions OH_ImageReceiverOptions; 71 72 /** 73 * @brief Defines the callbacks for images. 74 * 75 * @since 12 76 */ 77 typedef void (*OH_ImageReceiver_OnCallback)(OH_ImageReceiverNative *receiver); 78 79 /** 80 * @brief Defines the callback for the ImageArrive event. 81 * 82 * @since 20 83 */ 84 typedef void (*OH_ImageReceiver_ImageArriveCallback)(OH_ImageReceiverNative *receiver, void *userData); 85 86 /** 87 * @brief Creates an <b>OH_ImageReceiverOptions</b> object at the application layer. 88 * 89 * @param options Indicates the pointer to the <b>OH_ImageReceiverOptions</b> object obtained. 90 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 91 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 92 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 93 * @since 12 94 */ 95 Image_ErrorCode OH_ImageReceiverOptions_Create(OH_ImageReceiverOptions **options); 96 97 /** 98 * @brief Get size of an {@link OH_ImageReceiverOptions} object. 99 * 100 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 101 * @param size Indicates the value of the {@Link Image_Size} object will be obtained. 102 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 103 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 104 * @since 12 105 */ 106 Image_ErrorCode OH_ImageReceiverOptions_GetSize(OH_ImageReceiverOptions* options, Image_Size* size); 107 108 /** 109 * @brief Set size of an {@link OH_ImageReceiverOptions} object. 110 * 111 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 112 * @param size Indicates the value of the {@link Image_Size} object will be seted. 113 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 114 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 115 * @since 12 116 */ 117 Image_ErrorCode OH_ImageReceiverOptions_SetSize(OH_ImageReceiverOptions* options, Image_Size size); 118 119 /** 120 * @brief Get capacity from an {@link OH_ImageReceiverOptions} object. 121 * 122 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 123 * @param capacity Indicates the pointer to capacity will be obtained. 124 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 125 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 126 * @since 12 127 */ 128 Image_ErrorCode OH_ImageReceiverOptions_GetCapacity(OH_ImageReceiverOptions* options, int32_t* capacity); 129 130 /** 131 * @brief Set capacity of an {@link OH_ImageReceiverOptions} object. 132 * 133 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 134 * @param capacity Indicates the value of capacity will be seted. 135 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 136 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 137 * @since 12 138 */ 139 Image_ErrorCode OH_ImageReceiverOptions_SetCapacity(OH_ImageReceiverOptions* options, int32_t capacity); 140 141 /** 142 * @brief Releases an {@link OH_ImageReceiverOptions} object. 143 * It is used to release the object {@link OH_ImageReceiverOptions}. 144 * 145 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 146 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 147 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 148 * @see OH_ImageReceiverOptions 149 * @since 12 150 */ 151 Image_ErrorCode OH_ImageReceiverOptions_Release(OH_ImageReceiverOptions* options); 152 153 /** 154 * @brief Creates an <b>OH_ImageReceiverNative</b> object at the application layer. 155 * 156 * @param options Indicates the options for setting the <b>OH_ImageReceiverNative</b> object. 157 * @param receiver Indicates the pointer to the <b>OH_ImageReceiverNative</b> object obtained. 158 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 159 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 160 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 161 * @since 12 162 */ 163 Image_ErrorCode OH_ImageReceiverNative_Create(OH_ImageReceiverOptions* options, OH_ImageReceiverNative** receiver); 164 165 /** 166 * @brief Obtains the receiver ID through an {@link OH_ImageReceiverNative} object. 167 * 168 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 169 * @param surfaceId Indicates the pointer to the surfaceID will be obtained. 170 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 171 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 172 * returns {@link Image_ErrorCode} IMAGE_UNKNOWN_ERROR - inner unknown error. 173 * @see OH_ImageReceiverNative 174 * @since 12 175 */ 176 Image_ErrorCode OH_ImageReceiverNative_GetReceivingSurfaceId(OH_ImageReceiverNative* receiver, uint64_t* surfaceId); 177 178 /** 179 * @brief Obtains the latest image through an {@link OH_ImageReceiverNative} object. 180 * 181 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 182 * @param image Indicates the pointer to an <b>OH_ImageNative</b> object at the application layer. 183 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 184 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 185 * returns {@link Image_ErrorCode} IMAGE_UNKNOWN_ERROR - inner unknown error. 186 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 187 * @see OH_ImageReceiverNative, OH_ImageNative 188 * @since 12 189 */ 190 Image_ErrorCode OH_ImageReceiverNative_ReadLatestImage(OH_ImageReceiverNative* receiver, OH_ImageNative** image); 191 192 /** 193 * @brief Obtains the next image through an {@link OH_ImageReceiverNative} object. 194 * 195 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 196 * @param image Indicates the pointer to an <b>OH_ImageNative</b> object at the application layer. 197 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 198 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 199 * returns {@link Image_ErrorCode} IMAGE_UNKNOWN_ERROR - inner unknown error. 200 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 201 * @see OH_ImageReceiverNative, OH_ImageNative 202 * @since 12 203 */ 204 Image_ErrorCode OH_ImageReceiverNative_ReadNextImage(OH_ImageReceiverNative* receiver, OH_ImageNative** image); 205 206 /** 207 * @brief Registers an {@link OH_ImageReceiver_OnCallback} callback event. 208 * 209 * This callback event is triggered whenever a new image is received. 210 * 211 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 212 * @param callback Indicates the {@link OH_ImageReceiver_OnCallback} callback event to register. 213 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 214 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 215 * @see OH_ImageReceiverNative, OH_ImageReceiver_OnCallback 216 * @since 12 217 */ 218 Image_ErrorCode OH_ImageReceiverNative_On(OH_ImageReceiverNative* receiver, OH_ImageReceiver_OnCallback callback); 219 220 /** 221 * @brief Unregisters the {@link OH_ImageReceiver_OnCallback} callback event. 222 * 223 * Turn off the callback witch triggered by {@link OH_ImageReceiverNative_On}. 224 * 225 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 226 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 227 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 228 * @see OH_ImageReceiverNative, OH_ImageReceiverNative_On 229 * @since 12 230 */ 231 Image_ErrorCode OH_ImageReceiverNative_Off(OH_ImageReceiverNative* receiver); 232 233 /** 234 * Registers an {@link OH_ImageReceiver_ImageArriveCallback} callback. 235 * 236 * @param receiver Pointer to an OH_ImageReceiverNative object that processes the callback. 237 * @param callback OH_ImageReceiver_ImageArriveCallback to register. 238 * @param userData Pointer to the user data passed to the callback. 239 * @return Result code. {@link Image_ErrorCode} IMAGE_SUCCESS is returned if the operation is successful. 240 * {@link Image_ErrorCode} IMAGE_RECEIVER_INVALID_PARAMETER is returned if receiver or callback is null. 241 * @since 20 242 */ 243 Image_ErrorCode OH_ImageReceiverNative_OnImageArrive(OH_ImageReceiverNative *receiver, 244 OH_ImageReceiver_ImageArriveCallback callback, void *userData); 245 246 /** 247 * Unregisters an {@link OH_ImageReceiver_ImageArriveCallback} callback. 248 * 249 * @param receiver Pointer to an <b>OH_ImageReceiverNative</b> object that processes the callback. 250 * @param callback <b>OH_ImageReceiver_ImageArriveCallback</b> callback to unregister. 251 * @return {@link Image_ErrorCode} IMAGE_SUCCESS - Operation succeeded. 252 * {@link Image_ErrorCode} IMAGE_RECEIVER_INVALID_PARAMETER - <b>receiver</b> is empty or <b>callback</b> is not 253 * registered. 254 * @since 20 255 */ 256 Image_ErrorCode OH_ImageReceiverNative_OffImageArrive(OH_ImageReceiverNative *receiver, 257 OH_ImageReceiver_ImageArriveCallback callback); 258 259 /** 260 * @brief Obtains the size of the image receiver through an {@link OH_ImageReceiverNative} object. 261 * 262 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 263 * @param size Indicates the pointer to the {@link Image_Size} object will be obtained. 264 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 265 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 266 * @see OH_ImageReceiverNative, Image_Size 267 * @since 12 268 */ 269 Image_ErrorCode OH_ImageReceiverNative_GetSize(OH_ImageReceiverNative* receiver, Image_Size* size); 270 271 /** 272 * @brief Obtains the capacity of the image receiver through an {@link OH_ImageReceiverNative} object. 273 * 274 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 275 * @param capacity Indicates the pointer to the capacity will be obtained. 276 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 277 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 278 * @see OH_ImageReceiverNative 279 * @since 12 280 */ 281 Image_ErrorCode OH_ImageReceiverNative_GetCapacity(OH_ImageReceiverNative* receiver, int32_t* capacity); 282 283 /** 284 * @brief Releases an {@link OH_ImageReceiverNative} object. 285 * 286 * This API is not used to release an <b>ImageReceiver2</b> object at the application layer. 287 * 288 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 289 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 290 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 291 * @see OH_ImageReceiverNative 292 * @since 12 293 */ 294 Image_ErrorCode OH_ImageReceiverNative_Release(OH_ImageReceiverNative* receiver); 295 296 #ifdef __cplusplus 297 }; 298 #endif 299 /** @} */ 300 301 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_RECEIVER_NATIVE_H 302