2 * Copyright 2013 Samsung Electronics Co., Ltd
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
8 * http://floralicense.org/license/
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.
17 #ifndef __LIVEBOX_SERVICE_H
18 #define __LIVEBOX_SERVICE_H
25 * \addtogroup CAPI_LIVEBOX_SERVICE_MODULE
31 * Maximum number of supported livebox size type
33 #define NR_OF_SIZE_LIST 13
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')))
40 * List of supporting livebox size types
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 */
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.
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 */
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 */
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 */
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 */
91 * \brief Result of Accessibility event processing
92 * Reference the libprovider & liblivebox-viewer
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 */
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 */
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,
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,
124 * Handle of Package List
126 struct pkglist_handle;
129 * \brief Get the pixel size of given size type.
131 * Size types can be (defined in liblivebox-service pakcage, include livebox-service.h)
142 * LB_SIZE_TYPE_EASY_1x1
143 * LB_SIZE_TYPE_EASY_3x1
144 * LB_SIZE_TYPE_EASY_3x3
146 * \param[in] type Size type
147 * \param[out] width Pixel size width
148 * \param[out] height Pixel size height
150 * \retval LB_STATUS_SUCCESS Successfully done
153 * \see livebox_size_type
154 * \see livebox_service_size_type
156 extern int livebox_service_get_size(int type, int *width, int *height);
159 * \brief Get the size type for given pixel size.
161 * Returnable size types are (defined in liblivebox-service pakcage, include livebox-service.h)
172 * LB_SIZE_TYPE_EASY_1x1
173 * LB_SIZE_TYPE_EASY_3x1
174 * LB_SIZE_TYPE_EASY_3x3
176 * LB_SIZE_TYPE_UNKNOWN for error
178 * \param[in] width Pixel size width
179 * \param[in] height Pixel size height
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.
185 * \see livebox_size_type
186 * \see livebox_service_get_size
188 extern int livebox_service_size_type(int width, int height);
191 * \brief Is this livebox support the mouse event of livebox content?
194 * \param[in] pkgid Livebox's appid
196 * \retval 1 if the box requires mouse event
197 * \retval 0 if the box doesn't requires mouse event
200 * \see livebox_service_touch_effect
201 * \see livebox_service_need_frame
203 extern int livebox_service_mouse_event(const char *pkgid);
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
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
215 * \see livebox_service_mouse_event
216 * \see livebox_service_need_frame
218 extern int livebox_service_touch_effect(const char *pkgid, int size_type);
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.
225 * \param[in] pkgid Livebox's appid
226 * \param[in] size_type
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
233 extern int livebox_service_need_frame(const char *pkgid, int size_type);
236 * \brief Trigger the update event for given livebox instance
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
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
252 extern int livebox_service_trigger_update(const char *pkgname, const char *id, const char *cluster, const char *category, int force);
255 * \brief Trigger the update event for given livebox instance
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
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
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);
275 * \brief Change the update period of given livebox instance
278 * \param[in] pkgname Livebox package name
279 * \param[in] id Livebox instance id
280 * \param[in] period New update period in sec
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
288 extern int livebox_service_change_period(const char *pkgname, const char *id, double period);
291 * \brief Synchronous package list getter
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
299 * \param[in] cb Callback function
300 * \param[in] data Callback data
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
307 * \see livebox_service_get_pkglist_by_pkgid
309 extern int livebox_service_get_pkglist(int (*cb)(const char *pkgid, const char *lbid, int is_prime, void *data), void *data);
312 * \brief Synchronous uiapp list getter.
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.
318 * \param[in] lbid Livebox App Id
319 * \param[in] cb Callback function
320 * \param[in] data Callback Data
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
331 extern int livebox_service_get_applist(const char *lbid, void (*cb)(const char *lbid, const char *appid, void *data), void *data);
334 * \brief Get the MAIN application Id of given livebox package Id.
337 * \param[in] lbid Livebox Package Id
339 * \retval NULL if it fails to get main application Id (UI-APPID)
340 * \retval appid Main application Id
344 extern char *livebox_service_mainappid(const char *lbid);
347 * \brief Synchronous package list getter
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
354 * \param[in] pkgid Package Id (Not the UI App Id)
355 * \param[in] cb Callback function
356 * \param[in] data Callback data
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
363 extern int livebox_service_get_pkglist_by_pkgid(const char *pkgid, int (*cb)(const char *lbid, int is_prime, void *data), void *data);
366 * \brief Synchronous package list getter
369 * lbid == Livebox Package Id
370 * If the callback returns negative value, the list crawling will be stopped
372 * \param[in] category Package Id (Not the UI App Id)
373 * \param[in] cb Callback function
374 * \param[in] data Callback data
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
381 extern int livebox_service_get_pkglist_by_category(const char *category, int (*cb)(const char *lbid, void *data), void *data);
384 * \brief Get the lbid of a primary livebox using given lbid or pkgid or UI appid.
387 * \param[in] id Livebox Id or Package Id
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
393 * \see livebox_service_appid
395 extern char *livebox_service_pkgname(const char *id);
398 * \brief Check the pirmary flag of given livebox Id.
400 * \param[in] lbid Livebox Id
402 * \retval 0 if is not a primary
403 * \retval 1 if it is a primary livebox
408 extern int livebox_service_is_primary(const char *lbid);
411 * \brief Get the category using given lbid.
414 * \param[in] id Livebox Id
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
420 * \see livebox_service_pkgname
422 extern char *livebox_service_category(const char *lbid);
425 * \brief Get the name of a livebox (provider name == livebox appid), you have to release the return value after use it
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
433 * \retval NULL failed to get provider name
434 * \retval lbid Livebox AppId which is allocated on the heap
436 * \post Return'd string must be free'd manually
439 extern char *livebox_service_provider_name(const char *lbid);
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
445 * This function should be called before add a livebox.
446 * To determine the content information string.
448 * \param[in] lbid Livebox Id
450 * \retval NULL there is no setup application
451 * \retval appid AppId if exists or NULL
453 * \post return'd string must be free'd manually
456 extern char *livebox_service_setup_appid(const char *lbid);
459 * \brief Get the Package Id (Not the UI App Id) of given livebox, <manifest package="AAA">
462 * \param[in] lbid Livebox AppId
464 * \retval appid String which is allocated in the heap
465 * \retval NULL invalid appid
467 * \post return'd string must be free'd manually
468 * \see livebox_service_pkgname
470 extern char *livebox_service_appid(const char *lbid);
473 * \brief Internationalized name of given livebox package.
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
479 * \retval name if it fails to get name
480 * \retval NULL, or allocated heap address.
482 * \post Return'd string must be free'd by manually
483 * \see livebox_service_i18n_icon
484 * \see livebox_service_preview
486 extern char *livebox_service_i18n_name(const char *pkgid, const char *lang);
489 * \brief Get the preview image path of given size type.
490 * This function will returns i18nized preview image path.
493 * \param[in] pkgid livebox ID. NOT the UI-APP ID and PACKAGE ID
494 * \param[in] size_type Livebox size type.
496 * \retval path preview image path
497 * \retval NULL if there is no preview image file
499 * \post Return'd string must be free'd manually
500 * \see livebox_service_i18n_icon
501 * \see livebox_service_i18n_name
503 extern char *livebox_service_preview(const char *pkgid, int size_type);
506 * \brief Get the default content string of the given livebox
508 * If a user defins default content string in the manifest file (.xml)
509 * This API will returns it.
511 * \param[in] pkgid Livebox ID. Not the UI-APP ID and PACKAGE ID
513 * \retval content content string
514 * \retval NULL there is no specified content string
515 * \pre manifest has the default content string. <content>Default content string<content>
516 * \post return'd string must be free'd manually
519 extern char *livebox_service_content(const char *pkgid);
522 * \brief Internationalized icon path of given livebox package.
523 * USER must has to do "free" after using the returned string.
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
529 * \retval name allocated heap address.
530 * \retval NULL if it fails to get path of an icon
532 * \post return'd string must be free'd manually
533 * \see livebox_service_i18n_name
534 * \see livebox_service_preview
536 extern char *livebox_service_i18n_icon(const char *pkgid, const char *lang);
539 * \brief Get the path of the plug-in module
542 * \param[in] lbid Package name of a livebox
544 * \retval path String which is allocated on the heap
545 * \retval NULL if there is no libexec attribute
547 * \post return'd string must be free'd manually
550 extern char *livebox_service_libexec(const char *lbid);
553 * \brief Get the "nodisplay" value
556 * \param[in] pkgid Livebox package id.
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.
564 extern int livebox_service_nodisplay(const char *pkgid);
567 * \brief Get the "ABI" of given package
570 * \param[in] lbid Livebox package id.
572 * \retval abi String which is allocated in the heap
573 * \retval NULL if failed to get ABI of given livebox.
575 * \post return'd string must be free'd manually
578 extern char *livebox_service_abi(const char *lbid);
581 * \brief Check the status of the livebox
582 * Currently this API is not implemented. just returns 1 all the time.
584 * \remarks This API is not implemented. it will always returns 1
585 * \param[in] lbid Livebox Id
593 extern int livebox_service_is_enabled(const char *lbid);
596 * \brief Get the script file of livebox.
599 * \param[in] lbid Livebox Package Id
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
607 extern char *livebox_service_lb_script_path(const char *lbid);
610 * \brief Get the script group of livebox
613 * \param[in] lbid Livebox Package Id
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
621 extern char *livebox_service_lb_script_group(const char *lbid);
624 * \brief Get the script file path of given livebox package.
627 * \param[in] lbid Livebox Package Id
629 * \retval string script file path.
630 * \retval NULL if there is no specified script file for PD layout
632 * \post Return'd string must be free'd manually
633 * \see livebox_service_pd_script_group
635 extern char *livebox_service_pd_script_path(const char *lbid);
638 * \brief Get the group name for script file to load it.
641 * \param[in] lbid Livebox package Id
643 * \retval string script group name
644 * \retval NULL if there is no script path
646 * \post return'd string must be free'd manually
647 * \see livebox_service_pd_script_path
649 extern char *livebox_service_pd_script_group(const char *lbid);
652 * \brief Get the supported size list.
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
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
668 * \see livebox_service_get_supported_size_types
670 extern int livebox_service_get_supported_sizes(const char *pkgid, int *cnt, int *w, int *h);
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
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
684 * \see livebox_service_get_supported_sizes
686 extern int livebox_service_get_supported_size_types(const char *pkgid, int *cnt, int *types);
689 * \brief Get the category list of given cluster
692 * \param[in] cluster Cluster name
693 * \param[in] cb Callback function
694 * \param[in] data Callback data
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
701 * \see livebox_service_enumerate_cluster_list
703 extern int livebox_service_enumerate_category_list(const char *cluster, int (*cb)(const char *cluster, const char *category, void *data), void *data);
706 * \brief Get the cluster list
709 * \param[in] cb Callback function for retrieving the cluster list
710 * \param[in] data Callback data
712 * \retval LB_STATUS_ERROR_INVALID Invalid argument
713 * \retval LB_STATUS_ERROR_IO Failed to access DB
714 * \retval count of category items
717 * \see livebox_service_enumerate_category_list
719 extern int livebox_service_enumerate_cluster_list(int (*cb)(const char *cluster, void *data), void *data);
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.
731 * \retval LB_STATUS_SUCCESS if succeed to initialize
732 * \retval LB_STATUS_ERROR_IO Failed to access a DB
735 * \see livebox_service_fini
737 extern int livebox_service_init(void);
740 * \brief Finalize the livebox service API
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
748 * \see livebox_service_init
750 extern int livebox_service_fini(void);
753 * \brief Create a handle for getting the package list.
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.
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.
766 * \retval NULL if it fails
767 * \retval handle if it successfully create the package list iterator
768 * \see livebox_service_pkglist_destroy
770 extern struct pkglist_handle *livebox_service_pkglist_create(const char *pkgid, struct pkglist_handle *handle);
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
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
784 * \post you must release the lbid, pkgname manually
785 * \see livebox_service_pkglist_create
786 * \see livebox_service_pkglist_destroy
788 extern int livebox_service_get_pkglist_item(struct pkglist_handle *handle, char **lbid, char **pkgname, int *is_prime);
791 * \brief Destroy the iterator of pkglist
794 * \param[in] handle Package list handle
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
802 extern int livebox_service_pkglist_destroy(struct pkglist_handle *handle);
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
810 * \retval NULL if it fails to get pkgname
811 * \retval address heap address of pkgname
813 * \post return'd string should be released via "free"
815 extern char *livebox_service_pkgname_by_libexec(const char *libexec);