Tizen Native API  5.5
Activity Recognition

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:

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]activityActivity recognized
[in]dataDetailed information of the recognized activity
[in]timestampThe time when the activity is recognized. Epoch time in seconds.
[in]errorAn 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_dataThe user data had passed to activity_start_recognition()
Precondition:
activity_start_recognition()
See also:
activity_get_accuracy()

Enumeration Type Documentation

Enumeration for recognition accuracy.

Since :
2.3
Enumerator:
ACTIVITY_ACCURACY_LOW 

Not accurate

ACTIVITY_ACCURACY_MID 

Moderate

ACTIVITY_ACCURACY_HIGH 

Highly accurate

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

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]handleActivity handle to be initialized
Returns:
0 on success, otherwise a negative error value
Return values:
ACTIVITY_ERROR_NONESuccessful
ACTIVITY_ERROR_INVALID_PARAMETERInvalid parameter used
ACTIVITY_ERROR_NOT_SUPPORTEDActivity recognition is not supported
ACTIVITY_ERROR_OPERATION_FAILEDOperation 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]dataActivity data received through activity_cb()
[out]accuracyAccuracy
Returns:
0 on success, otherwise a negative error value
Return values:
ACTIVITY_ERROR_NONESuccessful
ACTIVITY_ERROR_INVALID_PARAMETERInvalid parameter used
ACTIVITY_ERROR_NOT_SUPPORTEDActivity recognition is not supported
ACTIVITY_ERROR_OPERATION_FAILEDOperation 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]activityActivity type to be checked
[out]supportedtrue 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_NONESupported
ACTIVITY_ERROR_INVALID_PARAMETERInvalid parameter used
ACTIVITY_ERROR_NOT_SUPPORTEDThe activity is not supported
ACTIVITY_ERROR_OPERATION_FAILEDOperation failed because of a system error
ACTIVITY_ERROR_PERMISSION_DENIEDDoes 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]handleActivity handle to be released
Returns:
0 on success, otherwise a negative error value
Return values:
ACTIVITY_ERROR_NONESuccessful
ACTIVITY_ERROR_INVALID_PARAMETERInvalid parameter used
ACTIVITY_ERROR_NOT_SUPPORTEDActivity recognition is not supported
ACTIVITY_ERROR_OPERATION_FAILEDOperation 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]handleActivity handle to be used to control the activity event
[in]activityActivity type to be monitored
[in]callbackCallback function to receive activity events
[in]user_dataUser data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
ACTIVITY_ERROR_NONESuccessful
ACTIVITY_ERROR_INVALID_PARAMETERInvalid parameter used
ACTIVITY_ERROR_NOT_SUPPORTEDActivity recognition is not supported
ACTIVITY_ERROR_ALREADY_STARTEDThe handle is being used already
ACTIVITY_ERROR_OPERATION_FAILEDOperation failed because of a system error
ACTIVITY_ERROR_PERMISSION_DENIEDDoes not have permission to use this
Precondition:
activity_create()
Postcondition:
activity_recognition_cb()
See also:
activity_stop_recognition()

Stops recognizing the activity registered to the activity handle.

Since :
2.3
Parameters:
[in]handleActivity handle to release its callback function registered
Returns:
0 on success, otherwise a negative error value
Return values:
ACTIVITY_ERROR_NONESuccessful
ACTIVITY_ERROR_INVALID_PARAMETERInvalid parameter used
ACTIVITY_ERROR_NOT_SUPPORTEDActivity recognition is not supported
ACTIVITY_ERROR_NOT_STARTEDNothing is started using the handle
ACTIVITY_ERROR_OPERATION_FAILEDOperation failed because of a system error