Tizen Native API  5.5
Functions | Typedefs
Widget Service
Widget

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:

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 TypeSize in pixelsSupported 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 TypeSize in pixelsSupported 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)
 Registers event handler callback function for life cycle events of widgets.
int widget_service_unset_lifecycle_event_cb (const char *widget_id, void **user_data)
 Unregisters 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 *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 *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 *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 *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_idThe widget id
The widget_id can be used only in the callback. To use outside, make a copy.
[in]is_disabledThe new value of the 'disabled' state of the widget
[in]user_dataThe 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 *data)

Callback function for getting result of widget_service_get_widget_instance_list.

Since :
2.3.1
Parameters:
[in]widget_idWidget appid
[in]widget_instance_idwidget instance ID
[in]datauser 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 *data)

Called when a widget is created or destroyed.

Since :
2.3.1
Parameters:
[in]widget_idappid of widget application
[in]lifecycle_eventType of event
[in]widget_instance_idWidget instance ID
[in]datauser 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 *data)

Callback function for getting result of widget_service_get_widget_list_by_pkgid.

Since :
2.3.1
Parameters:
[in]widget_idappid of widget application
[in]is_primewill be sent as 1 if the widget is a default widget
[in]datauser Data
Privilege Level:
public
Privilege:
http://tizen.org/privilege/widget.viewer
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 *data)

Callback function for getting result of widget_service_get_widget_list.

Since :
2.3.1
Parameters:
[in]pkgidpackage id
[in]widget_idappid of widget application
[in]is_primewill be sent as 1 if the widget is a default widget
[in]datauser Data
Privilege Level:
public
Privilege:
http://tizen.org/privilege/widget.viewer
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_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_idappid of widget application
[in]instance_idWidget instance ID
[in]periodNew update period in sec
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfully changed(requested)
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_FAULTFailed to create a request packet
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_OUT_OF_MEMORYNot enough memory
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_idappid of widget application
Returns:
char * type
Return values:
@cNULL There is no setup application or error occurred, you can check it using get_last_result()
appidAppId if exists or NULL
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_idappid of widget application
[in]widget_instance_idWidget instance ID
[out]bBundle(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_IO_ERRORFailed to access DB
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
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]pkgidPackage ID of widget application
[in]langLocale(en-us, ko-kr, ...), if it is NULL, function will use the system locale automatically
Returns:
char * type
Return values:
nameAllocated heap address
@cNULL Fails to get path of an icon, get_last_result() will return reasons of failure if it fails
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_idappid of widget application
Returns:
char * type
Return values:
@cNULL if it fails to get main application Id (UI-APPID), get_last_result() will returns reason of failure
appidMain application Id
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_idappid of widget application
[in]langLocale(en-us, ko-kr, ...), if it is NULL, function will use the system locale automatically
Returns:
char * type
Return values:
nameIf it fails to get name
@cNULL Allocated heap address, get_last_result() will return reasons of failure if it fails.
Postcondition:
Returned string must be freed manually.
See also:
widget_service_i18n_icon()
widget_service_preview()
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 API 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_idappid of widget application
[in]size_typeSize type
[out]need_of_framethe need of decoration frame
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter was given
WIDGET_ERROR_IO_ERRORSome 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_idappid of widget application
[in]size_typeWidget size type
[out]need_of_mouse_eventThe need of mouse event
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter was given
WIDGET_ERROR_IO_ERRORSome 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 API 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_idappid of widget application
[in]size_typeSize type
[out]need_of_touch_eventthe need of touch effect
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter was given
WIDGET_ERROR_IO_ERRORSome 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:
http://tizen.org/privilege/widget.viewer
Parameters:
[in]widget_idappid of widget application
Privilege Level:
public
Returns:
The "nodisplay" value of given widget
Return values:
1The box should not be listed by the widget list app
0Box should be listed, get_last_result() will return reasons of failure if it fails
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_idappid of widget application
Returns:
char * type
Return values:
appidString which is allocated in the heap
@cNULL Invalid appid, get_last_result() will return reasons of failure if it fails
Postcondition:
Returned string must be free'd manually.
See also:
widget_service_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_idappid of widget application
[in]size_typeWidget size type
Returns:
char * type
Return values:
pathPreview image path
@cNULL There is no preview image file, get_last_result() will returns reason of failure if it fails.
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]typeSize type
[out]widthPixel size width
[out]heightPixel size height
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfully done
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]widthPixel size width
[in]heightPixel size height
[out]size_typeWidget size type
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid 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
Parameters:
[in]widgetidappid of widget application
[in]cntSize of types array
[in,out]cntResult count of types array
[out]typesArray of types
Privilege Level:
public
Privilege:
http://tizen.org/privilege/widget.viewer
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_IO_ERRORFailed to access DB
WIDGET_ERROR_NONESuccessfully done
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
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_idappid of widget application
[in,out]cntCount of array w and h
[out]wWidth array
[out]hHeight array
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONEIf succeed to get supported size list
WIDGET_ERROR_IO_ERRORFailed to access DB
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
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_idThe widget id
[out]is_disabledThe disable state of widget
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfully done
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_IO_ERRORFailed to access DB
WIDGET_ERROR_FAULTFault
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]idPackage Id or UI App Id
Returns:
char * type
Return values:
@cNULL Failed to get primary widget id, get_last_result() will returns reason of failure
widget_idPrimary widget Id.
Precondition:
Must release returned string manually.
See also:
widget_service_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_idappid of widget application
[in]cbCallback function
[in]datauser Data for callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NOT_EXISTInstance is not exist
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_NOT_SUPPORTEDNot supported
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
Parameters:
[in]cbCallback function
[in]datauser Data for callback function
Privilege Level:
public
Privilege:
http://tizen.org/privilege/widget.viewer
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_IO_ERRORFailed to access DB
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
countCount 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
Parameters:
[in]pkgidPackage ID (Not the UI App ID)
[in]cbCallback function
[in]dataCallback data
Privilege Level:
public
Privilege:
http://tizen.org/privilege/widget.viewer
Returns:
0 on success, otherwise a negative error value
Return values:
intCount of widget packages
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_IO_ERRORFailed to access DB
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
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]callbackThe callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfully done
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_IO_ERRORIO 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 
)

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

Since :
2.3.1
Privilege Level:
public
Parameters:
[in]widget_idappid of widget application
[in]cbCallback function
[in]datauser Data
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
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_idThe widget id
[in]disabledtrue, the widget will be disabled
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfully done
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_FAULTFault
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_idappid of widget application
[in]instance_idSet NULL if you don't know what the ID is. Then every instance of given pkgname will trigger its update event
[in]bBundle data will be passed to the widget application via widget_update handler, default is NULL
[in]force1 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_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_CANCELEDProvider is paused, so this update request is canceled.(ignored), if you want to make update forcely, use force=1
WIDGET_ERROR_OUT_OF_MEMORYMemory is not enough to make request
WIDGET_ERROR_FAULTFailed to create a request packet
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_NONESuccessfully requested
See also:
widget_service_trigger_update()
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_NONESuccessfully done
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_IO_ERRORIO 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 
)

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

Since :
2.3.1
Parameters:
[in]widget_idappid of widget application
[out]user_dataUser callback data
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_PERMISSION_DENIEDPermission denied
WIDGET_ERROR_NOT_EXISTEvent handler callback function does not exist
See also:
widget_service_set_lifecycle_event_cb