frameworks/native: document native types and enums
Change-Id: Id94b610f27b87426abb30e13484cbd16990aa995
diff --git a/include/android/sensor.h b/include/android/sensor.h
index d58c460..4600dad 100644
--- a/include/android/sensor.h
+++ b/include/android/sensor.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Sensor
+ * @{
+ */
+
+/**
+ * @file sensor.h
+ */
#ifndef ANDROID_SENSOR_H
#define ANDROID_SENSOR_H
@@ -34,7 +42,7 @@
* - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
*/
-/*
+/**
* Structures and functions to receive and process sensor events in
* native code.
*
@@ -49,37 +57,82 @@
#endif
-/*
- * Sensor types
+/**
+ * Sensor types.
* (keep in sync with hardware/sensor.h)
*/
-
enum {
+ /**
+ * {@link ASENSOR_TYPE_ACCELEROMETER}
+ * reporting-mode: continuous
+ *
+ * All values are in SI units (m/s^2) and measure the acceleration of the
+ * device minus the force of gravity.
+ */
ASENSOR_TYPE_ACCELEROMETER = 1,
+ /**
+ * {@link ASENSOR_TYPE_MAGNETIC_FIELD}
+ * reporting-mode: continuous
+ *
+ * All values are in micro-Tesla (uT) and measure the geomagnetic
+ * field in the X, Y and Z axis.
+ */
ASENSOR_TYPE_MAGNETIC_FIELD = 2,
+ /**
+ * {@link ASENSOR_TYPE_GYROSCOPE}
+ * reporting-mode: continuous
+ *
+ * All values are in radians/second and measure the rate of rotation
+ * around the X, Y and Z axis.
+ */
ASENSOR_TYPE_GYROSCOPE = 4,
+ /**
+ * {@link ASENSOR_TYPE_LIGHT}
+ * reporting-mode: on-change
+ *
+ * The light sensor value is returned in SI lux units.
+ */
ASENSOR_TYPE_LIGHT = 5,
+ /**
+ * {@link ASENSOR_TYPE_PROXIMITY}
+ * reporting-mode: on-change
+ *
+ * The proximity sensor which turns the screen off and back on during calls is the
+ * wake-up proximity sensor. Implement wake-up proximity sensor before implementing
+ * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag
+ * SENSOR_FLAG_WAKE_UP.
+ * The value corresponds to the distance to the nearest object in centimeters.
+ */
ASENSOR_TYPE_PROXIMITY = 8
};
-/*
- * Sensor accuracy measure
+/**
+ * Sensor accuracy measure.
*/
enum {
+ /** no contact */
ASENSOR_STATUS_NO_CONTACT = -1,
+ /** unreliable */
ASENSOR_STATUS_UNRELIABLE = 0,
+ /** low accuracy */
ASENSOR_STATUS_ACCURACY_LOW = 1,
+ /** medium accuracy */
ASENSOR_STATUS_ACCURACY_MEDIUM = 2,
+ /** high accuracy */
ASENSOR_STATUS_ACCURACY_HIGH = 3
};
-/*
+/**
* Sensor Reporting Modes.
*/
enum {
+ /** continuous reporting */
AREPORTING_MODE_CONTINUOUS = 0,
+ /** reporting on change */
AREPORTING_MODE_ON_CHANGE = 1,
+ /** on shot reporting */
AREPORTING_MODE_ONE_SHOT = 2,
+ /** special trigger reporting */
AREPORTING_MODE_SPECIAL_TRIGGER = 3
};
@@ -87,14 +140,14 @@
* A few useful constants
*/
-/* Earth's gravity in m/s^2 */
+/** Earth's gravity in m/s^2 */
#define ASENSOR_STANDARD_GRAVITY (9.80665f)
-/* Maximum magnetic field on Earth's surface in uT */
+/** Maximum magnetic field on Earth's surface in uT */
#define ASENSOR_MAGNETIC_FIELD_EARTH_MAX (60.0f)
-/* Minimum magnetic field on Earth's surface in uT*/
+/** Minimum magnetic field on Earth's surface in uT*/
#define ASENSOR_MAGNETIC_FIELD_EARTH_MIN (30.0f)
-/*
+/**
* A sensor event.
*/
@@ -180,19 +233,82 @@
} ASensorEvent;
struct ASensorManager;
+/**
+ * {@link ASensorManager} is an opaque type to manage sensors and
+ * events queues.
+ *
+ * {@link ASensorManager} is a singleton that can be obtained using
+ * ASensorManager_getInstance().
+ *
+ * This file provides a set of functions that uses {@link
+ * ASensorManager} to access and list hardware sensors, and
+ * create and destroy event queues:
+ * - ASensorManager_getSensorList()
+ * - ASensorManager_getDefaultSensor()
+ * - ASensorManager_getDefaultSensorEx()
+ * - ASensorManager_createEventQueue()
+ * - ASensorManager_destroyEventQueue()
+ */
typedef struct ASensorManager ASensorManager;
+
struct ASensorEventQueue;
+/**
+ * {@link ASensorEventQueue} is an opaque type that provides access to
+ * {@link ASensorEvent} from hardware sensors.
+ *
+ * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue().
+ *
+ * This file provides a set of functions to enable and disable
+ * sensors, check and get events, and set event rates on a {@link
+ * ASensorEventQueue}.
+ * - ASensorEventQueue_enableSensor()
+ * - ASensorEventQueue_disableSensor()
+ * - ASensorEventQueue_hasEvents()
+ * - ASensorEventQueue_getEvents()
+ * - ASensorEventQueue_setEventRate()
+ */
typedef struct ASensorEventQueue ASensorEventQueue;
struct ASensor;
+/**
+ * {@link ASensor} is an opaque type that provides information about
+ * an hardware sensors.
+ *
+ * A {@link ASensor} pointer can be obtained using
+ * ASensorManager_getDefaultSensor(),
+ * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}.
+ *
+ * This file provides a set of functions to access properties of a
+ * {@link ASensor}:
+ * - ASensor_getName()
+ * - ASensor_getVendor()
+ * - ASensor_getType()
+ * - ASensor_getResolution()
+ * - ASensor_getMinDelay()
+ * - ASensor_getFifoMaxEventCount()
+ * - ASensor_getFifoReservedEventCount()
+ * - ASensor_getStringType()
+ * - ASensor_getReportingMode()
+ * - ASensor_isWakeUpSensor()
+ */
typedef struct ASensor ASensor;
+/**
+ * {@link ASensorRef} is a type for constant pointers to {@link ASensor}.
+ *
+ * This is used to define entry in {@link ASensorList} arrays.
+ */
typedef ASensor const* ASensorRef;
+/**
+ * {@link ASensorList} is an array of reference to {@link ASensor}.
+ *
+ * A {@link ASensorList} can be initialized using ASensorManager_getSensorList().
+ */
typedef ASensorRef const* ASensorList;
/*****************************************************************************/
-/*
+/**
* Get a reference to the sensor manager. ASensorManager is a singleton.
*
* Example:
@@ -203,31 +319,35 @@
ASensorManager* ASensorManager_getInstance();
-/*
+/**
* Returns the list of available sensors.
*/
int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list);
-/*
+/**
* Returns the default sensor for the given type, or NULL if no sensor
* of that type exists.
*/
ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type);
-/*
+/**
* Returns the default sensor with the given type and wakeUp properties or NULL if no sensor
* of this type and wakeUp properties exists.
*/
ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type,
bool wakeUp);
-/*
+/**
* Creates a new sensor event queue and associate it with a looper.
+ *
+ * "ident" is a identifier for the events that will be returned when
+ * calling ALooper_pollOnce(). The identifier must be >= 0, or
+ * ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
*/
ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager,
ALooper* looper, int ident, ALooper_callbackFunc callback, void* data);
-/*
+/**
* Destroys the event queue and free all resources associated to it.
*/
int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue);
@@ -235,17 +355,17 @@
/*****************************************************************************/
-/*
+/**
* Enable the selected sensor. Returns a negative error code on failure.
*/
int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor);
-/*
+/**
* Disable the selected sensor. Returns a negative error code on failure.
*/
int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor);
-/*
+/**
* Sets the delivery rate of events in microseconds for the given sensor.
* Note that this is a hint only, generally event will arrive at a higher
* rate. It is an error to set a rate inferior to the value returned by
@@ -254,14 +374,14 @@
*/
int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec);
-/*
+/**
* Returns true if there are one or more events available in the
* sensor queue. Returns 1 if the queue has events; 0 if
* it does not have events; and a negative value if there is an error.
*/
int ASensorEventQueue_hasEvents(ASensorEventQueue* queue);
-/*
+/**
* Returns the next available events from the queue. Returns a negative
* value if no events are available or an error has occurred, otherwise
* the number of events returned.
@@ -280,55 +400,55 @@
/*****************************************************************************/
-/*
+/**
* Returns this sensor's name (non localized)
*/
const char* ASensor_getName(ASensor const* sensor);
-/*
+/**
* Returns this sensor's vendor's name (non localized)
*/
const char* ASensor_getVendor(ASensor const* sensor);
-/*
+/**
* Return this sensor's type
*/
int ASensor_getType(ASensor const* sensor);
-/*
+/**
* Returns this sensors's resolution
*/
float ASensor_getResolution(ASensor const* sensor);
-/*
+/**
* Returns the minimum delay allowed between events in microseconds.
* A value of zero means that this sensor doesn't report events at a
* constant rate, but rather only when a new data is available.
*/
int ASensor_getMinDelay(ASensor const* sensor);
-/*
+/**
* Returns the maximum size of batches for this sensor. Batches will often be
* smaller, as the hardware fifo might be used for other sensors.
*/
int ASensor_getFifoMaxEventCount(ASensor const* sensor);
-/*
+/**
* Returns the hardware batch fifo size reserved to this sensor.
*/
int ASensor_getFifoReservedEventCount(ASensor const* sensor);
-/*
+/**
* Returns this sensor's string type.
*/
const char* ASensor_getStringType(ASensor const* sensor);
-/*
+/**
* Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants.
*/
int ASensor_getReportingMode(ASensor const* sensor);
-/*
+/**
* Returns true if this is a wake up sensor, false otherwise.
*/
bool ASensor_isWakeUpSensor(ASensor const* sensor);
@@ -338,3 +458,5 @@
#endif
#endif // ANDROID_SENSOR_H
+
+/** @} */