1/*
2 * Copyright (C) 2016 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
17package android.hardware.camera.device@3.2;
18
19import android.hardware.camera.common@1.0::types;
20import ICameraDeviceSession;
21import ICameraDeviceCallback;
22
23/**
24 * Camera device HAL, first modern version
25 *
26 * Supports the android.hardware.Camera API, and the android.hardware.camera2
27 * API at LIMITED or better hardware level.
28 *
29 */
30interface ICameraDevice {
31
32    /**
33     * Get camera device resource cost information.
34     *
35     * @return status Status code for the operation, one of:
36     *     OK:
37     *         On success
38     *     INTERNAL_ERROR:
39     *         An unexpected internal camera HAL error occurred, and the
40     *         resource cost is not available.
41     *     CAMERA_DISCONNECTED:
42     *         An external camera device has been disconnected, and is no longer
43     *         available. This camera device interface is now stale, and a new
44     *         instance must be acquired if the device is reconnected. All
45     *         subsequent calls on this interface must return
46     *         CAMERA_DISCONNECTED.
47     * @return resourceCost
48     *     The resources required to open this camera device, or unspecified
49     *     values if status is not OK.
50     */
51    getResourceCost() generates (Status status, CameraResourceCost resourceCost);
52
53    /**
54     * getCameraCharacteristics:
55     *
56     * Return the static camera information for this camera device. This
57     * information may not change between consecutive calls.
58     *
59     * When an external camera is disconnected, its camera id becomes
60     * invalid. Calling this method with this invalid camera id must result in
61     * ILLEGAL_ARGUMENT; this may happen even before the device status callback
62     * is invoked by the HAL.
63     *
64     * @return status Status code for the operation, one of:
65     *     OK:
66     *         On a successful open of the camera device.
67     *     INTERNAL_ERROR:
68     *         The camera device cannot be opened due to an internal
69     *         error.
70     *     CAMERA_DISCONNECTED:
71     *         An external camera device has been disconnected, and is no longer
72     *         available. This camera device interface is now stale, and a new
73     *         instance must be acquired if the device is reconnected. All
74     *         subsequent calls on this interface must return
75     *         CAMERA_DISCONNECTED.
76     *
77     * @return cameraCharacteristics
78     *     The static metadata for this camera device, or an empty metadata
79     *     structure if status is not OK.
80     *
81     */
82    getCameraCharacteristics() generates
83            (Status status, CameraMetadata cameraCharacteristics);
84
85    /**
86     * setTorchMode:
87     *
88     * Turn on or off the torch mode of the flash unit associated with this
89     * camera device. If the operation is successful, HAL must notify the
90     * framework torch state by invoking
91     * ICameraProviderCallback::torchModeStatusChange() with the new state.
92     *
93     * An active camera session has a higher priority accessing the flash
94     * unit. When there are any resource conflicts, such as when open() is
95     * called to fully activate a camera device, the provider must notify the
96     * framework through ICameraProviderCallback::torchModeStatusChange() that
97     * the torch mode has been turned off and the torch mode state has become
98     * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode
99     * become available again, the provider must notify the framework through
100     * ICameraProviderCallback::torchModeStatusChange() that the torch mode
101     * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to
102     * be called.
103     *
104     * When the client calls setTorchMode() to turn on the torch mode of a flash
105     * unit, if the HAL cannot keep multiple torch modes on simultaneously, the
106     * HAL must turn off the torch mode(s) that were turned on by previous
107     * setTorchMode() calls and notify the framework that the torch mode state
108     * of those flash unit(s) has become TORCH_MODE_STATUS_AVAILABLE_OFF.
109     *
110     * @param torchMode The new mode to set the device flash unit to.
111     *
112     * @return status Status code for the operation, one of:
113     *     OK:
114     *         On a successful change to the torch state
115     *     INTERNAL_ERROR:
116     *         The flash unit cannot be operated due to an unexpected internal
117     *         error.
118     *     ILLEGAL_ARGUMENT:
119     *         The camera ID is unknown.
120     *     CAMERA_IN_USE:
121     *         This camera device has been opened, so the torch cannot be
122     *         controlled until it is closed.
123     *     MAX_CAMERAS_IN_USE:
124     *         Due to other camera devices being open, or due to other
125     *         resource constraints, the torch cannot be controlled currently.
126     *     METHOD_NOT_SUPPORTED:
127     *         This provider does not support direct operation of flashlight
128     *         torch mode. The framework must open the camera device and turn
129     *         the torch on through the device interface.
130     *     OPERATION_NOT_SUPPORTED:
131     *         This camera device does not have a flash unit. This can
132     *         be returned if and only if android.flash.info.available is
133     *         false.
134     *     CAMERA_DISCONNECTED:
135     *         An external camera device has been disconnected, and is no longer
136     *         available. This camera device interface is now stale, and a new
137     *         instance must be acquired if the device is reconnected. All
138     *         subsequent calls on this interface must return
139     *         CAMERA_DISCONNECTED.
140     *
141     */
142    setTorchMode(TorchMode mode) generates (Status status);
143
144    /**
145     * open:
146     *
147     * Power on and initialize this camera device for active use, returning a
148     * session handle for active operations.
149     *
150     * @param callback Interface to invoke by the HAL for device asynchronous
151     *     events.
152     * @return status Status code for the operation, one of:
153     *     OK:
154     *         On a successful open of the camera device.
155     *     INTERNAL_ERROR:
156     *         The camera device cannot be opened due to an internal
157     *         error.
158     *     ILLEGAL_ARGUMENT:
159     *         The callbacks handle is invalid (for example, it is null).
160     *     CAMERA_IN_USE:
161     *         This camera device is already open.
162     *     MAX_CAMERAS_IN_USE:
163     *         The maximal number of camera devices that can be
164     *         opened concurrently were opened already.
165     *     CAMERA_DISCONNECTED:
166     *         This external camera device has been disconnected, and is no
167     *         longer available. This interface is now stale, and a new instance
168     *         must be acquired if the device is reconnected. All subsequent
169     *         calls on this interface must return CAMERA_DISCONNECTED.
170     * @return session The interface to the newly-opened camera session,
171     *     or null if status is not OK.
172     */
173    open(ICameraDeviceCallback callback) generates
174            (Status status, ICameraDeviceSession session);
175
176    /**
177     * dumpState:
178     *
179     * Print out debugging state for the camera device. This may be called by
180     * the framework when the camera service is asked for a debug dump, which
181     * happens when using the dumpsys tool, or when capturing a bugreport.
182     *
183     * The passed-in file descriptor can be used to write debugging text using
184     * dprintf() or write(). The text must be in ASCII encoding only.
185     *
186     * In case this camera device has been disconnected, the dump must not fail,
187     * but may simply print out 'Device disconnected' or equivalent.
188     *
189     * Performance requirements:
190     *
191     * This must be a non-blocking call. The HAL should return from this call
192     * in 1ms, must return from this call in 10ms. This call must avoid
193     * deadlocks, as it may be called at any point during camera operation.
194     * Any synchronization primitives used (such as mutex locks or semaphores)
195     * must be acquired with a timeout.
196     */
197    dumpState(handle fd);
198
199};
200