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 Creates an <b>OH_ImageReceiverOptions</b> object at the application layer. 81 * 82 * @param options Indicates the pointer to the <b>OH_ImageReceiverOptions</b> object obtained. 83 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 84 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 85 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 86 * @since 12 87 */ 88 Image_ErrorCode OH_ImageReceiverOptions_Create(OH_ImageReceiverOptions **options); 89 90 /** 91 * @brief Get size of an {@link OH_ImageReceiverOptions} object. 92 * 93 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 94 * @param size Indicates the value of the {@Link Image_Size} object will be obtained. 95 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 96 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 97 * @since 12 98 */ 99 Image_ErrorCode OH_ImageReceiverOptions_GetSize(OH_ImageReceiverOptions* options, Image_Size* size); 100 101 /** 102 * @brief Set size of an {@link OH_ImageReceiverOptions} object. 103 * 104 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 105 * @param size Indicates the value of the {@link Image_Size} object will be seted. 106 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 107 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 108 * @since 12 109 */ 110 Image_ErrorCode OH_ImageReceiverOptions_SetSize(OH_ImageReceiverOptions* options, Image_Size size); 111 112 /** 113 * @brief Get capacity from an {@link OH_ImageReceiverOptions} object. 114 * 115 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 116 * @param capacity Indicates the pointer to capacity will be obtained. 117 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 118 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 119 * @since 12 120 */ 121 Image_ErrorCode OH_ImageReceiverOptions_GetCapacity(OH_ImageReceiverOptions* options, int32_t* capacity); 122 123 /** 124 * @brief Set capacity of an {@link OH_ImageReceiverOptions} object. 125 * 126 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 127 * @param capacity Indicates the value of capacity will be seted. 128 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 129 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 130 * @since 12 131 */ 132 Image_ErrorCode OH_ImageReceiverOptions_SetCapacity(OH_ImageReceiverOptions* options, int32_t capacity); 133 134 /** 135 * @brief Releases an {@link OH_ImageReceiverOptions} object. 136 * It is used to release the object {@link OH_ImageReceiverOptions}. 137 * 138 * @param options Indicates the pointer to an {@link OH_ImageReceiverOptions} object. 139 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 140 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 141 * @see OH_ImageReceiverOptions 142 * @since 12 143 */ 144 Image_ErrorCode OH_ImageReceiverOptions_Release(OH_ImageReceiverOptions* options); 145 146 /** 147 * @brief Creates an <b>OH_ImageReceiverNative</b> object at the application layer. 148 * 149 * @param options Indicates the options for setting the <b>OH_ImageReceiverNative</b> object. 150 * @param receiver Indicates the pointer to the <b>OH_ImageReceiverNative</b> object obtained. 151 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 152 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 153 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 154 * @since 12 155 */ 156 Image_ErrorCode OH_ImageReceiverNative_Create(OH_ImageReceiverOptions* options, OH_ImageReceiverNative** receiver); 157 158 /** 159 * @brief Obtains the receiver ID through an {@link OH_ImageReceiverNative} object. 160 * 161 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 162 * @param surfaceId Indicates the pointer to the surfaceID will be obtained. 163 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 164 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 165 * returns {@link Image_ErrorCode} IMAGE_UNKNOWN_ERROR - inner unknown error. 166 * @see OH_ImageReceiverNative 167 * @since 12 168 */ 169 Image_ErrorCode OH_ImageReceiverNative_GetReceivingSurfaceId(OH_ImageReceiverNative* receiver, uint64_t* surfaceId); 170 171 /** 172 * @brief Obtains the latest image through an {@link OH_ImageReceiverNative} object. 173 * 174 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 175 * @param image Indicates the pointer to an <b>OH_ImageNative</b> object at the application layer. 176 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 177 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 178 * returns {@link Image_ErrorCode} IMAGE_UNKNOWN_ERROR - inner unknown error. 179 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 180 * @see OH_ImageReceiverNative, OH_ImageNative 181 * @since 12 182 */ 183 Image_ErrorCode OH_ImageReceiverNative_ReadLatestImage(OH_ImageReceiverNative* receiver, OH_ImageNative** image); 184 185 /** 186 * @brief Obtains the next image through an {@link OH_ImageReceiverNative} object. 187 * 188 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 189 * @param image Indicates the pointer to an <b>OH_ImageNative</b> object at the application layer. 190 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 191 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 192 * returns {@link Image_ErrorCode} IMAGE_UNKNOWN_ERROR - inner unknown error. 193 * returns {@link Image_ErrorCode} IMAGE_ALLOC_FAILED - if alloc failed. 194 * @see OH_ImageReceiverNative, OH_ImageNative 195 * @since 12 196 */ 197 Image_ErrorCode OH_ImageReceiverNative_ReadNextImage(OH_ImageReceiverNative* receiver, OH_ImageNative** image); 198 199 /** 200 * @brief Registers an {@link OH_ImageReceiver_OnCallback} callback event. 201 * 202 * This callback event is triggered whenever a new image is received. 203 * 204 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 205 * @param callback Indicates the {@link OH_ImageReceiver_OnCallback} callback event to register. 206 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 207 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 208 * @see OH_ImageReceiverNative, OH_ImageReceiver_OnCallback 209 * @since 12 210 */ 211 Image_ErrorCode OH_ImageReceiverNative_On(OH_ImageReceiverNative* receiver, OH_ImageReceiver_OnCallback callback); 212 213 /** 214 * @brief Unregisters the {@link OH_ImageReceiver_OnCallback} callback event. 215 * 216 * Turn off the callback witch triggered by {@link OH_ImageReceiverNative_On}. 217 * 218 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 219 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 220 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 221 * @see OH_ImageReceiverNative, OH_ImageReceiverNative_On 222 * @since 12 223 */ 224 Image_ErrorCode OH_ImageReceiverNative_Off(OH_ImageReceiverNative* receiver); 225 226 /** 227 * @brief Obtains the size of the image receiver through an {@link OH_ImageReceiverNative} object. 228 * 229 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 230 * @param size Indicates the pointer to the {@link Image_Size} object will be obtained. 231 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 232 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 233 * @see OH_ImageReceiverNative, Image_Size 234 * @since 12 235 */ 236 Image_ErrorCode OH_ImageReceiverNative_GetSize(OH_ImageReceiverNative* receiver, Image_Size* size); 237 238 /** 239 * @brief Obtains the capacity of the image receiver through an {@link OH_ImageReceiverNative} object. 240 * 241 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 242 * @param capacity Indicates the pointer to the capacity will be obtained. 243 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 244 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 245 * @see OH_ImageReceiverNative 246 * @since 12 247 */ 248 Image_ErrorCode OH_ImageReceiverNative_GetCapacity(OH_ImageReceiverNative* receiver, int32_t* capacity); 249 250 /** 251 * @brief Releases an {@link OH_ImageReceiverNative} object. 252 * 253 * This API is not used to release an <b>ImageReceiver2</b> object at the application layer. 254 * 255 * @param receiver Indicates the pointer to an {@link OH_ImageReceiverNative} object. 256 * @return Returns {@link Image_ErrorCode} IMAGE_SUCCESS - if the operation is successful. 257 * returns {@link Image_ErrorCode} IMAGE_BAD_PARAMETER - if bad parameter. 258 * @see OH_ImageReceiverNative 259 * @since 12 260 */ 261 Image_ErrorCode OH_ImageReceiverNative_Release(OH_ImageReceiverNative* receiver); 262 263 #ifdef __cplusplus 264 }; 265 #endif 266 /** @} */ 267 268 #endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_RECEIVER_NATIVE_H 269