To get the information of installed widgets.

Required Header

#include <widget_service.h> #include <widget_errno.h>

Related Features

This API is related with the following feature:

http://tizen.org/feature/shell.appwidget

Overview

1. widget service API

Tizen supports various kinds of APIs set for retrieving information of widgets. Every widgets are installed via package manager utilities. The information of installed widgets are stored in the system DB. In some cases, application developer needs to send update request to some widgets. To make it possible, this module provides related API set. But the API will only works if the widget and application are packaged in one.

1.1 APIs for retrieving information of widgets

To get the information for installed widgets.

1.2 APIs for communicating with running widget instances

To trigger the update event or send the updated content string to the widget.

2. Size of widget

Widget has predefined size types. 1x1 is a square so its pixel size of width and height must has to be same. 2x2, 4x4 also square. 2x1, 4x1, 4x2, 4x3 is a rectangle. so its pixel size of width & height should not be same. pixel size of width should be long than height. Pixel size can be differ between different devices. It depends on its screen resolution. So widget developer should care various kinds of devices (has different screen resolution).

Size Type	Size in pixels	Supported profile
WIDGET_SIZE_TYPE_1x1	- (SQUARE, depends on screen resolution)	No profile - This size type is not used. just defined for specifying a default cell size
WIDGET_SIZE_TYPE_2x1	- (RECTANGLE, depends on screen resolution)	Mobile
WIDGET_SIZE_TYPE_2x2	- (SQUARE, depends on screen resolution)	Mobile, Wearable (Default size)
WIDGET_SIZE_TYPE_4x1	- (RECTANGLE, depends on screen resolution)	Mobile
WIDGET_SIZE_TYPE_4x2	- (RECTANGLE, depends on screen resolution)	Mobile
WIDGET_SIZE_TYPE_4x3	- (RECTANGLE, depends on screen resolution)	Mobile
WIDGET_SIZE_TYPE_4x4	- (SQUARE, depends on screen resolution)	Mobile

Widget also works for Easy Mode. For the Easy Mode, there are different size types. Called WIDGET_SIZE_TYPE_EASY_NxM

Size Type	Size in pixels	Supported profile
WIDGET_SIZE_TYPE_EASY_1x1	- (SQUARE, depends on screen resolution)	Mobile
WIDGET_SIZE_TYPE_EASY_3x1	- (RECTANGLE, depends on screen resolution)	Mobile
WIDGET_SIZE_TYPE_EASY_3x3	- (SQUARE - depends on screen resolution)	Mobile

However the Easy Mode is not a mandatory requirements for viewer application development. So you will not be able to create your widgets using Easy Mode size types. But if you are developing the homescreen(or application which is related with widgets displaying), You should care these types too.

Functions
int	widget_service_get_size (widget_size_type_e type, int width, int height)
	Gets the pixel size of given size type.
int	widget_service_get_size_type (int width, int height, widget_size_type_e *size_type)
	Gets the size type for given pixel size.
int	widget_service_get_need_of_mouse_event (const char widget_id, widget_size_type_e size_type, bool need_of_mouse_event)
	Gets the need of mouse event for the given widget.
int	widget_service_get_need_of_touch_effect (const char widget_id, widget_size_type_e size_type, bool need_of_touch_event)
	Gets the need of touch effect for the given widget.
int	widget_service_get_need_of_frame (const char widget_id, widget_size_type_e size_type, bool need_of_frame)
	Gets the need of decoration frame for the given widget.
int	widget_service_trigger_update (const char widget_id, const char instance_id, bundle *b, int force)
	Triggers the update event for given widget instance.
int	widget_service_change_period (const char widget_id, const char instance_id, double period)
	Changes the update period of the given widget instance.
int	widget_service_get_widget_list (widget_list_cb cb, void *data)
	Gets a list of all widgets.
char *	widget_service_get_main_app_id (const char *widget_id)
	Gets the MAIN application ID of given widget package ID.
int	widget_service_get_widget_list_by_pkgid (const char pkgid, widget_list_by_pkgid_cb cb, void data)
	Gets a list of widgets included in the given package ID.
