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

Enumeration for recognition accuracy.

Since :: 2.3

Enumerator:

ACTIVITY_ACCURACY_LOW	Not accurate
ACTIVITY_ACCURACY_MID	Moderate
ACTIVITY_ACCURACY_HIGH	Highly accurate

enum activity_error_e

Enumeration for error codes.

Since :: 2.3

Enumerator:

ACTIVITY_ERROR_NONE	Successful
ACTIVITY_ERROR_INVALID_PARAMETER	Invalid function parameter
ACTIVITY_ERROR_INVALID_OPERATION	Function not implemented
ACTIVITY_ERROR_OUT_OF_MEMORY	Out of memory
ACTIVITY_ERROR_PERMISSION_DENIED	Permission denied
ACTIVITY_ERROR_NOT_SUPPORTED	Not supported
ACTIVITY_ERROR_ALREADY_STARTED	Recognition is already started
ACTIVITY_ERROR_NOT_STARTED	Recognition is not started
ACTIVITY_ERROR_OPERATION_FAILED	Operation failed because of a system error

enum activity_type_e

Enumeration for activity types.

Since :: 2.3

Enumerator:

ACTIVITY_STATIONARY	Stationary
ACTIVITY_WALK	Walking
ACTIVITY_RUN	Running
ACTIVITY_IN_VEHICLE	In a moving vehicle

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 the activity 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 supported
ACTIVITY_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 already
ACTIVITY_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

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation