All watch applications can request data shared by other watchface complication provider applications using watchface complication.

Required Header

#include <watchface-complication.h>

Overview

It provides watchface complication data request and receive service.

Functions
int	watchface_complication_get_current_provider_id (complication_h handle, char **cur_provider)
	Gets the id of provider in the complication.
int	watchface_complication_get_current_type (complication_h handle, watchface_complication_type_e *cur_type)
	Gets the currently set type of the complication.
int	watchface_complication_add_updated_cb (complication_h handle, watchface_complication_updated_cb cb, watchface_complication_error_cb error_cb, void *user_data)
	Adds the callback function to use for complication update.
int	watchface_complication_remove_updated_cb (complication_h handle, watchface_complication_updated_cb cb)
	Removes the callback function.
int	watchface_complication_send_update_request (complication_h handle)
	Sends request the provider to update the complication.
int	watchface_complication_create (int complication_id, const char default_provider_id, watchface_complication_type_e default_type, int supported_types, int supported_event_types, complication_h created_handle)
	Creates a complication handle.
int	watchface_complication_destroy (complication_h handle)
	Destroys a complication handle.
int	watchface_complication_data_get_type (const bundle data, watchface_complication_type_e type)
	Gets data type of complication data.
int	watchface_complication_data_get_short_text (const bundle data, char *short_text)
	Gets short text from complication data.
int	watchface_complication_data_get_long_text (const bundle data, char *long_text)
	Gets long text from complication data.
int	watchface_complication_data_get_title (const bundle data, char *title)
	Gets title text from complication data.
int	watchface_complication_data_get_timestamp (const bundle data, long timestamp)
	Gets timestamp from complication data.
int	watchface_complication_data_get_image_path (const bundle data, char *image_path)
	Gets image path from complication data.
int	watchface_complication_data_get_ranged_value (const bundle data, double current_value, double min_value, double max_value)
	Gets ranged value from complication data.
int	watchface_complication_data_get_icon_path (const bundle data, char *icon_path)
	Gets icon path from complication data.
int	watchface_complication_data_get_extra_data (const bundle data, char *extra_data)
	Gets extra data from complication data.
int	watchface_complication_data_get_screen_reader_text (const bundle data, char *screen_reader_text)
	Gets screen reader text from complication data.
int	watchface_complication_transfer_event (complication_h handle, watchface_complication_event_type_e event_type)
	Transfers touch event to the complication provider.
int	watchface_complication_allowed_list_create (complication_allowed_list_h *handle)
	Creates allowed list.
int	watchface_complication_allowed_list_destroy (complication_allowed_list_h handle)
	Destroys allowed list.
int	watchface_complication_allowed_list_add (complication_allowed_list_h handle, const char *provider_id, int types)
	Adds provider info to the allowed list.
int	watchface_complication_allowed_list_delete (complication_allowed_list_h handle, const char *provider_id)
	Deletes provider info from the allowed list.
int	watchface_complication_allowed_list_get_nth (complication_allowed_list_h handle, int index, char *provider_id, int types)
	Gets n-th item of the allowed list.
int	watchface_complication_allowed_list_apply (complication_h handle, complication_allowed_list_h list_handle)
	Applies the allowed list to a complication.
int	watchface_complication_allowed_list_clear (complication_h handle)
	Removes applied allowed list.
Typedefs
typedef void *	complication_h
	The complication handle.
typedef void(*	watchface_complication_updated_cb )(int complication_id, const char provider_id, watchface_complication_type_e type, const bundle data, void *user_data)
	Called when the complication is updated.
typedef void(*	watchface_complication_error_cb )(int complication_id, const char provider_id, watchface_complication_type_e type, watchface_complication_error_e error, void user_data)
	Called when the complication provider error is occured.
typedef struct complication_allowed_list_ *	complication_allowed_list_h
	The complication allowed list handle.

Typedef Documentation

typedef struct complication_allowed_list_* complication_allowed_list_h

The complication allowed list handle.

Since :: 5.0

typedef void* complication_h

The complication handle.

Since :: 5.0

typedef void(* watchface_complication_error_cb)(int complication_id, const char *provider_id, watchface_complication_type_e type, watchface_complication_error_e error, void *user_data)

