Tizen Native API
5.5
|
The activity recognition API allows applications to be notified and react when a user activity is recognized.
Required Header
#include <activity_recognition.h>
Overview
The activity recognition API allows to register callback functions to be called when a user activity is recognized, for example, the user starts to run.
Available activity types are listed in activity_type_e. Applications can check whether each activity type is recognizable in the current device using activity_is_supported().
bool supported = false; activity_is_supported(ACTIVITY_RUN, &supported); if (!supported) { // Not supported in the current device. }
Regarding a recognizable activity, an application can set and unset a callback function as follows.
First, an activity handle needs to be initialized. With the handle
, a callback function can be registered by activity_start_recognition().
activity_h handle; result = activity_create(&handle); if (result != ACTIVITY_ERROR_NONE) { // An error occurred. } result = activity_start_recognition(handle, ACTIVITY_RUN, activity_cb, NULL); if (result != ACTIVITY_ERROR_NONE) { // An error occurred. Do necessary error handling here. }
Note that, calling activity_start_recognition() twice on the same handle returns ACTIVITY_ERROR_ALREADY_STARTED. If the application needs to recognize multiple activities, it needs to created multiple handles, one handle for each activity type.
Once the activity recognition is started, the callback function is called if the registered activity is detected. Here is an example of the callback function.
void activity_cb(activity_type_e type, const activity_data_h data, double timestamp, activity_error_e error, void *user_data) { int result; activity_accuracy_e accuracy; if (error != ACTIVITY_ERROR_NONE) { // An error occurred. Do necessary error handling here. return; } if (type == ACTIVITY_RUN) { // More than one activities can be started using the same callback function. result = activity_get_accuracy(data, &accuracy); if (result != GESTURE_ERROR_NONE) { // An error occurred. Do necessary error handling here. return; } // ... } }
Finally, if the application does not need to be notified the activity event, it can be stopped as follows.
activity_stop_recognition(handle); // If the handle will not be used anymore, its resources needs be released explicitly. activity_release(handle);
Related Features
This API is related with the following features:
- http://tizen.org/feature/sensor.activity_recognition
It is recommended to design feature related code in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Functions | |
int | activity_is_supported (activity_type_e activity, bool *supported) |
Check whether the activity is supported or not. | |
int | activity_create (activity_h *handle) |
Initializes an activity handle. | |
int | activity_release (activity_h handle) |
Releases the resources occupied by the activity handle. | |
int | activity_start_recognition (activity_h handle, activity_type_e activity, activity_recognition_cb callback, void *user_data) |
Starts to recognize an activity. | |
int | activity_stop_recognition (activity_h handle) |
Stops recognizing the activity registered to the activity handle. | |
int | activity_get_accuracy (const activity_data_h data, activity_accuracy_e *accuracy) |
Gets the recognition accuracy. | |
Typedefs | |
typedef struct _activity_handle_s * | activity_h |
The activity recognizer controlling handle. | |
typedef struct _activity_data_s * | activity_data_h |
Delivery through activity_recognition_cb() of activity data handle. | |
typedef void(* | activity_recognition_cb )(activity_type_e activity, const activity_data_h data, double timestamp, activity_error_e error, void *user_data) |
Called when a activity is recognized. |
Typedef Documentation
typedef struct _activity_data_s* activity_data_h |
Delivery through activity_recognition_cb() of activity data handle.
- Since :
- 2.3
typedef struct _activity_handle_s* activity_h |
The activity recognizer controlling handle.
- Since :
- 2.3
typedef void(* activity_recognition_cb)(activity_type_e activity, const activity_data_h data, double timestamp, activity_error_e error, void *user_data) |
Called when a activity is recognized.
- Since :
- 2.3
- Parameters:
-
[in] activity Activity recognized [in] data Detailed information of the recognized activity [in] timestamp The time when the activity is recognized. Epoch time in seconds. [in] error An error value. It can be one of the following error values:
ACTIVITY_ERROR_NONE, if the operation succeeded.
ACTIVITY_ERROR_NOT_SUPPORTED, if the activity is not supported in the current profile.
ACTIVITY_ERROR_OPERATION_FAILED, if the operation failed because of a system error.
ACTIVITY_ERROR_PERMISSION_DENIED, if the application has no permission to use this.[in] user_data The user data had passed to activity_start_recognition()
- Precondition:
- activity_start_recognition()
- See also:
- activity_get_accuracy()
Enumeration Type Documentation
enum activity_accuracy_e |
enum activity_error_e |
Enumeration for error codes.
- Since :
- 2.3
- Enumerator:
enum activity_type_e |
Function Documentation
int activity_create | ( | activity_h * | handle | ) |
Initializes an activity handle.
- Since :
- 2.3
- Parameters:
-
[out] handle Activity handle to be initialized
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ACTIVITY_ERROR_NONE Successful ACTIVITY_ERROR_INVALID_PARAMETER Invalid parameter used ACTIVITY_ERROR_NOT_SUPPORTED Activity recognition is not supported ACTIVITY_ERROR_OPERATION_FAILED Operation failed because of a system error, e.g., out of memory
- See also:
- activity_release()
int activity_get_accuracy | ( | const activity_data_h | data, |
activity_accuracy_e * | accuracy | ||
) |
Gets the recognition accuracy.
- Since :
- 2.3
- Parameters:
-
[in] data Activity data received through activity_cb() [out] accuracy Accuracy
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ACTIVITY_ERROR_NONE Successful ACTIVITY_ERROR_INVALID_PARAMETER Invalid parameter used ACTIVITY_ERROR_NOT_SUPPORTED Activity recognition is not supported ACTIVITY_ERROR_OPERATION_FAILED Operation failed because of a system error
int activity_is_supported | ( | activity_type_e | activity, |
bool * | supported | ||
) |
Check whether the activity is supported or not.
Check if the given activity type is supported in the current device.
- Since :
- 2.3
- Parameters:
-
[in] activity Activity type to be checked [out] supported true
if the activity is recognizable in the current device,
false
otherwise
- Returns:
0
if theactivity
is supported, otherwise a negative error value
- Return values:
-
ACTIVITY_ERROR_NONE Supported ACTIVITY_ERROR_INVALID_PARAMETER Invalid parameter used ACTIVITY_ERROR_NOT_SUPPORTED The activity
is not supportedACTIVITY_ERROR_OPERATION_FAILED Operation failed because of a system error ACTIVITY_ERROR_PERMISSION_DENIED Does not have permission to use this
int activity_release | ( | activity_h | handle | ) |
Releases the resources occupied by the activity handle.
- Since :
- 2.3
- Parameters:
-
[in] handle Activity handle to be released
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ACTIVITY_ERROR_NONE Successful ACTIVITY_ERROR_INVALID_PARAMETER Invalid parameter used ACTIVITY_ERROR_NOT_SUPPORTED Activity recognition is not supported ACTIVITY_ERROR_OPERATION_FAILED Operation failed because of a system error
- Precondition:
- activity_create()
int activity_start_recognition | ( | activity_h | handle, |
activity_type_e | activity, | ||
activity_recognition_cb | callback, | ||
void * | user_data | ||
) |
Starts to recognize an activity.
Sets a callback function to be invoked when the activity is detected, and starts to monitor occurrences of the activity.
- Since :
- 2.3
- Parameters:
-
[in] handle Activity handle to be used to control the activity event [in] activity Activity type to be monitored [in] callback Callback function to receive activity events [in] user_data User data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ACTIVITY_ERROR_NONE Successful ACTIVITY_ERROR_INVALID_PARAMETER Invalid parameter used ACTIVITY_ERROR_NOT_SUPPORTED Activity recognition is not supported ACTIVITY_ERROR_ALREADY_STARTED The handle
is being used alreadyACTIVITY_ERROR_OPERATION_FAILED Operation failed because of a system error ACTIVITY_ERROR_PERMISSION_DENIED Does not have permission to use this
- Precondition:
- activity_create()
- Postcondition:
- activity_recognition_cb()
- See also:
- activity_stop_recognition()
int activity_stop_recognition | ( | activity_h | handle | ) |
Stops recognizing the activity registered to the activity handle.
- Since :
- 2.3
- Parameters:
-
[in] handle Activity handle to release its callback function registered
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ACTIVITY_ERROR_NONE Successful ACTIVITY_ERROR_INVALID_PARAMETER Invalid parameter used ACTIVITY_ERROR_NOT_SUPPORTED Activity recognition is not supported ACTIVITY_ERROR_NOT_STARTED Nothing is started using the handle
ACTIVITY_ERROR_OPERATION_FAILED Operation failed because of a system error