/*
 * Copyright (C) 2016 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.device@1.0;

import android.hardware.camera.common@1.0::types;
import ICameraDeviceCallback;
import ICameraDevicePreviewCallback;

/**
 * Camera device HAL, legacy version
 *
 * DEPRECATED. New devices are strongly recommended to use Camera HAL v3.2 or
 * newer.
 *
 * Supports the android.hardware.Camera API, and the android.hardware.camera2
 * API in LEGACY mode only.
 *
 * Will be removed in the Android P release.
 */
interface ICameraDevice {

    /**
     * Get camera device resource cost information.
     *
     * This method may be called at any time, including before open()
     *
     * @return status Status code for the operation, one of:
     *     OK:
     *         On success.
     *     INTERNAL_ERROR:
     *         An unexpected internal camera HAL error occurred, and the
     *         resource cost is not available.
     *     CAMERA_DISCONNECTED:
     *         An external camera device has been disconnected, and is no longer
     *         available. This camera device interface is now stale, and a new
     *         instance must be acquired if the device is reconnected. All
     *         subsequent calls on this interface must return
     *         CAMERA_DISCONNECTED.
     * @return resourceCost
     *     The resources required to open this camera device, or unspecified
     *     values if status is not OK.
     */
    getResourceCost() generates (Status status, CameraResourceCost resourceCost);

    /**
     * Get basic camera information.
     *
     * This method may be called at any time, including before open()
     *
     * @return status Status code for the operation, one of:
     *     OK:
     *         On success.
     *     INTERNAL_ERROR:
     *         An unexpected internal camera HAL error occurred, and the
     *         camera information is not available.
     *     CAMERA_DISCONNECTED:
     *         An external camera device has been disconnected, and is no longer
     *         available. This camera device interface is now stale, and a new
     *         instance must be acquired if the device is reconnected. All
     *         subsequent calls on this interface must return
     *         CAMERA_DISCONNECTED.
     * @return info Basic information about this camera device, or unspecified
     *     values if status is not OK.
     */
    getCameraInfo() generates (Status status, CameraInfo info);

    /**
     * setTorchMode:
     *
     * Turn on or off the torch mode of the flash unit associated with a given
     * camera ID. If the operation is successful, HAL must notify the framework
     * torch state by invoking
     * ICameraProviderCallback::torchModeStatusChange() with the new state.
     *
     * The camera device has a higher priority accessing the flash unit. When
     * there are any resource conflicts, such as when open() is called to fully
     * activate a camera device, the provider must notify the framework through
     * ICameraProviderCallback::torchModeStatusChange() that the torch mode has
     * been turned off and the torch mode state has become
     * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode
     * become available again, the provider must notify the framework through
     * ICameraProviderCallback::torchModeStatusChange() that the torch mode
     * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to
     * be called.
     *
     * When the framework calls setTorchMode() to turn on the torch mode of a
     * flash unit, if HAL cannot keep multiple torch modes on simultaneously,
     * HAL must turn off the torch mode that was turned on by
     * a previous setTorchMode() call and notify the framework that the torch
     * mode state of that flash unit has become TORCH_MODE_STATUS_AVAILABLE_OFF.
     *
     * @param torchMode The new mode to set the device flash unit to.
     *
     * @return status Status code for the operation, one of:
     *     OK:
     *         On a successful change to the torch state.
     *     INTERNAL_ERROR:
     *         The flash unit cannot be operated due to an unexpected internal
     *         error.
     *     ILLEGAL_ARGUMENT:
     *         The camera ID is unknown.
     *     CAMERA_IN_USE:
     *         This camera device has been opened, so the torch cannot be
     *         controlled until it is closed.
     *     MAX_CAMERAS_IN_USE:
     *         Due to other camera devices being open, or due to other
     *         resource constraints, the torch cannot be controlled currently.
     *     METHOD_NOT_SUPPORTED:
     *         This provider does not support direct operation of flashlight
     *         torch mode. The framework must open the camera device and turn
     *         the torch on through the device interface.
     *     OPERATION_NOT_SUPPORTED:
     *         This camera device does not have a flash unit. This must
     *         be returned if and only if parameter key flash-mode-values is not present.
     *     CAMERA_DISCONNECTED:
     *         An external camera device has been disconnected, and is no longer
     *         available. This camera device interface is now stale, and a new
     *         instance must be acquired if the device is reconnected. All
     *         subsequent calls on this interface must return
     *         CAMERA_DISCONNECTED.
     *
     */
    setTorchMode(TorchMode mode) generates (Status status);