Called when the complication provider error is occured.

Following error codes can be delivered. WATCHFACE_COMPLICATION_ERROR_PROVIDER_NOT_AVAILABLE : Provider application is not available now for some reason. (eg. uninstall, disable)
WATCHFACE_COMPLICATION_ERROR_IO_ERROR : Provider application is not responding for update request.
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY : Out of memory.

Since :: 5.0

Parameters:

[in]	complication_id	A number that identifies the complication
[in]	provider_id	The name of the provider. The provider_id can be used only in the callback. To use outside, make a copy.
[in]	type	The type shown in the complication
[in]	error	The error related with complication provider
[in]	user_data	The user data passed from the callback function

typedef void(* watchface_complication_updated_cb)(int complication_id, const char *provider_id, watchface_complication_type_e type, const bundle *data, void *user_data)

Called when the complication is updated.

Since :: 5.0

Parameters:

[in]	complication_id	A number that identifies the complication
[in]	provider_id	The name of the provider The provider_id can be used only in the callback. To use outside, make a copy.
[in]	type	The type shown in the complication
[in]	data	The data of the complication provided by the provider The data can be used only in the callback. To use outside, make a copy.
[in]	user_data	The user data passed from the callback function

Function Documentation

int watchface_complication_add_updated_cb	(	complication_h	handle,
		watchface_complication_updated_cb	cb,
		watchface_complication_error_cb	error_cb,
		void *	user_data
	)

Adds the callback function to use for complication update.

Since :: 5.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/datasharing

Parameters:

[in]	handle	Complication handle
[in]	cb	The callback function
[in]	error_cb	The error callback function
[in]	user_data	The user data to pass to the callback function

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Success
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported
WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED	Permission denied
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error

Precondition:: Complication handle should be created by watchface_complication_create().

See also:: watchface_complication_updated_cb(); watchface_complication_error_cb()

Sample code:

#include <watchface-complication.h>
{
    int ret;
    int comp_id = 1;
    complication_h complication;

    ret = watchface_complication_create(comp_id, "org.tizen.sample",
        WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
        WATCHFACE_COMPLICATION_EVENT_TAP,
        &complication);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
        return ret;

    ret = watchface_complication_add_updated_cb(complication,
            _watchface_complication_updated_cb,
            _watchface_complication_error_cb, NULL);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
        return ret;
}

int watchface_complication_allowed_list_add	(	complication_allowed_list_h	handle,
		const char *	provider_id,
		int	types
	)

Adds provider info to the allowed list.

Using this function the complication can add provider id and types which will be shown on the editor app's candidate provider list.

Since :: 5.0

Parameters:

[in]	handle	The complication allowed list handle
[in]	provider_id	The complication provider id
[in]	types	The complication types, values of watchface_complication_type_e combined with bitwise 'or'

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_EXIST_ID	The provider id is already exists in allowed list
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_allowed_list_create(); watchface_complication_allowed_list_destroy(); watchface_complication_allowed_list_delete(); watchface_complication_allowed_list_get_nth(); watchface_complication_allowed_list_apply(); watchface_complication_allowed_list_clear()

Sample code:

#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE)
      ret = watchface_complication_allowed_list_add(handle, provider_id, types);
}

int watchface_complication_allowed_list_apply	(	complication_h	handle,
		complication_allowed_list_h	list_handle
	)

Applies the allowed list to a complication.

After using this function, the editor will display providers included in the allowed list handle.

Since :: 5.0

Parameters:

[in]	handle	The complication handle
[in]	list_handle	The allowed list handle

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_DB	Database error
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_allowed_list_create(); watchface_complication_allowed_list_destroy(); watchface_complication_allowed_list_add(); watchface_complication_allowed_list_delete(); watchface_complication_allowed_list_get_nth(); watchface_complication_allowed_list_clear()

Sample code:

#include <watchface-complication.h>

{
  complication_h handle;
  complication_allowed_list_h allowed_list;

  // create complication handle

  int ret = watchface_complication_allowed_list_create(&allowed_list);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(allowed_list, provider_id);
        watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      }
      watchface_complication_allowed_list_get_nth(allowed_list, 0, &n_provider_id, &n_types);
      watchface_complication_allowed_list_apply(handle, allowed_list);
  }
}

