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