am 1108b845: Merge "Sensor documentation fixes." into lmp-docs

     * A sensor of this type triggers an event each time a step is taken by the user. The only

     * allowed value to return is 1.0 and an event is generated for each step. Like with any other

     * event, the timestamp indicates when the event (here the step) occurred, this corresponds to

     * when the foot hit the ground, generating a high variation in acceleration.

     * when the foot hit the ground, generating a high variation in acceleration. This sensor is

     * only for detecting every individual step as soon as it is taken, for example to perform dead

     * reckoning. If you only need aggregate number of steps taken over a period of time, register

     * for {@link #TYPE_STEP_COUNTER} instead. It is defined as a

     * {@link Sensor#REPORTING_MODE_SPECIAL_TRIGGER} sensor.

     * <p>

     * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details.

     */

     * while activated. The value is returned as a float (with the fractional part set to zero) and

     * is reset to zero only on a system reboot. The timestamp of the event is set to the time when

     * the last step for that event was taken. This sensor is implemented in hardware and is

     * expected to be low power.

     * expected to be low power. If you want to continuously track the number of steps over a long

     * period of time, do NOT unregister for this sensor, so that it keeps counting steps in the

     * background even when the AP is in suspend mode and report the aggregate count when the AP

     * is awake. Application needs to stay registered for this sensor because step counter does not

     * count steps if it is not activated. This sensor is ideal for fitness tracking applications.

     * It is defined as an {@link Sensor#REPORTING_MODE_ON_CHANGE} sensor.

     * <p>

     * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details.

     */

    }

    /**

     * Returns whether this sensor is a wake-up sensor.

     * Returns true if the sensor is a wake-up sensor.

     * <p>

     * Wake up sensors wake the application processor up when they have events to deliver. When a

     * wake up sensor is registered to without batching enabled, each event will wake the

     * application processor up.

     * <p>

     * When a wake up sensor is registered to with batching enabled, it

     * wakes the application processor up when maxReportingLatency has elapsed or when the hardware

     * FIFO storing the events from wake up sensors is getting full.

     * <p>

     * Non-wake up sensors never wake the application processor up. Their events are only reported

     * when the application processor is awake, for example because the application holds a wake

     * lock, or another source woke the application processor up.

     * <b>Application Processor Power modes</b> <p>

     * Application Processor(AP), is the processor on which applications run.  When no wake lock is held

     * and the user is not interacting with the device, this processor can enter a “Suspend” mode,

     * reducing the power consumption by 10 times or more.

     * </p>

     * <p>

     * When a non-wake up sensor is registered to without batching enabled, the measurements made

     * while the application processor is asleep might be lost and never returned.

     * <b>Non-wake-up sensors</b> <p>

     * Non-wake-up sensors are sensors that do not wake the AP out of suspend to report data. While

     * the AP is in suspend mode, the sensors continue to function and generate events, which are

     * put in a hardware FIFO. The events in the FIFO are delivered to the application when the AP

     * wakes up. If the FIFO was too small to store all events generated while the AP was in

     * suspend mode, the older events are lost: the oldest data is dropped to accommodate the newer

     * data. In the extreme case where the FIFO is non-existent {@code maxFifoEventCount() == 0},

     * all events generated while the AP was in suspend mode are lost. Applications using

     * non-wake-up sensors should usually:

     * <ul>

     * <li>Either unregister from the sensors when they do not need them, usually in the activity’s

     * {@code onPause} method. This is the most common case.

     * <li>Or realize that the sensors are consuming some power while the AP is in suspend mode and

     * that even then, some events might be lost.

     * </ul>

     * </p>

     * <p>

     * When a non-wake up sensor is registered to with batching enabled, the measurements made while

     * the application processor is asleep are stored in the hardware FIFO for non-wake up sensors.

     * When this FIFO gets full, new events start overwriting older events. When the application

     * then wakes up, the latest events are returned, and some old events might be lost. The number

     * of events actually returned depends on the hardware FIFO size, as well as on what other

     * sensors are activated. If losing sensor events is not acceptable during batching, you must

     * use the wake-up version of the sensor.

     * @return true if this is a wake up sensor, false otherwise.

     * <b>Wake-up sensors</b> <p>

     * In opposition to non-wake-up sensors, wake-up sensors ensure that their data is delivered

     * independently of the state of the AP. While the AP is awake, the wake-up sensors behave

     * like non-wake-up-sensors. When the AP is asleep, wake-up sensors wake up the AP to deliver

     * events. That is, the AP will wake up and the sensor will deliver the events before the

     * maximum reporting latency is elapsed or the hardware FIFO gets full. See {@link

     * SensorManager#registerListener(SensorEventListener, Sensor, int, int)} for more details.

     * </p>

     *

     * @return <code>true</code> if this is a wake-up sensor, <code>false</code> otherwise.

     */

    public boolean isWakeUpSensor() {

        return (mFlags & SENSOR_FLAG_WAKE_UP_SENSOR) != 0;

 */

public interface SensorEventListener2 extends SensorEventListener {

    /**

     * Called after flush() is completed. All the events in the batch at the point when

     * the flush was called have been delivered to the applications registered for those

     * sensor events. Flush Complete Events are sent ONLY to the application that has

     * explicitly called flush(). If the hardware FIFO is flushed due to some other

     * application calling flush(), flush complete event is not delivered to this application.

     * Called after flush() is completed. All the events in the batch at the point when the flush

     * was called have been delivered to the applications registered for those sensor events. In

     * {@link android.os.Build.VERSION_CODES#KITKAT}, applications may receive flush complete events

     * even if some other application has called flush() on the same sensor. Starting with

     * {@link android.os.Build.VERSION_CODES#LOLLIPOP}, flush Complete events are sent ONLY to the

     * application that has explicitly called flush(). If the hardware FIFO is flushed due to some

     * other application calling flush(), flush complete event is not delivered to this application.

     * <p>

     *

     * @param sensor The {@link android.hardware.Sensor Sensor} on which flush was called.

     *

     * @see android.hardware.SensorManager#flush(SensorEventListener)

     */

    public void onFlushCompleted(Sensor sensor);