char *	widget_service_get_widget_id (const char *id)
	Gets the ID of a widget by the given ID of package or UI app. If there are two or more widgets in the package, this function returns the ID of the primary widget.
char *	widget_service_get_app_id_of_setup_app (const char *widget_id)
	Gets the appId of setup app which is specified by the given widget ID's manifest.
char *	widget_service_get_package_id (const char *widget_id)
	Gets the package ID of the given widget.
char *	widget_service_get_name (const char widget_id, const char lang)
	Gets the name of the given widget.
char *	widget_service_get_preview_image_path (const char *widget_id, widget_size_type_e size_type)
	Gets the preview image path of given size type.
char *	widget_service_get_icon (const char pkgid, const char lang)
	Gets icon path of given widget package.
int	widget_service_get_nodisplay (const char *widget_id)
	Gets the "nodisplay" value.
int	widget_service_get_supported_sizes (const char widget_id, int cnt, int w, int h)
	Gets the supported size list.
int	widget_service_get_supported_size_types (const char widgetid, int cnt, int **types)
	Gets the supported size list of given widget ID.
int	widget_service_get_widget_instance_list (const char widget_id, widget_instance_list_cb cb, void data)
	Gets widget instances of given widget_id.
int	widget_service_set_lifecycle_event_cb (const char widget_id, widget_lifecycle_event_cb cb, void data)
	Sets event handler callback function for life cycle events of widgets.
int	widget_service_unset_lifecycle_event_cb (const char widget_id, void *user_data)
	Unsets event handler callback function for life cycle events of widgets.
int	widget_service_get_content_of_widget_instance (const char widget_id, const char widget_instance_id, bundle **b)
	Gets content of the widget instance.
int	widget_service_set_widget_disabled (const char *widget_id, bool disabled)
	Sets the 'disabled' state of a widget.
int	widget_service_get_widget_disabled (const char widget_id, bool is_disabled)
	Gets the 'disabled' state of a widget.
int	widget_service_set_disable_event_cb (widget_disable_event_cb callback, void *user_data)
	Sets the callback function for widget disable event.
int	widget_service_unset_disable_event_cb (void)
	Unsets the callback function for widget disable event.
Typedefs
typedef enum widget_error	widget_error_e
	Enumeration for the result status of widget operation.
typedef enum widget_size_type	widget_size_type_e
	Enumeration for list of supporting widget size types.
typedef enum widget_event_type	widget_event_type_e
	Enumeration for widget event type.
typedef int(*	widget_list_cb )(const char pkgid, const char widget_id, int is_prime, void *user_data)
	Callback function for getting result of widget_service_get_widget_list().
typedef int(*	widget_list_by_pkgid_cb )(const char widget_id, int is_prime, void user_data)
	Callback function for getting result of widget_service_get_widget_list_by_pkgid().
typedef int(*	widget_instance_list_cb )(const char widget_id, const char instance_id, void *user_data)
	Callback function for getting result of widget_service_get_widget_instance_list().
typedef enum widget_lifecycle_event	widget_lifecycle_event_e
	Enumeration for life cycle event of widgets.
typedef int(*	widget_lifecycle_event_cb )(const char widget_id, widget_lifecycle_event_e lifecycle_event, const char widget_instance_id, void *user_data)
	Called when a widget is created or destroyed.
typedef void(*	widget_disable_event_cb )(const char widget_id, bool is_disabled, void user_data)
	Called when a widget is disabled or enabled.

Typedef Documentation

typedef void(* widget_disable_event_cb)(const char *widget_id, bool is_disabled, void *user_data)

Called when a widget is disabled or enabled.

Since :: 5.5

Parameters:

[in]	widget_id	The widget id The widget_id can be used only in the callback. To use outside, make a copy.
[in]	is_disabled	The new value of the 'disabled' state of the widget
[in]	user_data	The user data passed from the callback registration function

See also:: widget_service_set_disable_event_cb(); widget_service_unset_disable_event_cb()

typedef enum widget_error widget_error_e

Enumeration for the result status of widget operation.

Since :: 2.3.1

typedef enum widget_event_type widget_event_type_e

Enumeration for widget event type.

These events will be sent from the provider.

Since :: 2.3.1

