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 OH_Camera
18 * @{
19 *
20 * @brief Provide the definition of the C interface for the camera module.
21 *
22 * @syscap SystemCapability.Multimedia.Camera.Core
23 *
24 * @since 11
25 * @version 1.0
26 */
27
28/**
29 * @file metadata_output.h
30 *
31 * @brief Declare the metadata output concepts.
32 *
33 * @library libohcamera.so
34 * @kit CameraKit
35 * @syscap SystemCapability.Multimedia.Camera.Core
36 * @since 11
37 * @version 1.0
38 */
39
40#ifndef NATIVE_INCLUDE_CAMERA_METADATAOUTPUT_H
41#define NATIVE_INCLUDE_CAMERA_METADATAOUTPUT_H
42
43#include <stdint.h>
44#include <stdio.h>
45#include "camera.h"
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/**
52 * @brief Metadata output object
53 *
54 * A pointer can be created using {@link Camera_MetadataOutput} method.
55 *
56 * @since 11
57 * @version 1.0
58 */
59typedef struct Camera_MetadataOutput Camera_MetadataOutput;
60
61/**
62 * @brief Metadata output metadata object available callback to be called in {@link MetadataOutput_Callbacks}.
63 *
64 * @param metadataOutput the {@link Camera_MetadataOutput} which deliver the callback.
65 * @param metadataObject the {@link Camera_MetadataObject} will be delivered by the callback.
66 * @param size the size of the metadataObject.
67 * @since 11
68 */
69typedef void (*OH_MetadataOutput_OnMetadataObjectAvailable)(Camera_MetadataOutput* metadataOutput,
70    Camera_MetadataObject* metadataObject, uint32_t size);
71
72/**
73 * @brief Metadata output error callback to be called in {@link MetadataOutput_Callbacks}.
74 *
75 * @param metadataOutput the {@link Camera_MetadataOutput} which deliver the callback.
76 * @param errorCode the {@link Camera_ErrorCode} of the metadata output.
77 *
78 * @see CAMERA_SERVICE_FATAL_ERROR
79 * @since 11
80 */
81typedef void (*OH_MetadataOutput_OnError)(Camera_MetadataOutput* metadataOutput, Camera_ErrorCode errorCode);
82
83/**
84 * @brief A listener for metadata output.
85 *
86 * @see OH_MetadataOutput_RegisterCallback
87 * @since 11
88 * @version 1.0
89 */
90typedef struct MetadataOutput_Callbacks {
91    /**
92     * Metadata output result data will be called by this callback.
93     */
94    OH_MetadataOutput_OnMetadataObjectAvailable onMetadataObjectAvailable;
95
96    /**
97     * Metadata output error event.
98     */
99    OH_MetadataOutput_OnError onError;
100} MetadataOutput_Callbacks;
101
102/**
103 * @brief Register metadata output change event callback.
104 *
105 * @param metadataOutput the {@link Camera_MetadataOutput} instance.
106 * @param callback the {@link MetadataOutput_Callbacks} to be registered.
107 * @return {@link #CAMERA_OK} if the method call succeeds.
108 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
109 * @since 11
110 */
111Camera_ErrorCode OH_MetadataOutput_RegisterCallback(Camera_MetadataOutput* metadataOutput,
112    MetadataOutput_Callbacks* callback);
113
114/**
115 * @brief Unregister metadata output change event callback.
116 *
117 * @param metadataOutput the {@link Camera_MetadataOutput} instance.
118 * @param callback the {@link MetadataOutput_Callbacks} to be unregistered.
119 * @return {@link #CAMERA_OK} if the method call succeeds.
120 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
121 * @since 11
122 */
123Camera_ErrorCode OH_MetadataOutput_UnregisterCallback(Camera_MetadataOutput* metadataOutput,
124    MetadataOutput_Callbacks* callback);
125
126/**
127 * @brief Start metadata output.
128 *
129 * @param metadataOutput the {@link Camera_MetadataOutput} instance to be started.
130 * @return {@link #CAMERA_OK} if the method call succeeds.
131 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
132 *         {@link #CAMERA_SESSION_NOT_CONFIG} if the capture session not config.
133 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
134 * @since 11
135 */
136Camera_ErrorCode OH_MetadataOutput_Start(Camera_MetadataOutput* metadataOutput);
137
138/**
139 * @brief Stop metadata output.
140 *
141 * @param metadataOutput the {@link Camera_MetadataOutput} instance to be stoped.
142 * @return {@link #CAMERA_OK} if the method call succeeds.
143 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
144 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
145 * @since 11
146 */
147Camera_ErrorCode OH_MetadataOutput_Stop(Camera_MetadataOutput* metadataOutput);
148
149/**
150 * @brief Release metadata output.
151 *
152 * @param metadataOutput the {@link Camera_MetadataOutput} instance to be released.
153 * @return {@link #CAMERA_OK} if the method call succeeds.
154 *         {@link #INVALID_ARGUMENT} if parameter missing or parameter type incorrect.
155 *         {@link #CAMERA_SERVICE_FATAL_ERROR} if camera service fatal error.
156 * @since 11
157 */
158Camera_ErrorCode OH_MetadataOutput_Release(Camera_MetadataOutput* metadataOutput);
159
160#ifdef __cplusplus
161}
162#endif
163
164#endif // NATIVE_INCLUDE_CAMERA_METADATAOUTPUT_H
165/** @} */