int watchface_complication_allowed_list_clear ( complication_h handle )

Removes applied allowed list.

Since :: 5.0

Parameters:

[in] handle The complication allowed list handle

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_allowed_list_create(); watchface_complication_allowed_list_destroy(); watchface_complication_allowed_list_add(); watchface_complication_allowed_list_delete(); watchface_complication_allowed_list_get_nth(); watchface_complication_allowed_list_apply()

Sample code:

#include <watchface-complication.h>

{
  complication_h handle;
  complication_allowed_list_h allowed_list;

  // create complication handle

  int ret = watchface_complication_allowed_list_create(&allowed_list);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(allowed_list, provider_id);
        watchface_complication_allowed_list_add(allowed_list, provider_id, types);
      }
      watchface_complication_allowed_list_get_nth(allowed_list, 0, &n_provider_id, &n_types);
      watchface_complication_allowed_list_apply(handle, allowed_list);
      watchface_complication_allowed_list_clear(handle);
  }
}

int watchface_complication_allowed_list_create ( complication_allowed_list_h * handle )

Creates allowed list.

The allowed list created by this function is provider list which will be shown on the editor app's candidate provider list.

Since :: 5.0

Remarks:: Created allowed list should be applied with watchface_complication_allowed_list_apply(). Created allowed list should be destroyed after applied.

Parameters:

[in] handle The complication allowed list handle

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_allowed_list_destroy(); watchface_complication_allowed_list_add(); watchface_complication_allowed_list_delete(); watchface_complication_allowed_list_get_nth(); watchface_complication_allowed_list_apply(); watchface_complication_allowed_list_clear()

Sample code:

#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
}

int watchface_complication_allowed_list_delete	(	complication_allowed_list_h	handle,
		const char *	provider_id
	)

Deletes provider info from the allowed list.

Since :: 5.0

Parameters:

[in]	handle	The complication allowed list handle
[in]	provider_id	The complication provider id

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_allowed_list_create(); watchface_complication_allowed_list_destroy(); watchface_complication_allowed_list_add(); watchface_complication_allowed_list_get_nth(); watchface_complication_allowed_list_apply(); watchface_complication_allowed_list_clear()

Sample code:

#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(handle, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(handle, provider_id);
        watchface_complication_allowed_list_add(handle, provider_id, types);
      }
  }
}

int watchface_complication_allowed_list_destroy ( complication_allowed_list_h handle )

Destroys allowed list.

Since :: 5.0

Parameters:

[in] handle The complication allowed list handle

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_allowed_list_create(); watchface_complication_allowed_list_add(); watchface_complication_allowed_list_delete(); watchface_complication_allowed_list_get_nth(); watchface_complication_allowed_list_apply(); watchface_complication_allowed_list_clear()

Sample code:

#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  ret = watchface_complication_allowed_list_destroy(handle);
}

int watchface_complication_allowed_list_get_nth	(	complication_allowed_list_h	handle,
		int	index,
		char **	provider_id,
		int *	types
	)

Gets n-th item of the allowed list.

Since :: 5.0

Remarks:: The provider_id should be freed using free().

Parameters:

[in]	handle	The complication allowed list handle
[in]	index	Index
[out]	provider_id	The complication provider id
[out]	types	The complication types, values of watchface_complication_type_e combined with bitwise 'or'

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_allowed_list_create(); watchface_complication_allowed_list_destroy(); watchface_complication_allowed_list_add(); watchface_complication_allowed_list_delete(); watchface_complication_allowed_list_apply(); watchface_complication_allowed_list_clear()

Sample code:

#include <watchface-complication.h>

{
  complication_allowed_list_h handle;
  int ret = watchface_complication_allowed_list_create(&handle);
  if (ret == WATCHFACE_COMPLICATION_ERROR_NONE) {
      ret = watchface_complication_allowed_list_add(handle, provider_id, types);
      if (ret == WATCHFACE_COMPLICATION_ERROR_EXIST_ID) {
        watchface_complication_allowed_list_delete(handle, provider_id);
        watchface_complication_allowed_list_add(handle, provider_id, types);
      }
      watchface_complication_allowed_list_get_nth(handle, 0, &n_provider_id, &n_types);
  }
}

int watchface_complication_create	(	int	complication_id,
		const char *	default_provider_id,
		watchface_complication_type_e	default_type,
		int	supported_types,
		int	supported_event_types,
		complication_h *	created_handle
	)

Creates a complication handle.

The default provider and type are the items to set for initial display. User should not enter null as the default provider and will receive an error. If user selects the other provider and type, they are no longer used. You can specify supported_types by combining the types you want to show in the complication. You can specify supported_event_types by combining the event types you want to handle for the complication.

Since :: 5.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/packagemanager.info

Remarks:: The created_handle should be released using watchface_complication_destroy(). Package manager privilege is needed to lookup provider application.

Parameters:

[in]	complication_id	A number that identifies the complication
[in]	default_provider_id	The default provider id
[in]	default_type	The default type to display
[in]	supported_types	The type shown in the complication, values of watchface_complication_type_e combined with bitwise 'or'.
[in]	supported_event_types	The event type supported by complication, values of watchface_complication_event_type_e combined with bitwise 'or'. Complication can send supported event to the provider using watchface_complication_transfer_event().
[out]	created_handle	Complication handle on success

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Success
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_EXIST_ID	Already exist complication_id
WATCHFACE_COMPLICATION_ERROR_NOT_EXIST	Provider does not exist
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_DB	Database error
WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED	Permission denied
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported
WATCHFACE_COMPLICATION_ERROR_PROVIDER_NOT_AVAILABLE	Provider application is not available now for some reason. (eg. uninstall, disable)

See also:: watchface_complication_type_e; watchface_complication_event_type_e; watchface_complication_transfer_event()

Sample code:

#include <watchface-complication.h>

complication_h complication;
void on_tap() {
    watchface_complication_transfer_event(complication,
            WATCHFACE_COMPLICATION_EVENT_TAP);
}

{
    int ret;
    int comp_id = 1;

    ret = watchface_complication_create(comp_id, "org.tizen.sample",
        WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
        WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT|WATCHFACE_COMPLICATION_TYPE_ICON,
        WATCHFACE_COMPLICATION_EVENT_TAP,
        &complication);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
        return ret;
}

int watchface_complication_data_get_extra_data	(	const bundle *	data,
		char **	extra_data
	)

Gets extra data from complication data.

Since :: 5.0

Remarks:: The extra_data should be freed using free().

Parameters:

[in]	data	The data received from complication provider app
[out]	extra_data	The extra data

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    char *value;
    watchface_complication_data_get_extra_data(data, &value);
}

int watchface_complication_data_get_icon_path	(	const bundle *	data,
		char **	icon_path
	)

Gets icon path from complication data.

Since :: 5.0

Remarks:: The icon_path should be freed using free().

Parameters:

[in]	data	The data received from complication provider app
[out]	icon_path	The icon path data

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    char *value;
    watchface_complication_type_e type;

    watchface_complication_data_get_type(data, &type);
    if (type == WATCHFACE_COMPLICATION_TYPE_ICON)
        watchface_complication_data_get_icon_path(data, &value);
}

int watchface_complication_data_get_image_path	(	const bundle *	data,
		char **	image_path
	)

Gets image path from complication data.

Since :: 5.0

Remarks:: The image_path should be freed using free().

Parameters:

[in]	data	The data received from complication provider app
[out]	image_path	The image path data

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    char *value;
    watchface_complication_type_e type;

    watchface_complication_data_get_type(data, &type);
    if (type == WATCHFACE_COMPLICATION_TYPE_IMAGE)
        watchface_complication_data_get_image_path(data, &value);
}

int watchface_complication_data_get_long_text	(	const bundle *	data,
		char **	long_text
	)

Gets long text from complication data.

Since :: 5.0

Remarks:: The long_text should be freed using free().

Parameters:

[in]	data	The data received from complication provider app
[out]	long_text	The long text data

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    char *value;
    watchface_complication_type_e type;

    watchface_complication_data_get_type(data, &type);
    if (type == WATCHFACE_COMPLICATION_TYPE_LONG_TEXT)
        watchface_complication_data_get_long_text(data, &value);
}