    /**
     * Dump state of the camera hardware.
     *
     * This must be callable at any time, whether the device is open or not.
     *
     * @param fd A native handle with one valid file descriptor. The descriptor
     *     must be able to be used with dprintf() or equivalent to dump the
     *     state of this camera device into the camera service dumpsys output.
     *
     * @return status The status code for this operation.
     */
    dumpState(handle fd) generates (Status status);

    /**
     * Open the camera device for active use.
     *
     * All methods besides getResourceCost(), getCameraInfo(), setTorchMode(),
     * and dump() must not be called unless open() has been called successfully,
     * and close() has not yet been called.
     *
     * @param callback Interface to invoke by the HAL for device callbacks.
     * @return status Status code for the operation, one of:
     *     OK:
     *         On a successful open of the camera device.
     *     INTERNAL_ERROR:
     *         The camera device cannot be opened due to an internal
     *         error.
     *     ILLEGAL_ARGUMENT:
     *         The callback handle is invalid (for example, it is null).
     *     CAMERA_IN_USE:
     *         This camera device is already open.
     *     MAX_CAMERAS_IN_USE:
     *         The maximal number of camera devices that can be
     *         opened concurrently were opened already.
     *     CAMERA_DISCONNECTED:
     *         This external camera device has been disconnected, and is no
     *         longer available. This interface is now stale, and a new instance
     *         must be acquired if the device is reconnected. All subsequent
     *         calls on this interface must return CAMERA_DISCONNECTED.
     */
    open(ICameraDeviceCallback callback) generates (Status status);


    /*****
     * All methods below this point must only be called between a successful
     * open() call and a close() call.
     */

    /** Set the callback interface through which preview frames are sent */
    setPreviewWindow(ICameraDevicePreviewCallback window)
            generates (Status status);

    /**
     * Enable a message, or set of messages.
     *
     * @param msgType The bitfield of messages to enable.
     */
    enableMsgType(FrameCallbackFlags msgType);

    /**
     * Disable a message, or a set of messages.
     *
     * Once received a call to disableMsgType(CAMERA_MSG_VIDEO_FRAME), camera
     * HAL must not rely on its client to call releaseRecordingFrame() to
     * release video recording frames sent out by the cameral HAL before and
     * after the disableMsgType(CAMERA_MSG_VIDEO_FRAME) call. Camera HAL
     * clients must not modify/access any video recording frame after calling
     * disableMsgType(CAMERA_MSG_VIDEO_FRAME).
     *
     * @param msgType The bitfield of messages to disable.
     */
    disableMsgType(FrameCallbackFlags msgType);

    /**
     * Query whether a message, or a set of messages, is enabled. Note that
     * this is operates as an AND, if any of the messages queried are off, this
     * must return false.
     *
     * @param msgType The bitfield of messages to query.
     * @return enabled Whether all the specified flags are enabled.
     */
    msgTypeEnabled(FrameCallbackFlags msgType) generates (bool enabled);

    /**
     * Start preview mode.
     *
     * @return status The status code for this operation.
     */
    startPreview() generates (Status status);

    /**
     * Stop a previously started preview.
     */
    stopPreview();

    /**
     * Returns true if preview is enabled.
     *
     * @return enabled Whether preview is currently enabled.
     */
    previewEnabled() generates (bool enabled);

    /**
     * Request the camera HAL to store meta data or real YUV data in the video
     * buffers sent out via CAMERA_MSG_VIDEO_FRAME for a recording session. If
     * it is not called, the default camera HAL behavior is to store real YUV
     * data in the video buffers.
     *
     * This method must be called before startRecording() in order to be
     * effective.
     *
     * If meta data is stored in the video buffers, it is up to the receiver of
     * the video buffers to interpret the contents and to find the actual frame
     * data with the help of the meta data in the buffer. How this is done is
     * outside of the scope of this method.
     *
     * Some camera HALs may not support storing meta data in the video buffers,
     * but all camera HALs must support storing real YUV data in the video
     * buffers. If the camera HAL does not support storing the meta data in the
     * video buffers when it is requested to do do, INVALID_OPERATION must be
     * returned. It is very useful for the camera HAL to pass meta data rather
     * than the actual frame data directly to the video encoder, since the
     * amount of the uncompressed frame data can be very large if video size is
     * large.
     *
     * @param enable Set to true to instruct the camera HAL to store meta data
     *     in the video buffers; false to instruct the camera HAL to store real
     *     YUV data in the video buffers.
     *
     * @return status OK on success.
     */
    storeMetaDataInBuffers(bool enable) generates (Status status);

