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 "NdkCameraError.h" 40 #include "NdkCameraMetadata.h" 41 #include "NdkCameraDevice.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 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(); 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); 74 75 /// Struct to hold list of camera devices 76 typedef struct ACameraIdList { 77 int numCameras; ///< Number of connected camera devices 78 const char** cameraIds; ///< list of identifier of connected camera devices 79 } ACameraIdList; 80 81 /** 82 * Create a list of currently connected camera devices, including 83 * cameras that may be in use by other camera API clients. 84 * 85 * <p>Non-removable cameras use integers starting at 0 for their 86 * identifiers, while removable cameras have a unique identifier for each 87 * individual device, even if they are the same model.</p> 88 * 89 * <p>ACameraManager_getCameraIdList will allocate and return an {@link ACameraIdList}. 90 * The caller must call {@link ACameraManager_deleteCameraIdList} to free the memory</p> 91 * 92 * @param manager the {@link ACameraManager} of interest 93 * @param cameraIdList the output {@link ACameraIdList} will be filled in here if the method call 94 * succeeds. 95 * 96 * @return <ul> 97 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 98 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or cameraIdList is NULL.</li> 99 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li> 100 * <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li></ul> 101 */ 102 camera_status_t ACameraManager_getCameraIdList(ACameraManager* manager, 103 /*out*/ACameraIdList** cameraIdList); 104 105 /** 106 * Delete a list of camera devices allocated via {@link ACameraManager_getCameraIdList}. 107 * 108 * @param cameraIdList the {@link ACameraIdList} to be deleted. 109 */ 110 void ACameraManager_deleteCameraIdList(ACameraIdList* cameraIdList); 111 112 /** 113 * Definition of camera availability callbacks. 114 * 115 * @param context The optional application context provided by user in 116 * {@link ACameraManager_AvailabilityCallbacks}. 117 * @param cameraId The ID of the camera device whose availability is changing. The memory of this 118 * argument is owned by camera framework and will become invalid immediately after 119 * this callback returns. 120 */ 121 typedef void (*ACameraManager_AvailabilityCallback)(void* context, const char* cameraId); 122 123 /** 124 * A listener for camera devices becoming available or unavailable to open. 125 * 126 * <p>Cameras become available when they are no longer in use, or when a new 127 * removable camera is connected. They become unavailable when some 128 * application or service starts using a camera, or when a removable camera 129 * is disconnected.</p> 130 * 131 * @see ACameraManager_registerAvailabilityCallback 132 */ 133 typedef struct ACameraManager_AvailabilityListener { 134 /// Optional application context. 135 void* context; 136 /// Called when a camera becomes available 137 ACameraManager_AvailabilityCallback onCameraAvailable; 138 /// Called when a camera becomes unavailable 139 ACameraManager_AvailabilityCallback onCameraUnavailable; 140 } ACameraManager_AvailabilityCallbacks; 141 142 /** 143 * Register camera availability callbacks. 144 * 145 * <p>onCameraUnavailable will be called whenever a camera device is opened by any camera API client. 146 * Other camera API clients may still be able to open such a camera device, evicting the existing 147 * client if they have higher priority than the existing client of a camera device. 148 * See {@link ACameraManager_openCamera} for more details.</p> 149 * 150 * <p>The callbacks will be called on a dedicated thread shared among all ACameraManager 151 * instances.</p> 152 * 153 * <p>Since this callback will be registered with the camera service, remember to unregister it 154 * once it is no longer needed; otherwise the callback will continue to receive events 155 * indefinitely and it may prevent other resources from being released. Specifically, the 156 * callbacks will be invoked independently of the general activity lifecycle and independently 157 * of the state of individual ACameraManager instances.</p> 158 * 159 * @param manager the {@link ACameraManager} of interest. 160 * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be registered. 161 * 162 * @return <ul> 163 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 164 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or callback is NULL, or 165 * {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or 166 * {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul> 167 */ 168 camera_status_t ACameraManager_registerAvailabilityCallback( 169 ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback); 170 171 /** 172 * Unregister camera availability callbacks. 173 * 174 * <p>Removing a callback that isn't registered has no effect.</p> 175 * 176 * @param manager the {@link ACameraManager} of interest. 177 * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be unregistered. 178 * 179 * @return <ul> 180 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 181 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if callback, 182 * {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or 183 * {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul> 184 */ 185 camera_status_t ACameraManager_unregisterAvailabilityCallback( 186 ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback); 187 188 /** 189 * Query the capabilities of a camera device. These capabilities are 190 * immutable for a given camera. 191 * 192 * <p>See {@link ACameraMetadata} document and {@link NdkCameraMetadataTags.h} for more details.</p> 193 * 194 * <p>The caller must call {@link ACameraMetadata_free} to free the memory of the output 195 * characteristics.</p> 196 * 197 * @param manager the {@link ACameraManager} of interest. 198 * @param cameraId the ID string of the camera device of interest. 199 * @param characteristics the output {@link ACameraMetadata} will be filled here if the method call 200 * succeeeds. 201 * 202 * @return <ul> 203 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 204 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, or characteristics 205 * is NULL, or cameraId does not match any camera devices connected.</li> 206 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li> 207 * <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li> 208 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 209 */ 210 camera_status_t ACameraManager_getCameraCharacteristics( 211 ACameraManager* manager, const char* cameraId, 212 /*out*/ACameraMetadata** characteristics); 213 214 /** 215 * Open a connection to a camera with the given ID. The opened camera device will be 216 * returned in the `device` parameter. 217 * 218 * <p>Use {@link ACameraManager_getCameraIdList} to get the list of available camera 219 * devices. Note that even if an id is listed, open may fail if the device 220 * is disconnected between the calls to {@link ACameraManager_getCameraIdList} and 221 * {@link ACameraManager_openCamera}, or if a higher-priority camera API client begins using the 222 * camera device.</p> 223 * 224 * <p>Devices for which the 225 * {@link ACameraManager_AvailabilityCallbacks#onCameraUnavailable} callback has been called due to 226 * the device being in use by a lower-priority, background camera API client can still potentially 227 * be opened by calling this method when the calling camera API client has a higher priority 228 * than the current camera API client using this device. In general, if the top, foreground 229 * activity is running within your application process, your process will be given the highest 230 * priority when accessing the camera, and this method will succeed even if the camera device is 231 * in use by another camera API client. Any lower-priority application that loses control of the 232 * camera in this way will receive an 233 * {@link ACameraDevice_stateCallbacks#onDisconnected} callback.</p> 234 * 235 * <p>Once the camera is successfully opened,the ACameraDevice can then be set up 236 * for operation by calling {@link ACameraDevice_createCaptureSession} and 237 * {@link ACameraDevice_createCaptureRequest}.</p> 238 * 239 * <p>If the camera becomes disconnected after this function call returns, 240 * {@link ACameraDevice_stateCallbacks#onDisconnected} with a 241 * ACameraDevice in the disconnected state will be called.</p> 242 * 243 * <p>If the camera runs into error after this function call returns, 244 * {@link ACameraDevice_stateCallbacks#onError} with a 245 * ACameraDevice in the error state will be called.</p> 246 * 247 * @param manager the {@link ACameraManager} of interest. 248 * @param cameraId the ID string of the camera device to be opened. 249 * @param callback the {@link ACameraDevice_StateCallbacks} associated with the opened camera device. 250 * @param device the opened {@link ACameraDevice} will be filled here if the method call succeeds. 251 * 252 * @return <ul> 253 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 254 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, callback, or device 255 * is NULL, or cameraId does not match any camera devices connected.</li> 256 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li> 257 * <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li> 258 * <li>{@link ACAMERA_ERROR_CAMERA_IN_USE} if camera device is being used by a higher 259 * priority camera API client.</li> 260 * <li>{@link ACAMERA_ERROR_MAX_CAMERA_IN_USE} if the system-wide limit for number of open 261 * cameras or camera resources has been reached, and more camera devices cannot be 262 * opened until previous instances are closed.</li> 263 * <li>{@link ACAMERA_ERROR_CAMERA_DISABLED} if the camera is disabled due to a device 264 * policy, and cannot be opened.</li> 265 * <li>{@link ACAMERA_ERROR_PERMISSION_DENIED} if the application does not have permission 266 * to open camera.</li> 267 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 268 */ 269 camera_status_t ACameraManager_openCamera( 270 ACameraManager* manager, const char* cameraId, 271 ACameraDevice_StateCallbacks* callback, 272 /*out*/ACameraDevice** device); 273 274 #ifdef __cplusplus 275 } // extern "C" 276 #endif 277 278 #endif //_NDK_CAMERA_MANAGER_H 279 280 /** @} */ 281