include/widget_service.h

   1 /*
   2  * Copyright 2013  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.1 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://floralicense.org/license/
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __WIDGET_SERVICE_H
  18 #define __WIDGET_SERVICE_H
  19
  20 #include <tizen.h>
  21 #include <bundle.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file widget_service.h
  29  * @brief  This file declares API of libwidget-service library
  30  * @since_tizen 2.3.1
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_WIDGET_SERVICE_MODULE
  35  * @{
  36  */
  37
  38
  39 /**
  40  * @brief Enumeration for list of supporting widget size types.
  41  * @since_tizen 2.3.1
  42  */
  43 typedef enum widget_size_type {
  44         WIDGET_SIZE_TYPE_1x1 = 0x0001, /**< 175x175 based on 720x1280 resolution */
  45         WIDGET_SIZE_TYPE_2x1 = 0x0002, /**< 354x175 based on 720x1280 resolution */
  46         WIDGET_SIZE_TYPE_2x2 = 0x0004, /**< 354x354 based on 720x1280 resolution */
  47         WIDGET_SIZE_TYPE_4x1 = 0x0008, /**< 712x175 based on 720x1280 resolution */
  48         WIDGET_SIZE_TYPE_4x2 = 0x0010, /**< 712x354 based on 720x1280 resolution */
  49         WIDGET_SIZE_TYPE_4x3 = 0x0020, /**< 712x533 based on 720x1280 resolution */
  50         WIDGET_SIZE_TYPE_4x4 = 0x0040, /**< 712x712 based on 720x1280 resolution */
  51         WIDGET_SIZE_TYPE_4x5 = 0x0080, /**< 712x891 based on 720x1280 resolution */
  52         WIDGET_SIZE_TYPE_4x6 = 0x0100, /**< 712x1070 based on 720x1280 resolution */
  53         WIDGET_SIZE_TYPE_EASY_1x1 = 0x1000, /**< 224x215 based on 720x1280 resolution */
  54         WIDGET_SIZE_TYPE_EASY_3x1 = 0x2000, /**< 680x215 based on 720x1280 resolution */
  55         WIDGET_SIZE_TYPE_EASY_3x3 = 0x4000, /**< 680x653 based on 720x1280 resolution */
  56         WIDGET_SIZE_TYPE_FULL = 0x0800, /**< 720x1280 based on 720x1280 resolution */
  57         WIDGET_SIZE_TYPE_UNKNOWN = 0xFFFF /**< Error case */
  58 } widget_size_type_e;
  59
  60
  61 /**
  62  * @brief Enumeration for widget event type.
  63  * @details These events will be sent from the provider.
  64  * @since_tizen 2.3.1
  65  */
  66 typedef enum widget_event_type {
  67         WIDGET_EVENT_WIDGET_UPDATED = 0, /**< Contents of the given widget is updated */
  68         WIDGET_EVENT_WIDGET_EXTRA_UPDATED = 1, /**< widget extra is updated */
  69         WIDGET_EVENT_CREATED = 4, /**< A new widget is created */
  70         WIDGET_EVENT_DELETED = 5, /**< A widget is deleted */
  71         WIDGET_EVENT_PERIOD_CHANGED = 8, /**< Update period is changed */
  72         WIDGET_EVENT_WIDGET_SIZE_CHANGED = 9, /**< widget size is changed */
  73         WIDGET_EVENT_EXTRA_INFO_UPDATED = 21, /**< Extra information is updated */
  74         WIDGET_EVENT_IGNORED = 0xFF /**< Request is ignored */
  75 } widget_event_type_e;
  76
  77
  78 /**
  79  * @brief Gets the pixel size of given size type.
  80  * @details Size types would be\n
  81  *          #WIDGET_SIZE_TYPE_1x1\n
  82  *          #WIDGET_SIZE_TYPE_2x1\n
  83  *          #WIDGET_SIZE_TYPE_2x2\n
  84  *          #WIDGET_SIZE_TYPE_4x1\n
  85  *          #WIDGET_SIZE_TYPE_4x2\n
  86  *          #WIDGET_SIZE_TYPE_4x3\n
  87  *          #WIDGET_SIZE_TYPE_4x4\n
  88  *          #WIDGET_SIZE_TYPE_4x5\n
  89  *          #WIDGET_SIZE_TYPE_4x6\n
  90  *          #WIDGET_SIZE_TYPE_FULL\n
  91  *          #WIDGET_SIZE_TYPE_EASY_1x1\n
  92  *          #WIDGET_SIZE_TYPE_EASY_3x1\n
  93  *          #WIDGET_SIZE_TYPE_EASY_3x3.
  94  * @since_tizen 2.3.1
  95  * @param[in] type Size type
  96  * @param[out] width Pixel size width
  97  * @param[out] height Pixel size height
  98  * @return @c 0 on success,
  99  *         otherwise a negative error value
 100  * @retval #WIDGET_ERROR_NONE Successfully done
 101  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 102  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
 103  * @see widget_size_type()
 104  * @see widget_service_get_size_type()
 105  */
 106 int widget_service_get_size(widget_size_type_e type, int *width, int *height);
 107
 108
 109 /**
 110  * @brief Gets the size type for given pixel size.
 111  * @details Returnable size types are\n
 112  *          #WIDGET_SIZE_TYPE_1x1\n
 113  *          #WIDGET_SIZE_TYPE_2x1\n
 114  *          #WIDGET_SIZE_TYPE_2x2\n
 115  *          #WIDGET_SIZE_TYPE_4x1\n
 116  *          #WIDGET_SIZE_TYPE_4x2\n
 117  *          #WIDGET_SIZE_TYPE_4x3\n
 118  *          #WIDGET_SIZE_TYPE_4x4\n
 119  *          #WIDGET_SIZE_TYPE_4x5\n
 120  *          #WIDGET_SIZE_TYPE_4x6\n
 121  *          #WIDGET_SIZE_TYPE_FULL\n
 122  *          #WIDGET_SIZE_TYPE_EASY_1x1\n
 123  *          #WIDGET_SIZE_TYPE_EASY_3x1\n
 124  *          #WIDGET_SIZE_TYPE_EASY_3x3\n
 125  *          or\n
 126  *          #WIDGET_SIZE_TYPE_UNKNOWN for error.
 127  * @since_tizen 2.3.1
 128  * @param[in] width Pixel size width
 129  * @param[in] height Pixel size height
 130  * @param[out] size_type Widget size type\n
 131  * @return @c 0 on success,
 132  *         otherwise a negative error value
 133  * @retval #WIDGET_ERROR_NONE Successfully done
 134  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 135  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
 136  * @see widget_size_type()
 137  * @see widget_service_get_size()
 138  */
 139 int widget_service_get_size_type(int width, int height, widget_size_type_e *size_type);
 140
 141
 142 /**
 143  * @brief Gets the need of mouse event for the given widget.
 144  * @details This function gets need of mouse event for the given widget from database.\n
 145  *          The value of mouse event requirement means: \n
 146  *          true : The widget requires mouse event. A viewer must feed the mouse event to the widget instance.\n
 147  *          false : The widget doesn't require mouse event.\n
 148  * @since_tizen 2.3.1
 149  * @privlevel public
 150  * @privilege %http://tizen.org/privilege/widget.viewer
 151  * @param[in] widget_id appid of widget application
 152  * @param[in] size_type Widget size type
 153  * @param[out] need_of_mouse_event The need of mouse event
 154  * @return 0 on success,
 155  *         otherwise a negative error value
 156  * @retval #WIDGET_ERROR_NONE Successfully done
 157  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 158  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 159  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
 160  * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file
 161  * @see widget_size_type_e
 162  * @see widget_service_get_need_of_touch_effect()
 163  * @see widget_service_get_need_of_frame()
 164  */
 165 int widget_service_get_need_of_mouse_event(const char *widget_id, widget_size_type_e size_type, bool *need_of_mouse_event);
 166
 167
 168 /**
 169  * @brief Gets the need of touch effect for the given widget.
 170  * @details This function gets the need of touch effect for the given widget from database.\n
 171  *          The value of the need of touch effect means: \n
 172  *          true : A viewer is required to make the touch effect when a user clicks the widget, but it is just a recommendation.\n
 173  *          false : A viewer is not required to make the touch effect, the box will make the touch effect itself.
 174  * @since_tizen 2.3.1
 175  * @privlevel public
 176  * @privilege %http://tizen.org/privilege/widget.viewer
 177  * @param[in] widget_id appid of widget application
 178  * @param[in] size_type Size type
 179  * @param[out] need_of_touch_event the need of touch effect
 180  * @return @c 0 on success,
 181  *         otherwise a negative error value
 182  * @retval #WIDGET_ERROR_NONE Successfully done
 183  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 184  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 185  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
 186  * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file
 187  * @see widget_size_type_e
 188  * @see widget_service_get_need_of_mouse_event()
 189  * @see widget_service_get_need_of_frame()
 190   */
 191 int widget_service_get_need_of_touch_effect(const char *widget_id, widget_size_type_e size_type, bool *need_of_touch_event);
 192
 193
 194 /**
 195  * @brief Gets the need of decoration frame for the given widget.
 196  * @details This function gets the need of decoration frame for the given widget from database.\n
 197  *          The value of the need of touch effect means: \n
 198  *          true : The viewer should make decoration frame outside of the widget.
 199  *          false : No need to make decoration frame.
 200  * @since_tizen 2.3.1
 201  * @privlevel public
 202  * @privilege %http://tizen.org/privilege/widget.viewer
 203  * @param[in] widget_id appid of widget application
 204  * @param[in] size_type Size type
 205  * @param[out] need_of_frame the need of decoration frame
 206  * @return @c 0 on success,
 207  *         otherwise a negative error value
 208  * @retval #WIDGET_ERROR_NONE Successfully done
 209  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 210  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 211  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
 212  * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file
 213  * @see widget_service_get_need_of_mouse_event()
 214  * @see widget_service_get_need_of_touch_effect()
 215  */
 216 int widget_service_get_need_of_frame(const char *widget_id, widget_size_type_e size_type, bool *need_of_frame);
 217
 218
 219 /**
 220  * @brief Triggers the update event for given widget instance.
 221  * @since_tizen 2.3.1
 222  * @param[in] widget_id appid of widget application
 223  * @param[in] instance_id Set @c NULL if you don't know what the ID is. Then every instance of given pkgname will trigger its update event
 224  * @param[in] b Bundle data will be passed to the widget application via widget_update handler, default is @c NULL
 225  * @param[in] force 1 If you want to update your widget even if the provider is paused or 0. 0 is default
 226  * @return @c 0 on success,
 227  *         otherwise a negative error value
 228  * @retval #WIDGET_ERROR_NONE Successfully done
 229  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 230  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 231  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 232  * @retval #WIDGET_ERROR_CANCELED Provider is paused, so this update request is canceled.(ignored), if you want to make update forcely, use force=1
 233  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Memory is not enough to make request
 234  * @retval #WIDGET_ERROR_FAULT Failed to create a request packet
 235  * @retval #WIDGET_ERROR_NOT_EXIST Not exists
 236  */
 237 int widget_service_trigger_update(const char *widget_id, const char *instance_id, bundle *b, int force);
 238
 239
 240 /**
 241  * @brief Changes the update period of the given widget instance.
 242  * @since_tizen 2.3.1
 243  * @param[in] widget_id appid of widget application
 244  * @param[in] instance_id Widget instance ID
 245  * @param[in] period New update period in sec
 246  * @return @c 0 on success,
 247  *         otherwise a negative error value
 248  * @retval #WIDGET_ERROR_NONE Successfully changed(requested)
 249  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 250  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 251  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 252  * @retval #WIDGET_ERROR_FAULT Failed to create a request packet
 253  * @retval #WIDGET_ERROR_NOT_EXIST Not exists
 254  */
 255 int widget_service_change_period(const char *widget_id, const char *instance_id, double period);
 256
 257
 258 /**
 259  * @brief Callback function for getting result of widget_service_get_widget_list().
 260  * @since_tizen 2.3.1
 261  * @param[in] pkgid package id
 262  * @param[in] widget_id appid of widget application
 263  * @param[in] is_prime will be sent as 1 if the widget is a default widget
 264  * @param[in] user_data user Data
 265  * @return #WIDGET_ERROR_NONE to continue with the next iteration of the loop,
 266  *         other error values to break out of the loop
 267  * @see widget_service_get_widget_list()
 268  */
 269 typedef int (*widget_list_cb)(const char *pkgid, const char *widget_id, int is_prime, void *user_data);
 270
 271
 272 /**
 273  * @brief Gets a list of all widgets.
 274  * @since_tizen 2.3.1
 275  * @privlevel public
 276  * @privilege %http://tizen.org/privilege/widget.viewer
 277  * @param[in] cb Callback function
 278  * @param[in] data user Data for callback function
 279  * @return @c 0 on success,
 280  *         otherwise a negative error value
 281  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 282  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 283  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 284  * @retval #WIDGET_ERROR_NOT_EXIST Not exists
 285  * @retval count Count of widget packages
 286  * @see widget_service_get_widget_list_by_pkgid()
 287  * @see widget_list_cb()
 288  */
 289 int widget_service_get_widget_list(widget_list_cb cb, void *data);
 290
 291
 292 /**
 293  * @brief Gets the MAIN application ID of given widget package ID.
 294  * @since_tizen 2.3.1
 295  * @privlevel public
 296  * @privilege %http://tizen.org/privilege/widget.viewer
 297  * @remarks Result string should be freed by free().
 298  * @param[in] widget_id appid of widget application
 299  * @return Main application Id on success,
 300  *         @c NULL if it fails to get main application Id (UI-APPID), get_last_result() will returns reason of failure
 301  * @exception #WIDGET_ERROR_NONE Successful
 302  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 303  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 304  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 305  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 306  * @exception #WIDGET_ERROR_FAULT Fault
 307  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 308  * @see get_last_result()
 309  */
 310 char *widget_service_get_main_app_id(const char *widget_id);
 311
 312
 313 /**
 314  * @brief Callback function for getting result of widget_service_get_widget_list_by_pkgid().
 315  * @since_tizen 2.3.1
 316  * @privlevel public
 317  * @privilege %http://tizen.org/privilege/widget.viewer
 318  * @param[in] widget_id appid of widget application
 319  * @param[in] is_prime will be sent as 1 if the widget is a default widget
 320  * @param[in] user_data user Data
 321  * @return #WIDGET_ERROR_NONE to continue with the next iteration of the loop,
 322  *         other error values to break out of the loop
 323  * @see widget_service_get_widget_list_by_pkgid()
 324  */
 325 typedef int (*widget_list_by_pkgid_cb)(const char *widget_id, int is_prime, void *user_data);
 326
 327
 328 /**
 329  * @brief Gets a list of widgets included in the given package ID.
 330  * @since_tizen 2.3.1
 331  * @privlevel public
 332  * @privilege %http://tizen.org/privilege/widget.viewer
 333  * @param[in] pkgid Package ID (Not the UI App ID)
 334  * @param[in] cb Callback function
 335  * @param[in] data Callback data
 336  * @return Count of widget packages on success,
 337  *         otherwise a negative error value
 338  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 339  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 340  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 341  * @see widget_service_get_widget_list()
 342  * @see widget_list_by_pkgid_cb()
 343  */
 344 int widget_service_get_widget_list_by_pkgid(const char *pkgid, widget_list_by_pkgid_cb cb, void *data);
 345
 346
 347 /**
 348  * @brief Gets the ID of a widget by the given ID of package or UI app.
 349  *        If there are two or more widgets in the package, this function returns the ID of the primary widget.
 350  * @since_tizen 2.3.1
 351  * @privlevel public
 352  * @privilege %http://tizen.org/privilege/widget.viewer
 353  * @remarks Result string should be freed by free().
 354  * @param[in] id Package Id or UI App Id
 355  * @return Primary widget Id on success,
 356  *         @c NULL Failed to get primary widget id, get_last_result() will returns reason of failure
 357  * @exception #WIDGET_ERROR_NONE Successful
 358  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 359  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 360  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 361  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 362  * @exception #WIDGET_ERROR_FAULT Fault
 363  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 364  * @pre Must release returned string manually.
 365  * @see widget_service_package_id()
 366  */
 367 char *widget_service_get_widget_id(const char *id);
 368
 369
 370 /**
 371  * @brief Gets the appId of setup app which is specified by the given widget ID's manifest.
 372  * @details This setup app should be launched before adding the widget to get the content_info.\n
 373  *          This function should be called before adding a widget.\n
 374  *          To determine the content information string.
 375  * @since_tizen 2.3.1
 376  * @privlevel public
 377  * @privilege %http://tizen.org/privilege/widget.viewer
 378  * @remarks Result string should be freed by free()
 379  * @param[in] widget_id appid of widget application
 380  * @return AppId on success,
 381  *         @c NULL There is no setup application or error occurred, you can check it using get_last_result()
 382  * @exception #WIDGET_ERROR_NONE Successful
 383  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 384  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 385  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 386  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 387  * @exception #WIDGET_ERROR_FAULT Fault
 388  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 389  * @post Returned string must be freed manually.
 390  * @see get_last_result()
 391  */
 392 char *widget_service_get_app_id_of_setup_app(const char *widget_id);
 393
 394
 395 /**
 396  * @brief Gets the package ID of the given widget.
 397  * @since_tizen 2.3.1
 398  * @privlevel public
 399  * @privilege %http://tizen.org/privilege/widget.viewer
 400  * @remarks Result string should be freed by free()
 401  * @param[in] widget_id appid of widget application
 402  * @return appid on success,
 403  *         @c NULL Invalid appid, get_last_result() will return reasons of failure if it fails
 404  * @exception #WIDGET_ERROR_NONE Successful
 405  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 406  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 407  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 408  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 409  * @exception #WIDGET_ERROR_FAULT Fault
 410  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 411  * @post Returned string must be free'd manually.
 412  * @see widget_service_widget_id()
 413  */
 414 char *widget_service_get_package_id(const char *widget_id);
 415
 416
 417 /**
 418  * @brief Gets the name of the given widget.
 419  * @since_tizen 2.3.1
 420  * @privlevel public
 421  * @privilege %http://tizen.org/privilege/widget.viewer
 422  * @remarks Result string should be freed by free()
 423  * @param[in] widget_id appid of widget application
 424  * @param[in] lang Locale(en-us, ko-kr, ...), if it is @c NULL, function will use the system locale automatically
 425  * @return name on success,
 426  *         @c NULL Allocated heap address, get_last_result() will return reasons of failure if it fails.
 427  * @exception #WIDGET_ERROR_NONE Successful
 428  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 429  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 430  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 431  * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 432  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 433  * @exception #WIDGET_ERROR_FAULT Fault
 434  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 435  * @post Returned string must be freed manually.
 436  * @see widget_service_i18n_icon()
 437  * @see widget_service_preview()
 438  */
 439 char *widget_service_get_name(const char *widget_id, const char *lang);
 440
 441
 442 /**
 443  * @brief Gets the preview image path of given size type.
 444  * @details This function will return the preview image path.
 445  * @since_tizen 2.3.1
 446  * @privlevel public
 447  * @privilege %http://tizen.org/privilege/widget.viewer
 448  * @remarks Result string should be freed by free().
 449  * @param[in] widget_id appid of widget application
 450  * @param[in] size_type Widget size type
 451  * @return Preview image path on success,
 452  *         @c NULL There is no preview image file, get_last_result() will returns reason of failure if it fails.
 453  * @exception #WIDGET_ERROR_NONE Successful
 454  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 455  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 456  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 457  * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 458  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 459  * @exception #WIDGET_ERROR_FAULT Fault
 460  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 461  * @post Returned string must be freed manually.
 462  * @see widget_service_get_icon()
 463  * @see widget_service_get_name()
 464  */
 465 char *widget_service_get_preview_image_path(const char *widget_id, widget_size_type_e size_type);
 466
 467
 468 /**
 469  * @brief Gets icon path of given widget package.
 470  * @details The user should free the returned string with free().
 471  * @since_tizen 2.3.1
 472  * @privlevel public
 473  * @privilege %http://tizen.org/privilege/widget.viewer
 474  * @remarks Result string should be freed by free().
 475  * @param[in] pkgid Package ID of widget application
 476  * @param[in] lang Locale(en-us, ko-kr, ...), if it is @c NULL, function will use the system locale automatically
 477  * @return icon path on success,
 478  *         @c NULL Fails to get path of an icon, get_last_result() will return reasons of failure if it fails
 479  * @exception #WIDGET_ERROR_NONE Successful
 480  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 481  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 482  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 483  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 484  * @exception #WIDGET_ERROR_FAULT Fault
 485  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 486  * @post Returned string must be freed manually.
 487  * @see widget_service_get_name()
 488  * @see widget_service_get_preview_image_path()
 489  */
 490 char *widget_service_get_icon(const char *pkgid, const char *lang);
 491
 492
 493 /**
 494  * @brief Gets the "nodisplay" value.
 495  * @since_tizen 2.3.1
 496  * @privlevel public
 497  * @privilege %http://tizen.org/privilege/widget.viewer
 498  * @param[in] widget_id appid of widget application
 499  * @return The "nodisplay" value of given widget
 500  *         @c 1 The box should not be listed by the widget list app
 501  *         @c 0 Box should be listed, get_last_result() will return reasons of failure if it fails
 502  * @exception #WIDGET_ERROR_NONE Successful
 503  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
 504  * @exception #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 505  * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 506  * @exception #WIDGET_ERROR_IO_ERROR Failed to access DB
 507  * @exception #WIDGET_ERROR_FAULT Fault
 508  * @exception #WIDGET_ERROR_NOT_EXIST Not exists
 509  * @pre Widget tag includes "nodisplay" attribute
 510  */
 511 int widget_service_get_nodisplay(const char *widget_id);
 512
 513
 514 /**
 515  * @brief Gets the supported size list.
 516  * @since_tizen 2.3.1
 517  * @privlevel public
 518  * @privilege %http://tizen.org/privilege/widget.viewer
 519  * @param[in] widget_id appid of widget application
 520  * @param[in,out] cnt Count of array w and h
 521  * @param[out] w Width array
 522  * @param[out] h Height array
 523  * @return @c 0 on success,
 524  *         otherwise a negative error value
 525  * @retval #WIDGET_ERROR_NONE If succeed to get supported size list
 526  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 527  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 528  * @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
 529  * @see widget_service_get_supported_size_types()
 530  */
 531 int widget_service_get_supported_sizes(const char *widget_id, int *cnt, int **w, int **h);
 532
 533
 534 /**
 535  * @brief Gets the supported size list of given widget ID.
 536  * @since_tizen 2.3.1
 537  * @privlevel public
 538  * @privilege %http://tizen.org/privilege/widget.viewer
 539  * @param[in] widgetid appid of widget application
 540  * @param[in] cnt Size of types array
 541  * @param[out] types Array of types
 542  * @return @c 0 on success,
 543  *         otherwise a negative error value
 544  * @retval #WIDGET_ERROR_NONE Successfully done
 545  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 546  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 547  * @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
 548  * @see widget_service_get_supported_sizes()
 549  */
 550 int widget_service_get_supported_size_types(const char *widgetid, int *cnt, int **types);
 551
 552
 553 /**
 554  * @brief Callback function for getting result of widget_service_get_widget_instance_list().
 555  * @since_tizen 2.3.1
 556  * @param[in] widget_id Widget appid
 557  * @param[in] instance_id widget instance ID
 558  * @param[in] user_data user Data
 559  * @return #WIDGET_ERROR_NONE to continue with the next iteration of the loop,
 560  *         other error values to break out of the loop
 561  * @see widget_service_get_widget_instance_list()
 562  */
 563 typedef int (*widget_instance_list_cb)(const char *widget_id, const char *instance_id, void *user_data);
 564
 565
 566 /**
 567  * @brief Gets widget instances of given widget_id.
 568  * @since_tizen 2.3.1
 569  * @param[in] widget_id appid of widget application
 570  * @param[in] cb Callback function
 571  * @param[in] data user Data for callback function
 572  * @return Size of widget instance list on success,
 573  *         otherwise a negative error value
 574  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 575  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 576  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 577  * @retval #WIDGET_ERROR_NOT_EXIST Instance is not exist
 578  * @see widget_instance_list_cb()
 579  */
 580 int widget_service_get_widget_instance_list(const char *widget_id, widget_instance_list_cb cb, void *data);
 581
 582
 583 /**
 584  * @brief Enumeration for life cycle event of widgets.
 585  * @since_tizen 2.3.1
 586  * @see widget_lifecycle_event_cb()
 587  */
 588 typedef enum widget_lifecycle_event {
 589         WIDGET_LIFE_CYCLE_EVENT_APP_DEAD = 0,
 590         WIDGET_LIFE_CYCLE_EVENT_CREATE  = 1,    /**< The widget is created */
 591         WIDGET_LIFE_CYCLE_EVENT_DESTROY = 2,    /**< The widget is destroyed */
 592         WIDGET_LIFE_CYCLE_EVENT_PAUSE   = 3,    /**< The widget is paused */
 593         WIDGET_LIFE_CYCLE_EVENT_RESUME  = 4,    /**< The widget is resumed */
 594         WIDGET_LIFE_CYCLE_EVENT_MAX     = 5
 595 } widget_lifecycle_event_e;
 596
 597
 598 /**
 599  * @brief Called when a widget is created or destroyed.
 600  * @since_tizen 2.3.1
 601  * @param[in] widget_id appid of widget application
 602  * @param[in] lifecycle_event Type of event
 603  * @param[in] widget_instance_id Widget instance ID
 604  * @param[in] user_data user data
 605  * @return @c 0 on success,
 606  *         otherwise a negative error value
 607  * @see widget_service_set_lifecycle_event_cb()
 608  */
 609 typedef int (*widget_lifecycle_event_cb)(const char *widget_id, widget_lifecycle_event_e lifecycle_event, const char *widget_instance_id, void *user_data);
 610
 611
 612 /**
 613  * @brief Sets event handler callback function for life cycle events of widgets.
 614  * @since_tizen 2.3.1
 615  * @param[in] widget_id appid of widget application
 616  * @param[in] cb Callback function
 617  * @param[in] data user Data
 618  * @return @c 0 on success,
 619  *         otherwise a negative error value
 620  * @retval #WIDGET_ERROR_NONE Successfully done
 621  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 622  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 623  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
 624  * @see widget_lifecycle_event_cb()
 625  * @see widget_service_unset_lifecycle_event_cb()
 626  */
 627 int widget_service_set_lifecycle_event_cb(const char *widget_id, widget_lifecycle_event_cb cb, void *data);
 628
 629
 630 /**
 631  * @brief Unsets event handler callback function for life cycle events of widgets.
 632  * @since_tizen 2.3.1
 633  * @param[in] widget_id appid of widget application
 634  * @param[out] user_data User callback data
 635  * @return @c 0 on success,
 636  *         otherwise a negative error value
 637  * @retval #WIDGET_ERROR_NONE Successfully done
 638  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 639  * @retval #WIDGET_ERROR_NOT_EXIST Event handler callback function does not exist
 640  * @see widget_service_set_lifecycle_event_cb()
 641  */
 642 int widget_service_unset_lifecycle_event_cb(const char *widget_id, void **user_data);
 643
 644
 645 /**
 646  * @brief Gets content of the widget instance.
 647  * @since_tizen 2.3.1
 648  * @param[in] widget_id appid of widget application
 649  * @param[in] widget_instance_id Widget instance ID
 650  * @param[out] b Bundle(content) data of the given widget instance, it should be released by caller.
 651  * @return @c 0 on success,
 652  *         otherwise a negative error value
 653  * @retval #WIDGET_ERROR_NONE Successfully done
 654  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
 655  * @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
 656  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 657  * @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
 658  * @retval #WIDGET_ERROR_FAULT Failed to create a request packet
 659  * @retval #WIDGET_ERROR_NOT_EXIST Not exists
 660  * @post Caller should have to release the bundle.
 661  */
 662 int widget_service_get_content_of_widget_instance(const char *widget_id, const char *widget_instance_id, bundle **b);
 663
 664 /**
 665  * @brief Called when a widget is disabled or enabled.
 666  * @since_tizen 5.5
 667  * @param[in] widget_id The widget id\n
 668  *            The @a widget_id can be used only in the callback. To use outside, make a copy.
 669  * @param[in] is_disabled The new value of the 'disabled' state of the widget
 670  * @param[in] user_data The user data passed from the callback registration function
 671  * @see widget_service_set_disable_event_cb()
 672  * @see widget_service_unset_disable_event_cb()
 673  */
 674 typedef void (*widget_disable_event_cb)(const char *widget_id, bool is_disabled, void *user_data);
 675
 676 /**
 677  * @platform
 678  * @brief Sets the 'disabled' state of a widget.
 679  * @since_tizen 5.5
 680  * @privlevel platform
 681  * @privilege %http://tizen.org/privilege/packagemanager.admin
 682  * @param[in] widget_id The widget id
 683  * @param[in] disabled @c true, the widget will be disabled
 684  * @return @c 0 on success,
 685  *         otherwise a negative error value
 686  * @retval WIDGET_ERROR_NONE Successfully done
 687  * @retval WIDGET_ERROR_NOT_SUPPORTED Not supported
 688  * @retval WIDGET_ERROR_PERMISSION_DENIED Permission denied
 689  * @retval WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 690  * @retval WIDGET_ERROR_FAULT Fault
 691  */
 692 int widget_service_set_widget_disabled(const char *widget_id, bool disabled);
 693
 694 /**
 695  * @brief Gets the 'disabled' state of a widget.
 696  * @since_tizen 5.5
 697  * @privlevel public
 698  * @privilege %http://tizen.org/privilege/widget.viewer
 699  * @param[in] widget_id The widget id
 700  * @param[out] is_disabled The disable state of widget
 701  * @return @c 0 on success,
 702  *         otherwise a negative error value
 703  * @retval WIDGET_ERROR_NONE Successfully done
 704  * @retval WIDGET_ERROR_NOT_SUPPORTED Not supported
 705  * @retval WIDGET_ERROR_PERMISSION_DENIED Permission denied
 706  * @retval WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 707  * @retval WIDGET_ERROR_IO_ERROR Failed to access DB
 708  * @retval WIDGET_ERROR_FAULT Fault
 709  */
 710 int widget_service_get_widget_disabled(const char *widget_id, bool *is_disabled);
 711
 712 /**
 713  * @brief Sets the callback function for widget disable event.
 714  * @since_tizen 5.5
 715  * @privlevel public
 716  * @privilege %http://tizen.org/privilege/widget.viewer
 717  * @remarks The @a callback should be unset using widget_service_unset_disable_event_cb() before the application exits.
 718  * @param[in] callback The callback function
 719  * @param[in] user_data The user data to be passed to the callback function
 720  * @return @c 0 on success,
 721  *         otherwise a negative error value
 722  * @retval WIDGET_ERROR_NONE Successfully done
 723  * @retval WIDGET_ERROR_NOT_SUPPORTED Not supported
 724  * @retval WIDGET_ERROR_PERMISSION_DENIED Permission denied
 725  * @retval WIDGET_ERROR_INVALID_PARAMETER Invalid argument
 726  * @retval WIDGET_ERROR_IO_ERROR IO error
 727  * @see widget_disable_event_cb()
 728  * @see widget_service_unset_disable_event_cb()
 729  */
 730 int widget_service_set_disable_event_cb(widget_disable_event_cb callback, void *user_data);
 731
 732 /**
 733  * @brief Unsets the callback function for widget disable event.
 734  * @since_tizen 5.5
 735  * @privlevel public
 736  * @privilege %http://tizen.org/privilege/widget.viewer
 737  * @return @c 0 on success,
 738  *         otherwise a negative error value
 739  * @retval WIDGET_ERROR_NONE Successfully done
 740  * @retval WIDGET_ERROR_NOT_SUPPORTED Not supported
 741  * @retval WIDGET_ERROR_PERMISSION_DENIED Permission denied
 742  * @retval WIDGET_ERROR_IO_ERROR IO error
 743  * @see widget_disable_event_cb()
 744  * @see widget_service_set_disable_event_cb()
 745  */
 746 int widget_service_unset_disable_event_cb(void);
 747
 748
 749 /**
 750  * @}
 751  */
 752
 753 #ifdef __cplusplus
 754 }
 755 #endif
 756
 757 #endif
 758
 759 /* End of a file */