/**
* @brief Checks whether a given sensor type is supported in the current device.
- * @details If the given sensor type is not supported, sensor_get_default_sensor() will return an error.
- * It is thus recommended to check the availability of the sensor before actually acquiring #sensor_h.
+ * @details If sensor type is supported, @a supported will be true. Otherwise,
+ * it will be false and the return value will be an error.
* @since_tizen 2.3
*
+ * @remarks If the given sensor type is not supported,
+ * sensor_get_default_sensor() will return an error.
+ * It is thus recommended to check the availability of the sensor
+ * before actually acquiring #sensor_h.
+ *
* @param[in] type A sensor type to check
* @param[out] supported If supported, @c true; Otherwise @c false
*
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see sensor_is_supported_by_uri()
+ *
+ * @code
+ * ...
+ * sensor_type_e type;
+ * bool supported;
+ * ...
+ * sensor_is_supported(type, &supported);
+ * if (!supported)
+ * return -1;
+ * @endcode
*/
int sensor_is_supported(sensor_type_e type, bool *supported);
/**
* @brief Checks whether a sensor corresponding to a given URI is supported in the current device.
- * @details To correctly check the availability of a sensor, a valid URI should be provided.
+ * @details @a supported is set as @c true if the sensor is available; otherwise, it is set as @c false.
+ * It is recommended to check the availability of the sensors corresponding to the URI
+ * before actually acquiring #sensor_h.
+ * @since_tizen 4.0
+ *
+ * @remarks @a uri should be valid and not null to correctly check the availability of a sensor.
* The valid form of URIs is explained in \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI.\n
* If a URI with the sensor's name is given, for example, %http://tizen.org/sensor/general/light/front,
* the availability of the @"front@" light sensor is checked.
* Otherwise, if a URI without the name, %http://tizen.org/sensor/general/light, is given,
- * this function checks the availability of any light sensor in the device.\n
- * It is recommended to check the availability of the sensors corresponding to the URI
- * before actually acquiring #sensor_h.
- * @since_tizen 4.0
+ * this function checks the availability of any light sensor in the device.
*
* @param[in] uri A sensor or a sensor type URI to check
* @param[out] supported If supported, @c true, otherwise @c false
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see sensor_is_supported()
+ *
+ * @code
+ * bool supported;
+ * sensor_is_supported_by_uri("http://tizen.org/sensor/general/light/front", &supported);
+ * if (!supported) {
+ * return -1;
+ * }
+ * @endcode
*/
int sensor_is_supported_by_uri(const char *uri, bool *supported);
*
* @pre The handle @c sensor needs to be initialized using
* sensor_get_default_sensor() or sensor_get_sensor_list() in advance.
+ * @code
+ * bool is_wakeup_sensor = false;
+ * sensor_is_wake_up(sensor, &is_wakeup_sensor);
+ * is (!is_wakeup_sensor)
+ * return -1;
+ * @endcode
*/
int sensor_is_wake_up(sensor_h sensor, bool *wakeup);
* @retval #SENSOR_ERROR_NOT_SUPPORTED The sensor type is not supported in the current device
* @retval #SENSOR_ERROR_PERMISSION_DENIED Permission denied
* @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory
+ *
+ * @code
+ * sensor_h *sensor_list = NULL;
+ * int sensor_list_len = 0;
+ * sensor_get_sensor_list(SENSOR_ACCELEROMETER, &sensor_list, &sensor_list_len);
+ * @endcode
*/
int sensor_get_sensor_list(sensor_type_e type, sensor_h **list, int *sensor_count);
* @retval #SENSOR_ERROR_NOT_SUPPORTED The URI is not supported in the current device
* @retval #SENSOR_ERROR_PERMISSION_DENIED Permission denied
* @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory
+ * @code
+ * sensor_h *sensor_list = NULL;
+ * int sensor_list_len = 0;
+ * sensor_get_sensor_list("http://tizen.org/sensor/general/accelerometer", &sensor_list, &sensor_list_len);
+ * @endcode
*/
int sensor_get_sensor_list_by_uri(const char *uri, sensor_h **list, int *sensor_count);
/**
- * @brief Gets the URI of a sensor.
+ * @brief Gets the URI of a given sensor as a newly allocated string.
+ * @details Get the URI of a given sensor and store it in the @a uri.
* @since_tizen 4.0
*
* @remarks The @a uri must be released using free(), if not being used anymore.
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * char *uri = NULL;
+ * sensor_get_uri(sensor, &uri);
+ * ...
+ * free(uri);
+ * @endcode
*/
int sensor_get_uri(sensor_h sensor, char **uri);
/**
- * @brief Gets the name of a sensor.
+ * @brief Gets the name of a given sensor as a newly allocated string.
+ * @details Get the name of a given sensor and store it in the @a name.
* @since_tizen 2.3
*
* @remarks The @a name must be released using free(), if not being used anymore.
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * char *name = NULL;
+ * sensor_get_name(sensor, &name);
+ * ...
+ * free(name);
+ * @endcode
*/
int sensor_get_name(sensor_h sensor, char **name);
/**
- * @brief Gets the vendor of a sensor.
+ * @brief Gets the vandor name of a given sensor as a newly allocated string.
+ * @details Get the vendor name of a given sensor and store it in the @a vendor.
* @since_tizen 2.3
*
* @remarks The @a vendor must be released using free(), if not being used anymore.
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * char *vendor_name = NULL;
+ * sensor_get_vendor(sensor, &vendor_name);
+ * ...
+ * free(vendor_name);
+ * @endcode
*/
int sensor_get_vendor(sensor_h sensor, char **vendor);
/**
- * @brief Gets the type of a sensor, if it belongs to the known types defined in #sensor_type_e.
+ * @brief Gets the type of a given sensor as #sensor_type_e data type.
+ * @details Get the type of a given sensor if it belongs to the known types
+ * defined in #sensor_type_e.
* @since_tizen 2.3
*
* @param[in] sensor A sensor handle
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_NO_DATA No known sensor type for the given sensor
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * sensor_type_e sensor_type;
+ * sensor_get_type(sensor, &sensor_type);
+ * @endcode
*/
int sensor_get_type(sensor_h sensor, sensor_type_e *type);
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_get_max_range()
+ * @code
+ * ...
+ * float min_range;
+ * sensor_get_min_range(sensor, &min_range);
+ * @endcode
*/
int sensor_get_min_range(sensor_h sensor, float *min_range);
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_get_min_range()
+ * @code
+ * ...
+ * float max_range;
+ * sensor_get_max_range(sensor, &max_range);
+ * @endcode
*/
int sensor_get_max_range(sensor_h sensor, float *max_range);
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * float resolution;
+ * sensor_get_resolution(sensor, &resolution);
+ * @endcode
*/
int sensor_get_resolution(sensor_h sensor, float *resolution);
/**
- * @brief Gets the possible shorted update interval of a sensor.
+ * @brief Gets the minimum update interval of a given sensor.
+ * @details Get the minimum update interval and store it in @a min_interval.
* @since_tizen 2.3
*
* @param[in] sensor A sensor handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * int min_interval;
+ * sensor_get_min_interval(sensor, &min_interval);
+ * @endcode
*/
int sensor_get_min_interval(sensor_h sensor, int *min_interval);
/**
- * @brief Gets the size of the hardware FIFO of a sensor.
+ * @brief Gets the size of the hardware FIFO of a given sensor.
* @details This function returns the size of the hardware FIFO that may be used by
* a specific sensor to support batching.
* However, regarding the underlying hardware configuration,
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * int fifo_count;
+ * sensor_get_min_interval(sensor, &fifo_count);
+ * @endcode
*/
int sensor_get_fifo_count(sensor_h sensor, int *fifo_count);
/**
- * @brief Gets the maximum batch count of a sensor.
+ * @brief Gets the maximum value of batch count of a given sensor.
* @details This function returns the maximum number of sensor data events
* that can be possibly delivered when the batched data are flushed.
* Therefore, this count can be used to check whether the sensor supports
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_listener_set_max_batch_latency()
+ * @code
+ * ...
+ * int max_batch_count = 0;
+ * sensor_get_min_interval(sensor, &max_batch_count);
+ * @endcode
*/
int sensor_get_max_batch_count(sensor_h sensor, int *max_batch_count);
/**
- * @brief Called when a new sensor is added.
+ * @brief Callback function type to be called when a new sensor is added.
+ * @details Will be called when a new sensor is added with parameters: uri of a
+ * newly added sensor and user_data which is passed to
+ * sensor_add_sensor_cb().
* @since_tizen 4.0
*
* @remarks @a uri should not be freed and can be used only in the callback.
* @pre A callback function needs to be set using sensor_add_sensor_added_cb().
* @see sensor_add_sensor_added_cb()
* @see sensor_remove_sensor_added_cb()
+ * @code
+ * void sensor_add_callback(const char *uri, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_add_sensor_added_cb(sensor_add_callback, NULL);
+ * ...
+ * sensor_remove_sensor_added_cb(sensor_add_callback);
+ * @endcode
*/
typedef void (*sensor_added_cb)(const char *uri, void *user_data);
/**
- * @brief Adds a callback function to be invoked when a new sensor is added.
+ * @brief Adds a callback function to be invoked when a new sensor is added.
+ * @details Add a given callback function @a callback to be invoked when a new
+ * sensor is added. @a user_data will be passed to the callback
+ * function when it is called.
* @since_tizen 4.0
*
* @param[in] callback A callback function to be added
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_remove_sensor_added_cb()
+ * @code
+ * void sensor_add_callback(const char *uri, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_add_sensor_added_cb(sensor_add_callback, NULL);
+ * ...
+ * sensor_remove_sensor_added_cb(sensor_add_callback);
+ * @endcode
*/
int sensor_add_sensor_added_cb(sensor_added_cb callback, void *user_data);
/**
- * @brief Removes a callback function added using sensor_add_sensor_added_cb().
+ * @brief Removes a callback added by sensor_add_sensor_added_cb().
+ * @details Remove a given callback function which is added by
+ * sensor_add_sensor_added_cb() before.
* @since_tizen 4.0
*
* @param[in] callback A callback function to be removed
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_add_sensor_added_cb()
+ * @code
+ * void sensor_add_callback(const char *uri, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_add_sensor_added_cb(sensor_add_callback, NULL);
+ * ...
+ * sensor_remove_sensor_added_cb(sensor_add_callback);
+ * @endcode
*/
int sensor_remove_sensor_added_cb(sensor_added_cb callback);
/**
- * @brief Called when a sensor is removed.
+ * @brief Callback function type to be called when a sensor is removed.
+ * @details Will be called when a sensor is removed with parameters: uri of a
+ * removed sensor and user_data which is passed to
+ * sensor_add_sensor_cb().
* @since_tizen 4.0
*
* @remarks @a uri should not be freed and can be used only in the callback.
* @pre A callback function needs to be set using sensor_add_sensor_removed_cb().
* @see sensor_add_sensor_removed_cb()
* @see sensor_remove_sensor_removed_cb()
+ * @code
+ * void sensor_removed_callback(const char *uri, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_add_sensor_removed_cb(sensor_add_callback, NULL);
+ * ...
+ * sensor_remove_sensor_removed_cb(sensor_add_callback);
+ * @endcode
*/
typedef void (*sensor_removed_cb)(const char *uri, void *user_data);
/**
* @brief Adds a callback function to be invoked when a sensor is removed.
+ * @details Add a given callback function @a callback to be invoked when a
+ * sensor is removed. @a user_data will be passed to the callback
+ * function when it is called.
* @since_tizen 4.0
*
* @param[in] callback A callback function to be removed
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_remove_sensor_removed_cb()
+ * @code
+ * void sensor_removed_callback(const char *uri, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_add_sensor_removed_cb(sensor_add_callback, NULL);
+ * ...
+ * sensor_remove_sensor_removed_cb(sensor_add_callback);
+ * @endcode
*/
int sensor_add_sensor_removed_cb(sensor_removed_cb callback, void *user_data);
/**
* @brief Removes a callback function added using sensor_add_sensor_removed_cb().
+ * @details Remove a given callback function which is added by
+ * sensor_add_sensor_removed_cb() before.
* @since_tizen 4.0
*
* @param[in] callback A callback function to be removed
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_add_sensor_removed_cb()
+ * @code
+ * void sensor_removed_callback(const char *uri, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_add_sensor_removed_cb(sensor_add_callback, NULL);
+ * ...
+ * sensor_remove_sensor_removed_cb(sensor_add_callback);
+ * @endcode
*/
int sensor_remove_sensor_removed_cb(sensor_removed_cb callback);
/**
- * @brief Called when sensor events occur.
+ * @brief Callback function type to be called when sensor events occur.
+ * @details Will be called when a sensor event is occured. Callback function can
+ * be added using function sensor_listener_set_events_cb().
* @since_tizen 5.5
*
* @remarks @a sensor should not be freed, it's managed by platform.
* @param[in] user_data The user data passed to sensor_listener_set_events_cb()
*
* @pre The sensor needs to be started regarding a listener handle, using sensor_listener_start().
+ * @code
+ * void accelerator_event_callback(sensor_h sensor, sensor_event_s events[], int events_count, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_listener_set_events_cb(accelerator_listener, accelerator_event_callback, NULL);
+ * sensor_listener_unset_events_cb(accelerator_listener);
+ * @endcode
*/
typedef void (*sensor_events_cb)(sensor_h sensor, sensor_event_s events[], int events_count, void *user_data);
/**
- * @brief Called when the accuracy of a sensor changes.
+ * @brief Callback function type to be called when the accuracy of a sensor is
+ * changed.
* @details Sensors can be affected by the environment.
* For example, #SENSOR_MAGNETIC is sensitive to any surrounding objects that can influence
* electromagnetic fields. This function is called if the accuracy of the corresponding sensor is changed.
* @param[in] timestamp The time in milliseconds when the accuracy changed
* @param[in] accuracy The current accuracy of the sensor
* @param[in] data The user data had passed to sensor_listener_set_accuracy_cb()
+ * @code
+ * void accuracy_changed_callback(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_listener_set_accuracy_cb(listener, accuracy_changed_callback, NULL);
+ * ...
+ * sensor_listener_unset_accuracy_cb(listener);
+ * @endcode
*/
typedef void (*sensor_accuracy_changed_cb)(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data);
/**
- * @brief Creates a sensor listener.
+ * @brief Creates a sensor listener for a given sensor handle.
+ * @details Create a listener(sensor_listener_h) for the specified sensor and
+ * return a handle of the listener to the caller through @a listener.
* @since_tizen 2.3
*
* @remarks The @a listener must be released using sensor_destroy_listener().
*
* @pre The handle @a sensor needs to be initialized using
* sensor_get_default_sensor() or sensor_get_sensor_list() in advance.
+ * @code
+ * ...
+ * sensor_listener_h listener;
+ * sensor_create_listener(sensor, &listener);
+ * ...
+ * sensor_destroy_listener(listener);
+ * @endcode
*/
int sensor_create_listener(sensor_h sensor, sensor_listener_h *listener);
/**
- * @brief Releases all the resources allocated for a listener.
+ * @brief Destroy resources of a given listener for a sensor.
+ * @details Release all the resources allocated for a given sensor listener.
* @since_tizen 2.3
*
* @remarks If this function is called while the sensor is still running,
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see sensor_create_listener()
+ * @code
+ * ...
+ * sensor_listener_h listener;
+ * sensor_create_listener(sensor, &listener);
+ * ...
+ * sensor_destroy_listener(listener);
+ * @endcode
*/
int sensor_destroy_listener(sensor_listener_h listener);
* only if their states change.
* @since_tizen 2.3
*
+ * @remarks The @a listener will be stopped when sensor_listener_stop() is
+ * called or the @a listener is destroied by sensor_destroy_listener
+ * function call.
+ *
* @param[in] listener A listener handle
*
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* Then the callback function needs to be attached to the @a listener, by using
* sensor_listener_set_event_cb().
* @see sensor_listener_stop()
+ * @code
+ * ...
+ * sensor_listener_h listener;
+ * sensor_create_listener(sensor, &listener);
+ * ...
+ * sensor_listener_start(listener);
+ * ...
+ * sensor_destroy_listener(listener);
+ * @endcode
*/
int sensor_listener_start(sensor_listener_h listener);
/**
* @brief Stops observing the sensor events regarding a given sensor listener.
* @details The listener's event callback function stops being called.
- * But the sensor itself may not be stopped if there are other listeners
- * that are using the same sensor.
* @since_tizen 2.3
*
+ * @remarks The sensor(which is @a listener was listened to) itself may not be
+ * stopped if there are other listeners that are using the same sensor.
+ *
* @param[in] listener A listener handle
*
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_listener_start()
+ * @code
+ * ...
+ * sensor_listener_h listener;
+ * sensor_create_listener(sensor, &listener);
+ * ...
+ * sensor_listener_start(listener);
+ * ...
+ * sensor_destroy_listener(listener);
+ * ...
+ * sensor_listener_stop(listener);
+ * @endcode
*/
int sensor_listener_stop(sensor_listener_h listener);
/**
- * @brief Sets the callback function to be invoked when sensor events are delivered via a sensor listener.
+ * @brief Set the callback to be called when the sensor events occured.
+ * @details Set the callback function to be invoked when sensor events are
+ * delivered via a sensor listener.
* @since_tizen 5.5
*
* @param[in] listener A listener handle
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_listener_unset_events_cb()
+ * @code
+ * void accelerator_event_callback(sensor_h sensor, sensor_event_s events[], int events_count, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_listener_set_events_cb(accelerator_listener, accelerator_event_callback, NULL);
+ * sensor_listener_unset_events_cb(accelerator_listener);
+ * @endcode
*/
int sensor_listener_set_events_cb(sensor_listener_h listener, sensor_events_cb callback, void *user_data);
/**
- * @brief Unsets the sensor events callback function attached to a given sensor listener.
+ * @brief Unset the callback function from a sensor listener.
+ * @details Unset the sensor events callback function attached to a given sensor
+ * listener.
* @since_tizen 5.5
*
* @param[in] listener A listener handle
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_listener_set_events_cb()
+ * @code
+ * void accelerator_event_callback(sensor_h sensor, sensor_event_s events[], int events_count, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_listener_set_events_cb(accelerator_listener, accelerator_event_callback, NULL);
+ * sensor_listener_unset_events_cb(accelerator_listener);
+ * @endcode
*/
int sensor_listener_unset_events_cb(sensor_listener_h listener);
*
* @pre The @a listener needs to be started to get the change callbacks.
* @see sensor_listener_unset_accuracy_cb()
+ * @code
+ * void accuracy_changed_callback(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_listener_set_accuracy_cb(listener, accuracy_changed_callback, NULL);
+ * ...
+ * sensor_listener_unset_accuracy_cb(listener);
+ * @endcode
*/
int sensor_listener_set_accuracy_cb(sensor_listener_h listener, sensor_accuracy_changed_cb callback, void *data);
/**
- * @brief Unregisters the sensor accuracy change callback function attached to a given sensor listener.
+ * @brief Unregister the accuracy change callback from a sensor listener.
+ * @details Unregister the sensor accuracy change callback function attached to
+ * a given sensor listener.
* @since_tizen 2.3
*
* @param[in] listener A listener handle
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_listener_set_accuracy_cb()
+ * @code
+ * void accuracy_changed_callback(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_listener_set_accuracy_cb(listener, accuracy_changed_callback, NULL);
+ * ...
+ * sensor_listener_unset_accuracy_cb(listener);
+ * @endcode
*/
int sensor_listener_unset_accuracy_cb(sensor_listener_h listener);
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * sensor_event_s *events = NULL;
+ * int events_count = 0;
+ * sensor_listener_read_data_list(listener, &events, &events_count);
+ * @endcode
*/
int sensor_listener_read_data_list(sensor_listener_h listener, sensor_event_s **events, int *count);
/**
- * @brief Changes the update interval of a sensor.
+ * @brief Change the interval between updates for a given sensor.
* @details The specified interval is only a suggested interval between sensor measurements.
* You will get at least one sensor measurement within the interval you specify,
* but the actual interval between sensor measurements can be affected by other applications and the system.
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_get_min_interval()
+ * @code
+ * ...
+ * int interval = 1000;
+ * sensor_listener_set_interval(listener, interval);
+ * @endcode
*/
int sensor_listener_set_interval(sensor_listener_h listener, unsigned int interval_ms);
/**
- * @brief Sets the desired max batch latency of a sensor.
+ * @brief Sets the desired maximum batch latency of a sensor.
* @details Sensors that support batching may allow applications to change their maximum batch latencies.
* For example, if you set the latency as 10,000 ms, the sensor may store its data
* up to 10,000 ms, before delivering the data through the HAL.@n
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * int max_batch_latency = 10;
+ * sensor_listener_set_max_batch_latency(listener, max_batch_latency);
+ * @endcode
*/
int sensor_listener_set_max_batch_latency(sensor_listener_h listener, unsigned int max_batch_latency);
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * sensor_listener_set_attribute_int(listener,
+ * SENSOR_ATTRIBUTE_PAUSE_POLICY,
+ * SENSOR_PAUSE_ON_DISPLAY_OFF);
+ * @endcode
*/
int sensor_listener_set_attribute_int(sensor_listener_h listener, sensor_attribute_e attribute, int value);
/**
- * @brief Changes the power-saving behavior of a sensor listener.
+ * @brief Change the power-saving behavior of a sensor listener.
+ * @details Change the pause policy of a sensor listener, refer the values of
+ * sensor_option_e enum type for the available options.
* @since_tizen 2.3
*
* @remarks sensor_listener_set_attribute_int() with #SENSOR_ATTRIBUTE_PAUSE_POLICY replaces this function.
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * sensor_listener_set_option(listener, SENSOR_PAUSE_ON_DISPLAY_OFF);
+ * @endcode
*/
int sensor_listener_set_option(sensor_listener_h listener, sensor_option_e option);
/**
- * @brief Flushes stored data of a sensor.
- * @details Flushes all data of a sensor as if the max batch latency has expired.
+ * @brief Flush the stored sensor data for the given listener.
+ * @details Flush all data of a sensor as if the max batch latency has expired.
* Data is delivered in the usual way through the event callback function. @n
* In case of non-batching sensors, this function does nothing and returns #SENSOR_ERROR_NONE.
* @since_tizen 5.5
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * sensor_listener_flush(listener);
+ * @endcode
*/
int sensor_listener_flush(sensor_listener_h listener);
typedef struct _sensor_provider_s *sensor_provider_h;
/**
- * @brief Creates a sensor provider.
+ * @brief Create a sensor provider for a given valid URI string.
* @details This function creates a sensor provider handle with a given URI.
* The URI should be in the valid form described in \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI.
* In addition, it is not allowed to set the vendor in the URI to @"tizen.org@",
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_destroy_provider()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * @endcode
*/
int sensor_create_provider(const char *uri, sensor_provider_h *provider);
/**
- * @brief Registers the sensor provider.
+ * @brief Register the sensor provider created by sensor_create_provider().
* @details A sensor provider is created via sensor_create_provider(),
* and the three callback functions sensor_provider_start_cb(), sensor_provider_stop_cb(),
* and sensor_provider_set_interval_changed_cb() should be set in advance.
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_remove_provider()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * ...
+ * sensor_add_provider(sensor_provider);
+ * @endcode
*/
int sensor_add_provider(sensor_provider_h provider);
/**
- * @brief Unregisters the sensor provider.
+ * @brief Unregisters the given sensor provider registered by sensor_add_provider().
+ * @details A sensor provider that registered by sensor_add_provider() function
+ * call previously, can be unregistered by sensor_removed_provider().
* @since_tizen 4.0
*
* @param[in] provider The sensor provider handle
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_add_provider()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * ...
+ * sensor_add_provider(sensor_provider);
+ * ...
+ * sensor_remove_provider(sensor_provider);
+ * @endcode
*/
int sensor_remove_provider(sensor_provider_h provider);
/**
- * @brief Releases all the resources allocated for the sensor provider.
+ * @brief Destroy resources of the given sensor provider.
+ * @details Release all the resources allocated for the sensor provider by the
+ * function sensor_create_provider().
* @since_tizen 4.0
*
* @remarks If this function is called before sensor_remove_provider() is called,
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see sensor_create_provider()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * ...
+ * sensor_add_provider(sensor_provider);
+ * ...
+ * sensor_remove_provider(sensor_provider);
+ * sensor_destroy_provider(sensor_provider);
+ * @endcode
*/
int sensor_destroy_provider(sensor_provider_h provider);
/**
- * @brief Sets the name to the sensor provider.
+ * @brief Set the name of the given sensor provider as @a name.
+ * @details The name of the given sensor provider will be @a name if success.
* @since_tizen 4.0
*
* @param[in] provider The sensor provider handle
* @see sensor_provider_set_vendor()
* sensor_provider_set_range()
* sensor_provider_set_resolution()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * ...
+ * sensor_provider_set_name(sensor_provider, "heartbeat");
+ * @endcode
*/
int sensor_provider_set_name(sensor_provider_h provider, const char *name);
/**
- * @brief Sets the vendor to the sensor provider.
+ * @brief Set the vendor name of the given sensor provider as @a vendor.
+ * @details The vendor name of the given sensor provider will be @a vendor if
+ * success.
* @since_tizen 4.0
*
* @param[in] provider The sensor provider handle
* @see sensor_provider_set_name()
* sensor_provider_set_range()
* sensor_provider_set_resolution()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * ...
+ * sensor_provider_set_vendor(sensor_provider, "appsensor");
+ * @endcode
*/
int sensor_provider_set_vendor(sensor_provider_h provider, const char *vendor);
/**
- * @brief Sets the range of possible sensor values to the sensor provider.
+ * @brief Set the range of sensor values to the sensor provider.
+ * @details Set the range of possible sensor values to the sensor provider
+ * handle.
* @since_tizen 4.0
*
* @remarks If the application does not set the range, the default values are 0 and 1.
* @see sensor_provider_set_name()
* sensor_provider_set_vendor()
* sensor_provider_set_resolution()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * ...
+ * sensor_provider_set_range(sensor_provider, 0.0f, 1.0f);
+ * @endcode
*/
int sensor_provider_set_range(sensor_provider_h provider, float min_range, float max_range);
/**
- * @brief Sets the resolution of sensor values to the sensor provider.
+ * @brief Set the resolution of sensor values of the sensor provider.
+ * @details Set the resolution of sensor values as a float value of the given
+ * sensor provider.
* @since_tizen 4.0
*
* @remarks If the application does not set the resolution, the default value is 1.
* @see sensor_provider_set_name()
* sensor_provider_set_vendor()
* sensor_provider_set_range()
+ * @code
+ * const char *provider_uri = "http://appsensor/sensor/general/providersensor/heartbeat";
+ * sensor_provider_h sensor_provider;
+ * sensor_create_provider(provider_uri, &sensor_provider);
+ * ...
+ * sensor_provider_set_resolution(sensor_provider, 0.1f);
+ * @endcode
*/
int sensor_provider_set_resolution(sensor_provider_h provider, float resolution);
/**
- * @brief Called when a sensor listener starts the sensor provider.
+ * @brief Callback function type to be called when a sensor listener starts
+ * the sensor provider.
+ * @details Will be called when a sensor listener starts the sensor provider.
+ * Callback function can be added using function
+ * sensor_provider_set_start_cb().
* @since_tizen 4.0
*
* @remarks @a provider is the object created with sensor_create_provider()
*
* @pre A callback function needs to be set using sensor_provider_set_start_cb().
* @see sensor_provider_set_start_cb()
+ * @code
+ * void sensor_provider_start_callback(sensor_provider_h provider, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_provider_set_start_cb(provider, sensor_provider_start_callback, NULL);
+ * @endcode
*/
typedef void (*sensor_provider_start_cb)(sensor_provider_h provider, void *user_data);
/**
- * @brief Registers the callback function to be invoked when a listener starts the sensor provider.
+ * @brief Register the callback to be called when a listener starts the sensor
+ * provider.
+ * @details Register the callback function(sensor_provider_start_cb) to be
+ * invoked when a listener starts the sensor provider.
* @since_tizen 4.0
*
* @param[in] provider The provider handle
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
+ * @code
+ * void sensor_provider_start_callback(sensor_provider_h provider, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_provider_set_start_cb(provider, sensor_provider_start_callback, NULL);
+ * @endcode
*/
int sensor_provider_set_start_cb(sensor_provider_h provider,
sensor_provider_start_cb callback, void *user_data);
/**
- * @brief Called when a sensor listener stops the sensor provider.
+ * @brief Callback function type to be called when a sensor listener stops
+ * the sensor provider.
+ * @details Will be called when a sensor listener stops the sensor provider.
+ * Callback function can be added using function
+ * sensor_provider_set_stop_cb().
* @since_tizen 4.0
*
* @remarks @a provider is the object created with sensor_create_provider()
*
* @pre A callback function needs to be set using sensor_provider_set_stop_cb().
* @see sensor_provider_set_stop_cb()
+ * @code
+ * void sensor_provider_stop_callback(sensor_provider_h provider, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_provider_set_stop_cb(provider, sensor_provider_start_callback, NULL);
+ * @endcode
*/
typedef void (*sensor_provider_stop_cb)(sensor_provider_h provider, void *user_data);
/**
- * @brief Registers the callback function to be invoked when a sensor listener stops the sensor provider.
+ * @brief Register the callback to be called when a sensor listener stops the
+ * sensor provider.
+ * @details Register the callback function(sensor_provider_stop_cb) to be
+ * invoked when a sensor listener stops the sensor provider.
* @since_tizen 4.0
*
* @param[in] provider The sensor provider handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * void sensor_provider_stop_callback(sensor_provider_h provider, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_provider_set_stop_cb(provider, sensor_provider_start_callback, NULL);
+ * @endcode
*/
int sensor_provider_set_stop_cb(sensor_provider_h provider,
sensor_provider_stop_cb callback, void *user_data);
/**
- * @brief Called when the interval of the sensor provider is changed.
+ * @brief Callback function type to be called when the interval of the sensor
+ * provider is changed.
+ * @details Will be called when the interval of the sensor provider is changed.
+ * Callback function can be added using function
+ * sensor_provider_set_interval_changed_cb().
* @since_tizen 4.0
*
* @remarks @a provider is the object created with sensor_create_provider()
*
* @pre A callback function needs to be set using sensor_provider_set_interval_changed_cb().
* @see sensor_provider_set_interval_changed_cb()
+ * @code
+ * void sensor_provider_interval_change_callback(sensor_provider_h provider, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_provider_set_interval_changed_cb(provider, sensor_provider_interval_change_callback, NULL);
+ * @endcode
*/
typedef void (*sensor_provider_interval_changed_cb)(sensor_provider_h provider,
unsigned int interval_ms, void *user_data);
/**
- * @brief Registers the callback function to be invoked when the interval is changed.
+ * @brief Register the callback to be invoked when the interval is changed.
+ * @details Register the callback function(sensor_provider_interval_changed_cb)
+ * to be invoked when the interval is changed.
* @since_tizen 4.0
*
* @param[in] provider The sensor provider handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * void sensor_provider_interval_change_callback(sensor_provider_h provider, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_provider_set_interval_changed_cb(provider, sensor_provider_interval_change_callback, NULL);
+ * @endcode
*/
int sensor_provider_set_interval_changed_cb(sensor_provider_h provider,
sensor_provider_interval_changed_cb callback, void *user_data);
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * ...
+ * sensor_event_s events[10];
+ * ...
+ * for (int i = 0; i < 10; ++i) {
+ * events[i].accuracy = 3;
+ * events[i].timestamp = timestamp;
+ * events[i].value_count = 3;
+ * events[i].values[0] = i;
+ * events[i].values[1] = i + 2;
+ * events[i].values[2] = i + 4;
+ * }
+ * ...
+ * sensor_provider_publish_events(provider, events, 10);
+ * @endcode
*/
int sensor_provider_publish_events(sensor_provider_h provider, sensor_event_s events[], int count);
/**
* @brief Checks whether it is supported to record a given sensor type.
+ * @details Check if it is supported to record for a given sensor type and
+ * stores it to @a supported.
* @since_tizen 3.0
*
* @param[in] type A sensor type to check
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * bool is_supported = false;
+ * sensor_recorder_is_supported(SENSOR_ACCELEROMETER, &is_supported);
+ * @endcode
*/
int sensor_recorder_is_supported(sensor_type_e type, bool *supported);
/**
- * @brief Starts to record a given sensor type.
+ * @brief Start to record for a given sensor type with specified option.
+ * @details Start to record sensor for a given sensor type with specified
+ * option. Some sensor types are privileged, check remarks.
* @since_tizen 3.0
*
* @remarks Some sensor types are privileged. An application should have the privilege
* @retval #SENSOR_ERROR_NOT_AVAILABLE The sensor is already being recorded by the request of the current application
*
* @see sensor_recorder_stop()
+ * @code
+ * sensor_record_start(SENSOR_ACCELEROMETER, NULL);
+ * @endcode
*/
int sensor_recorder_start(sensor_type_e type, sensor_recorder_option_h option);
/**
- * @brief Stops recording a given sensor type.
+ * @brief Stop to record sensor which is started to record for a given sensor
+ * type.
+ * @details Stop the recording for a given sensor type, which is started by
+ * sensor_recorder_start().
* @since_tizen 3.0
*
* @param[in] type A sensor type being recorded
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_recorder_start()
+ * @code
+ * sensor_record_start(SENSOR_ACCELEROMETER, NULL);
+ * ...
+ * sensor_recorder_stop(SENSOR_ACCELEROMETER);
+ * @endcode
*/
int sensor_recorder_stop(sensor_type_e type);
/**
- * @brief Creates a recorder option handle.
+ * @brief Create a recorder option handle for sensor recorder.
+ * @details Allocate a recorder option handle and store it to @a option.
* @since_tizen 3.0
*
* @remarks The @a option must be released using sensor_recorder_destroy_option().
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_option_h option;
+ * sensor_recorder_create_option(&option);
+ * @endcode
*/
int sensor_recorder_create_option(sensor_recorder_option_h *option);
/**
- * @brief Destroys a recorder option handle.
+ * @brief Destroy a recorder option handle for sensor recorder.
+ * @details Destroy a recorder option which is stored in @a option.
* @since_tizen 3.0
*
* @param[in] option Option handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_option_h option;
+ * sensor_recorder_create_option(&option);
+ * ...
+ * sensor_recorder_destroy_option(option);
+ * @endcode
*/
int sensor_recorder_destroy_option(sensor_recorder_option_h option);
/**
- * @brief Sets a recording option parameter.
+ * @brief Set a recording option parameter to a given option handle @a option.
+ * @details Set @a option as a recording option parameter @a param as @a value.
* @since_tizen 3.0
*
* @param[in] option Option handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_option_h option;
+ * sensor_recorder_create_option(&option);
+ * sensor_recorder_option_set_int(option, SENSOR_RECORDER_OPTION_INTERVAL, 1000);
+ * @endcode
*/
int sensor_recorder_option_set_int(sensor_recorder_option_h option, sensor_recorder_option_e param, int value);
/**
- * @brief Creates a recorder query handle.
+ * @brief Create a recorder query handle for sensor recorder.
+ * @details Allocate a recorder query handle and store it to @a query.
* @since_tizen 3.0
*
* @remarks The @a query must be released using sensor_recorder_destroy_query().
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_query_h query;
+ * sensor_recorder_create_query(&query);
+ * @endcode
*/
int sensor_recorder_create_query(sensor_recorder_query_h *query);
/**
- * @brief Destroys a recorder query handle.
+ * @brief Destroy a recorder query handle for sensor recorder.
+ * @details Destroy a recorder query which is stored in @a query.
* @since_tizen 3.0
*
* @param[in] query Query handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_query_h query;
+ * sensor_recorder_create_query(&query);
+ * ...
+ * sensor_recorder_destroy_query(query);
+ * @endcode
*/
int sensor_recorder_destroy_query(sensor_recorder_query_h query);
/**
- * @brief Sets an integer-type query parameter
+ * @brief Set an integer-type query parameter for a sensor recorder query.
+ * @details Set a query parameter @a param as @a value for a given @a query.
* @since_tizen 3.0
*
* @param[in] query Query handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_query_h query;
+ * sensor_recorder_create_query(&query);
+ * sensor_recorder_query_set_int(query, SENSOR_RECORDER_QUERY_TIME_INTERVAL, 1);
+ * @endcode
*/
int sensor_recorder_query_set_int(sensor_recorder_query_h query, sensor_recorder_query_e param, int value);
/**
- * @brief Sets a time-type query parameter.
+ * @brief Set a time-type query parameter for a sensor recorder query.
+ * @details Set a query parameter @a param as @a value for a given @a query.
* @since_tizen 3.0
*
* @param[in] query Query handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_query_h query;
+ * sensor_recorder_create_query(&query);
+ * time_t start_time = time(NULL);
+ * sensor_recorder_query_set_time(query, SENSOR_RECORDER_QUERY_START_TIME, start_time);
+ * @endcode
*/
int sensor_recorder_query_set_time(sensor_recorder_query_h query, sensor_recorder_query_e param, time_t t);
/**
- * @brief Called when the query results are retrieved.
+ * @brief Callback function type to be called when the query results are retrieved.
* @details One of the following errors can be delivered.\n
* #SENSOR_ERROR_NONE, Successful\n
* #SENSOR_ERROR_OPERATION_FAILED, Operation failed\n
* @param[in] user_data The user data passed from sensor_recorder_read() or sensor_recorder_read_sync()
*
* @return If @c true, it continues to iterate to the next record; If @c false, the iteration stops
+ * @code
+ * bool sensor_recorder_data_callback(sensor_type_e type, sensor_recorder_data_h data, int remains, sensor_error_e error, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_recorder_read(type, query, sensor_recorder_data_callback, NULL);
+ * ...
+ * sensor_recorder_read_sync(type, query, sensor_recorder_data_callback, NULL);
+ * @endcode
*/
typedef bool (*sensor_recorder_data_cb)(sensor_type_e type, sensor_recorder_data_h data, int remains, sensor_error_e error, void *user_data);
/**
- * @brief Queries the recorded data asynchronously.
+ * @brief Query the recorded data asynchronously for the given sensor type.
+ * @details Query and call the callback function @a cb for the recorded data
+ * asynchronously.
* @since_tizen 3.0
*
* @remarks Some sensor types are privileged. An application should have the privilege
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
* @see sensor_recorder_read_sync()
+ * @code
+ * bool sensor_recorder_data_callback(sensor_type_e type, sensor_recorder_data_h data, int remains, sensor_error_e error, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_recorder_read(type, query, sensor_recorder_data_callback, NULL);
+ * @endcode
*/
int sensor_recorder_read(sensor_type_e type, sensor_recorder_query_h query, sensor_recorder_data_cb cb, void *user_data);
/**
- * @brief Queries the recorded data synchronously.
+ * @brief Query the recorded data synchronously for the given sensor type.
+ * @details Query and call the callback function @a cb for the recorded data
+ * synchronously.
* @since_tizen 3.0
*
* @remarks Some sensor types are privileged. An application should have the privilege
* @retval #SENSOR_ERROR_NO_DATA No data retrieved
*
* @see sensor_recorder_read()
+ * @code
+ * bool sensor_recorder_data_callback(sensor_type_e type, sensor_recorder_data_h data, int remains, sensor_error_e error, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * sensor_recorder_read_sync(type, query, sensor_recorder_data_callback, NULL);
+ * @endcode
*/
int sensor_recorder_read_sync(sensor_type_e type, sensor_recorder_query_h query, sensor_recorder_data_cb cb, void *user_data);
/**
- * @brief Gets the start and the end time of the time period of a given record data.
+ * @brief Get the start and the end time of the time period.
+ * @details Get the start/end time of the time period for a given record data.
* @since_tizen 3.0
*
* @param[in] data Record data handle
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * sensor_recorder_data_h data;
+ * ... // data(sensor_recorded_data_h) is assigned by sensor_recorder_read_sync().
+ * time_t start_time;
+ * time_t end_time;
+ * sensor_recorder_data_get_time(data, &start_time, &end_time);
+ * @endcode
*/
int sensor_recorder_data_get_time(sensor_recorder_data_h data, time_t *start_time, time_t *end_time);
/**
- * @brief Gets an integer value from a record data.
+ * @brief Get an integer value from a record data according to the @a key.
+ * @details Get an integer value from a given sensor record data according to
+ * the @a key and store it in @a value. For the available values of
+ * @a key, please refer the type sensor_recorder_data_e.
* @since_tizen 3.0
*
* @param[in] data Record data handle
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
* @retval #SENSOR_ERROR_NO_DATA No data retrieved
+ * @code
+ * int steps;
+ * sensor_recorder_data_get_int(data, SENSOR_RECORDER_DATA_STEPS, &steps);
+ * @endcode
*/
int sensor_recorder_data_get_int(sensor_recorder_data_h data, sensor_recorder_data_e key, int *value);
/**
- * @brief Gets a double value from a record data.
+ * @brief Get a double value from a record data according to the @a key.
+ * @details Get a double value from a given sensor record data according to the
+ * @a key and store it in @a value. For the available values of @a key,
+ * please refer the type sensor_recorder_data_e.
* @since_tizen 3.0
*
* @param[in] data Record data handle
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
* @retval #SENSOR_ERROR_NO_DATA No data retrieved
+ * @code
+ * double distance
+ * sensor_recorder_data_get_double(data, SENSOR_RECORDER_DATA_DISTANCE, &distance);
+ * @endcode
*/
int sensor_recorder_data_get_double(sensor_recorder_data_h data, sensor_recorder_data_e key, double *value);
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * float R[9];
+ * float I[9];
+ * sensor_util_get_rotation_matrix(Gx, Gy, Gz, Mx, My, Mz, R, I);
+ * @endcode
*/
int sensor_util_get_rotation_matrix(float Gx, float Gy, float Gz,
float Mx, float My, float Mz,
float R[], float I[]);
/**
- * @brief Converts a rotation vector to a rotation matrix.
+ * @brief Convert a rotation vector to a rotation matrix and store it to @a R.
*
* @details Rotation vectors (Vx, Vy, Vz) can be obtained from #SENSOR_ROTATION_VECTOR.
* It returns a 9 element rotation matrix in the array R. R must have length as 9.
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * float R[9];
+ * sensor_util_get_rotation_matrix_from_vector(Vx, Vy, Vz, R);
+ * @endcode
*/
int sensor_util_get_rotation_matrix_from_vector(float Vx, float Vy, float Vz, float R[]);
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
- *
+ * @code
+ * float inR[9];
+ * ...
+ * float outR[9];
+ * sensor_util_remap_coordinate_system(inR, SENSOR_UTIL_AXIS_X, SENSOR_UTIL_AXIS_Y, outR);
+ * @endcode
*/
int sensor_util_remap_coordinate_system(float inR[], sensor_util_axis_e x, sensor_util_axis_e y, float outR[]);
/**
- * @brief Computes the geomagnetic inclination angle in radians from the inclination matrix I returned by sensor_util_get_rotation_matrix().
+ * @brief Compute the geomagnetic inclination angle in radians from the
+ * inclination matrix.
+ * @details Compute the geomagnetic inclination angle in radians from the
+ * inclination matrix. Inclination matrix is a matrix which is returned
+ * by sensor_util_get_rotation_matrix().
* @since_tizen 2.3
*
* @param[in] I The inclination matrix from sensor_util_get_rotation_matrix()
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see sensor_util_get_rotation_matrix()
+ * @code
+ * float I[9];
+ * ...
+ * float inclination;
+ * sensor_util_get_inclination(I, &inclination);
+ * @endcode
*/
int sensor_util_get_inclination(float I[], float* inclination);
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see sensor_util_get_rotation_matrix()
- *
+ * @code
+ * float R[9];
+ * ...
+ * float values[3];
+ * sensor_util_get_orientation(R, values);
+ * @endcode
*/
int sensor_util_get_orientation(float R[], float values[]);
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * float R[9];
+ * float prevR[9];
+ * ...
+ * float angleChange[3];
+ * sensor_util_get_angle_change(R, prevR, float angleChange[]);
+ * @endcode
*/
int sensor_util_get_angle_change(float R[], float prevR[], float angleChange[]);
/**
- * @brief Gets the declination of the horizontal component of the magnetic field from true north, in degrees.
+ * @brief Get the declination in degrees from geodetic coordinates.
+ * @details Get the declination of the horizontal component of the magnetic
+ * field from true north, in degrees.
* @since_tizen 2.3
*
* @param[in] latitude The latitude in geodetic coordinates
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * float declination;
+ * sensor_util_get_declination(latitude, longitude, altitude, &declination);
+ * @endcode
*/
int sensor_util_get_declination(float latitude, float longitude, float altitude, float* declination);
/**
- * @brief Gets the altitude from the atmospheric pressure, the pressure at sea level and temperature, in meters.
+ * @brief Get the altitude in meters from pressure and temperature.
+ * @details Get the altitude from the atmospheric pressure, the pressure at sea
+ * level and temperature, in meters.
* @since_tizen 4.0
*
* @param[in] pressure The atmospheric pressure (hPa)
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * ...
+ * float altitude;
+ * sensor_util_get_altitude(pressure, sea_level_pressure, temperature, &altitude);
+ * @endcode
*/
int sensor_util_get_altitude(float pressure, float sea_level_pressure, float temperature, float* altitude);
projects / platform / core / api / sensor.git / commitdiff