    /**
     * Start record mode.
     *
     * When a record image is available, a CAMERA_MSG_VIDEO_FRAME message is
     * sent with the corresponding frame. Every record frame must be released by
     * a camera HAL client via releaseRecordingFrame() before the client calls
     * disableMsgType(CAMERA_MSG_VIDEO_FRAME). After the client calls
     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
     * responsibility to manage the life-cycle of the video recording frames,
     * and the client must not modify/access any video recording frames.
     *
     * @return status The status code for the operation.
     */
    startRecording() generates (Status status);

    /**
     * Stop a previously started recording.
     */
    stopRecording();

    /**
     * Returns true if recording is enabled.
     *
     * @return enabled True if recording is currently active.
     */
    recordingEnabled() generates (bool enabled);

    /**
     * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME in
     * dataCallbackTimestamp.
     *
     * It is camera HAL client's responsibility to release video recording
     * frames sent out by the camera HAL before the camera HAL receives a call
     * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to
     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
     * responsibility to manage the life-cycle of the video recording frames.
     *
     * @param memId The memory buffer to release a recording frame from.
     * @param bufferIndex The specific buffer index to return to the HAL.
     */
    releaseRecordingFrame(MemoryId memId, uint32_t bufferIndex);

    /**
     * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME in
     * handleCallbackTimestamp.
     *
     * It is camera HAL client's responsibility to release video recording
     * frames sent out by the camera HAL before the camera HAL receives a call
     * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to
     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
     * responsibility to manage the life-cycle of the video recording frames.
     *
     * @param memId The memory buffer to release a recording frame from.
     * @param bufferIndex The specific buffer index to return to the HAL.
     * @param frame The handle for a released video frame
     */
    releaseRecordingFrameHandle(MemoryId memId, uint32_t bufferIndex, handle frame);

    /**
     * Release a batch of record frames previously returned by CAMERA_MSG_VIDEO_FRAME
     * in handleCallbackTimestampBatch.
     *
     * It is camera HAL client's responsibility to release video recording
     * frames sent out by the camera HAL before the camera HAL receives a call
     * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to
     * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's
     * responsibility to manage the life-cycle of the video recording frames.
     *
     * @param batch A batch of recording frames to be released by camera HAL.
     */
    releaseRecordingFrameHandleBatch(vec<VideoFrameMessage> batch);

    /**
     * Start auto focus.
     *
     * The notification callback routine is called with
     * CAMERA_MSG_FOCUS once when focusing is complete. autoFocus() can be
     * called again after that if another auto focus is needed.
     *
     * @return status The status code for this operation.
     */
    autoFocus() generates (Status status);

    /**
     * Cancels auto-focus function.
     *
     * If the auto-focus is still in progress, this function must cancel
     * it. Whether the auto-focus is in progress or not, this function must
     * return the focus position to the default. If the camera does not support
     * auto-focus, this is a no-op.
     *
     * @return status The status code for this operation.
     */
    cancelAutoFocus() generates (Status status);

    /**
     * Take a picture.
     *
     * @return status The status code for this operation.
     */
    takePicture() generates (Status status);

    /**
     * Cancel a picture that was started with takePicture. Calling this method
     * when no picture is being taken is a no-op.
     *
     * @return status The status code for this operation.
     */
    cancelPicture() generates (Status status);

    /**
     * Set the camera parameters.
     *
     * @param params The parameter string, consisting of
     *    '<key1>=<value1>; ...;<keyN>=<valueN>'.
     * @return status The status code for this operation:
     *     OK: Parameter update was successful
     *     ILLEGAL_ARGUMENT: At least one parameter was invalid or not supported
     *
     */
    setParameters(string params) generates (Status status);

    /**
     * Retrieve the camera parameters.
     */
    getParameters() generates (string parms);

    /**
     * Send command to camera driver.
     * The meaning of the arguments is defined by the value of cmd, documented
     * in the CommandType definition.
     *
     * @param cmd The command to invoke.
     * @param arg1 The first argument for the command, if needed.
     * @param arg2 The second argument for the command, if needed.
     *
     * @return status The status code for this operation.
     */
    sendCommand(CommandType cmd, int32_t arg1, int32_t arg2)
            generates (Status status);

    /**
     * Release the hardware resources owned by this object, shutting down the
     * camera device.
     */
    close();

};