typedef int(* widget_instance_list_cb)(const char *widget_id, const char *instance_id, void *user_data)

Callback function for getting result of widget_service_get_widget_instance_list().

Since :: 2.3.1

Parameters:

[in]	widget_id	Widget appid
[in]	instance_id	widget instance ID
[in]	user_data	user Data

Returns:: WIDGET_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop

See also:: widget_service_get_widget_instance_list()

typedef int(* widget_lifecycle_event_cb)(const char *widget_id, widget_lifecycle_event_e lifecycle_event, const char *widget_instance_id, void *user_data)

Called when a widget is created or destroyed.

Since :: 2.3.1

Parameters:

[in]	widget_id	appid of widget application
[in]	lifecycle_event	Type of event
[in]	widget_instance_id	Widget instance ID
[in]	user_data	user data

Returns:: 0 on success, otherwise a negative error value

See also:: widget_service_set_lifecycle_event_cb()

typedef enum widget_lifecycle_event widget_lifecycle_event_e

Enumeration for life cycle event of widgets.

Since :: 2.3.1

See also:: widget_lifecycle_event_cb()

typedef int(* widget_list_by_pkgid_cb)(const char *widget_id, int is_prime, void *user_data)

Callback function for getting result of widget_service_get_widget_list_by_pkgid().

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	widget_id	appid of widget application
[in]	is_prime	will be sent as 1 if the widget is a default widget
[in]	user_data	user Data

Returns:: WIDGET_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop

See also:: widget_service_get_widget_list_by_pkgid()

typedef int(* widget_list_cb)(const char *pkgid, const char *widget_id, int is_prime, void *user_data)

Callback function for getting result of widget_service_get_widget_list().

Since :: 2.3.1

Parameters:

[in]	pkgid	package id
[in]	widget_id	appid of widget application
[in]	is_prime	will be sent as 1 if the widget is a default widget
[in]	user_data	user Data

Returns:: WIDGET_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop

See also:: widget_service_get_widget_list()

typedef enum widget_size_type widget_size_type_e

Enumeration for list of supporting widget size types.

Since :: 2.3.1

Enumeration Type Documentation

enum widget_error

Enumeration for the result status of widget operation.

Since :: 2.3.1

Enumerator:

WIDGET_ERROR_NONE	Operation is successfully completed
WIDGET_ERROR_INVALID_PARAMETER	Invalid function parameter
WIDGET_ERROR_OUT_OF_MEMORY	Out of memory
WIDGET_ERROR_RESOURCE_BUSY	Device or resource busy
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_CANCELED	Operation Canceled
WIDGET_ERROR_IO_ERROR	I/O error
WIDGET_ERROR_TIMED_OUT	Time out
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_FILE_NO_SPACE_ON_DEVICE	No space left on device
WIDGET_ERROR_FAULT	Fault - Unable to recover from the error
WIDGET_ERROR_ALREADY_EXIST	Already exists
WIDGET_ERROR_ALREADY_STARTED	Operation is already started
WIDGET_ERROR_NOT_EXIST	Not exists
WIDGET_ERROR_DISABLED	Disabled
WIDGET_ERROR_MAX_EXCEEDED	Maximum number of instances exceeded (Since 3.0)

enum widget_event_type

Enumeration for widget event type.

These events will be sent from the provider.

Since :: 2.3.1

Enumerator:

WIDGET_EVENT_WIDGET_UPDATED	Contents of the given widget is updated
WIDGET_EVENT_WIDGET_EXTRA_UPDATED	widget extra is updated
WIDGET_EVENT_CREATED	A new widget is created
WIDGET_EVENT_DELETED	A widget is deleted
WIDGET_EVENT_PERIOD_CHANGED	Update period is changed
WIDGET_EVENT_WIDGET_SIZE_CHANGED	widget size is changed
WIDGET_EVENT_EXTRA_INFO_UPDATED	Extra information is updated
WIDGET_EVENT_IGNORED	Request is ignored

enum widget_lifecycle_event

Enumeration for life cycle event of widgets.

Since :: 2.3.1

See also:: widget_lifecycle_event_cb()

Enumerator:

