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