int watchface_complication_data_get_ranged_value	(	const bundle *	data,
		double *	current_value,
		double *	min_value,
		double *	max_value
	)

Gets ranged value from complication data.

Since :: 5.0

Parameters:

[in]	data	The data received from complication provider app
[out]	current_value	The current value
[out]	min_value	The minimum value
[out]	max_value	The max value

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    double cur_val, min_val, max_val;
    watchface_complication_type_e type;

    watchface_complication_data_get_type(data, &type);
    if (type == WATCHFACE_COMPLICATION_TYPE_RANGED_VALUE)
        watchface_complication_data_get_ranged_value(data, &cur_val, &min_val, &max_val);
}

int watchface_complication_data_get_screen_reader_text	(	const bundle *	data,
		char **	screen_reader_text
	)

Gets screen reader text from complication data.

Since :: 5.0

Remarks:: The screen_reader_text should be freed using free().

Parameters:

[in]	data	The data received from complication provider app
[out]	screen_reader_text	The screen reader text

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    char *screen_reader_text;
    watchface_complication_data_get_screen_reader_text(data, &screen_reader_text);
    ...
    free(screen_reader_text);
}

int watchface_complication_data_get_short_text	(	const bundle *	data,
		char **	short_text
	)

Gets short text from complication data.

Since :: 5.0

Remarks:: The short_text should be freed using free().

Parameters:

[in]	data	The data received from complication provider app
[out]	short_text	The short text data

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    char *value;
    watchface_complication_type_e type;

    watchface_complication_data_get_type(data, &type);
    if (type == WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT)
        watchface_complication_data_get_short_text(data, &value);
}

int watchface_complication_data_get_timestamp	(	const bundle *	data,
		long *	timestamp
	)

Gets timestamp from complication data.

Since :: 5.0

Parameters:

[in]	data	The data received from complication provider app
[out]	timestamp	The timestamp

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    long value;
    watchface_complication_type_e type;

    watchface_complication_data_get_type(data, &type);
    if (type == WATCHFACE_COMPLICATION_TYPE_TIME)
        watchface_complication_data_get_timestamp(data, &value);
}

int watchface_complication_data_get_title	(	const bundle *	data,
		char **	title
	)

Gets title text from complication data.

Since :: 5.0

Remarks:: The title should be freed using free().

Parameters:

[in]	data	The data received from complication provider app
[out]	title	The title text data

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    char *value;

    watchface_complication_data_get_title(data, &value);
}

int watchface_complication_data_get_type	(	const bundle *	data,
		watchface_complication_type_e *	type
	)

Gets data type of complication data.

Developer can get different set of data from data depends on data type. Data will be passed through watchface_complication_updated_cb callback and sent by complication provider app.

Since :: 5.0

Parameters:

[in]	data	The data received from complication provider app
[out]	type	The data type

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_type_e; watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
void _on_complication_update(int complication_id,
        const char *provider_id,
        watchface_complication_type_e type,
        const bundle *data, void *user_data)
{
    watchface_complication_type_e type;
    watchface_complication_data_get_type(data, &type);
}

int watchface_complication_destroy ( complication_h handle )

Destroys a complication handle.

Since :: 5.0

Parameters:

[in] handle Complication handle

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Success
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

Precondition:: Complication handle should be created by watchface_complication_create().

See also:: watchface_complication_create()

Sample code:

#include <watchface-complication.h>
{
    int ret;
    complication_h complication;

    // Create complication

    // Do something

    ret = watchface_complication_destroy(complication);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
        return;
}

int watchface_complication_get_current_provider_id	(	complication_h	handle,
		char **	cur_provider
	)

Gets the id of provider in the complication.

Since :: 5.0

Remarks:: The cur_provider should be released using free().

Parameters:

[in]	handle	Complication handle
[out]	cur_provider	The name of the provider supplying the data

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Success
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

Precondition:: Complication handle should be created by watchface_complication_create().

Sample code:

#include <watchface-complication.h>
{
    int ret;
    int comp_id = 1;
    complication_h complication;
    const char *cur_provider_id;

    ret = watchface_complication_create(comp_id, "org.tizen.sample",
        WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
        WATCHFACE_COMPLICATION_EVENT_TAP,
        &complication);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
        return ret;

    ret = watchface_complication_get_current_provider_id(complication, &cur_provider_id);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
        return ret;
}

