/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.camera.provider@2.5;

import android.hardware.camera.common@1.0::Status;
import android.hardware.camera.provider@2.4::ICameraProvider;

/**
 * Camera provider HAL
 *
 * Version 2.5 adds support for the notifyDeviceStateChange method
 */
interface ICameraProvider extends @2.4::ICameraProvider {

    /**
     * notifyDeviceStateChange:
     *
     * Notify the HAL provider that the state of the overall device has
     * changed in some way that the HAL may want to know about.
     *
     * For example, a physical shutter may have been uncovered or covered,
     * or a camera may have been covered or uncovered by an add-on keyboard
     * or other accessory.
     *
     * The state is a bitfield of potential states, and some physical configurations
     * could plausibly correspond to multiple different combinations of state bits.
     * The HAL must ignore any state bits it is not actively using to determine
     * the appropriate camera configuration.
     *
     * For example, on some devices the FOLDED state could mean that
     * backward-facing cameras are covered by the fold, so FOLDED by itself implies
     * BACK_COVERED. But other devices may support folding but not cover any cameras
     * when folded, so for those FOLDED would not imply any of the other flags.
     * Since these relationships are very device-specific, it is difficult to specify
     * a comprehensive policy.  But as a recommendation, it is suggested that if a flag
     * necessarily implies other flags are set as well, then those flags should be set.
     * So even though FOLDED would be enough to infer BACK_COVERED on some devices, the
     * BACK_COVERED flag should also be set for clarity.
     *
     * This method may be invoked by the HAL client at any time. It must not
     * cause any active camera device sessions to be closed, but may dynamically
     * change which physical camera a logical multi-camera is using for its
     * active and future output.
     *
     * The method must be invoked by the HAL client at least once before the
     * client calls ICameraDevice::open on any camera device interfaces listed
     * by this provider, to establish the initial device state.
     *
     * @param newState
     *    The new state of the device.
     */
    notifyDeviceStateChange(bitfield<DeviceState> newState);

};