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.provider@2.4;
18
19import ICameraProviderCallback;
20import android.hardware.camera.common@1.0::types;
21import android.hardware.camera.device@1.0::ICameraDevice;
22import android.hardware.camera.device@3.2::ICameraDevice;
23
24/**
25 * Camera provider HAL, which enumerates the available individual camera devices
26 * known to the provider, and provides updates about changes to device status,
27 * such as connection, disconnection, or torch mode enable/disable.
28 *
29 * The provider is responsible for generating a list of camera device service
30 * names that can then be opened via the hardware service manager.
31 *
32 * Multiple camera provider HALs may be present in a single system.
33 * For discovery, the service names, and process names, must be of the form
34 * "android.hardware.camera.provider@<major>.<minor>/<type>/<instance>"
35 * where
36 *   - <major>/<minor> is the provider HAL HIDL version,
37 *   - <type> is the type of devices this provider knows about, such as
38 *     "internal", "legacy", "external", "remote" etc. The camera framework
39 *     must not differentiate or chage its behavior based on the specific type.
40 *   - <instance> is a non-negative integer starting from 0 to disambiguate
41 *     between multiple HALs of the same type.
42 *
43 * The "legacy" type is only used for passthrough legacy HAL mode, and must
44 * not be used by a standalone binderized HAL.
45 *
46 * The device instance names enumerated by the provider in getCameraIdList() or
47 * ICameraProviderCallback::cameraDeviceStatusChange() must be of the form
48 * "device@<major>.<minor>/<type>/<id>" where
49 * <major>/<minor> is the HIDL version of the interface. <id> is either a small
50 * incrementing integer for "internal" device types, with 0 being the main
51 * back-facing camera and 1 being the main front-facing camera, if they exist.
52 * Or, for external devices, a unique serial number (if possible) that can be
53 * used to identify the device reliably when it is disconnected and reconnected.
54 *
55 * Multiple providers must not enumerate the same device ID.
56 */
57interface ICameraProvider {
58
59    /**
60     * setCallback:
61     *
62     * Provide a callback interface to the HAL provider to inform framework of
63     * asynchronous camera events. The framework must call this function once
64     * during camera service startup, before any other calls to the provider
65     * (note that in case the camera service restarts, this method must be
66     * invoked again during its startup).
67     *
68     * @param callback
69     *     A non-null callback interface to invoke when camera events occur.
70     * @return status
71     *     Status code for the operation, one of:
72     *     OK:
73     *         On success
74     *     INTERNAL_ERROR:
75     *         An unexpected internal error occurred while setting the callbacks
76     *     ILLEGAL_ARGUMENT:
77     *         The callback argument is invalid (for example, null).
78     *
79     */
80    setCallback(ICameraProviderCallback callback) generates (Status status);
81
82    /**
83     * getVendorTags:
84     *
85     * Retrieve all vendor tags supported by devices discoverable through this
86     * provider. The tags are grouped into sections.
87     *
88     * @return status
89     *     Status code for the operation, one of:
90     *     OK:
91     *         On success
92     *     INTERNAL_ERROR:
93     *         An unexpected internal error occurred while setting the callbacks
94     * @return sections
95     *     The supported vendor tag sections; empty if there are no supported
96     *     vendor tags, or status is not OK.
97     *
98     */
99    getVendorTags() generates (Status status, vec<VendorTagSection> sections);
100
101    /**
102     * getCameraIdList:
103     *
104     * Returns the list of internal camera device interfaces known to this
105     * camera provider. These devices can then be accessed via the hardware
106     * service manager.
107     *
108     * External camera devices (camera facing EXTERNAL) must be reported through
109     * the device status change callback, not in this list. Only devices with
110     * facing BACK or FRONT must be listed here.
111     *
112     * @return status Status code for the operation, one of:
113     *     OK:
114     *         On a succesful generation of camera ID list
115     *     INTERNAL_ERROR:
116     *         A camera ID list cannot be created. This may be due to
117     *         a failure to initialize the camera subsystem, for example.
118     * @return cameraDeviceNames The vector of internal camera device
119     *     names known to this provider.
120     */
121    getCameraIdList()
122            generates (Status status, vec<string> cameraDeviceNames);
123
124    /**
125     * isSetTorchModeSupported:
126     *
127     * Returns if the camera devices known to this camera provider support
128     * setTorchMode API or not. If the provider does not support setTorchMode
129     * API, calling to setTorchMode will return METHOD_NOT_SUPPORTED.
130     *
131     * Note that not every camera device has a flash unit, so even this API
132     * returns true, setTorchMode call might still fail due to the camera device
133     * does not have a flash unit. In such case, the returned status will be
134     * OPERATION_NOT_SUPPORTED.
135     *
136     * @return status Status code for the operation, one of:
137     *     OK:
138     *         On a succesful call
139     *     INTERNAL_ERROR:
140     *         Torch API support cannot be queried. This may be due to
141     *         a failure to initialize the camera subsystem, for example.
142     * @return support Whether the camera devices known to this provider
143     *     supports setTorchMode API or not. Devices launched with SDK
144     *     level 29 or higher must return true.
145     *
146     */
147    isSetTorchModeSupported() generates (Status status, bool support);
148
149    /**
150     * getCameraDeviceInterface_VN_x:
151     *
152     * Return a android.hardware.camera.device@N.x/ICameraDevice interface for
153     * the requested device name. This does not power on the camera device, but
154     * simply acquires the interface for querying the device static information,
155     * or to additionally open the device for active use.
156     *
157     * A separate method is required for each major revision of the camera device
158     * HAL interface, since they are not compatible with each other.
159     *
160     * Valid device names for this provider can be obtained via either
161     * getCameraIdList(), or via availability callbacks from
162     * ICameraProviderCallback::cameraDeviceStatusChange().
163     *
164     * The returned interface must be of the highest defined minor version for
165     * the major version; it's the responsibility of the HAL client to ensure
166     * they do not use methods/etc that are not valid for the actual minor
167     * version of the device.
168     *
169     * @param cameraDeviceName the name of the device to get an interface to.
170     * @return status Status code for the operation, one of:
171     *     OK:
172     *         On a succesful generation of camera ID list
173     *     ILLEGAL_ARGUMENT:
174     *         This device name is unknown, or has been disconnected
175     *     OPERATION_NOT_SUPPORTED:
176     *         The specified device does not support this major version of the
177     *         HAL interface.
178     *     INTERNAL_ERROR:
179     *         A camera interface cannot be returned due to an unexpected
180     *         internal error.
181     * @return device The inteface to this camera device, or null in case of
182     *     error.
183     */
184    getCameraDeviceInterface_V1_x(string cameraDeviceName) generates
185            (Status status,
186             android.hardware.camera.device@1.0::ICameraDevice device);
187    getCameraDeviceInterface_V3_x(string cameraDeviceName) generates
188            (Status status,
189             android.hardware.camera.device@3.2::ICameraDevice device);
190
191};
192