WIDGET_LIFE_CYCLE_EVENT_CREATE	The widget is created
WIDGET_LIFE_CYCLE_EVENT_DESTROY	The widget is destroyed
WIDGET_LIFE_CYCLE_EVENT_PAUSE	The widget is paused
WIDGET_LIFE_CYCLE_EVENT_RESUME	The widget is resumed

enum widget_size_type

Enumeration for list of supporting widget size types.

Since :: 2.3.1

Enumerator:

WIDGET_SIZE_TYPE_1x1	175x175 based on 720x1280 resolution
WIDGET_SIZE_TYPE_2x1	354x175 based on 720x1280 resolution
WIDGET_SIZE_TYPE_2x2	354x354 based on 720x1280 resolution
WIDGET_SIZE_TYPE_4x1	712x175 based on 720x1280 resolution
WIDGET_SIZE_TYPE_4x2	712x354 based on 720x1280 resolution
WIDGET_SIZE_TYPE_4x3	712x533 based on 720x1280 resolution
WIDGET_SIZE_TYPE_4x4	712x712 based on 720x1280 resolution
WIDGET_SIZE_TYPE_4x5	712x891 based on 720x1280 resolution
WIDGET_SIZE_TYPE_4x6	712x1070 based on 720x1280 resolution
WIDGET_SIZE_TYPE_EASY_1x1	224x215 based on 720x1280 resolution
WIDGET_SIZE_TYPE_EASY_3x1	680x215 based on 720x1280 resolution
WIDGET_SIZE_TYPE_EASY_3x3	680x653 based on 720x1280 resolution
WIDGET_SIZE_TYPE_FULL	720x1280 based on 720x1280 resolution
WIDGET_SIZE_TYPE_UNKNOWN	Error case

Function Documentation

int widget_service_change_period	(	const char *	widget_id,
		const char *	instance_id,
		double	period
	)

Changes the update period of the given widget instance.

Since :: 2.3.1

Parameters:

[in]	widget_id	appid of widget application
[in]	instance_id	Widget instance ID
[in]	period	New update period in sec

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully changed(requested)
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_FAULT	Failed to create a request packet
WIDGET_ERROR_NOT_EXIST	Not exists

char* widget_service_get_app_id_of_setup_app ( const char * widget_id )

Gets the appId of setup app which is specified by the given widget ID's manifest.

This setup app should be launched before adding the widget to get the content_info.
This function should be called before adding a widget.
To determine the content information string.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: Result string should be freed by free()

Parameters:

[in] widget_id appid of widget application

Returns:: AppId on success, NULL There is no setup application or error occurred, you can check it using get_last_result()

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

Postcondition:: Returned string must be freed manually.

See also:: get_last_result()

int widget_service_get_content_of_widget_instance	(	const char *	widget_id,
		const char *	widget_instance_id,
		bundle **	b
	)

Gets content of the widget instance.

Since :: 2.3.1

Parameters:

[in]	widget_id	appid of widget application
[in]	widget_instance_id	Widget instance ID
[out]	b	Bundle(content) data of the given widget instance, it should be released by caller.

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Failed to create a request packet
WIDGET_ERROR_NOT_EXIST	Not exists

Postcondition:: Caller should have to release the bundle.

char* widget_service_get_icon	(	const char *	pkgid,
		const char *	lang
	)

Gets icon path of given widget package.

The user should free the returned string with free().

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: Result string should be freed by free().

Parameters:

[in]	pkgid	Package ID of widget application
[in]	lang	Locale(en-us, ko-kr, ...), if it is `NULL`, function will use the system locale automatically

Returns:: icon path on success, NULL Fails to get path of an icon, get_last_result() will return reasons of failure if it fails

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

Postcondition:: Returned string must be freed manually.

See also:: widget_service_get_name(); widget_service_get_preview_image_path()

char* widget_service_get_main_app_id ( const char * widget_id )

Gets the MAIN application ID of given widget package ID.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: Result string should be freed by free().

Parameters:

[in] widget_id appid of widget application

Returns:: Main application Id on success, NULL if it fails to get main application Id (UI-APPID), get_last_result() will returns reason of failure

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

See also:: get_last_result()

