From 8fa41d2cedc4b0384914d414ce7b73013c6d82c1 Mon Sep 17 00:00:00 2001 From: SangYoun Kwak Date: Mon, 23 Sep 2024 17:36:33 +0900 Subject: [PATCH] sensor: Update description of sensor APIs The description of sensor APIs are updated for the sections: @brief, @details, @remarks and @code. Notice: Descriptions of deprecated functions are not updated. Change-Id: I0883723c0597aac0ac65b9a3bf0d7740918cfe9a Signed-off-by: SangYoun Kwak --- include/sensor.h | 773 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 706 insertions(+), 67 deletions(-) diff --git a/include/sensor.h b/include/sensor.h index ecfba59..436c795 100644 --- a/include/sensor.h +++ b/include/sensor.h @@ -171,10 +171,15 @@ typedef enum /** * @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 * @@ -183,20 +188,32 @@ typedef enum * @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 @@ -206,6 +223,14 @@ int sensor_is_supported(sensor_type_e type, bool *supported); * @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); @@ -226,6 +251,12 @@ 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); @@ -337,6 +368,12 @@ int sensor_get_default_sensor_by_uri(const char *uri, sensor_h *sensor); * @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); @@ -362,12 +399,18 @@ int sensor_get_sensor_list(sensor_type_e type, sensor_h **list, int *sensor_coun * @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. @@ -378,11 +421,19 @@ int sensor_get_sensor_list_by_uri(const char *uri, sensor_h **list, int *sensor_ * @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. @@ -393,12 +444,20 @@ int sensor_get_uri(sensor_h sensor, char **uri); * @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. @@ -409,12 +468,21 @@ int sensor_get_name(sensor_h sensor, char **name); * @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 @@ -425,6 +493,11 @@ int sensor_get_vendor(sensor_h sensor, char **vendor); * @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); @@ -448,6 +521,11 @@ 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); @@ -471,6 +549,11 @@ 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); @@ -490,12 +573,18 @@ 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 @@ -505,12 +594,17 @@ int sensor_get_resolution(sensor_h sensor, float *resolution); * @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, @@ -526,12 +620,17 @@ int sensor_get_min_interval(sensor_h sensor, int *min_interval); * @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 @@ -551,12 +650,20 @@ int sensor_get_fifo_count(sensor_h sensor, int *fifo_count); * @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. @@ -568,11 +675,24 @@ int sensor_get_max_batch_count(sensor_h sensor, int *max_batch_count); * @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 @@ -584,11 +704,23 @@ typedef void (*sensor_added_cb)(const char *uri, void *user_data); * @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 @@ -599,11 +731,24 @@ int sensor_add_sensor_added_cb(sensor_added_cb callback, void *user_data); * @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. @@ -615,11 +760,24 @@ int sensor_remove_sensor_added_cb(sensor_added_cb 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 @@ -631,11 +789,23 @@ typedef void (*sensor_removed_cb)(const char *uri, void *user_data); * @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 @@ -646,6 +816,16 @@ int sensor_add_sensor_removed_cb(sensor_removed_cb callback, void *user_data); * @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); @@ -796,7 +976,9 @@ typedef void (*sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *us /** - * @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. @@ -808,11 +990,21 @@ typedef void (*sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *us * @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. @@ -822,12 +1014,24 @@ typedef void (*sensor_events_cb)(sensor_h sensor, sensor_event_s events[], int e * @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(). @@ -843,12 +1047,20 @@ typedef void (*sensor_accuracy_changed_cb)(sensor_h sensor, unsigned long long t * * @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, @@ -862,6 +1074,13 @@ int sensor_create_listener(sensor_h sensor, sensor_listener_h *listener); * @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); @@ -876,6 +1095,10 @@ 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 @@ -887,6 +1110,15 @@ int sensor_destroy_listener(sensor_listener_h listener); * 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); @@ -894,10 +1126,11 @@ 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 @@ -906,6 +1139,17 @@ int sensor_listener_start(sensor_listener_h listener); * @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); @@ -950,7 +1194,9 @@ int sensor_listener_unset_event_cb(sensor_listener_h listener) TIZEN_DEPRECATED_ /** - * @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 @@ -963,11 +1209,22 @@ int sensor_listener_unset_event_cb(sensor_listener_h listener) TIZEN_DEPRECATED_ * @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 @@ -978,6 +1235,15 @@ int sensor_listener_set_events_cb(sensor_listener_h listener, sensor_events_cb c * @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); @@ -999,12 +1265,24 @@ 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 @@ -1015,6 +1293,16 @@ int sensor_listener_set_accuracy_cb(sensor_listener_h listener, sensor_accuracy_ * @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); @@ -1070,11 +1358,17 @@ int sensor_listener_read_data(sensor_listener_h listener, sensor_event_s *event) * @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. @@ -1100,12 +1394,17 @@ int sensor_listener_read_data_list(sensor_listener_h listener, sensor_event_s ** * @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 @@ -1124,6 +1423,11 @@ int sensor_listener_set_interval(sensor_listener_h listener, unsigned int interv * @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); @@ -1143,12 +1447,20 @@ int sensor_listener_set_max_batch_latency(sensor_listener_h listener, unsigned i * @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. @@ -1160,12 +1472,16 @@ int sensor_listener_set_attribute_int(sensor_listener_h listener, sensor_attribu * @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 @@ -1175,6 +1491,10 @@ int sensor_listener_set_option(sensor_listener_h listener, sensor_option_e optio * @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); @@ -1199,7 +1519,7 @@ 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@", @@ -1223,11 +1543,16 @@ typedef struct _sensor_provider_s *sensor_provider_h; * @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. @@ -1242,11 +1567,20 @@ int sensor_create_provider(const char *uri, sensor_provider_h *provider); * @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 @@ -1257,11 +1591,22 @@ int sensor_add_provider(sensor_provider_h provider); * @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, @@ -1274,11 +1619,22 @@ int sensor_remove_provider(sensor_provider_h provider); * @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 @@ -1292,11 +1648,20 @@ int sensor_destroy_provider(sensor_provider_h provider); * @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 @@ -1310,11 +1675,20 @@ int sensor_provider_set_name(sensor_provider_h provider, const char *name); * @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. @@ -1331,11 +1705,20 @@ int sensor_provider_set_vendor(sensor_provider_h provider, const char *vendor); * @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. @@ -1351,12 +1734,23 @@ int sensor_provider_set_range(sensor_provider_h provider, float min_range, float * @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() @@ -1367,11 +1761,22 @@ int sensor_provider_set_resolution(sensor_provider_h provider, float resolution) * * @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 @@ -1383,13 +1788,25 @@ typedef void (*sensor_provider_start_cb)(sensor_provider_h provider, void *user_ * @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() @@ -1400,11 +1817,22 @@ int sensor_provider_set_start_cb(sensor_provider_h 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 @@ -1415,13 +1843,25 @@ typedef void (*sensor_provider_stop_cb)(sensor_provider_h provider, void *user_d * @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() @@ -1433,12 +1873,22 @@ int sensor_provider_set_stop_cb(sensor_provider_h 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 @@ -1449,6 +1899,14 @@ typedef void (*sensor_provider_interval_changed_cb)(sensor_provider_h provider, * @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); @@ -1494,6 +1952,21 @@ int sensor_provider_publish(sensor_provider_h provider, sensor_event_s event) TI * @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); @@ -1601,6 +2074,8 @@ typedef enum /** * @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 @@ -1610,11 +2085,17 @@ typedef enum * @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 @@ -1635,11 +2116,17 @@ int sensor_recorder_is_supported(sensor_type_e type, bool *supported); * @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 @@ -1651,11 +2138,17 @@ int sensor_recorder_start(sensor_type_e type, sensor_recorder_option_h option); * @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(). @@ -1667,11 +2160,16 @@ int sensor_recorder_stop(sensor_type_e type); * @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 @@ -1680,11 +2178,18 @@ int sensor_recorder_create_option(sensor_recorder_option_h *option); * @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 @@ -1695,11 +2200,17 @@ int sensor_recorder_destroy_option(sensor_recorder_option_h option); * @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(). @@ -1711,11 +2222,16 @@ int sensor_recorder_option_set_int(sensor_recorder_option_h option, sensor_recor * @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 @@ -1724,11 +2240,18 @@ int sensor_recorder_create_query(sensor_recorder_query_h *query); * @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 @@ -1739,11 +2262,17 @@ int sensor_recorder_destroy_query(sensor_recorder_query_h query); * @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 @@ -1754,11 +2283,17 @@ int sensor_recorder_query_set_int(sensor_recorder_query_h query, sensor_recorder * @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 @@ -1772,11 +2307,23 @@ int sensor_recorder_query_set_time(sensor_recorder_query_h query, sensor_recorde * @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 @@ -1798,11 +2345,21 @@ typedef bool (*sensor_recorder_data_cb)(sensor_type_e type, sensor_recorder_data * @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 @@ -1825,11 +2382,20 @@ int sensor_recorder_read(sensor_type_e type, sensor_recorder_query_h query, sens * @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 @@ -1840,11 +2406,21 @@ int sensor_recorder_read_sync(sensor_type_e type, sensor_recorder_query_h query, * @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 @@ -1856,11 +2432,18 @@ int sensor_recorder_data_get_time(sensor_recorder_data_h data, time_t *start_tim * @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 @@ -1872,6 +2455,10 @@ int sensor_recorder_data_get_int(sensor_recorder_data_h data, sensor_recorder_da * @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); @@ -1937,13 +2524,19 @@ typedef enum * @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. @@ -1957,6 +2550,11 @@ int sensor_util_get_rotation_matrix(float Gx, float Gy, float Gz, * @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[]); @@ -1977,12 +2575,21 @@ int sensor_util_get_rotation_matrix_from_vector(float Vx, float Vy, float Vz, fl * @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() @@ -1993,6 +2600,12 @@ int sensor_util_remap_coordinate_system(float inR[], sensor_util_axis_e x, senso * @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); @@ -2016,7 +2629,12 @@ 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[]); @@ -2042,11 +2660,20 @@ 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 @@ -2057,11 +2684,18 @@ int sensor_util_get_angle_change(float R[], float prevR[], float angleChange[]); * @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) @@ -2074,6 +2708,11 @@ int sensor_util_get_declination(float latitude, float longitude, float altitude, * @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); -- 2.34.1