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