char* widget_service_get_name	(	const char *	widget_id,
		const char *	lang
	)

Gets the name of the given widget.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: Result string should be freed by free()

Parameters:

[in]	widget_id	appid of widget application
[in]	lang	Locale(en-us, ko-kr, ...), if it is `NULL`, function will use the system locale automatically

Returns:: name on success, NULL Allocated heap address, get_last_result() will return reasons of failure if it fails.

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_OUT_OF_MEMORY	Out of memory
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

Postcondition:: Returned string must be freed manually.

See also:: widget_service_get_icon(); widget_service_get_preview_image_path()

int widget_service_get_need_of_frame	(	const char *	widget_id,
		widget_size_type_e	size_type,
		bool *	need_of_frame
	)

Gets the need of decoration frame for the given widget.

This function gets the need of decoration frame for the given widget from database.
The value of the need of touch effect means:
true : The viewer should make decoration frame outside of the widget. false : No need to make decoration frame.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	widget_id	appid of widget application
[in]	size_type	Size type
[out]	need_of_frame	the need of decoration frame

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid parameter was given
WIDGET_ERROR_IO_ERROR	Some error occurs on opening DB file

See also:: widget_service_get_need_of_mouse_event(); widget_service_get_need_of_touch_effect()

int widget_service_get_need_of_mouse_event	(	const char *	widget_id,
		widget_size_type_e	size_type,
		bool *	need_of_mouse_event
	)

Gets the need of mouse event for the given widget.

This function gets need of mouse event for the given widget from database.
The value of mouse event requirement means:
true : The widget requires mouse event. A viewer must feed the mouse event to the widget instance.
false : The widget doesn't require mouse event.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	widget_id	appid of widget application
[in]	size_type	Widget size type
[out]	need_of_mouse_event	The need of mouse event

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid parameter was given
WIDGET_ERROR_IO_ERROR	Some error occurs on opening DB file

See also:: widget_size_type_e; widget_service_get_need_of_touch_effect(); widget_service_get_need_of_frame()

int widget_service_get_need_of_touch_effect	(	const char *	widget_id,
		widget_size_type_e	size_type,
		bool *	need_of_touch_event
	)

Gets the need of touch effect for the given widget.

This function gets the need of touch effect for the given widget from database.
The value of the need of touch effect means:
true : A viewer is required to make the touch effect when a user clicks the widget, but it is just a recommendation.
false : A viewer is not required to make the touch effect, the box will make the touch effect itself.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	widget_id	appid of widget application
[in]	size_type	Size type
[out]	need_of_touch_event	the need of touch effect

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid parameter was given
WIDGET_ERROR_IO_ERROR	Some error occurs on opening DB file

See also:: widget_size_type_e; widget_service_get_need_of_mouse_event(); widget_service_get_need_of_frame()

int widget_service_get_nodisplay ( const char * widget_id )

Gets the "nodisplay" value.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in] widget_id appid of widget application

Returns:: The "nodisplay" value of given widget 1 The box should not be listed by the widget list app 0 Box should be listed, get_last_result() will return reasons of failure if it fails

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

Precondition:: Widget tag includes "nodisplay" attribute

char* widget_service_get_package_id ( const char * widget_id )

Gets the package ID of the given widget.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: Result string should be freed by free()

Parameters:

[in] widget_id appid of widget application

Returns:: appid on success, NULL Invalid appid, get_last_result() will return reasons of failure if it fails

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

Postcondition:: Returned string must be free'd manually.

See also:: widget_service_get_widget_id()

char* widget_service_get_preview_image_path	(	const char *	widget_id,
		widget_size_type_e	size_type
	)

Gets the preview image path of given size type.

This function will return the preview image path.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: Result string should be freed by free().

Parameters:

[in]	widget_id	appid of widget application
[in]	size_type	Widget size type

Returns:: Preview image path on success, NULL There is no preview image file, get_last_result() will returns reason of failure if it fails.

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_OUT_OF_MEMORY	Out of memory
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

Postcondition:: Returned string must be freed manually.

See also:: widget_service_get_icon(); widget_service_get_name()

int widget_service_get_size	(	widget_size_type_e	type,
		int *	width,
		int *	height
	)

