1/*
2 * Copyright (C) 2018 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.5;
18
19import android.hardware.camera.common@1.0::Status;
20import android.hardware.camera.provider@2.4::ICameraProvider;
21
22/**
23 * Camera provider HAL
24 *
25 * Version 2.5 adds support for the notifyDeviceStateChange method
26 */
27interface ICameraProvider extends @2.4::ICameraProvider {
28
29    /**
30     * notifyDeviceStateChange:
31     *
32     * Notify the HAL provider that the state of the overall device has
33     * changed in some way that the HAL may want to know about.
34     *
35     * For example, a physical shutter may have been uncovered or covered,
36     * or a camera may have been covered or uncovered by an add-on keyboard
37     * or other accessory.
38     *
39     * The state is a bitfield of potential states, and some physical configurations
40     * could plausibly correspond to multiple different combinations of state bits.
41     * The HAL must ignore any state bits it is not actively using to determine
42     * the appropriate camera configuration.
43     *
44     * For example, on some devices the FOLDED state could mean that
45     * backward-facing cameras are covered by the fold, so FOLDED by itself implies
46     * BACK_COVERED. But other devices may support folding but not cover any cameras
47     * when folded, so for those FOLDED would not imply any of the other flags.
48     * Since these relationships are very device-specific, it is difficult to specify
49     * a comprehensive policy.  But as a recommendation, it is suggested that if a flag
50     * necessarily implies other flags are set as well, then those flags should be set.
51     * So even though FOLDED would be enough to infer BACK_COVERED on some devices, the
52     * BACK_COVERED flag should also be set for clarity.
53     *
54     * This method may be invoked by the HAL client at any time. It must not
55     * cause any active camera device sessions to be closed, but may dynamically
56     * change which physical camera a logical multi-camera is using for its
57     * active and future output.
58     *
59     * The method must be invoked by the HAL client at least once before the
60     * client calls ICameraDevice::open on any camera device interfaces listed
61     * by this provider, to establish the initial device state.
62     *
63     * @param newState
64     *    The new state of the device.
65     */
66    notifyDeviceStateChange(bitfield<DeviceState> newState);
67
68};
69