include/livebox-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 __LIVEBOX_SERVICE_H
  18 #define __LIVEBOX_SERVICE_H
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /*!
  25  * \addtogroup CAPI_LIVEBOX_SERVICE_MODULE
  26  * \{
  27  */
  28
  29 /*!
  30  * \brief
  31  * Maximum number of supported livebox size type
  32  */
  33 #define NR_OF_SIZE_LIST 13
  34
  35 #define CH_IDX(a, idx) (((char *)(a))[(idx)])
  36 #define IS_INHOUSE_LIVEBOX(abi) ((CH_IDX(abi, 0) == 'c' || CH_IDX(abi, 0) == 'C') && (CH_IDX(abi, 1) == '\0' || ((CH_IDX(abi, 1) == 'p' || CH_IDX(abi, 1) == 'P') && (CH_IDX(abi, 2) == 'p' || CH_IDX(abi, 2) == 'P') && CH_IDX(abi, 3) == '\0')))
  37
  38 /*!
  39  * \brief
  40  * List of supporting livebox size types
  41  */
  42 enum livebox_size_type {
  43         LB_SIZE_TYPE_1x1 = 0x0001, /*!< 175x175 */
  44         LB_SIZE_TYPE_2x1 = 0x0002, /*!< 354x175 */
  45         LB_SIZE_TYPE_2x2 = 0x0004, /*!< 354x354 */
  46         LB_SIZE_TYPE_4x1 = 0x0008, /*!< 712x175 */
  47         LB_SIZE_TYPE_4x2 = 0x0010, /*!< 712x354 */
  48         LB_SIZE_TYPE_4x3 = 0x0020, /*!< 712x533 */
  49         LB_SIZE_TYPE_4x4 = 0x0040, /*!< 712x712 */
  50         LB_SIZE_TYPE_4x5 = 0x0080, /*!< 712x891 */
  51         LB_SIZE_TYPE_4x6 = 0x0100, /*!< 712x1070 */
  52         LB_SIZE_TYPE_EASY_1x1 = 0x1000, /*!< 224x215 */
  53         LB_SIZE_TYPE_EASY_3x1 = 0x2000, /*!< 680x215 */
  54         LB_SIZE_TYPE_EASY_3x3 = 0x4000, /*!< 680x653 */
  55         LB_SIZE_TYPE_0x0 = 0x0800, /*!< 720x1280 */
  56         LB_SIZE_TYPE_UNKNOWN = 0xFFFF /*!< Error */
  57 };
  58
  59 /*!
  60  * \brief
  61  * Script event of livebox
  62  * This enumeration value will be used for script plugin of data-provider-master.
  63  * master will send down these accessibility events to the script plugin.
  64  */
  65 enum livebox_script_event {
  66         LB_SCRIPT_ACCESS_EVENT          = 0x01000000, /*!< Mask value */
  67         LB_SCRIPT_MOUSE_EVENT           = 0x02000000, /*!< Mask value */
  68         LB_SCRIPT_KEY_EVENT             = 0x04000000, /*!< Mask value */
  69
  70         LB_SCRIPT_ACCESS_HIGHLIGHT      = LB_SCRIPT_ACCESS_EVENT | 0x00000001, /*!< Highlight */
  71         LB_SCRIPT_ACCESS_HIGHLIGHT_NEXT = LB_SCRIPT_ACCESS_EVENT | 0x00000002, /*!< Move Highlight focus to the next object */
  72         LB_SCRIPT_ACCESS_HIGHLIGHT_PREV = LB_SCRIPT_ACCESS_EVENT | 0x00000004, /*!< Move Highlight focus to the prev object */
  73         LB_SCRIPT_ACCESS_ACTIVATE       = LB_SCRIPT_ACCESS_EVENT | 0x00000008, /*!< Activate the highlighted object */
  74         LB_SCRIPT_ACCESS_ACTION         = LB_SCRIPT_ACCESS_EVENT | 0x00000010, /*!< Do specified action for the highlighted object */
  75         LB_SCRIPT_ACCESS_SCROLL         = LB_SCRIPT_ACCESS_EVENT | 0x00000020, /*!< Scroll operation */
  76         LB_SCRIPT_ACCESS_UNHIGHLIGHT    = LB_SCRIPT_ACCESS_EVENT | 0x00000040, /*!< Remove highlight */
  77
  78         LB_SCRIPT_MOUSE_DOWN    = LB_SCRIPT_MOUSE_EVENT | 0x00001000, /*!< Mouse down */
  79         LB_SCRIPT_MOUSE_MOVE    = LB_SCRIPT_MOUSE_EVENT | 0x00002000, /*!< Mouse move */
  80         LB_SCRIPT_MOUSE_UP      = LB_SCRIPT_MOUSE_EVENT | 0x00004000, /*!< Mouse up */
  81         LB_SCRIPT_MOUSE_IN      = LB_SCRIPT_MOUSE_EVENT | 0x00008000, /*!< Mouse in */
  82         LB_SCRIPT_MOUSE_OUT     = LB_SCRIPT_MOUSE_EVENT | 0x00010000, /*!< Mouse out */
  83
  84         LB_SCRIPT_KEY_DOWN      = LB_SCRIPT_KEY_EVENT | 0x00020000, /*!< Key pressed */
  85         LB_SCRIPT_KEY_UP        = LB_SCRIPT_KEY_EVENT | 0x00040000, /*!< Key released */
  86         LB_SCRIPT_KEY_FOCUS_IN  = LB_SCRIPT_KEY_EVENT | 0x00080000, /*!< Key focus in */
  87         LB_SCRIPT_KEY_FOCUS_OUT = LB_SCRIPT_KEY_EVENT | 0x00100000, /*!< Key focus out */
  88 };
  89
  90 /*!
  91  * \brief Result of Accessibility event processing
  92  * Reference the libprovider & liblivebox-viewer
  93  */
  94 enum livebox_access_status {
  95         LB_ACCESS_STATUS_ERROR = 0x80000000, /*!< Mask value */
  96         LB_ACCESS_STATUS_DONE = 0x00000000, /*!< Successfully finished */
  97         LB_ACCESS_STATUS_FIRST, /*!< Reach to the first item */
  98         LB_ACCESS_STATUS_LAST, /*!< Reach to the last item */
  99         LB_ACCESS_STATUS_READ /*!< TTS is done */
 100 };
 101
 102 enum livebox_key_status {
 103         LB_KEY_STATUS_ERROR = 0x80000000, /*!< Key operation is failed */
 104         LB_KEY_STATUS_DONE = 0x00000000, /*!< Key operation is successfully done */
 105         LB_KEY_STATUS_FIRST, /*!< Focusable object item reaches to the first in it */
 106         LB_KEY_STATUS_LAST, /*!< Focusable object item reaches to the last in it */
 107 };
 108
 109 enum livebox_delete_type {
 110         LB_DELETE_PERMANENTLY = 0x01, /*!< The livebox is removed from the homescreen temporary */
 111         LB_DELETE_TEMPORARY = 0x02, /*!< The livebox is removed from the homescreen by user permanently */
 112         LB_DELETE_INVALID = 0xff,
 113 };
 114
 115 enum livebox_pd_close_type {
 116         LB_CLOSE_PD_NORMAL = 0x00,
 117         LB_CLOSE_PD_TIMEOUT = 0x01,
 118         LB_CLOSE_PD_FAULT = 0x02,
 119         LB_CLOSE_PD_INVALID = 0xff,
 120 };
 121
 122 /*!
 123  * \brief
 124  * Handle of Package List
 125  */
 126 struct pkglist_handle;
 127
 128 /*!
 129  * \brief Get the pixel size of given size type.
 130  * \details
 131  *  Size types can be (defined in liblivebox-service pakcage, include livebox-service.h)
 132  *  LB_SIZE_TYPE_1x1
 133  *  LB_SIZE_TYPE_2x1
 134  *  LB_SIZE_TYPE_2x2
 135  *  LB_SIZE_TYPE_4x1
 136  *  LB_SIZE_TYPE_4x2
 137  *  LB_SIZE_TYPE_4x3
 138  *  LB_SIZE_TYPE_4x4
 139  *  LB_SIZE_TYPE_4x5
 140  *  LB_SIZE_TYPE_4x6
 141  *  LB_SIZE_TYPE_0x0
 142  *  LB_SIZE_TYPE_EASY_1x1
 143  *  LB_SIZE_TYPE_EASY_3x1
 144  *  LB_SIZE_TYPE_EASY_3x3
 145  * \remarks N/A
 146  * \param[in] type Size type
 147  * \param[out] width Pixel size width
 148  * \param[out] height Pixel size height
 149  * \return int
 150  * \retval LB_STATUS_SUCCESS Successfully done
 151  * \pre N/A
 152  * \post N/A
 153  * \see livebox_size_type
 154  * \see livebox_service_size_type
 155  */
 156 extern int livebox_service_get_size(int type, int *width, int *height);
 157
 158 /*!
 159  * \brief Get the size type for given pixel size.
 160  * \details
 161  *  Returnable size types are (defined in liblivebox-service pakcage, include livebox-service.h)
 162  *  LB_SIZE_TYPE_1x1
 163  *  LB_SIZE_TYPE_2x1
 164  *  LB_SIZE_TYPE_2x2
 165  *  LB_SIZE_TYPE_4x1
 166  *  LB_SIZE_TYPE_4x2
 167  *  LB_SIZE_TYPE_4x3
 168  *  LB_SIZE_TYPE_4x4
 169  *  LB_SIZE_TYPE_4x5
 170  *  LB_SIZE_TYPE_4x6
 171  *  LB_SIZE_TYPE_0x0
 172  *  LB_SIZE_TYPE_EASY_1x1
 173  *  LB_SIZE_TYPE_EASY_3x1
 174  *  LB_SIZE_TYPE_EASY_3x3
 175  *  or
 176  *  LB_SIZE_TYPE_UNKNOWN for error
 177  * \remarks N/A
 178  * \param[in] width Pixel size width
 179  * \param[in] height Pixel size height
 180  * \return int
 181  * \retval LB_SIZE_TYPE_[EASY_]WxH Size type of given pixel size.
 182  * \retval LB_SIZE_TYPE_UNKNOWN if the given pixel size is not valid.
 183  * \pre N/A
 184  * \post N/A
 185  * \see livebox_size_type
 186  * \see livebox_service_get_size
 187  */
 188 extern int livebox_service_size_type(int width, int height);
 189
 190 /*!
 191  * \brief Is this livebox support the mouse event of livebox content?
 192  * \details N/A
 193  * \remarks N/A
 194  * \param[in] pkgid Livebox's appid
 195  * \return int
 196  * \retval 1 if the box requires mouse event
 197  * \retval 0 if the box doesn't requires mouse event
 198  * \pre N/A
 199  * \post N/A
 200  * \see livebox_service_touch_effect
 201  * \see livebox_service_need_frame
 202  */
 203 extern int livebox_service_mouse_event(const char *pkgid);
 204
 205 /*!
 206  * \brief Is this livebox requires touch effect?
 207  *        If this API returns true(1), the viewer should make touch effect when a user click the livebox.
 208  * \param[in] pkgid Livebox's appid
 209  * \param[in] size_type
 210  * \return int
 211  * \retval 1 if the box requires touch effect
 212  * \retval 0 if the box doesn't requires touch effect, the box will make touch effect itself
 213  * \pre N/A
 214  * \post N/A
 215  * \see livebox_service_mouse_event
 216  * \see livebox_service_need_frame
 217  */
 218 extern int livebox_service_touch_effect(const char *pkgid, int size_type);
 219
 220 /*!
 221  * \brief Is this livebox requires decoration frame?
 222  *        If this API returns true(1), the viewer should make decoration border on the livebox content.
 223  * \details N/A
 224  * \remarks N/A
 225  * \param[in] pkgid Livebox's appid
 226  * \param[in] size_type
 227  * \return int
 228  * \retval 1 If the box requires frame for decorating its contents
 229  * \retval 0 If the box doesn't requires frame
 230  * \see livebox_service_mouse_event
 231  * \see livebox_service_touch_effect
 232  */
 233 extern int livebox_service_need_frame(const char *pkgid, int size_type);
 234
 235 /*!
 236  * \brief Trigger the update event for given livebox instance
 237  * \details N/A
 238  * \remarks N/A
 239  * \param[in] pkgname Livebox package name
 240  * \param[in] id Set NULL if you don't know what the Id is. Then every instance of given pkgname will be triggered its update event.
 241  * \param[in] cluster Cluster name. Default NULL
 242  * \param[in] category Category name, Default NULL
 243  * \param[in] force 1 if you want to update your livebox even if the provider is paused or 0. 0 is default
 244  * \return int
 245  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 246  * \retval LB_STATUS_ERROR_CANCEL Provider is paused, so this update request is canceld.(ignored), if you want to make update forcely, use force=1
 247  * \retval LB_STATUS_ERROR_MEMORY Memory is not enough to make request
 248  * \retval LB_STATUS_ERROR_FAULT Failed to create a request packet
 249  * \retval LB_STATUS_SUCCESS Successfully requested
 250  * \see N/A
 251  */
 252 extern int livebox_service_trigger_update(const char *pkgname, const char *id, const char *cluster, const char *category, int force);
 253
 254 /*!
 255  * \brief Trigger the update event for given livebox instance
 256  * \details N/A
 257  * \remarks N/A
 258  * \param[in] pkgname Livebox package name
 259  * \param[in] id Set NULL if you don't know what the Id is. Then every instance of given pkgname will be triggered its update event.
 260  * \param[in] cluster Cluster name. Default NULL
 261  * \param[in] category Category name, Default NULL
 262  * \param[in] content New content information, Default NULL
 263  * \param[in] force 1 if you want to update your livebox even if the provider is paused or 0. 0 is default
 264  * \return int
 265  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 266  * \retval LB_STATUS_ERROR_CANCEL Provider is paused, so this update request is canceld.(ignored), if you want to make update forcely, use force=1
 267  * \retval LB_STATUS_ERROR_MEMORY Memory is not enough to make request
 268  * \retval LB_STATUS_ERROR_FAULT Failed to create a request packet
 269  * \retval LB_STATUS_SUCCESS Successfully requested
 270  * \see livebox_service_trigger_update
 271  */
 272 extern int livebox_service_trigger_update_with_content(const char *pkgname, const char *id, const char *cluster, const char *category, const char *content, int force);
 273
 274 /*!
 275  * \brief Change the update period of given livebox instance
 276  * \details N/A
 277  * \remarks N/A
 278  * \param[in] pkgname Livebox package name
 279  * \param[in] id Livebox instance id
 280  * \param[in] period New update period in sec
 281  * \return int
 282  * \retval LB_STATUS_SUCCESS Successfully changed(requested)
 283  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 284  * \retval LB_STATUS_ERROR_FAULT Failed to create a request packet
 285  * \retval LB_STATUS_ERROR_MEMORY Not enough memory
 286  * \see N/A
 287  */
 288 extern int livebox_service_change_period(const char *pkgname, const char *id, double period);
 289
 290 /*!
 291  * \brief Synchronous package list getter
 292  * \details
 293  *        callback (appid, lbid, is_prime)
 294  *        appid == Application Package ID (pkgname)
 295  *        lbid = Livebox Package ID
 296  *        is_prime = 1 if the livebox is default one for associated application package
 297  *        If the callback returns negative value, the list crawling will be stopped
 298  * \remarks N/A
 299  * \param[in] cb Callback function
 300  * \param[in] data Callback data
 301  * \return int
 302  * \retval LB_STATUS_ERROR_IO Failed to access DB
 303  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 304  * \retval count count of livebox packages
 305  * \pre N/A
 306  * \post N/A
 307  * \see livebox_service_get_pkglist_by_pkgid
 308  */
 309 extern int livebox_service_get_pkglist(int (*cb)(const char *pkgid, const char *lbid, int is_prime, void *data), void *data);
 310
 311 /*!
 312  * \brief Synchronous uiapp list getter.
 313  * \details
 314  *        callback (appid, data)
 315  *        This function will retrieve all UI Apps in a package which has given livebox appid(lbid).
 316  *        If you need to get all ui-app list, using a livebox appid, this function is able to help you.
 317  * \remarks N/A
 318  * \param[in] lbid Livebox App Id
 319  * \param[in] cb Callback function
 320  * \param[in] data Callback Data
 321  * \return int
 322  * \retval LB_STATUS_SUCCESS
 323  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 324  * \retval LB_STATUS_ERROR_IO Failed to access DB
 325  * \retval LB_STATUS_ERROR_MEMORY
 326  * \retval LB_STATUS_ERROR_FAULT
 327  * \pre N/A
 328  * \post N/A
 329  * \see N/A
 330  */
 331 extern int livebox_service_get_applist(const char *lbid, void (*cb)(const char *lbid, const char *appid, void *data), void *data);
 332
 333 /*!
 334  * \brief Get the MAIN application Id of given livebox package Id.
 335  * \details N/A
 336  * \remarks N/A
 337  * \param[in] lbid Livebox Package Id
 338  * \return char *
 339  * \retval NULL if it fails to get main application Id (UI-APPID)
 340  * \retval appid Main application Id
 341  * \pre N/A
 342  * \post N/A
 343  */
 344 extern char *livebox_service_mainappid(const char *lbid);
 345
 346 /*!
 347  * \brief Synchronous package list getter
 348  * \details
 349  *        callback (lbid, is_prime)
 350  *        lbid == Livebox Package Id
 351  *        is_prime = 1 if the livebox is default one for selected package
 352  *        If the callback returns negative value, the list crawling will be stopped
 353  * \remarks N/A
 354  * \param[in] pkgid Package Id (Not the UI App Id)
 355  * \param[in] cb Callback function
 356  * \param[in] data Callback data
 357  * \return int
 358  * \retval Count of livebox packages
 359  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 360  * \retval LB_STATUS_ERROR_IO Failed to access DB
 361  * \see livebox_service_get_pkglist
 362  */
 363 extern int livebox_service_get_pkglist_by_pkgid(const char *pkgid, int (*cb)(const char *lbid, int is_prime, void *data), void *data);
 364
 365 /*!
 366  * \brief Synchronous package list getter
 367  * \details
 368  *        callback (lbid)
 369  *        lbid == Livebox Package Id
 370  *        If the callback returns negative value, the list crawling will be stopped
 371  * \remarks N/A
 372  * \param[in] category Package Id (Not the UI App Id)
 373  * \param[in] cb Callback function
 374  * \param[in] data Callback data
 375  * \return int
 376  * \retval Count of livebox packages
 377  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 378  * \retval LB_STATUS_ERROR_IO Failed to access DB
 379  * \see livebox_service_get_pkglist_by_pkgid
 380  */
 381 extern int livebox_service_get_pkglist_by_category(const char *category, int (*cb)(const char *lbid, void *data), void *data);
 382
 383 /*!
 384  * \brief Get the lbid of a primary livebox using given lbid or pkgid or UI appid.
 385  * \details N/A
 386  * \remarks N/A
 387  * \param[in] id Livebox Id or Package Id
 388  * \return char *
 389  * \retval NULL Failed to get primary lbid
 390  * \retval lbid Primary livebox Id. which is allocated in the heap
 391  * \pre Must be released returned string by manually
 392  * \post N/A
 393  * \see livebox_service_appid
 394  */
 395 extern char *livebox_service_pkgname(const char *id);
 396
 397 /*!
 398  * \brief Check the pirmary flag of given livebox Id.
 399  * \details N/A
 400  * \param[in] lbid Livebox Id
 401  * \return int
 402  * \retval 0 if is not a primary
 403  * \retval 1 if it is a primary livebox
 404  * \pre N/A
 405  * \post N/A
 406  * \see N/A
 407  */
 408 extern int livebox_service_is_primary(const char *lbid);
 409
 410 /*!
 411  * \brief Get the category using given lbid.
 412  * \details N/A
 413  * \remarks N/A
 414  * \param[in] id Livebox Id
 415  * \return char *
 416  * \retval NULL Failed to get primary lbid
 417  * \retval category Category string which is allocated in the heap.
 418  * \pre Must be released returned string by manually
 419  * \post N/A
 420  * \see livebox_service_pkgname
 421  */
 422 extern char *livebox_service_category(const char *lbid);
 423
 424 /*!
 425  * \brief Get the name of a livebox (provider name == livebox appid), you have to release the return value after use it
 426  * \details
 427  *    OSP livebox has provider process for each livebox instances.
 428  *    To get the provider's package name, you can use this API.
 429  *    If the given lbid is inhouse livebox, the return string will be the same with given argument but it is allocated in the heap.
 430  *    So you have to free it if you don't need it anymore.
 431  * \param[in] lbid Livebox Id
 432  * \return char *
 433  * \retval NULL failed to get provider name
 434  * \retval lbid Livebox AppId which is allocated on the heap
 435  * \pre N/A
 436  * \post Return'd string must be free'd manually
 437  * \see N/A
 438  */
 439 extern char *livebox_service_provider_name(const char *lbid);
 440
 441 /*!
 442  * \brief Get the appId of setup app which is specified by given livebox Id's manifest.
 443  *        This setup app should be launched before add the livebox to get the content_info
 444  * \details
 445  *    This function should be called before add a livebox.
 446  *    To determine the content information string.
 447  * \remarks N/A
 448  * \param[in] lbid Livebox Id
 449  * \return char *
 450  * \retval NULL there is no setup application
 451  * \retval appid AppId if exists or NULL
 452  * \pre N/A
 453  * \post return'd string must be free'd manually
 454  * \see N/A
 455  */
 456 extern char *livebox_service_setup_appid(const char *lbid);
 457
 458 /*!
 459  * \brief Get the Package Id (Not the UI App Id) of given livebox, &lt;manifest package="AAA"&gt;
 460  * \details N/A
 461  * \remarks N/A
 462  * \param[in] lbid Livebox AppId
 463  * \return char *
 464  * \retval appid String which is allocated in the heap
 465  * \retval NULL invalid appid
 466  * \pre N/A
 467  * \post return'd string must be free'd manually
 468  * \see livebox_service_pkgname
 469  */
 470 extern char *livebox_service_appid(const char *lbid);
 471
 472 /*!
 473  * \brief Internationalized name of given livebox package.
 474  * \details N/A
 475  * \remarks N/A
 476  * \param[in] pkgid App ID of a livebox. (It must has to be a livebox package ID. not the UI-APP and the PACKAGE.
 477  * \param[in] lang locale(en-us, ko-kr, ...), if it is NULL, function will use the system locale automatically
 478  * \return char *
 479  * \retval name if it fails to get name
 480  * \retval NULL, or allocated heap address.
 481  * \pre N/A
 482  * \post Return'd string must be free'd by manually
 483  * \see livebox_service_i18n_icon
 484  * \see livebox_service_preview
 485  */
 486 extern char *livebox_service_i18n_name(const char *pkgid, const char *lang);
 487
 488 /*!
 489  * \brief Get the preview image path of given size type.
 490  *        This function will returns i18nized preview image path.
 491  * \details N/A
 492  * \remarks N/A
 493  * \param[in] pkgid livebox ID. NOT the UI-APP ID and PACKAGE ID
 494  * \param[in] size_type Livebox size type.
 495  * \return char *
 496  * \retval path preview image path
 497  * \retval NULL if there is no preview image file
 498  * \pre N/A
 499  * \post Return'd string must be free'd manually
 500  * \see livebox_service_i18n_icon
 501  * \see livebox_service_i18n_name
 502  */
 503 extern char *livebox_service_preview(const char *pkgid, int size_type);
 504
 505 /*!
 506  * \brief Get the default content string of the given livebox
 507  * \details
 508  *    If a user defins default content string in the manifest file (.xml)
 509  *    This API will returns it.
 510  * \remarks N/A
 511  * \param[in] pkgid Livebox ID. Not the UI-APP ID and PACKAGE ID
 512  * \return char *
 513  * \retval content content string
 514  * \retval NULL there is no specified content string
 515  * \pre manifest has the default content string. &lt;content&gt;Default content string&lt;content&gt;
 516  * \post return'd string must be free'd manually
 517  * \see N/A
 518  */
 519 extern char *livebox_service_content(const char *pkgid);
 520
 521 /*!
 522  * \brief Internationalized icon path of given livebox package.
 523  *        USER must has to do "free" after using the returned string.
 524  * \details N/A
 525  * \remarks N/A
 526  * \param[in] pkgid App ID of a livebox. (It must has to be a livebox package ID. not the UI-APP and the PACKAGE.
 527  * \param[in] lang locale(en-us, ko-kr, ...), if it is NULL, function will use the system locale automatically
 528  * \return char *
 529  * \retval name allocated heap address.
 530  * \retval NULL if it fails to get path of an icon
 531  * \pre N/A
 532  * \post return'd string must be free'd manually
 533  * \see livebox_service_i18n_name
 534  * \see livebox_service_preview
 535  */
 536 extern char *livebox_service_i18n_icon(const char *pkgid, const char *lang);
 537
 538 /*!
 539  * \brief Get the path of the plug-in module
 540  * \details N/A
 541  * \remarks N/A
 542  * \param[in] lbid Package name of a livebox
 543  * \return char *
 544  * \retval path String which is allocated on the heap
 545  * \retval NULL if there is no libexec attribute
 546  * \pre N/A
 547  * \post return'd string must be free'd manually
 548  * \see N/A
 549  */
 550 extern char *livebox_service_libexec(const char *lbid);
 551
 552 /*!
 553  * \brief Get the "nodisplay" value
 554  * \details N/A
 555  * \remarks N/A
 556  * \param[in] pkgid Livebox package id.
 557  * \return int
 558  * \retval 1 if the box should not be listed by the livebox list app
 559  * \retval 0 box should be listed
 560  * \pre livebox tag includes "nodisplay" attribute.
 561  * \post N/A
 562  * \see N/A
 563  */
 564 extern int livebox_service_nodisplay(const char *pkgid);
 565
 566 /*!
 567  * \brief Get the "ABI" of given package
 568  * \details N/A
 569  * \remarks N/A
 570  * \param[in] lbid Livebox package id.
 571  * \return char *
 572  * \retval abi String which is allocated in the heap
 573  * \retval NULL if failed to get ABI of given livebox.
 574  * \pre N/A
 575  * \post return'd string must be free'd manually
 576  * \see N/A
 577  */
 578 extern char *livebox_service_abi(const char *lbid);
 579
 580 /*!
 581  * \brief Check the status of the livebox
 582  *        Currently this API is not implemented. just returns 1 all the time.
 583  * \details N/A
 584  * \remarks This API is not implemented. it will always returns 1
 585  * \param[in] lbid Livebox Id
 586  * \return int
 587  * \retval 1 enabled
 588  * \retval 0 disabled
 589  * \pre N/A
 590  * \post N/A
 591  * \see N/A
 592  */
 593 extern int livebox_service_is_enabled(const char *lbid);
 594
 595 /*!
 596  * \brief Get the script file of livebox.
 597  * \details N/A
 598  * \remarks N/A
 599  * \param[in] lbid Livebox Package Id
 600  * \return char *
 601  * \retval string script file path
 602  * \retval NULL if there is not specified script file
 603  * \pre livebox should be developed as script type
 604  * \post Return'd string must be free'd manually
 605  * \see livebox_service_lb_script_group
 606  */
 607 extern char *livebox_service_lb_script_path(const char *lbid);
 608
 609 /*!
 610  * \brief Get the script group of livebox
 611  * \details N/A
 612  * \remarks N/A
 613  * \param[in] lbid Livebox Package Id
 614  * \return char *
 615  * \retval Group name of livebox
 616  * \retval NULL if there is no group defined
 617  * \pre livebox should be developed as script type
 618  * \post return'd string must be free'd manually
 619  * \see livebox_service_lb_script_path
 620  */
 621 extern char *livebox_service_lb_script_group(const char *lbid);
 622
 623 /*!
 624  * \brief Get the script file path of given livebox package.
 625  * \details N/A
 626  * \remarks N/A
 627  * \param[in] lbid Livebox Package Id
 628  * \return char *
 629  * \retval string script file path.
 630  * \retval NULL if there is no specified script file for PD layout
 631  * \pre N/A
 632  * \post Return'd string must be free'd manually
 633  * \see livebox_service_pd_script_group
 634  */
 635 extern char *livebox_service_pd_script_path(const char *lbid);
 636
 637 /*!
 638  * \brief Get the group name for script file to load it.
 639  * \details N/A
 640  * \remarks N/A
 641  * \param[in] lbid Livebox package Id
 642  * \return char *
 643  * \retval string script group name
 644  * \retval NULL if there is no script path
 645  * \pre N/A
 646  * \post return'd string must be free'd manually
 647  * \see livebox_service_pd_script_path
 648  */
 649 extern char *livebox_service_pd_script_group(const char *lbid);
 650
 651 /*!
 652  * \brief Get the supported size list.
 653  * \details N/A
 654  * \remarks N/A
 655  * \param[in] pkgid Livebox Package Id
 656  * \param[in] cnt Count of array w and h
 657  * \param[in] w Width array
 658  * \param[in] h Height array
 659  * \param[out] cnt Count of array w and h
 660  * \param[out] w Width array
 661  * \param[out] h Height array
 662  * \return int
 663  * \retval LB_STATUS_SUCCESS if succeed to get supported size list
 664  * \retval LB_STATUS_ERROR_IO Failed to access DB
 665  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 666  * \pre N/A
 667  * \post N/A
 668  * \see livebox_service_get_supported_size_types
 669  */
 670 extern int livebox_service_get_supported_sizes(const char *pkgid, int *cnt, int *w, int *h);
 671
 672 /*!
 673  * \brief Get the supported size list of given pkgid
 674  * \param[in] pkgid Package Name of livebox
 675  * \param[in] cnt size of types array
 676  * \param[out] cnt result count of types array
 677  * \param[out] types array of types
 678  * \return int
 679  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 680  * \retval LB_STATUS_ERROR_IO Failed to access DB
 681  * \retval LB_STATUS_SUCCESS Successfully done
 682  * \pre N/A
 683  * \post N/A
 684  * \see livebox_service_get_supported_sizes
 685  */
 686 extern int livebox_service_get_supported_size_types(const char *pkgid, int *cnt, int *types);
 687
 688 /*!
 689  * \brief Get the category list of given cluster
 690  * \details N/A
 691  * \remarks N/A
 692  * \param[in] cluster Cluster name
 693  * \param[in] cb Callback function
 694  * \param[in] data Callback data
 695  * \return int
 696  * \retval LB_STATUS_SUCCESS Successfully done
 697  * \retval LB_STATUS_ERROR_IO Failed to access DB
 698  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 699  * \pre N/A
 700  * \post N/A
 701  * \see livebox_service_enumerate_cluster_list
 702  */
 703 extern int livebox_service_enumerate_category_list(const char *cluster, int (*cb)(const char *cluster, const char *category, void *data), void *data);
 704
 705 /*!
 706  * \brief Get the cluster list
 707  * \details N/A
 708  * \remarks N/A
 709  * \param[in] cb Callback function for retrieving the cluster list
 710  * \param[in] data Callback data
 711  * \return int
 712  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 713  * \retval LB_STATUS_ERROR_IO Failed to access DB
 714  * \retval count of category items
 715  * \pre N/A
 716  * \post N/A
 717  * \see livebox_service_enumerate_category_list
 718  */
 719 extern int livebox_service_enumerate_cluster_list(int (*cb)(const char *cluster, void *data), void *data);
 720
 721 /*!
 722  * \brief Initialize the Livebox service API
 723  * \details Open the DB file.
 724  *    You don't need to call this if you are using livebox service API shortly.
 725  *    but if you are using livebox service API while whole life of your S/W,
 726  *    using this, initate the livebox service is more benefical to you.
 727  *    This API will prepare the DB operation, if you don't initiate the livebox service,
 728  *    every API which are related with DB operation will open DB and close it before return from it.
 729  * \remarks N/A
 730  * \return int
 731  * \retval LB_STATUS_SUCCESS if succeed to initialize
 732  * \retval LB_STATUS_ERROR_IO Failed to access a DB
 733  * \pre N/A
 734  * \post N/A
 735  * \see livebox_service_fini
 736  */
 737 extern int livebox_service_init(void);
 738
 739 /*!
 740  * \brief Finalize the livebox service API
 741  * \details N/A
 742  * \remarks N/A
 743  * \return int
 744  * \retval LB_STATUS_SUCCESS if succeed to finalize
 745  * \retval LB_STATUS_ERROR_IO Failed to close the DB (access failed to DB)
 746  * \pre livebox_service_init
 747  * \post N/A
 748  * \see livebox_service_init
 749  */
 750 extern int livebox_service_fini(void);
 751
 752 /*!
 753  * \brief Create a handle for getting the package list.
 754  * \details
 755  *    If you want get the record one by one from DB, use this.
 756  *    This function will create a iterator.
 757  *    Then you can get the record one by one, but there is no backward iterator.
 758  *    Only you can get forward iterator.
 759  *    After call this function the iterator will be moved to next record automatically.
 760  * \remarks
 761  *    If you call this function again using created pkglist handle, it will be reset'd
 762  *    so you can get record from first one again.
 763  * \param[in] pkgid Livebox Package Id
 764  * \param[in] handle NULL if you call this first. or it will be reseted.
 765  * \return handle
 766  * \retval NULL if it fails
 767  * \retval handle if it successfully create the package list iterator
 768  * \see livebox_service_pkglist_destroy
 769  */
 770 extern struct pkglist_handle *livebox_service_pkglist_create(const char *pkgid, struct pkglist_handle *handle);
 771
 772 /*!
 773  * \brief Get the lbid & package name & is_prime flag.
 774  * \param[in] handle Handle which is created by livebox_service_pkglist_create function
 775  * \param[out] lbid  Livebox Id
 776  * \param[out] pkgname Package Id that includes lbid
 777  * \param[out] is_prime if the returned lbid is primary, this will be 1 or 0
 778  * \return int
 779  * \retval LB_STATUS_SUCCESS Successfully get the record
 780  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 781  * \retval LB_STATUS_ERROR_NOT_EXIST reach to the end of result set. you can rewind the iterator call livebox_service_pkglist_create again with current handle.
 782  * \retval LB_STATUS_ERROR_MEMORY Not enough memory
 783  * \pre N/A
 784  * \post you must release the lbid, pkgname manually
 785  * \see livebox_service_pkglist_create
 786  * \see livebox_service_pkglist_destroy
 787  */
 788 extern int livebox_service_get_pkglist_item(struct pkglist_handle *handle, char **lbid, char **pkgname, int *is_prime);
 789
 790 /*!
 791  * \brief Destroy the iterator of pkglist
 792  * \details N/A
 793  * \remarks N/A
 794  * \param[in] handle Package list handle
 795  * \return int
 796  * \retval LB_STATUS_ERROR_INVALID Invalid handle
 797  * \retval LB_STATUS_SUCCESS Successfully destroyed
 798  * \pre handle must be created by livebox_service_pkglist_create
 799  * \post you have not to use the handle again after destroy it.
 800  * \see livebox_service_pkglist_create
 801  */
 802 extern int livebox_service_pkglist_destroy(struct pkglist_handle *handle);
 803
 804 /*!
 805  * \brief Find the pkgname by its libexec
 806  * \details only if the livebox should use the "libexec" attribute in its "<livebox>" tag
 807  * \remars Only usable for inhouse liveboxes
 808  * \param[in] libexec so filename
 809  * \return char *
 810  * \retval NULL if it fails to get pkgname
 811  * \retval address heap address of pkgname
 812  * \pre N/A
 813  * \post return'd string should be released via "free"
 814  */
 815 extern char *livebox_service_pkgname_by_libexec(const char *libexec);
 816
 817 /*!
 818  * \}
 819  */
 820
 821 #ifdef __cplusplus
 822 }
 823 #endif
 824
 825 #endif
 826
 827 /* End of a file */