Gets the pixel size of given size type.

Size types would be
WIDGET_SIZE_TYPE_1x1
WIDGET_SIZE_TYPE_2x1
WIDGET_SIZE_TYPE_2x2
WIDGET_SIZE_TYPE_4x1
WIDGET_SIZE_TYPE_4x2
WIDGET_SIZE_TYPE_4x3
WIDGET_SIZE_TYPE_4x4
WIDGET_SIZE_TYPE_4x5
WIDGET_SIZE_TYPE_4x6
WIDGET_SIZE_TYPE_FULL
WIDGET_SIZE_TYPE_EASY_1x1
WIDGET_SIZE_TYPE_EASY_3x1
WIDGET_SIZE_TYPE_EASY_3x3.

Since :: 2.3.1

Parameters:

[in]	type	Size type
[out]	width	Pixel size width
[out]	height	Pixel size height

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: widget_size_type(); widget_service_get_size_type()

int widget_service_get_size_type	(	int	width,
		int	height,
		widget_size_type_e *	size_type
	)

Gets the size type for given pixel size.

Returnable size types are
WIDGET_SIZE_TYPE_1x1
WIDGET_SIZE_TYPE_2x1
WIDGET_SIZE_TYPE_2x2
WIDGET_SIZE_TYPE_4x1
WIDGET_SIZE_TYPE_4x2
WIDGET_SIZE_TYPE_4x3
WIDGET_SIZE_TYPE_4x4
WIDGET_SIZE_TYPE_4x5
WIDGET_SIZE_TYPE_4x6
WIDGET_SIZE_TYPE_FULL
WIDGET_SIZE_TYPE_EASY_1x1
WIDGET_SIZE_TYPE_EASY_3x1
WIDGET_SIZE_TYPE_EASY_3x3
or
WIDGET_SIZE_TYPE_UNKNOWN for error.

Since :: 2.3.1

Parameters:

[in]	width	Pixel size width
[in]	height	Pixel size height
[out]	size_type	Widget size type

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_INVALID_PARAMETER	Invalid parameter was given

See also:: widget_size_type(); widget_service_get_size()

int widget_service_get_supported_size_types	(	const char *	widgetid,
		int *	cnt,
		int **	types
	)

Gets the supported size list of given widget ID.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	widgetid	appid of widget application
[in]	cnt	Size of types array
[out]	types	Array of types

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB

See also:: widget_service_get_supported_sizes()

int widget_service_get_supported_sizes	(	const char *	widget_id,
		int *	cnt,
		int **	w,
		int **	h
	)

Gets the supported size list.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	widget_id	appid of widget application
[in,out]	cnt	Count of array w and h
[out]	w	Width array
[out]	h	Height array

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	If succeed to get supported size list
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB

See also:: widget_service_get_supported_size_types()

int widget_service_get_widget_disabled	(	const char *	widget_id,
		bool *	is_disabled
	)

Gets the 'disabled' state of a widget.

Since :: 5.5

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	widget_id	The widget id
[out]	is_disabled	The disable state of widget

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault

char* widget_service_get_widget_id ( const char * id )

Gets the ID of a widget by the given ID of package or UI app. If there are two or more widgets in the package, this function returns the ID of the primary widget.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: Result string should be freed by free().

Parameters:

[in] id Package Id or UI App Id

Returns:: Primary widget Id on success, NULL Failed to get primary widget id, get_last_result() will returns reason of failure

Exceptions:

WIDGET_ERROR_NONE	Successful
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	Failed to access DB
WIDGET_ERROR_FAULT	Fault
WIDGET_ERROR_NOT_EXIST	Not exists

Precondition:: Must release returned string manually.

See also:: widget_service_get_package_id()

int widget_service_get_widget_instance_list	(	const char *	widget_id,
		widget_instance_list_cb	cb,
		void *	data
	)

Gets widget instances of given widget_id.

Since :: 2.3.1

Parameters:

[in]	widget_id	appid of widget application
[in]	cb	Callback function
[in]	data	user Data for callback function

Returns:: Size of widget instance list on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_NOT_EXIST	Instance is not exist

See also:: widget_instance_list_cb()

