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
	Handle for controlling the activity recognizer.
typedef struct _activity_data_s *	activity_data_h
	Activity data handle delivered through activity_recognition_cb()
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.

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.

Typedef Documentation

typedef struct _activity_data_s* activity_data_h

Activity data handle delivered through activity_recognition_cb()

Since :: 2.3

typedef struct _activity_handle_s* activity_h

Handle for controlling the activity recognizer.

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

Recognition accuracy.

Since :: 2.3

Enumerator:

ACTIVITY_ACCURACY_LOW	Not accurate
ACTIVITY_ACCURACY_MID	Moderate
ACTIVITY_ACCURACY_HIGH	Highly accurate

enum activity_error_e

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

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.

Functions

Typedefs

Required Header

Overview

Related Features

Typedef Documentation

Enumeration Type Documentation

Function Documentation