1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/**
18 * @addtogroup Camera
19 * @{
20 */
21
22/**
23 * @file NdkCameraManager.h
24 */
25
26/*
27 * This file defines an NDK API.
28 * Do not remove methods.
29 * Do not change method signatures.
30 * Do not change the value of constants.
31 * Do not change the size of any of the classes defined in here.
32 * Do not reference types that are not part of the NDK.
33 * Do not #include files that aren't part of the NDK.
34 */
35
36#ifndef _NDK_CAMERA_MANAGER_H
37#define _NDK_CAMERA_MANAGER_H
38
39#include <sys/cdefs.h>
40
41#include "NdkCameraError.h"
42#include "NdkCameraMetadata.h"
43#include "NdkCameraDevice.h"
44
45__BEGIN_DECLS
46
47#if __ANDROID_API__ >= 24
48
49/**
50 * ACameraManager is opaque type that provides access to camera service.
51 *
52 * A pointer can be obtained using {@link ACameraManager_create} method.
53 */
54typedef struct ACameraManager ACameraManager;
55
56/**
57 * Create ACameraManager instance.
58 *
59 * <p>The ACameraManager is responsible for
60 * detecting, characterizing, and connecting to {@link ACameraDevice}s.</p>
61 *
62 * <p>The caller must call {@link ACameraManager_delete} to free the resources once it is done
63 * using the ACameraManager instance.</p>
64 *
65 * @return a {@link ACameraManager} instance.
66 *
67 */
68ACameraManager* ACameraManager_create();
69
70/**
71 * <p>Delete the {@link ACameraManager} instance and free its resources. </p>
72 *
73 * @param manager the {@link ACameraManager} instance to be deleted.
74 */
75void ACameraManager_delete(ACameraManager* manager);
76
77/// Struct to hold list of camera devices
78typedef struct ACameraIdList {
79    int numCameras;          ///< Number of connected camera devices
80    const char** cameraIds;  ///< list of identifier of connected camera devices
81} ACameraIdList;
82
83/**
84 * Create a list of currently connected camera devices, including
85 * cameras that may be in use by other camera API clients.
86 *
87 * <p>Non-removable cameras use integers starting at 0 for their
88 * identifiers, while removable cameras have a unique identifier for each
89 * individual device, even if they are the same model.</p>
90 *
91 * <p>ACameraManager_getCameraIdList will allocate and return an {@link ACameraIdList}.
92 * The caller must call {@link ACameraManager_deleteCameraIdList} to free the memory</p>
93 *
94 * @param manager the {@link ACameraManager} of interest
95 * @param cameraIdList the output {@link ACameraIdList} will be filled in here if the method call
96 *        succeeds.
97 *
98 * @return <ul>
99 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
100 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or cameraIdList is NULL.</li>
101 *         <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li>
102 *         <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li></ul>
103 */
104camera_status_t ACameraManager_getCameraIdList(ACameraManager* manager,
105                                              /*out*/ACameraIdList** cameraIdList);
106
107/**
108 * Delete a list of camera devices allocated via {@link ACameraManager_getCameraIdList}.
109 *
110 * @param cameraIdList the {@link ACameraIdList} to be deleted.
111 */
112void ACameraManager_deleteCameraIdList(ACameraIdList* cameraIdList);
113
114/**
115 * Definition of camera availability callbacks.
116 *
117 * @param context The optional application context provided by user in
118 *                {@link ACameraManager_AvailabilityCallbacks}.
119 * @param cameraId The ID of the camera device whose availability is changing. The memory of this
120 *                 argument is owned by camera framework and will become invalid immediately after
121 *                 this callback returns.
122 */
123typedef void (*ACameraManager_AvailabilityCallback)(void* context, const char* cameraId);
124
125/**
126 * A listener for camera devices becoming available or unavailable to open.
127 *
128 * <p>Cameras become available when they are no longer in use, or when a new
129 * removable camera is connected. They become unavailable when some
130 * application or service starts using a camera, or when a removable camera
131 * is disconnected.</p>
132 *
133 * @see ACameraManager_registerAvailabilityCallback
134 */
135typedef struct ACameraManager_AvailabilityListener {
136    /// Optional application context.
137    void*                               context;
138    /// Called when a camera becomes available
139    ACameraManager_AvailabilityCallback onCameraAvailable;
140    /// Called when a camera becomes unavailable
141    ACameraManager_AvailabilityCallback onCameraUnavailable;
142} ACameraManager_AvailabilityCallbacks;
143
144/**
145 * Register camera availability callbacks.
146 *
147 * <p>onCameraUnavailable will be called whenever a camera device is opened by any camera API client.
148 * Other camera API clients may still be able to open such a camera device, evicting the existing
149 * client if they have higher priority than the existing client of a camera device.
150 * See {@link ACameraManager_openCamera} for more details.</p>
151 *
152 * <p>The callbacks will be called on a dedicated thread shared among all ACameraManager
153 * instances.</p>
154 *
155 * <p>Since this callback will be registered with the camera service, remember to unregister it
156 * once it is no longer needed; otherwise the callback will continue to receive events
157 * indefinitely and it may prevent other resources from being released. Specifically, the
158 * callbacks will be invoked independently of the general activity lifecycle and independently
159 * of the state of individual ACameraManager instances.</p>
160 *
161 * @param manager the {@link ACameraManager} of interest.
162 * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be registered.
163 *
164 * @return <ul>
165 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
166 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or callback is NULL, or
167 *                  {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or
168 *                  {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul>
169 */
170camera_status_t ACameraManager_registerAvailabilityCallback(
171        ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback);
172
173/**
174 * Unregister camera availability callbacks.
175 *
176 * <p>Removing a callback that isn't registered has no effect.</p>
177 *
178 * @param manager the {@link ACameraManager} of interest.
179 * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be unregistered.
180 *
181 * @return <ul>
182 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
183 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if callback,
184 *                  {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or
185 *                  {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul>
186 */
187camera_status_t ACameraManager_unregisterAvailabilityCallback(
188        ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback);
189
190/**
191 * Query the capabilities of a camera device. These capabilities are
192 * immutable for a given camera.
193 *
194 * <p>See {@link ACameraMetadata} document and {@link NdkCameraMetadataTags.h} for more details.</p>
195 *
196 * <p>The caller must call {@link ACameraMetadata_free} to free the memory of the output
197 * characteristics.</p>
198 *
199 * @param manager the {@link ACameraManager} of interest.
200 * @param cameraId the ID string of the camera device of interest.
201 * @param characteristics the output {@link ACameraMetadata} will be filled here if the method call
202 *        succeeeds.
203 *
204 * @return <ul>
205 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
206 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, or characteristics
207 *                  is NULL, or cameraId does not match any camera devices connected.</li>
208 *         <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li>
209 *         <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li>
210 *         <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
211 */
212camera_status_t ACameraManager_getCameraCharacteristics(
213        ACameraManager* manager, const char* cameraId,
214        /*out*/ACameraMetadata** characteristics);
215
216/**
217 * Open a connection to a camera with the given ID. The opened camera device will be
218 * returned in the `device` parameter.
219 *
220 * <p>Use {@link ACameraManager_getCameraIdList} to get the list of available camera
221 * devices. Note that even if an id is listed, open may fail if the device
222 * is disconnected between the calls to {@link ACameraManager_getCameraIdList} and
223 * {@link ACameraManager_openCamera}, or if a higher-priority camera API client begins using the
224 * camera device.</p>
225 *
226 * <p>Devices for which the
227 * {@link ACameraManager_AvailabilityCallbacks#onCameraUnavailable} callback has been called due to
228 * the device being in use by a lower-priority, background camera API client can still potentially
229 * be opened by calling this method when the calling camera API client has a higher priority
230 * than the current camera API client using this device.  In general, if the top, foreground
231 * activity is running within your application process, your process will be given the highest
232 * priority when accessing the camera, and this method will succeed even if the camera device is
233 * in use by another camera API client. Any lower-priority application that loses control of the
234 * camera in this way will receive an
235 * {@link ACameraDevice_stateCallbacks#onDisconnected} callback.</p>
236 *
237 * <p>Once the camera is successfully opened,the ACameraDevice can then be set up
238 * for operation by calling {@link ACameraDevice_createCaptureSession} and
239 * {@link ACameraDevice_createCaptureRequest}.</p>
240 *
241 * <p>If the camera becomes disconnected after this function call returns,
242 * {@link ACameraDevice_stateCallbacks#onDisconnected} with a
243 * ACameraDevice in the disconnected state will be called.</p>
244 *
245 * <p>If the camera runs into error after this function call returns,
246 * {@link ACameraDevice_stateCallbacks#onError} with a
247 * ACameraDevice in the error state will be called.</p>
248 *
249 * @param manager the {@link ACameraManager} of interest.
250 * @param cameraId the ID string of the camera device to be opened.
251 * @param callback the {@link ACameraDevice_StateCallbacks} associated with the opened camera device.
252 * @param device the opened {@link ACameraDevice} will be filled here if the method call succeeds.
253 *
254 * @return <ul>
255 *         <li>{@link ACAMERA_OK} if the method call succeeds.</li>
256 *         <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, callback, or device
257 *                  is NULL, or cameraId does not match any camera devices connected.</li>
258 *         <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li>
259 *         <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li>
260 *         <li>{@link ACAMERA_ERROR_CAMERA_IN_USE} if camera device is being used by a higher
261 *                   priority camera API client.</li>
262 *         <li>{@link ACAMERA_ERROR_MAX_CAMERA_IN_USE} if the system-wide limit for number of open
263 *                   cameras or camera resources has been reached, and more camera devices cannot be
264 *                   opened until previous instances are closed.</li>
265 *         <li>{@link ACAMERA_ERROR_CAMERA_DISABLED} if the camera is disabled due to a device
266 *                   policy, and cannot be opened.</li>
267 *         <li>{@link ACAMERA_ERROR_PERMISSION_DENIED} if the application does not have permission
268 *                   to open camera.</li>
269 *         <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
270 */
271camera_status_t ACameraManager_openCamera(
272        ACameraManager* manager, const char* cameraId,
273        ACameraDevice_StateCallbacks* callback,
274        /*out*/ACameraDevice** device);
275
276#endif /* __ANDROID_API__ >= 24 */
277
278__END_DECLS
279
280#endif /* _NDK_CAMERA_MANAGER_H */
281
282/** @} */
283