int watchface_complication_get_current_type	(	complication_h	handle,
		watchface_complication_type_e *	cur_type
	)

Gets the currently set type of the complication.

Since :: 5.0

Parameters:

[in]	handle	Complication handle
[out]	cur_type	The type shown in the complication

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Success
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NO_DATA	No data
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

Sample code:

#include <watchface-complication.h>
{
    int ret;
    int comp_id = 1;
    complication_h complication;
    watchface_complication_type_e cur_type;

    ret = watchface_complication_create(comp_id, "org.tizen.sample",
        WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
        WATCHFACE_COMPLICATION_EVENT_TAP,
        &complication);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
        return ret;

    ret = watchface_complication_get_current_type(complication, &cur_type);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
        return ret;
}

int watchface_complication_remove_updated_cb	(	complication_h	handle,
		watchface_complication_updated_cb	cb
	)

Removes the callback function.

Since :: 5.0

Parameters:

[in]	handle	Complication handle
[in]	cb	The callback function

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Success
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_updated_cb()

Sample code:

#include <watchface-complication.h>
{
    int ret;

    ret = watchface_complication_remove_updated_cb(complication,
            _watchface_complication_updated_cb);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
        return ret;
}

int watchface_complication_send_update_request ( complication_h handle )

Sends request the provider to update the complication.

Since :: 5.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appmanager.launch

Privilege:: http://tizen.org/privilege/datasharing

Remarks:: The watchface complication provider application can declare privileges for specific provider id in manifest xml file, in that case, the watchface application needs those privileges to use this function. If your app doesn't have those privileges, this function will return WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED.

Parameters:

[in] handle Complication handle

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE if success, other value if failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Success
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED	Permission denied
WATCHFACE_COMPLICATION_ERROR_DB	Database error
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

Sample code:

#include <watchface-complication.h>
{
    int ret;
    int comp_id = 1;
    complication_h complication;
    int supported_types;

    ret = watchface_complication_create(comp_id, "org.tizen.sample",
        WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT, WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
        WATCHFACE_COMPLICATION_EVENT_TAP,
        &complication);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE || complication == NULL)
        return ret;

    ret = watchface_complication_send_update_request(complication);
    if (ret != WATCHFACE_COMPLICATION_ERROR_NONE)
        return ret;
}

int watchface_complication_transfer_event	(	complication_h	handle,
		watchface_complication_event_type_e	event_type
	)

Transfers touch event to the complication provider.

This function launches the provider application with extra data, so that provider can tell it is launched by transferred touch event.

Since :: 5.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appmanager.launch

Privilege:: http://tizen.org/privilege/datasharing

Remarks:: The watchface complication provider application can declare privileges for specific provider id in manifest xml file, in that case, the watchface application needs those privileges to use this function. If your app doesn't have those privileges, this function will return WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED.

Parameters:

[in]	handle	The complication handle
[in]	event_type	The event type that is transferred to complication provider

Returns:: WATCHFACE_COMPLICATION_ERROR_NONE on success, otherwise an error code (see watchface_complication_error_e) on failure

Return values:

WATCHFACE_COMPLICATION_ERROR_NONE	Successful
WATCHFACE_COMPLICATION_ERROR_INVALID_PARAMETER	Invalid parameter
WATCHFACE_COMPLICATION_ERROR_OUT_OF_MEMORY	Out of memory
WATCHFACE_COMPLICATION_ERROR_IO_ERROR	I/O error
WATCHFACE_COMPLICATION_ERROR_PERMISSION_DENIED	Permission denied
WATCHFACE_COMPLICATION_ERROR_DB	Database error
WATCHFACE_COMPLICATION_ERROR_NOT_SUPPORTED	Not supported

See also:: watchface_complication_provider_event_get_type(); watchface_complication_provider_event_get_provider_id(); watchface_complication_provider_event_get_complication_type()

Sample code:

#include <watchface-complication.h>
void _on_complication_clicked(complication_h handle)
{
    watchface_complication_transfer_event(handle, WATCHFACE_COMPLICATION_EVENT_TAP);
}

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation