1/*
2 * Copyright (C) 2010 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
17/**
18 * @addtogroup Sensor
19 * @{
20 */
21
22/**
23 * @file sensor.h
24 */
25
26#ifndef ANDROID_SENSOR_H
27#define ANDROID_SENSOR_H
28
29/******************************************************************
30 *
31 * IMPORTANT NOTICE:
32 *
33 *   This file is part of Android's set of stable system headers
34 *   exposed by the Android NDK (Native Development Kit).
35 *
36 *   Third-party source AND binary code relies on the definitions
37 *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
38 *
39 *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
40 *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
41 *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
42 *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
43 */
44
45/**
46 * Structures and functions to receive and process sensor events in
47 * native code.
48 *
49 */
50
51#include <android/looper.h>
52
53#include <stdbool.h>
54#include <sys/types.h>
55#include <math.h>
56#include <stdint.h>
57
58#ifdef __cplusplus
59extern "C" {
60#endif
61
62typedef struct AHardwareBuffer AHardwareBuffer;
63
64#define ASENSOR_RESOLUTION_INVALID     (nanf(""))
65#define ASENSOR_FIFO_COUNT_INVALID     (-1)
66#define ASENSOR_DELAY_INVALID          INT32_MIN
67
68/* (Keep in sync with hardware/sensors-base.h and Sensor.java.) */
69
70/**
71 * Sensor types.
72 *
73 * See
74 * [android.hardware.SensorEvent#values](https://developer.android.com/reference/android/hardware/SensorEvent.html#values)
75 * for detailed explanations of the data returned for each of these types.
76 */
77enum {
78    /**
79     * Invalid sensor type. Returned by {@link ASensor_getType} as error value.
80     */
81    ASENSOR_TYPE_INVALID = -1,
82    /**
83     * {@link ASENSOR_TYPE_ACCELEROMETER}
84     * reporting-mode: continuous
85     *
86     *  All values are in SI units (m/s^2) and measure the acceleration of the
87     *  device minus the force of gravity.
88     */
89    ASENSOR_TYPE_ACCELEROMETER       = 1,
90    /**
91     * {@link ASENSOR_TYPE_MAGNETIC_FIELD}
92     * reporting-mode: continuous
93     *
94     *  All values are in micro-Tesla (uT) and measure the geomagnetic
95     *  field in the X, Y and Z axis.
96     */
97    ASENSOR_TYPE_MAGNETIC_FIELD      = 2,
98    /**
99     * {@link ASENSOR_TYPE_GYROSCOPE}
100     * reporting-mode: continuous
101     *
102     *  All values are in radians/second and measure the rate of rotation
103     *  around the X, Y and Z axis.
104     */
105    ASENSOR_TYPE_GYROSCOPE           = 4,
106    /**
107     * {@link ASENSOR_TYPE_LIGHT}
108     * reporting-mode: on-change
109     *
110     * The light sensor value is returned in SI lux units.
111     */
112    ASENSOR_TYPE_LIGHT               = 5,
113    /**
114     * {@link ASENSOR_TYPE_PRESSURE}
115     *
116     * The pressure sensor value is returned in hPa (millibar).
117     */
118    ASENSOR_TYPE_PRESSURE            = 6,
119    /**
120     * {@link ASENSOR_TYPE_PROXIMITY}
121     * reporting-mode: on-change
122     *
123     * The proximity sensor which turns the screen off and back on during calls is the
124     * wake-up proximity sensor. Implement wake-up proximity sensor before implementing
125     * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag
126     * SENSOR_FLAG_WAKE_UP.
127     * The value corresponds to the distance to the nearest object in centimeters.
128     */
129    ASENSOR_TYPE_PROXIMITY           = 8,
130    /**
131     * {@link ASENSOR_TYPE_GRAVITY}
132     *
133     * All values are in SI units (m/s^2) and measure the direction and
134     * magnitude of gravity. When the device is at rest, the output of
135     * the gravity sensor should be identical to that of the accelerometer.
136     */
137    ASENSOR_TYPE_GRAVITY             = 9,
138    /**
139     * {@link ASENSOR_TYPE_LINEAR_ACCELERATION}
140     * reporting-mode: continuous
141     *
142     *  All values are in SI units (m/s^2) and measure the acceleration of the
143     *  device not including the force of gravity.
144     */
145    ASENSOR_TYPE_LINEAR_ACCELERATION = 10,
146    /**
147     * {@link ASENSOR_TYPE_ROTATION_VECTOR}
148     */
149    ASENSOR_TYPE_ROTATION_VECTOR     = 11,
150    /**
151     * {@link ASENSOR_TYPE_RELATIVE_HUMIDITY}
152     *
153     * The relative humidity sensor value is returned in percent.
154     */
155    ASENSOR_TYPE_RELATIVE_HUMIDITY   = 12,
156    /**
157     * {@link ASENSOR_TYPE_AMBIENT_TEMPERATURE}
158     *
159     * The ambient temperature sensor value is returned in Celcius.
160     */
161    ASENSOR_TYPE_AMBIENT_TEMPERATURE = 13,
162    /**
163     * {@link ASENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED}
164     */
165    ASENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14,
166    /**
167     * {@link ASENSOR_TYPE_GAME_ROTATION_VECTOR}
168     */
169    ASENSOR_TYPE_GAME_ROTATION_VECTOR = 15,
170    /**
171     * {@link ASENSOR_TYPE_GYROSCOPE_UNCALIBRATED}
172     */
173    ASENSOR_TYPE_GYROSCOPE_UNCALIBRATED = 16,
174    /**
175     * {@link ASENSOR_TYPE_SIGNIFICANT_MOTION}
176     */
177    ASENSOR_TYPE_SIGNIFICANT_MOTION = 17,
178    /**
179     * {@link ASENSOR_TYPE_STEP_DETECTOR}
180     */
181    ASENSOR_TYPE_STEP_DETECTOR = 18,
182    /**
183     * {@link ASENSOR_TYPE_STEP_COUNTER}
184     */
185    ASENSOR_TYPE_STEP_COUNTER = 19,
186    /**
187     * {@link ASENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR}
188     */
189    ASENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20,
190    /**
191     * {@link ASENSOR_TYPE_HEART_RATE}
192     */
193    ASENSOR_TYPE_HEART_RATE = 21,
194    /**
195     * {@link ASENSOR_TYPE_POSE_6DOF}
196     */
197    ASENSOR_TYPE_POSE_6DOF = 28,
198    /**
199     * {@link ASENSOR_TYPE_STATIONARY_DETECT}
200     */
201    ASENSOR_TYPE_STATIONARY_DETECT = 29,
202    /**
203     * {@link ASENSOR_TYPE_MOTION_DETECT}
204     */
205    ASENSOR_TYPE_MOTION_DETECT = 30,
206    /**
207     * {@link ASENSOR_TYPE_HEART_BEAT}
208     */
209    ASENSOR_TYPE_HEART_BEAT = 31,
210    /**
211     * {@link ASENSOR_TYPE_LOW_LATENCY_OFFBODY_DETECT}
212     */
213    ASENSOR_TYPE_LOW_LATENCY_OFFBODY_DETECT = 34,
214    /**
215     * {@link ASENSOR_TYPE_ACCELEROMETER_UNCALIBRATED}
216     */
217    ASENSOR_TYPE_ACCELEROMETER_UNCALIBRATED = 35,
218};
219
220/**
221 * Sensor accuracy measure.
222 */
223enum {
224    /** no contact */
225    ASENSOR_STATUS_NO_CONTACT       = -1,
226    /** unreliable */
227    ASENSOR_STATUS_UNRELIABLE       = 0,
228    /** low accuracy */
229    ASENSOR_STATUS_ACCURACY_LOW     = 1,
230    /** medium accuracy */
231    ASENSOR_STATUS_ACCURACY_MEDIUM  = 2,
232    /** high accuracy */
233    ASENSOR_STATUS_ACCURACY_HIGH    = 3
234};
235
236/**
237 * Sensor Reporting Modes.
238 */
239enum {
240    /** invalid reporting mode */
241    AREPORTING_MODE_INVALID = -1,
242    /** continuous reporting */
243    AREPORTING_MODE_CONTINUOUS = 0,
244    /** reporting on change */
245    AREPORTING_MODE_ON_CHANGE = 1,
246    /** on shot reporting */
247    AREPORTING_MODE_ONE_SHOT = 2,
248    /** special trigger reporting */
249    AREPORTING_MODE_SPECIAL_TRIGGER = 3
250};
251
252/**
253 * Sensor Direct Report Rates.
254 */
255enum {
256    /** stopped */
257    ASENSOR_DIRECT_RATE_STOP = 0,
258    /** nominal 50Hz */
259    ASENSOR_DIRECT_RATE_NORMAL = 1,
260    /** nominal 200Hz */
261    ASENSOR_DIRECT_RATE_FAST = 2,
262    /** nominal 800Hz */
263    ASENSOR_DIRECT_RATE_VERY_FAST = 3
264};
265
266/**
267 * Sensor Direct Channel Type.
268 */
269enum {
270    /** shared memory created by ASharedMemory_create */
271    ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY = 1,
272    /** AHardwareBuffer */
273    ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER = 2
274};
275
276/*
277 * A few useful constants
278 */
279
280/** Earth's gravity in m/s^2 */
281#define ASENSOR_STANDARD_GRAVITY            (9.80665f)
282/** Maximum magnetic field on Earth's surface in uT */
283#define ASENSOR_MAGNETIC_FIELD_EARTH_MAX    (60.0f)
284/** Minimum magnetic field on Earth's surface in uT*/
285#define ASENSOR_MAGNETIC_FIELD_EARTH_MIN    (30.0f)
286
287/**
288 * A sensor event.
289 */
290
291/* NOTE: changes to these structs have to be backward compatible */
292typedef struct ASensorVector {
293    union {
294        float v[3];
295        struct {
296            float x;
297            float y;
298            float z;
299        };
300        struct {
301            float azimuth;
302            float pitch;
303            float roll;
304        };
305    };
306    int8_t status;
307    uint8_t reserved[3];
308} ASensorVector;
309
310typedef struct AMetaDataEvent {
311    int32_t what;
312    int32_t sensor;
313} AMetaDataEvent;
314
315typedef struct AUncalibratedEvent {
316    union {
317        float uncalib[3];
318        struct {
319            float x_uncalib;
320            float y_uncalib;
321            float z_uncalib;
322        };
323    };
324    union {
325        float bias[3];
326        struct {
327            float x_bias;
328            float y_bias;
329            float z_bias;
330        };
331    };
332} AUncalibratedEvent;
333
334typedef struct AHeartRateEvent {
335    float bpm;
336    int8_t status;
337} AHeartRateEvent;
338
339typedef struct ADynamicSensorEvent {
340    int32_t  connected;
341    int32_t  handle;
342} ADynamicSensorEvent;
343
344typedef struct {
345    int32_t type;
346    int32_t serial;
347    union {
348        int32_t data_int32[14];
349        float   data_float[14];
350    };
351} AAdditionalInfoEvent;
352
353/* NOTE: changes to this struct has to be backward compatible */
354typedef struct ASensorEvent {
355    int32_t version; /* sizeof(struct ASensorEvent) */
356    int32_t sensor;
357    int32_t type;
358    int32_t reserved0;
359    int64_t timestamp;
360    union {
361        union {
362            float           data[16];
363            ASensorVector   vector;
364            ASensorVector   acceleration;
365            ASensorVector   magnetic;
366            float           temperature;
367            float           distance;
368            float           light;
369            float           pressure;
370            float           relative_humidity;
371            AUncalibratedEvent uncalibrated_gyro;
372            AUncalibratedEvent uncalibrated_magnetic;
373            AMetaDataEvent meta_data;
374            AHeartRateEvent heart_rate;
375            ADynamicSensorEvent dynamic_sensor_meta;
376            AAdditionalInfoEvent additional_info;
377        };
378        union {
379            uint64_t        data[8];
380            uint64_t        step_counter;
381        } u64;
382    };
383
384    uint32_t flags;
385    int32_t reserved1[3];
386} ASensorEvent;
387
388struct ASensorManager;
389/**
390 * {@link ASensorManager} is an opaque type to manage sensors and
391 * events queues.
392 *
393 * {@link ASensorManager} is a singleton that can be obtained using
394 * ASensorManager_getInstance().
395 *
396 * This file provides a set of functions that uses {@link
397 * ASensorManager} to access and list hardware sensors, and
398 * create and destroy event queues:
399 * - ASensorManager_getSensorList()
400 * - ASensorManager_getDefaultSensor()
401 * - ASensorManager_getDefaultSensorEx()
402 * - ASensorManager_createEventQueue()
403 * - ASensorManager_destroyEventQueue()
404 */
405typedef struct ASensorManager ASensorManager;
406
407
408struct ASensorEventQueue;
409/**
410 * {@link ASensorEventQueue} is an opaque type that provides access to
411 * {@link ASensorEvent} from hardware sensors.
412 *
413 * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue().
414 *
415 * This file provides a set of functions to enable and disable
416 * sensors, check and get events, and set event rates on a {@link
417 * ASensorEventQueue}.
418 * - ASensorEventQueue_enableSensor()
419 * - ASensorEventQueue_disableSensor()
420 * - ASensorEventQueue_hasEvents()
421 * - ASensorEventQueue_getEvents()
422 * - ASensorEventQueue_setEventRate()
423 */
424typedef struct ASensorEventQueue ASensorEventQueue;
425
426struct ASensor;
427/**
428 * {@link ASensor} is an opaque type that provides information about
429 * an hardware sensors.
430 *
431 * A {@link ASensor} pointer can be obtained using
432 * ASensorManager_getDefaultSensor(),
433 * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}.
434 *
435 * This file provides a set of functions to access properties of a
436 * {@link ASensor}:
437 * - ASensor_getName()
438 * - ASensor_getVendor()
439 * - ASensor_getType()
440 * - ASensor_getResolution()
441 * - ASensor_getMinDelay()
442 * - ASensor_getFifoMaxEventCount()
443 * - ASensor_getFifoReservedEventCount()
444 * - ASensor_getStringType()
445 * - ASensor_getReportingMode()
446 * - ASensor_isWakeUpSensor()
447 */
448typedef struct ASensor ASensor;
449/**
450 * {@link ASensorRef} is a type for constant pointers to {@link ASensor}.
451 *
452 * This is used to define entry in {@link ASensorList} arrays.
453 */
454typedef ASensor const* ASensorRef;
455/**
456 * {@link ASensorList} is an array of reference to {@link ASensor}.
457 *
458 * A {@link ASensorList} can be initialized using ASensorManager_getSensorList().
459 */
460typedef ASensorRef const* ASensorList;
461
462/*****************************************************************************/
463
464/**
465 * Get a reference to the sensor manager. ASensorManager is a singleton
466 * per package as different packages may have access to different sensors.
467 *
468 * Deprecated: Use ASensorManager_getInstanceForPackage(const char*) instead.
469 *
470 * Example:
471 *
472 *     ASensorManager* sensorManager = ASensorManager_getInstance();
473 *
474 */
475#if __ANDROID_API__ >= __ANDROID_API_O__
476__attribute__ ((deprecated)) ASensorManager* ASensorManager_getInstance();
477#else
478ASensorManager* ASensorManager_getInstance();
479#endif
480
481#if __ANDROID_API__ >= __ANDROID_API_O__
482/**
483 * Get a reference to the sensor manager. ASensorManager is a singleton
484 * per package as different packages may have access to different sensors.
485 *
486 * Example:
487 *
488 *     ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz");
489 *
490 */
491ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName);
492#endif
493
494/**
495 * Returns the list of available sensors.
496 */
497int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list);
498
499/**
500 * Returns the default sensor for the given type, or NULL if no sensor
501 * of that type exists.
502 */
503ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type);
504
505#if __ANDROID_API__ >= 21
506/**
507 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor
508 * of this type and wakeUp properties exists.
509 */
510ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type, bool wakeUp);
511#endif
512
513/**
514 * Creates a new sensor event queue and associate it with a looper.
515 *
516 * "ident" is a identifier for the events that will be returned when
517 * calling ALooper_pollOnce(). The identifier must be >= 0, or
518 * ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
519 */
520ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager,
521        ALooper* looper, int ident, ALooper_callbackFunc callback, void* data);
522
523/**
524 * Destroys the event queue and free all resources associated to it.
525 */
526int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue);
527
528#if __ANDROID_API__ >= __ANDROID_API_O__
529/**
530 * Create direct channel based on shared memory
531 *
532 * Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY} to be used
533 * for configuring sensor direct report.
534 *
535 * \param manager the {@link ASensorManager} instance obtained from
536 *                {@link ASensorManager_getInstanceForPackage}.
537 * \param fd      file descriptor representing a shared memory created by
538 *                {@link ASharedMemory_create}
539 * \param size    size to be used, must be less or equal to size of shared memory.
540 *
541 * \return a positive integer as a channel id to be used in
542 *         {@link ASensorManager_destroyDirectChannel} and
543 *         {@link ASensorManager_configureDirectReport}, or value less or equal to 0 for failures.
544 */
545int ASensorManager_createSharedMemoryDirectChannel(ASensorManager* manager, int fd, size_t size);
546
547/**
548 * Create direct channel based on AHardwareBuffer
549 *
550 * Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER} type to be used
551 * for configuring sensor direct report.
552 *
553 * \param manager the {@link ASensorManager} instance obtained from
554 *                {@link ASensorManager_getInstanceForPackage}.
555 * \param buffer  {@link AHardwareBuffer} instance created by {@link AHardwareBuffer_allocate}.
556 * \param size    the intended size to be used, must be less or equal to size of buffer.
557 *
558 * \return a positive integer as a channel id to be used in
559 *         {@link ASensorManager_destroyDirectChannel} and
560 *         {@link ASensorManager_configureDirectReport}, or value less or equal to 0 for failures.
561 */
562int ASensorManager_createHardwareBufferDirectChannel(
563        ASensorManager* manager, AHardwareBuffer const * buffer, size_t size);
564
565/**
566 * Destroy a direct channel
567 *
568 * Destroy a direct channel previously created using {@link ASensorManager_createDirectChannel}.
569 * The buffer used for creating direct channel does not get destroyed with
570 * {@link ASensorManager_destroy} and has to be close or released separately.
571 *
572 * \param manager the {@link ASensorManager} instance obtained from
573 *                {@link ASensorManager_getInstanceForPackage}.
574 * \param channelId channel id (a positive integer) returned from
575 *                  {@link ASensorManager_createSharedMemoryDirectChannel} or
576 *                  {@link ASensorManager_createHardwareBufferDirectChannel}.
577 */
578void ASensorManager_destroyDirectChannel(ASensorManager* manager, int channelId);
579
580/**
581 * Configure direct report on channel
582 *
583 * Configure sensor direct report on a direct channel: set rate to value other than
584 * {@link ASENSOR_DIRECT_RATE_STOP} so that sensor event can be directly
585 * written into the shared memory region used for creating the buffer. It returns a positive token
586 * which can be used for identify sensor events from different sensors on success. Calling with rate
587 * {@link ASENSOR_DIRECT_RATE_STOP} will stop direct report of the sensor specified in the channel.
588 *
589 * To stop all active sensor direct report configured to a channel, set sensor to NULL and rate to
590 * {@link ASENSOR_DIRECT_RATE_STOP}.
591 *
592 * In order to successfully configure a direct report, the sensor has to support the specified rate
593 * and the channel type, which can be checked by {@link ASensor_getHighestDirectReportRateLevel} and
594 * {@link ASensor_isDirectChannelTypeSupported}, respectively.
595 *
596 * Example:
597 *
598 *     ASensorManager *manager = ...;
599 *     ASensor *sensor = ...;
600 *     int channelId = ...;
601 *
602 *     ASensorManager_configureDirectReport(manager, sensor, channel_id, ASENSOR_DIRECT_RATE_FAST);
603 *
604 * \param manager   the {@link ASensorManager} instance obtained from
605 *                  {@link ASensorManager_getInstanceForPackage}.
606 * \param sensor    a {@link ASensor} to denote which sensor to be operate. It can be NULL if rate
607 *                  is {@link ASENSOR_DIRECT_RATE_STOP}, denoting stopping of all active sensor
608 *                  direct report.
609 * \param channelId channel id (a positive integer) returned from
610 *                  {@link ASensorManager_createSharedMemoryDirectChannel} or
611 *                  {@link ASensorManager_createHardwareBufferDirectChannel}.
612 *
613 * \return positive token for success or negative error code.
614 */
615int ASensorManager_configureDirectReport(
616        ASensorManager* manager, ASensor const* sensor, int channelId, int rate);
617#endif
618
619/*****************************************************************************/
620
621/**
622 * Enable the selected sensor with sampling and report parameters
623 *
624 * Enable the selected sensor at a specified sampling period and max batch report latency.
625 * To disable  sensor, use {@link ASensorEventQueue_disableSensor}.
626 *
627 * \param queue {@link ASensorEventQueue} for sensor event to be report to.
628 * \param sensor {@link ASensor} to be enabled.
629 * \param samplingPeriodUs sampling period of sensor in microseconds.
630 * \param maxBatchReportLatencyus maximum time interval between two batch of sensor events are
631 *                                delievered in microseconds. For sensor streaming, set to 0.
632 * \return 0 on success or a negative error code on failure.
633 */
634int ASensorEventQueue_registerSensor(ASensorEventQueue* queue, ASensor const* sensor,
635        int32_t samplingPeriodUs, int64_t maxBatchReportLatencyUs);
636
637/**
638 * Enable the selected sensor at default sampling rate.
639 *
640 * Start event reports of a sensor to specified sensor event queue at a default rate.
641 *
642 * \param queue {@link ASensorEventQueue} for sensor event to be report to.
643 * \param sensor {@link ASensor} to be enabled.
644 *
645 * \return 0 on success or a negative error code on failure.
646 */
647int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor);
648
649/**
650 * Disable the selected sensor.
651 *
652 * Stop event reports from the sensor to specified sensor event queue.
653 *
654 * \param queue {@link ASensorEventQueue} to be changed
655 * \param sensor {@link ASensor} to be disabled
656 * \return 0 on success or a negative error code on failure.
657 */
658int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor);
659
660/**
661 * Sets the delivery rate of events in microseconds for the given sensor.
662 *
663 * This function has to be called after {@link ASensorEventQueue_enableSensor}.
664 * Note that this is a hint only, generally event will arrive at a higher
665 * rate. It is an error to set a rate inferior to the value returned by
666 * ASensor_getMinDelay().
667 *
668 * \param queue {@link ASensorEventQueue} to which sensor event is delivered.
669 * \param sensor {@link ASensor} of which sampling rate to be updated.
670 * \param usec sensor sampling period (1/sampling rate) in microseconds
671 * \return 0 on sucess or a negative error code on failure.
672 */
673int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec);
674
675/**
676 * Determine if a sensor event queue has pending event to be processed.
677 *
678 * \param queue {@link ASensorEventQueue} to be queried
679 * \return 1 if the queue has events; 0 if it does not have events;
680 *         or a negative value if there is an error.
681 */
682int ASensorEventQueue_hasEvents(ASensorEventQueue* queue);
683
684/**
685 * Retrieve pending events in sensor event queue
686 *
687 * Retrieve next available events from the queue to a specified event array.
688 *
689 * \param queue {@link ASensorEventQueue} to get events from
690 * \param events pointer to an array of {@link ASensorEvents}.
691 * \param count max number of event that can be filled into array event.
692 * \return number of events returned on success; negative error code when
693 *         no events are pending or an error has occurred.
694 *
695 * Examples:
696 *
697 *     ASensorEvent event;
698 *     ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1);
699 *
700 *     ASensorEvent eventBuffer[8];
701 *     ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8);
702 *
703 */
704ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, ASensorEvent* events, size_t count);
705
706
707/*****************************************************************************/
708
709/**
710 * Returns this sensor's name (non localized)
711 */
712const char* ASensor_getName(ASensor const* sensor);
713
714/**
715 * Returns this sensor's vendor's name (non localized)
716 */
717const char* ASensor_getVendor(ASensor const* sensor);
718
719/**
720 * Return this sensor's type
721 */
722int ASensor_getType(ASensor const* sensor);
723
724/**
725 * Returns this sensors's resolution
726 */
727float ASensor_getResolution(ASensor const* sensor);
728
729/**
730 * Returns the minimum delay allowed between events in microseconds.
731 * A value of zero means that this sensor doesn't report events at a
732 * constant rate, but rather only when a new data is available.
733 */
734int ASensor_getMinDelay(ASensor const* sensor);
735
736#if __ANDROID_API__ >= 21
737/**
738 * Returns the maximum size of batches for this sensor. Batches will often be
739 * smaller, as the hardware fifo might be used for other sensors.
740 */
741int ASensor_getFifoMaxEventCount(ASensor const* sensor);
742
743/**
744 * Returns the hardware batch fifo size reserved to this sensor.
745 */
746int ASensor_getFifoReservedEventCount(ASensor const* sensor);
747
748/**
749 * Returns this sensor's string type.
750 */
751const char* ASensor_getStringType(ASensor const* sensor);
752
753/**
754 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants.
755 */
756int ASensor_getReportingMode(ASensor const* sensor);
757
758/**
759 * Returns true if this is a wake up sensor, false otherwise.
760 */
761bool ASensor_isWakeUpSensor(ASensor const* sensor);
762#endif /* __ANDROID_API__ >= 21 */
763
764#if __ANDROID_API__ >= __ANDROID_API_O__
765/**
766 * Test if sensor supports a certain type of direct channel.
767 *
768 * \param sensor  a {@link ASensor} to denote the sensor to be checked.
769 * \param channelType  Channel type constant, either
770 *                     {@ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY}
771 *                     or {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER}.
772 * \returns true if sensor supports the specified direct channel type.
773 */
774bool ASensor_isDirectChannelTypeSupported(ASensor const* sensor, int channelType);
775/**
776 * Get the highest direct rate level that a sensor support.
777 *
778 * \param sensor  a {@link ASensor} to denote the sensor to be checked.
779 *
780 * \return a ASENSOR_DIRECT_RATE_... enum denoting the highest rate level supported by the sensor.
781 *         If return value is {@link ASENSOR_DIRECT_RATE_STOP}, it means the sensor
782 *         does not support direct report.
783 */
784int ASensor_getHighestDirectReportRateLevel(ASensor const* sensor);
785#endif
786
787#ifdef __cplusplus
788};
789#endif
790
791#endif // ANDROID_SENSOR_H
792
793/** @} */
794