int widget_service_get_widget_list	(	widget_list_cb	cb,
		void *	data
	)

Gets a list of all widgets.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	cb	Callback function
[in]	data	user Data for callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_NOT_EXIST	Not exists
count	Count of widget packages

See also:: widget_service_get_widget_list_by_pkgid(); widget_list_cb()

int widget_service_get_widget_list_by_pkgid	(	const char *	pkgid,
		widget_list_by_pkgid_cb	cb,
		void *	data
	)

Gets a list of widgets included in the given package ID.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Parameters:

[in]	pkgid	Package ID (Not the UI App ID)
[in]	cb	Callback function
[in]	data	Callback data

Returns:: Count of widget packages on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument

See also:: widget_service_get_widget_list(); widget_list_by_pkgid_cb()

int widget_service_set_disable_event_cb	(	widget_disable_event_cb	callback,
		void *	user_data
	)

Sets the callback function for widget disable event.

Since :: 5.5

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Remarks:: The callback should be unset using widget_service_unset_disable_event_cb() before the application exits.

Parameters:

[in]	callback	The callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_IO_ERROR	IO error

See also:: widget_disable_event_cb(); widget_service_unset_disable_event_cb()

int widget_service_set_lifecycle_event_cb	(	const char *	widget_id,
		widget_lifecycle_event_cb	cb,
		void *	data
	)

Sets event handler callback function for life cycle events of widgets.

Since :: 2.3.1

Parameters:

[in]	widget_id	appid of widget application
[in]	cb	Callback function
[in]	data	user Data

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_OUT_OF_MEMORY	Out of memory

See also:: widget_lifecycle_event_cb(); widget_service_unset_lifecycle_event_cb()

int widget_service_set_widget_disabled	(	const char *	widget_id,
		bool	disabled
	)

Sets the 'disabled' state of a widget.

Warning:: This is not for use by third-party applications.

Since :: 5.5

Privilege Level:: platform

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

Parameters:

[in]	widget_id	The widget id
[in]	disabled	`true`, the widget will be disabled

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_FAULT	Fault

int widget_service_trigger_update	(	const char *	widget_id,
		const char *	instance_id,
		bundle *	b,
		int	force
	)

Triggers the update event for given widget instance.

Since :: 2.3.1

Parameters:

[in]	widget_id	appid of widget application
[in]	instance_id	Set `NULL` if you don't know what the ID is. Then every instance of given pkgname will trigger its update event
[in]	b	Bundle data will be passed to the widget application via widget_update handler, default is `NULL`
[in]	force	1 If you want to update your widget even if the provider is paused or 0. 0 is default

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_INVALID_PARAMETER	Invalid argument
WIDGET_ERROR_CANCELED	Provider is paused, so this update request is canceled.(ignored), if you want to make update forcely, use force=1
WIDGET_ERROR_OUT_OF_MEMORY	Memory is not enough to make request
WIDGET_ERROR_FAULT	Failed to create a request packet
WIDGET_ERROR_NOT_EXIST	Not exists

int widget_service_unset_disable_event_cb ( void )

Unsets the callback function for widget disable event.

Since :: 5.5

Privilege Level:: public

Privilege:: http://tizen.org/privilege/widget.viewer

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_PERMISSION_DENIED	Permission denied
WIDGET_ERROR_IO_ERROR	IO error

See also:: widget_disable_event_cb(); widget_service_set_disable_event_cb()

int widget_service_unset_lifecycle_event_cb	(	const char *	widget_id,
		void **	user_data
	)

Unsets event handler callback function for life cycle events of widgets.

Since :: 2.3.1

Parameters:

[in]	widget_id	appid of widget application
[out]	user_data	User callback data

Returns:: 0 on success, otherwise a negative error value

Return values:

WIDGET_ERROR_NONE	Successfully done
WIDGET_ERROR_NOT_SUPPORTED	Not supported
WIDGET_ERROR_NOT_EXIST	Event handler callback function does not exist

See also:: widget_service_set_lifecycle_event_cb()

Required Header

Related Features

Overview

1. widget service API

1.1 APIs for retrieving information of widgets

1.2 APIs for communicating with running widget instances

2. Size of widget

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation