public final class CameraManager extends Object
A system service manager for detecting, characterizing, and connecting to
CameraDevices
.
You can get an instance of this class by calling
Context.getSystemService()
.
CameraManager manager = (CameraManager) getSystemService(Context.CAMERA_SERVICE);
For more details about communicating with camera devices, read the Camera
developer guide or the camera2
package documentation.
Modifier and Type | Class and Description |
---|---|
static class |
CameraManager.AvailabilityCallback
A callback for camera devices becoming available or unavailable to open.
|
static class |
CameraManager.TorchCallback
A callback for camera flash torch modes becoming unavailable, disabled, or enabled.
|
Constructor and Description |
---|
CameraManager(Context context) |
Modifier and Type | Method and Description |
---|---|
CameraCharacteristics |
getCameraCharacteristics(String cameraId)
Query the capabilities of a camera device.
|
String[] |
getCameraIdList()
Return the list of currently connected camera devices by identifier, including
cameras that may be in use by other camera API clients.
|
void |
openCamera(String cameraId,
CameraDevice.StateCallback callback,
Handler handler)
Open a connection to a camera with the given ID.
|
void |
openCameraForUid(String cameraId,
CameraDevice.StateCallback callback,
Handler handler,
int clientUid)
Open a connection to a camera with the given ID, on behalf of another application
specified by clientUid.
|
void |
registerAvailabilityCallback(CameraManager.AvailabilityCallback callback,
Handler handler)
Register a callback to be notified about camera device availability.
|
void |
registerTorchCallback(CameraManager.TorchCallback callback,
Handler handler)
Register a callback to be notified about torch mode status.
|
void |
setTorchMode(String cameraId,
boolean enabled)
Set the flash unit's torch mode of the camera of the given ID without opening the camera
device.
|
static void |
throwAsPublicException(Throwable t)
Convert ServiceSpecificExceptions and Binder RemoteExceptions from camera binder interfaces
into the correct public exceptions.
|
void |
unregisterAvailabilityCallback(CameraManager.AvailabilityCallback callback)
Remove a previously-added callback; the callback will no longer receive connection and
disconnection callbacks.
|
void |
unregisterTorchCallback(CameraManager.TorchCallback callback)
Remove a previously-added callback; the callback will no longer receive torch mode status
callbacks.
|
public CameraManager(Context context)
public String[] getCameraIdList() throws CameraAccessException
Non-removable cameras use integers starting at 0 for their identifiers, while removable cameras have a unique identifier for each individual device, even if they are the same model.
CameraAccessException
public void registerAvailabilityCallback(CameraManager.AvailabilityCallback callback, Handler handler)
Registering the same callback again will replace the handler with the new one provided.
The first time a callback is registered, it is immediately called with the availability status of all currently known camera devices.
CameraManager.AvailabilityCallback.onCameraUnavailable(String)
will be called whenever a camera
device is opened by any camera API client. As of API level 23, other camera API clients may
still be able to open such a camera device, evicting the existing client if they have higher
priority than the existing client of a camera device. See open() for more details.
Since this callback will be registered with the camera service, remember to unregister it once it is no longer needed; otherwise the callback will continue to receive events indefinitely and it may prevent other resources from being released. Specifically, the callbacks will be invoked independently of the general activity lifecycle and independently of the state of individual CameraManager instances.
callback
- the new callback to send camera availability notices tohandler
- The handler on which the callback should be invoked, or null
to use
the current thread's looper
.IllegalArgumentException
- if the handler is null
but the current thread has
no looper.public void unregisterAvailabilityCallback(CameraManager.AvailabilityCallback callback)
Removing a callback that isn't registered has no effect.
callback
- The callback to remove from the notification listpublic void registerTorchCallback(CameraManager.TorchCallback callback, Handler handler)
Registering the same callback again will replace the handler with the new one provided.
The first time a callback is registered, it is immediately called with the torch mode status of all currently known camera devices with a flash unit.
Since this callback will be registered with the camera service, remember to unregister it once it is no longer needed; otherwise the callback will continue to receive events indefinitely and it may prevent other resources from being released. Specifically, the callbacks will be invoked independently of the general activity lifecycle and independently of the state of individual CameraManager instances.
callback
- The new callback to send torch mode status tohandler
- The handler on which the callback should be invoked, or null
to use
the current thread's looper
.IllegalArgumentException
- if the handler is null
but the current thread has
no looper.public void unregisterTorchCallback(CameraManager.TorchCallback callback)
Removing a callback that isn't registered has no effect.
callback
- The callback to remove from the notification listpublic CameraCharacteristics getCameraCharacteristics(String cameraId) throws CameraAccessException
Query the capabilities of a camera device. These capabilities are immutable for a given camera.
cameraId
- The id of the camera device to queryIllegalArgumentException
- if the cameraId does not match any
known camera device.CameraAccessException
- if the camera device has been disconnected.getCameraIdList()
,
DevicePolicyManager.setCameraDisabled(android.content.ComponentName, boolean)
public void openCamera(String cameraId, CameraDevice.StateCallback callback, Handler handler) throws CameraAccessException
Use getCameraIdList()
to get the list of available camera
devices. Note that even if an id is listed, open may fail if the device
is disconnected between the calls to getCameraIdList()
and
openCamera(java.lang.String, android.hardware.camera2.CameraDevice.StateCallback, android.os.Handler)
, or if a higher-priority camera API client begins using the
camera device.
As of API level 23, devices for which the
CameraManager.AvailabilityCallback.onCameraUnavailable(String)
callback has been called due to the
device being in use by a lower-priority, background camera API client can still potentially
be opened by calling this method when the calling camera API client has a higher priority
than the current camera API client using this device. In general, if the top, foreground
activity is running within your application process, your process will be given the highest
priority when accessing the camera, and this method will succeed even if the camera device is
in use by another camera API client. Any lower-priority application that loses control of the
camera in this way will receive an
CameraDevice.StateCallback.onDisconnected(android.hardware.camera2.CameraDevice)
callback.
Once the camera is successfully opened, CameraDevice.StateCallback.onOpened(android.hardware.camera2.CameraDevice)
will
be invoked with the newly opened CameraDevice
. The camera device can then be set up
for operation by calling CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
and
CameraDevice.createCaptureRequest(int)
If the camera becomes disconnected during initialization
after this function call returns,
CameraDevice.StateCallback.onDisconnected(android.hardware.camera2.CameraDevice)
with a
CameraDevice
in the disconnected state (and
CameraDevice.StateCallback.onOpened(android.hardware.camera2.CameraDevice)
will be skipped).
If opening the camera device fails, then the device callback's
onError
method will be called, and subsequent
calls on the camera device will throw a CameraAccessException
.
cameraId
- The unique identifier of the camera device to opencallback
- The callback which is invoked once the camera is openedhandler
- The handler on which the callback should be invoked, or
null
to use the current thread's looper
.CameraAccessException
- if the camera is disabled by device policy,
has been disconnected, or is being used by a higher-priority camera API client.IllegalArgumentException
- if cameraId or the callback was null,
or the cameraId does not match any currently or previously available
camera device.SecurityException
- if the application does not have permission to
access the cameragetCameraIdList()
,
DevicePolicyManager.setCameraDisabled(android.content.ComponentName, boolean)
public void openCameraForUid(String cameraId, CameraDevice.StateCallback callback, Handler handler, int clientUid) throws CameraAccessException
The behavior of this method matches that of openCamera(java.lang.String, android.hardware.camera2.CameraDevice.StateCallback, android.os.Handler)
, except that it allows
the caller to specify the UID to use for permission/etc verification. This can only be
done by services trusted by the camera subsystem to act on behalf of applications and
to forward the real UID.
clientUid
- The UID of the application on whose behalf the camera is being opened.
Must be USE_CALLING_UID unless the caller is a trusted service.CameraAccessException
public void setTorchMode(String cameraId, boolean enabled) throws CameraAccessException
Use getCameraIdList()
to get the list of available camera devices and use
getCameraCharacteristics(java.lang.String)
to check whether the camera device has a flash unit.
Note that even if a camera device has a flash unit, turning on the torch mode may fail
if the camera device or other camera resources needed to turn on the torch mode are in use.
If setTorchMode(java.lang.String, boolean)
is called to turn on or off the torch mode successfully,
CameraManager.TorchCallback.onTorchModeChanged(java.lang.String, boolean)
will be invoked.
However, even if turning on the torch mode is successful, the application does not have the
exclusive ownership of the flash unit or the camera device. The torch mode will be turned
off and becomes unavailable when the camera device that the flash unit belongs to becomes
unavailable or when other camera resources to keep the torch on become unavailable (
CameraManager.TorchCallback.onTorchModeUnavailable(java.lang.String)
will be invoked). Also,
other applications are free to call setTorchMode(java.lang.String, boolean)
to turn off the torch mode (
CameraManager.TorchCallback.onTorchModeChanged(java.lang.String, boolean)
will be invoked). If the latest
application that turned on the torch mode exits, the torch mode will be turned off.
cameraId
- The unique identifier of the camera device that the flash unit belongs to.enabled
- The desired state of the torch mode for the target camera device. Set to
true
to turn on the torch mode. Set to false
to turn off the
torch mode.CameraAccessException
- if it failed to access the flash unit.
CameraAccessException.CAMERA_IN_USE
will be thrown if the camera device
is in use. CameraAccessException.MAX_CAMERAS_IN_USE
will be thrown if
other camera resources needed to turn on the torch mode are in use.
CameraAccessException.CAMERA_DISCONNECTED
will be thrown if camera
service is not available.IllegalArgumentException
- if cameraId was null, cameraId doesn't match any currently
or previously available camera device, or the camera device doesn't have a
flash unit.public static void throwAsPublicException(Throwable t) throws CameraAccessException
CameraAccessException