/*
 * 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.sensors@1.0;

interface ISensors {
    /**
     * Enumerate all available (static) sensors.
     */
    getSensorsList() generates (vec<SensorInfo> list);

    /**
     *  Place the module in a specific mode. The following modes are defined
     *
     *  SENSOR_HAL_NORMAL_MODE - Normal operation. Default state of the module.
     *
     *  SENSOR_HAL_DATA_INJECTION_MODE - Loopback mode.
     *    Data is injected for the supported sensors by the sensor service in
     *    this mode.
     *
     * @return OK on success
     *         BAD_VALUE if requested mode is not supported
     *         PERMISSION_DENIED if operation is not allowed
     */
    setOperationMode(OperationMode mode) generates (Result result);

    /* Activate/de-activate one sensor.
     *
     * sensorHandle is the handle of the sensor to change.
     * enabled set to true to enable, or false to disable the sensor.
     *
     * After sensor de-activation, existing sensor events that have not
     * been picked up by poll() should be abandoned immediately so that
     * subsequent activation will not get stale sensor events (events
     * that are generated prior to the latter activation).
     *
     * Returns OK on success, BAD_VALUE if sensorHandle is invalid.
     */
    activate(int32_t sensorHandle, bool enabled) generates (Result result);

    /**
     * Set the sampling period in nanoseconds for a given sensor.
     * If samplingPeriodNs > maxDelay it will be truncated to
     * maxDelay and if samplingPeriodNs < minDelay it will be
     * replaced by minDelay.
     *
     * Returns OK on success, BAD_VALUE if sensorHandle is invalid.
     */
    setDelay(int32_t sensorHandle, int64_t samplingPeriodNs)
        generates (Result result);

    /**
     * Generate a vector of sensor events containing at most "maxCount"
     * entries.
     *
     * Additionally a vector of SensorInfos is returned for any dynamic sensors
     * connected as notified by returned events of type DYNAMIC_SENSOR_META.
     *
     * This function should block if there is no sensor event
     * available when being called.
     *
     * Returns OK on success or BAD_VALUE if maxCount <= 0.
     */
    poll(int32_t maxCount)
        generates (
                Result result,
                vec<Event> data,
                vec<SensorInfo> dynamicSensorsAdded);

    /*
     * Sets a sensor’s parameters, including sampling frequency and maximum
     * report latency. This function can be called while the sensor is
     * activated, in which case it must not cause any sensor measurements to
     * be lost: transitioning from one sampling rate to the other cannot cause
     * lost events, nor can transitioning from a high maximum report latency to
     * a low maximum report latency.
     * See the Batching sensor results page for details:
     * http://source.android.com/devices/sensors/batching.html
     *
     * Returns OK on success, BAD_VALUE if any parameters are invalid.
     */
    batch(int32_t sensorHandle,
          int32_t flags,
          int64_t samplingPeriodNs,
          int64_t maxReportLatencyNs) generates (Result result);

    /*
     * Flush adds a FLUSH_COMPLETE metadata event to the end of the "batch mode"
     * FIFO for the specified sensor and flushes the FIFO.
     * If the FIFO is empty or if the sensor doesn't support batching
     * (FIFO size zero), it should return SUCCESS along with a trivial
     * FLUSH_COMPLETE event added to the event stream.
     * This applies to all sensors other than one-shot sensors.
     * If the sensor is a one-shot sensor, flush must return BAD_VALUE and not
     * generate any flush complete metadata.
     * If the sensor is not active at the time flush() is called, flush() should
     * return BAD_VALUE.
     * Returns OK on success and BAD_VALUE if sensorHandle is invalid.
     */
    flush(int32_t sensorHandle) generates (Result result);

    /*
     * Inject a single sensor sample to this device.
     * data points to the sensor event to be injected
     * Returns OK on success
     *         PERMISSION_DENIED if operation is not allowed
     *         INVALID_OPERATION, if this functionality is unsupported
     *         BAD_VALUE if sensor event cannot be injected
     */
    injectSensorData(Event event) generates (Result result);
};