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 */ 54 typedef 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 */ 68 ACameraManager* ACameraManager_create() __INTRODUCED_IN(24); 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 */ 75 void ACameraManager_delete(ACameraManager* manager) __INTRODUCED_IN(24); 76 77 /** 78 * Create a list of currently connected camera devices, including 79 * cameras that may be in use by other camera API clients. 80 * 81 * <p>Non-removable cameras use integers starting at 0 for their 82 * identifiers, while removable cameras have a unique identifier for each 83 * individual device, even if they are the same model.</p> 84 * 85 * <p>ACameraManager_getCameraIdList will allocate and return an {@link ACameraIdList}. 86 * The caller must call {@link ACameraManager_deleteCameraIdList} to free the memory</p> 87 * 88 * <p>Note: the returned camera list might be a subset to the output of <a href= 89 * "https://developer.android.com/reference/android/hardware/camera2/CameraManager.html#getCameraIdList()"> 90 * SDK CameraManager#getCameraIdList API</a> as the NDK API does not support some legacy camera 91 * hardware.</p> 92 * 93 * @param manager the {@link ACameraManager} of interest 94 * @param cameraIdList the output {@link ACameraIdList} will be filled in here if the method call 95 * succeeds. 96 * 97 * @return <ul> 98 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 99 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or cameraIdList is NULL.</li> 100 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li> 101 * <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li></ul> 102 */ 103 camera_status_t ACameraManager_getCameraIdList(ACameraManager* manager, 104 /*out*/ACameraIdList** cameraIdList) __INTRODUCED_IN(24); 105 106 /** 107 * Delete a list of camera devices allocated via {@link ACameraManager_getCameraIdList}. 108 * 109 * @param cameraIdList the {@link ACameraIdList} to be deleted. 110 */ 111 void ACameraManager_deleteCameraIdList(ACameraIdList* cameraIdList) __INTRODUCED_IN(24); 112 113 /** 114 * Definition of camera availability callbacks. 115 * 116 * @param context The optional application context provided by user in 117 * {@link ACameraManager_AvailabilityCallbacks}. 118 * @param cameraId The ID of the camera device whose availability is changing. The memory of this 119 * argument is owned by camera framework and will become invalid immediately after 120 * this callback returns. 121 */ 122 typedef void (*ACameraManager_AvailabilityCallback)(void* context, 123 const char* cameraId); 124 125 /** 126 * Definition of physical camera availability callbacks. 127 * 128 * @param context The optional application context provided by user in 129 * {@link ACameraManager_AvailabilityCallbacks}. 130 * @param cameraId The ID of the logical multi-camera device whose physical camera status is 131 * changing. The memory of this argument is owned by camera framework and will 132 * become invalid immediately after this callback returns. 133 * @param physicalCameraId The ID of the physical camera device whose status is changing. The 134 * memory of this argument is owned by camera framework and will become invalid 135 * immediately after this callback returns. 136 */ 137 typedef void (*ACameraManager_PhysicalCameraAvailabilityCallback)(void* context, 138 const char* cameraId, const char* physicalCameraId); 139 140 /** 141 * A listener for camera devices becoming available or unavailable to open. 142 * 143 * <p>Cameras become available when they are no longer in use, or when a new 144 * removable camera is connected. They become unavailable when some 145 * application or service starts using a camera, or when a removable camera 146 * is disconnected.</p> 147 * 148 * @see ACameraManager_registerAvailabilityCallback 149 */ 150 typedef struct ACameraManager_AvailabilityListener { 151 /// Optional application context. 152 void* context; 153 /// Called when a camera becomes available 154 ACameraManager_AvailabilityCallback onCameraAvailable; 155 /// Called when a camera becomes unavailable 156 ACameraManager_AvailabilityCallback onCameraUnavailable; 157 } ACameraManager_AvailabilityCallbacks; 158 159 /** 160 * Register camera availability callbacks. 161 * 162 * <p>onCameraUnavailable will be called whenever a camera device is opened by any camera API client. 163 * Other camera API clients may still be able to open such a camera device, evicting the existing 164 * client if they have higher priority than the existing client of a camera device. 165 * See {@link ACameraManager_openCamera} for more details.</p> 166 * 167 * <p>The callbacks will be called on a dedicated thread shared among all ACameraManager 168 * instances.</p> 169 * 170 * <p>Since this callback will be registered with the camera service, remember to unregister it 171 * once it is no longer needed; otherwise the callback will continue to receive events 172 * indefinitely and it may prevent other resources from being released. Specifically, the 173 * callbacks will be invoked independently of the general activity lifecycle and independently 174 * of the state of individual ACameraManager instances.</p> 175 * 176 * @param manager the {@link ACameraManager} of interest. 177 * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be registered. 178 * 179 * @return <ul> 180 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 181 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or callback is NULL, or 182 * {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or 183 * {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul> 184 */ 185 camera_status_t ACameraManager_registerAvailabilityCallback( 186 ACameraManager* manager, 187 const ACameraManager_AvailabilityCallbacks* callback) __INTRODUCED_IN(24); 188 189 /** 190 * Unregister camera availability callbacks. 191 * 192 * <p>Removing a callback that isn't registered has no effect.</p> 193 * 194 * <p>This function must not be called with a mutex lock also held by 195 * the availability callbacks.</p> 196 * 197 * @param manager the {@link ACameraManager} of interest. 198 * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be unregistered. 199 * 200 * @return <ul> 201 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 202 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if callback, 203 * {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or 204 * {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul> 205 */ 206 camera_status_t ACameraManager_unregisterAvailabilityCallback( 207 ACameraManager* manager, 208 const ACameraManager_AvailabilityCallbacks* callback) __INTRODUCED_IN(24); 209 210 /** 211 * Query the capabilities of a camera device. These capabilities are 212 * immutable for a given camera. 213 * 214 * <p>See {@link ACameraMetadata} document and {@link NdkCameraMetadataTags.h} for more details.</p> 215 * 216 * <p>The caller must call {@link ACameraMetadata_free} to free the memory of the output 217 * characteristics.</p> 218 * 219 * @param manager the {@link ACameraManager} of interest. 220 * @param cameraId the ID string of the camera device of interest. 221 * @param characteristics the output {@link ACameraMetadata} will be filled here if the method call 222 * succeeeds. 223 * 224 * @return <ul> 225 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 226 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, or characteristics 227 * is NULL, or cameraId does not match any camera devices connected.</li> 228 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li> 229 * <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li> 230 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 231 */ 232 camera_status_t ACameraManager_getCameraCharacteristics( 233 ACameraManager* manager, const char* cameraId, 234 /*out*/ACameraMetadata** characteristics) __INTRODUCED_IN(24); 235 236 /** 237 * Open a connection to a camera with the given ID. The opened camera device will be 238 * returned in the `device` parameter. 239 * 240 * <p>Use {@link ACameraManager_getCameraIdList} to get the list of available camera 241 * devices. Note that even if an id is listed, open may fail if the device 242 * is disconnected between the calls to {@link ACameraManager_getCameraIdList} and 243 * {@link ACameraManager_openCamera}, or if a higher-priority camera API client begins using the 244 * camera device.</p> 245 * 246 * <p>Devices for which the 247 * {@link ACameraManager_AvailabilityCallbacks#onCameraUnavailable} callback has been called due to 248 * the device being in use by a lower-priority, background camera API client can still potentially 249 * be opened by calling this method when the calling camera API client has a higher priority 250 * than the current camera API client using this device. In general, if the top, foreground 251 * activity is running within your application process, your process will be given the highest 252 * priority when accessing the camera, and this method will succeed even if the camera device is 253 * in use by another camera API client. Any lower-priority application that loses control of the 254 * camera in this way will receive an 255 * {@link ACameraDevice_StateCallbacks#onDisconnected} callback.</p> 256 * 257 * <p>Once the camera is successfully opened,the ACameraDevice can then be set up 258 * for operation by calling {@link ACameraDevice_createCaptureSession} and 259 * {@link ACameraDevice_createCaptureRequest}.</p> 260 * 261 * <p>If the camera becomes disconnected after this function call returns, 262 * {@link ACameraDevice_StateCallbacks#onDisconnected} with a 263 * ACameraDevice in the disconnected state will be called.</p> 264 * 265 * <p>If the camera runs into error after this function call returns, 266 * {@link ACameraDevice_StateCallbacks#onError} with a 267 * ACameraDevice in the error state will be called.</p> 268 * 269 * @param manager the {@link ACameraManager} of interest. 270 * @param cameraId the ID string of the camera device to be opened. 271 * @param callback the {@link ACameraDevice_StateCallbacks} associated with the opened camera device. 272 * @param device the opened {@link ACameraDevice} will be filled here if the method call succeeds. 273 * 274 * @return <ul> 275 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 276 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, callback, or device 277 * is NULL, or cameraId does not match any camera devices connected.</li> 278 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li> 279 * <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li> 280 * <li>{@link ACAMERA_ERROR_CAMERA_IN_USE} if camera device is being used by a higher 281 * priority camera API client.</li> 282 * <li>{@link ACAMERA_ERROR_MAX_CAMERA_IN_USE} if the system-wide limit for number of open 283 * cameras or camera resources has been reached, and more camera devices cannot be 284 * opened until previous instances are closed.</li> 285 * <li>{@link ACAMERA_ERROR_CAMERA_DISABLED} if the camera is disabled due to a device 286 * policy, and cannot be opened.</li> 287 * <li>{@link ACAMERA_ERROR_PERMISSION_DENIED} if the application does not have permission 288 * to open camera.</li> 289 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 290 */ 291 camera_status_t ACameraManager_openCamera( 292 ACameraManager* manager, const char* cameraId, 293 ACameraDevice_StateCallbacks* callback, 294 /*out*/ACameraDevice** device) __INTRODUCED_IN(24); 295 296 #endif /* __ANDROID_API__ >= 24 */ 297 298 #if __ANDROID_API__ >= 29 299 300 /** 301 * Definition of camera access permission change callback. 302 * 303 * <p>Notification that camera access priorities have changed and the camera may 304 * now be openable. An application that was previously denied camera access due to 305 * a higher-priority user already using the camera, or that was disconnected from an 306 * active camera session due to a higher-priority user trying to open the camera, 307 * should try to open the camera again if it still wants to use it. Note that 308 * multiple applications may receive this callback at the same time, and only one of 309 * them will succeed in opening the camera in practice, depending on exact access 310 * priority levels and timing. This method is useful in cases where multiple 311 * applications may be in the resumed state at the same time, and the user switches 312 * focus between them, or if the current camera-using application moves between 313 * full-screen and Picture-in-Picture (PiP) states. In such cases, the camera 314 * available/unavailable callbacks will not be invoked, but another application may 315 * now have higher priority for camera access than the current camera-using 316 * application.</p> 317 318 * @param context The optional application context provided by user in 319 * {@link ACameraManager_AvailabilityListener}. 320 */ 321 typedef void (*ACameraManager_AccessPrioritiesChangedCallback)(void* context); 322 323 /** 324 * A listener for camera devices becoming available/unavailable to open or when 325 * the camera access permissions change. 326 * 327 * <p>Cameras become available when they are no longer in use, or when a new 328 * removable camera is connected. They become unavailable when some 329 * application or service starts using a camera, or when a removable camera 330 * is disconnected.</p> 331 * 332 * @see ACameraManager_registerExtendedAvailabilityCallback 333 */ 334 typedef struct ACameraManager_ExtendedAvailabilityListener { 335 /// 336 ACameraManager_AvailabilityCallbacks availabilityCallbacks; 337 338 /// Called when there is camera access permission change 339 ACameraManager_AccessPrioritiesChangedCallback onCameraAccessPrioritiesChanged; 340 341 /// Called when a physical camera becomes available 342 ACameraManager_PhysicalCameraAvailabilityCallback onPhysicalCameraAvailable __INTRODUCED_IN(30); 343 344 /// Called when a physical camera becomes unavailable 345 ACameraManager_PhysicalCameraAvailabilityCallback onPhysicalCameraUnavailable 346 __INTRODUCED_IN(30); 347 348 /// Reserved for future use, please ensure that all entries are set to NULL 349 void *reserved[4]; 350 } ACameraManager_ExtendedAvailabilityCallbacks; 351 352 /** 353 * Register camera extended availability callbacks. 354 * 355 * <p>onCameraUnavailable will be called whenever a camera device is opened by any camera API 356 * client. Other camera API clients may still be able to open such a camera device, evicting the 357 * existing client if they have higher priority than the existing client of a camera device. 358 * See {@link ACameraManager_openCamera} for more details.</p> 359 * 360 * <p>The callbacks will be called on a dedicated thread shared among all ACameraManager 361 * instances.</p> 362 * 363 * <p>Since this callback will be registered with the camera service, remember to unregister it 364 * once it is no longer needed; otherwise the callback will continue to receive events 365 * indefinitely and it may prevent other resources from being released. Specifically, the 366 * callbacks will be invoked independently of the general activity lifecycle and independently 367 * of the state of individual ACameraManager instances.</p> 368 * 369 * @param manager the {@link ACameraManager} of interest. 370 * @param callback the {@link ACameraManager_ExtendedAvailabilityCallbacks} to be registered. 371 * 372 * @return <ul> 373 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 374 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or callback is NULL, or 375 * {ACameraManager_ExtendedAvailabilityCallbacks#onCameraAccessPrioritiesChanged} 376 * or {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or 377 * {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul> 378 */ 379 camera_status_t ACameraManager_registerExtendedAvailabilityCallback( 380 ACameraManager* manager, 381 const ACameraManager_ExtendedAvailabilityCallbacks* callback) __INTRODUCED_IN(29); 382 383 /** 384 * Unregister camera extended availability callbacks. 385 * 386 * <p>Removing a callback that isn't registered has no effect.</p> 387 * 388 * <p>This function must not be called with a mutex lock also held by 389 * the extended availability callbacks.</p> 390 * 391 * @param manager the {@link ACameraManager} of interest. 392 * @param callback the {@link ACameraManager_ExtendedAvailabilityCallbacks} to be unregistered. 393 * 394 * @return <ul> 395 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 396 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if callback, 397 * {ACameraManager_ExtendedAvailabilityCallbacks#onCameraAccessPrioritiesChanged} 398 * or {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or 399 * {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul> 400 */ 401 camera_status_t ACameraManager_unregisterExtendedAvailabilityCallback( 402 ACameraManager* manager, 403 const ACameraManager_ExtendedAvailabilityCallbacks* callback) __INTRODUCED_IN(29); 404 405 #ifdef __ANDROID_VNDK__ 406 /** 407 * Retrieve the tag value, given the tag name and camera id. 408 * This method is device specific since some metadata might be defined by device manufacturers 409 * and might only be accessible for specific cameras. 410 * @param manager The {@link ACameraManager} of interest. 411 * @param cameraId The cameraId, which is used to query camera characteristics. 412 * @param name The name of the tag being queried. 413 * @param tag The output tag assigned by this method. 414 * 415 * @return ACAMERA_OK only if the function call was successful. 416 */ 417 camera_status_t ACameraManager_getTagFromName(ACameraManager *manager, const char* cameraId, 418 const char *name, /*out*/uint32_t *tag) 419 __INTRODUCED_IN(29); 420 #endif 421 422 #endif /* __ANDROID_API__ >= 29 */ 423 424 __END_DECLS 425 426 #endif /* _NDK_CAMERA_MANAGER_H */ 427 428 /** @} */ 429