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.
25 * \addtogroup CAPI_LIVEBOX_VIEWER_MODULE
31 * Structure for a Livebox instance
37 * Use the default update period which is defined in the livebox package manifest.
39 #define DEFAULT_PERIOD -1.0f
43 * Mouse & Key event for buffer type Livebox or PD
44 * Viewer should send these events to livebox.
46 enum content_event_type {
47 CONTENT_EVENT_MOUSE_DOWN = 0x00000001, /*!< LB mouse down event for livebox */
48 CONTENT_EVENT_MOUSE_UP = 0x00000002, /*!< LB mouse up event for livebox */
49 CONTENT_EVENT_MOUSE_MOVE = 0x00000004, /*!< LB mouse move event for livebox */
50 CONTENT_EVENT_MOUSE_ENTER = 0x00000008, /*!< LB mouse enter event for livebox */
51 CONTENT_EVENT_MOUSE_LEAVE = 0x00000010, /*!< LB mouse leave event for livebox */
52 CONTENT_EVENT_MOUSE_SET = 0x00000020, /*!< LB mouse set auto event for livebox */
53 CONTENT_EVENT_MOUSE_UNSET = 0x00000040, /*!< LB mouse unset auto event for livebox */
55 CONTENT_EVENT_KEY_DOWN = 0x00100000, /*!< LB key press */
56 CONTENT_EVENT_KEY_UP = 0x00200000, /*!< LB key release */
58 CONTENT_EVENT_KEY_MASK = 0x80000000,
59 CONTENT_EVENT_MOUSE_MASK = 0x20000000,
60 CONTENT_EVENT_PD_MASK = 0x10000000,
61 CONTENT_EVENT_LB_MASK = 0x40000000,
63 LB_MOUSE_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the livebox */
64 LB_MOUSE_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the livebox */
65 LB_MOUSE_MOVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Move move on the livebox */
66 LB_MOUSE_ENTER = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the livebox */
67 LB_MOUSE_LEAVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the livebox */
68 LB_MOUSE_SET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET,
69 LB_MOUSE_UNSET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET,
71 PD_MOUSE_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the PD */
72 PD_MOUSE_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the PD */
73 PD_MOUSE_MOVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Mouse move on the PD */
74 PD_MOUSE_ENTER = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the PD */
75 PD_MOUSE_LEAVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the PD */
76 PD_MOUSE_SET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET,
77 PD_MOUSE_UNSET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET,
79 LB_KEY_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */
80 LB_KEY_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */
82 PD_KEY_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */
83 PD_KEY_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */
85 CONTENT_EVENT_MAX = 0xFFFFFFFF
90 * Accessibility event for buffer type Livebox or PD.
91 * These event set are sync'd with Tizen accessibility event set.
93 enum access_event_type {
94 ACCESS_EVENT_PD_MASK = 0x10000000,
95 ACCESS_EVENT_LB_MASK = 0x20000000,
97 ACCESS_EVENT_HIGHLIGHT = 0x00000100, /*!< LB accessibility: Hightlight a object */
98 ACCESS_EVENT_HIGHLIGHT_NEXT = 0x00000200, /*!< LB accessibility: Set highlight to next object */
99 ACCESS_EVENT_HIGHLIGHT_PREV = 0x00000400, /*!< LB accessibility: Set highlight to prev object */
100 ACCESS_EVENT_UNHIGHLIGHT = 0x00000800, /*!< LB accessibility unhighlight */
101 ACCESS_EVENT_ACTIVATE = 0x00001000, /*!< LB accessibility activate */
102 ACCESS_EVENT_ACTION_DOWN = 0x00010000, /*!< LB accessibility value changed */
103 ACCESS_EVENT_ACTION_UP = 0x00020000, /*!< LB accessibility value changed */
104 ACCESS_EVENT_SCROLL_DOWN = 0x00100000, /*!< LB accessibility scroll down */
105 ACCESS_EVENT_SCROLL_MOVE = 0x00200000, /*!< LB accessibility scroll move */
106 ACCESS_EVENT_SCROLL_UP = 0x00400000, /*!< LB accessibility scroll up */
108 LB_ACCESS_HIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT, /*!< Access event - Highlight an object in the livebox */
109 LB_ACCESS_HIGHLIGHT_NEXT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT, /*!< Access event - Move highlight to the next object in a livebox */
110 LB_ACCESS_HIGHLIGHT_PREV = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_PREV, /*!< Access event - Move highlight to the prev object in a livebox */
111 LB_ACCESS_UNHIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_UNHIGHLIGHT, /*!< Access event - Delete highlight from the livebox */
112 LB_ACCESS_ACTIVATE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTIVATE, /*!< Access event - Launch or activate the highlighted object */
113 LB_ACCESS_ACTION_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_DOWN, /*!< Access event - down */
114 LB_ACCESS_ACTION_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_UP, /*!< Access event - up */
115 LB_ACCESS_SCROLL_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_DOWN, /*!< Access event - scroll down */
116 LB_ACCESS_SCROLL_MOVE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_MOVE, /*!< Access event - scroll move */
117 LB_ACCESS_SCROLL_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_UP, /*!< Access event - scroll up */
119 PD_ACCESS_HIGHLIGHT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT,
120 PD_ACCESS_HIGHLIGHT_NEXT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT,
121 PD_ACCESS_HIGHLIGHT_PREV = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_PREV,
122 PD_ACCESS_UNHIGHLIGHT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_UNHIGHLIGHT,
123 PD_ACCESS_ACTIVATE = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTIVATE,
124 PD_ACCESS_ACTION_DOWN = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTION_DOWN,
125 PD_ACCESS_ACTION_UP = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTION_UP,
126 PD_ACCESS_SCROLL_DOWN = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_DOWN,
127 PD_ACCESS_SCROLL_MOVE = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_MOVE,
128 PD_ACCESS_SCROLL_UP = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_UP
133 * Livebox LB content type
135 enum livebox_lb_type {
136 LB_TYPE_IMAGE = 0x01, /*!< Contents of a livebox is based on the image file */
137 LB_TYPE_BUFFER = 0x02, /*!< Contents of a livebox is based on canvas buffer(shared) */
138 LB_TYPE_TEXT = 0x04, /*!< Contents of a livebox is based on formatted text file */
139 LB_TYPE_PIXMAP = 0x08, /*!< Contens of a livebox is shared by the pixmap(depends on X) */
141 LB_TYPE_INVALID = 0xFF
146 * Livebox PD content type
148 enum livebox_pd_type {
149 PD_TYPE_BUFFER = 0x01, /*!< Contents of a PD is based on canvas buffer(shared) */
150 PD_TYPE_TEXT = 0x02, /*!< Contents of a PD is based on formatted text file */
151 PD_TYPE_PIXMAP = 0x04, /*!< Contents of a livebox is shared by the pixmap(depends on X) */
153 PD_TYPE_INVALID = 0xFF
158 * Livebox event type.
159 * These event will be sent from the provider.
161 enum livebox_event_type { /*!< livebox_event_handler_set Event list */
162 LB_EVENT_LB_UPDATED, /*!< Contents of the given livebox is updated */
163 LB_EVENT_PD_UPDATED, /*!< Contents of the given pd is updated */
165 LB_EVENT_CREATED, /*!< A new livebox is created */
166 LB_EVENT_DELETED, /*!< A livebox is deleted */
168 LB_EVENT_GROUP_CHANGED, /*!< Group (Cluster/Sub-cluster) information is changed */
169 LB_EVENT_PINUP_CHANGED, /*!< PINUP status is changed */
170 LB_EVENT_PERIOD_CHANGED, /*!< Update period is changed */
172 LB_EVENT_LB_SIZE_CHANGED, /*!< Livebox size is changed */
173 LB_EVENT_PD_SIZE_CHANGED, /*!< PD size is changed */
175 LB_EVENT_PD_CREATED, /*!< If a PD is created even if you didn't call the livebox_create_pd API */
176 LB_EVENT_PD_DESTROYED, /*!< If a PD is destroyed even if you didn't call the livebox_destroy_pd API */
178 LB_EVENT_HOLD_SCROLL, /*!< If the screen should be freezed */
179 LB_EVENT_RELEASE_SCROLL, /*!< If the screen can be scrolled */
181 LB_EVENT_LB_UPDATE_BEGIN, /*!< Livebox LB content update is started */
182 LB_EVENT_LB_UPDATE_END, /*!< Livebox LB content update is finished */
184 LB_EVENT_PD_UPDATE_BEGIN, /*!< Livebox PD content update is started */
185 LB_EVENT_PD_UPDATE_END, /*!< Livebox PD content update is finished */
187 LB_EVENT_UPDATE_MODE_CHANGED, /*!< Livebox Update mode is changed */
189 LB_EVENT_IGNORED /*!< Request is ignored */
192 enum livebox_fault_type {
193 LB_FAULT_DEACTIVATED, /*!< Livebox is deactivated by its fault operation */
194 LB_FAULT_PROVIDER_DISCONNECTED /*!< Provider is disconnected */
199 * Must be sync'd with the provider
201 enum livebox_visible_state {
202 LB_SHOW = 0x00, /*!< Livebox is showed. Default state */
203 LB_HIDE = 0x01, /*!< Livebox is hide, Update timer is not be freezed. but you cannot receive any updates events. you should refresh(reload) the content of a livebox when you make this show again */
205 LB_HIDE_WITH_PAUSE = 0x02, /*!< Livebix is hide, it will paused the update timer, but if a livebox update its contents, update event will come to you */
207 LB_VISIBLE_ERROR = 0xFFFFFFFF /* To enlarge the size of this enumeration type */
212 * TEXT type livebox contents handling opertators.
214 struct livebox_script_operators {
215 int (*update_begin)(struct livebox *handle); /*!< Content parser is started */
216 int (*update_end)(struct livebox *handle); /*!< Content parser is stopped */
220 * Listed functions will be called when parser meets each typed component
222 int (*update_text)(struct livebox *handle, const char *id, const char *part, const char *data); /*!< Update text content */
223 int (*update_image)(struct livebox *handle, const char *id, const char *part, const char *data, const char *option); /*!< Update image content */
224 int (*update_script)(struct livebox *handle, const char *id, const char *part, const char *file, const char *group); /*!< Update script content */
225 int (*update_signal)(struct livebox *handle, const char *id, const char *emission, const char *signal); /*!< Update signal */
226 int (*update_drag)(struct livebox *handle, const char *id, const char *part, double dx, double dy); /*!< Update drag info */
227 int (*update_info_size)(struct livebox *handle, const char *id, int w, int h); /*!< Update content size */
228 int (*update_info_category)(struct livebox *handle, const char *id, const char *category); /*!< Update content category info */
229 int (*update_access)(struct livebox *handle, const char *id, const char *part, const char *text, const char *option); /*!< Update access information */
230 int (*operate_access)(struct livebox *handle, const char *id, const char *part, const char *operation, const char *option); /*!< Update access operation */
234 * \brief Prototype of the return callback of every async functions
237 * \param[in] handle Handle of the livebox instance
238 * \param[in] ret Result status of operation. LB_STATUS_XXX defined from liblivebox-service
239 * \param[in] data data for result callback
244 * \see livebox_add_with_size
246 * \see livebox_activate
247 * \see livebox_resize
248 * \see livebox_set_group
249 * \see livebox_set_period
250 * \see livebox_access_event
251 * \see livebox_set_pinup
252 * \see livebox_create_pd
253 * \see livebox_create_pd_with_position
254 * \see livebox_destroy_pd
255 * \see livebox_emit_text_signal
256 * \see livebox_acquire_pd_pixmap
257 * \see livebox_acquire_lb_pixmap
258 * \see livebox_set_update_mode
260 typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data);
263 * \brief Initialize the livebox system
266 * \param[in] disp If you have X Display connection object, you can re-use it. but you should care its life cycle.
267 * It must be alive before call the livebox_fini
269 * \retval LB_STATUS_SUCCESS if success
274 extern int livebox_init(void *disp);
277 * \brief Initialize the livebox system with some options
278 * \details livebox_init function uses environment value to initiate some configurable values
279 * But some application doesn't want to use the env value.
280 * For them, this API will give a chance to set default options using given arguments
283 * \param[in] prevent_overwrite
284 * \param[in] event_filter
286 * \retval LB_STATUS_SUCCESS if success
292 extern int livebox_init_with_options(void *disp, int prevent_overwrite, double event_filter);
295 * \brief Finalize the livebox system
299 * \retval LB_STATUS_SUCCES if success
300 * \retval LB_STATUS_ERROR_INVALID if livebox_init is not called.
305 extern int livebox_fini(void);
308 * \brief Client is paused.
312 * \retval LB_STATUS_SUCCESS if success
313 * \retval LB_STATUS_ERROR_FAULT if it failed to send state(paused) info
316 * \see livebox_client_resumed
318 extern int livebox_client_paused(void);
321 * \brief Client is rfesumed.
325 * \retval LB_STATUS_SUCCESS if success
326 * \retval LB_STATUS_ERROR_FAULT if it failed to send state(resumed) info
329 * \see livebox_client_paused
331 extern int livebox_client_resumed(void);
334 * \brief Add a new livebox
337 * Even though you get the livebox handle from return value of this function,
338 * it is not matured before return callback called.
339 * You have to use the handle after get the return callback with "ret == LB_STATUS_SUCCESS"
340 * \param[in] pkgname Livebox Id
341 * \param[in] content Will be passed to the livebox instance.
342 * \param[in] cluster Main group
343 * \param[in] category Sub group
344 * \param[in] period Update period. if you set DEFAULT_PERIOD, the provider will use the default period which is described in the manifest.
345 * \param[in] cb After send the request to the provider, its result will be passed
348 * \retval NULL if it fails to add a new instance
349 * \retval handle livebox handle
353 * \see livebox_add_with_size
355 extern struct livebox *livebox_add(const char *pkgname, const char *content, const char *cluster, const char *category, double period, ret_cb_t cb, void *data);
358 * \brief Add a new livebox
360 * Normal mode livebox
381 * Even if you get the handle by return value of this function, it is not created instance.
382 * So you have to deal it as not initialized handle.
383 * Only it can be initialized after get the return callback with "ret == LB_STATUS_SUCCESS".
384 * \param[in] pkgname Livebox Id
385 * \param[in] content Will be passed to the livebox instance.
386 * \param[in] cluster Main group
387 * \param[in] category Sub group
388 * \param[in] period DEFAULT_PERIOD can be used for this. this argument will be used to specify the period of update content of livebox.
389 * \param[in] type Size type - which are defined from liblivebox-service package.
390 * \param[in] cb After the request is sent to the master provider, this callback will be called.
391 * \param[in] data This data will be passed to the callback.
393 * \retval handle Livebox handle but not yet initialized
394 * \retval NULL if it fails to create a handle
398 extern struct livebox *livebox_add_with_size(const char *pkgname, const char *content, const char *cluster, const char *category, double period, int type, ret_cb_t cb, void *data);
401 * \brief Delete a livebox
404 * If you call this with uninitialized handle, the return callback will be called synchronously.
405 * So before return from this function, the return callback will be called first.
406 * \param[in] handler Handle of a livebox instance
407 * \param[in] cb return callback
408 * \param[in] data user data for return callback
410 * \retval LB_STATUS_ERROR_INVALID Invalid argument
411 * \retval LB_STATUS_ERROR_BUSY already in process
412 * \retval LB_STATUS_ERROR_FAULT failed to create a request packet
413 * \retval LB_STATUS_SUCCESS successfully sent, return callack will be called
418 extern int livebox_del(struct livebox *handler, ret_cb_t cb, void *data);
421 * \brief Set a livebox events callback
423 * To get the events push from the provider, register the event callback using this function
424 * The callback will be called if there is any events from the provider.
426 * \param[in] cb Event handler
427 * \param[in] data User data for the event handler
429 * \retval LB_STATUS_SUCCESS if succeed to set event handler
430 * \retval LB_STATUS_ERROR_INVALID Invalid argument
431 * \retval LB_STATUS_ERROR_MEMORY Not enough memory
434 * \see livebox_unset_event_handler
436 extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data);
439 * \brief Unset the livebox event handler
444 * \retval pointer of 'data' which is used with the livebox_set_event_handler
447 * \see livebox_set_event_handler
449 extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data));
452 * \brief Live box fault event handler registeration function
454 * event, pkgname, filename, funcname
460 * \retval LB_STATUS_SUCCESS if succeed to set fault event handler
461 * \retval LB_STATUS_ERROR_INVALID Invalid argument
462 * \retval LB_STATUS_ERROR_MEMORY Not enough memory
465 * \see livebox_unset_fault_handler
467 extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data);
470 * \brief Unset the live box fault event handler
475 * \retval pointer of 'data' which is used with the livebox_set_fault_handler
478 * \see livebox_set_fault_handler
480 extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *));
483 * \brief Activate the faulted livebox.
485 * Request result will be back via return callback.
487 * Even though this function returns SUCCESS, it means just successfully sent a request to provider.
488 * So you have to check the return callback. and its "ret" argument.
493 * \retval LB_STATUS_SUCCESS Successfully sent a request
494 * \retval LB_STATUS_ERROR_INVALID Invalid argument
495 * \retval LB_STATUS_ERROR_FAULT Failed to make a request
500 extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data);
503 * \brief Resize the livebox
505 * Normal mode livebox size
513 * Extended livebox size
518 * Easy mode livebox size
523 * Special mode livebox size
526 * You have to check the return callback.
527 * \param[in] handler Handler of a livebox
528 * \param[in] type Type of a livebox size, LB_SIZE_TYPE_1x1, ...
529 * \param[in] cb Result callback of the resize operation.
530 * \param[in] data User data for return callback
532 * \retval LB_STATUS_ERROR_INVALID Invalid argument
533 * \retval LB_STATUS_ERROR_BUSY Previous request of resize is in progress.
534 * \retval LB_STATUS_ERROR_ALREADY Already resized, there is no differences between current size and requested size.
535 * \retval LB_STATUS_ERROR_PERMISSION Permission denied, you only have view the content of this box.
536 * \retval LB_STATUS_ERROR_FAULT Failed to make a request
541 extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data);
544 * \brief Send the click event for a livebox.
547 * \param[in] handler Handler of a livebox
548 * \param[in] x Rational X of the content width.
549 * \param[in] y Rational Y of the content height.
551 * \retval LB_STATUS_ERROR_INVALID
552 * \retval LB_STATUS_ERROR_FAULT
553 * \retval LB_STATUS_SUCCESS
558 extern int livebox_click(struct livebox *handler, double x, double y);
561 * \brief Change the cluster/sub-cluster name of given livebox handler
564 * \param[in] handler Handler of a livebox
565 * \param[in] cluster New cluster of a livebox
566 * \param[in] category New category of a livebox
567 * \param[in] cb Result callback for changing the cluster/category of a livebox
568 * \param[in] data User data for the result callback
570 * \retval LB_STATUS_SUCCESS Request is successfully sent. the return callback will be called.
571 * \retval LB_STATUS_ERROR_BUSY previous request is not finished yet.
572 * \retval LB_STATUS_ERROR_ALREADY group name is same with current one.
573 * \retval LB_STATUS_ERROR_PERMISSION you have no permission to change property of this livebox instance.
574 * \retval LB_STATUS_ERROR_FAULT Failed to make a request.
579 extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data);
582 * \brief Get the cluster and category(sub-cluster) name of given livebox (It is not I18N format, only english)
585 * You have to do not release the cluster & category.
586 * It is allocated inside of given livebox instance, so you can only read it.
587 * \param[in] handler Handler of a livebox
588 * \param[out] cluster Storage(memory) for containing the cluster name
589 * \param[out] category Storage(memory) for containing the category name
591 * \retval LB_STATUS_ERROR_INVALID
592 * \retval LB_STATUS_SUCCESS
597 extern int livebox_get_group(struct livebox *handler, char ** const cluster, char ** const category);
600 * \brief Get the period of this livebox handler
603 * if this function returns 0.0f, it means the livebox has no update period.
604 * or the handle is not valid.
605 * This function only can be works after the return callback of livebox_create fucntion is called.
606 * \param[in] handler Handler of a livebox
608 * \retval Current update period of a livebox
609 * \retval 0.0f it means the box has no update period, or it can returns 0.0 if the handles is not valid.
614 extern double livebox_period(struct livebox *handler);
617 * \brief Change the update period
620 * \param[in] handler Handler of a livebox
621 * \param[in] period New update period of a livebox
622 * \param[in] cb Result callback of changing the update period of this livebox
623 * \param[in] data User data for the result callback
625 * \retval LB_STATUS_SUCCESS
626 * \retval LB_STATUS_ERROR_INVALID
627 * \retval LB_STATUS_ERROR_BUSY
628 * \retval LB_STATUS_ERROR_ALREADY
629 * \retval LB_STATUS_ERROR_FAULT
634 extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data);
637 * \brief Is this an text type livebox?
641 * \return livebox_lb_type
642 * \retval LB_TYPE_IMAGE Contents of a livebox is based on the image file
643 * \retval LB_TYPE_BUFFER Contents of a livebox is based on canvas buffer(shared)
644 * \retval LB_TYPE_TEXT Contents of a livebox is based on formatted text file
645 * \retval LB_TYPE_PIXMAP Contens of a livebox is shared by the pixmap(depends on X)
646 * \retval LB_TYPE_INVALID
649 * \see livebox_lb_type
651 extern enum livebox_lb_type livebox_lb_type(struct livebox *handler);
654 * \brief Is this livebox is created by a user?
656 * If the livebox instance is created by system this will returns 0.
660 * \retval LB_STATUS_ERROR_INVALID Invalid argument
661 * \retval 0 automatically created livebox by the provider
662 * \retval 1 created by user via livebox_add or livebox_add_with_size
666 * \see livebox_add_with_size
667 * \see livebox_set_event_handler
669 extern int livebox_is_user(struct livebox *handler);
672 * \brief Get the content information string of given livebox
677 * \retval content_info Livebox content info that can be used again via content_info argument of livebox_add or livebox_add_with_size.
681 * \see livebox_add_with_size
683 extern const char *livebox_content(struct livebox *handler);
686 * \brief Get the sub cluster title string of given livebox
690 * \return const char *
691 * \retval sub cluster name
697 extern const char *livebox_category_title(struct livebox *handler);
700 * \brief Get the filename of given livebox, if it is an IMAGE type livebox
704 * \return const char *
705 * \retval filename if the livebox type is image this function will give you a abspath of an image file (content is rendered)
706 * \retval NULL if this has no image file or type is not image file.
711 extern const char *livebox_filename(struct livebox *handler);
714 * \brief Get the package name of given livebox handler
718 * \return const char *
719 * \retval pkgname package name
720 * \retval NULL if the handler is not valid
725 extern const char *livebox_pkgname(struct livebox *handler);
728 * \brief Get the priority of a current content.
733 * \retval 0.0f handler is NULL
734 * \retval -1.0f Handler is not valid (not yet initialized)
735 * \retval real number between 0.0 and 1.0
740 extern double livebox_priority(struct livebox *handler);
743 * \brief Acquire the buffer of given livebox (Only for the buffer type)
748 * \retval address of a FB
749 * \retval NULL if it fails to get fb address
754 extern void *livebox_acquire_fb(struct livebox *handler);
757 * \brief Release the buffer of a livebox (Only for the buffer type)
762 * \retval LB_STATUS_ERROR_INVALID
763 * \retval LB_STATUS_SUCCESS
766 * \see livebox_acquire_fb
768 extern int livebox_release_fb(void *buffer);
771 * \brief Get the reference count of Livebox buffer (Only for the buffer type)
776 * \retval LB_STATUS_ERROR_INVALID
777 * \retval LB_STATUS_ERROR_FAULT
778 * \retval refcnt positive integer including ZERO
781 * \see livebox_pdfb_refcnt
783 extern int livebox_fb_refcnt(void *buffer);
786 * \brief Acquire the buffer of a PD frame (Only for the buffer type)
792 * \retval adress of buffer of PD
795 * \see livebox_release_pdfb
797 extern void *livebox_acquire_pdfb(struct livebox *handler);
800 * \brief Release the acquired buffer of the PD Frame (Only for the buffer type)
805 * \retval LB_STATUS_ERROR_INVALID
806 * \retval LB_STATUS_SUCCESS
809 * \see livebox_acquire_pdfb
811 extern int livebox_release_pdfb(void *buffer);
814 * \brief Reference count of given PD buffer (Only for the buffer type)
819 * \retval LB_STATUS_ERROR_INVALID
820 * \retval LB_STATUS_ERROR_FAULT
821 * \retval reference count
824 * \see livebox_fb_refcnt
826 extern int livebox_pdfb_refcnt(void *buffer);
829 * \brief Get the size of the Livebox
834 * \retval LB_SIZE_TYPE_NxM
835 * \retval LB_SIZE_TYPE_INVALID
840 extern int livebox_size(struct livebox *handler);
843 * \brief Get the size of the Progressive Disclosure
850 * \retval LB_STATUS_ERROR_INVALID
851 * \retval LB_STATUS_SUCCESS
856 extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h);
859 * \brief List of supported sizes of given handler
864 * \param[out] size_list
866 * \retval LB_STATUS_ERROR_INVALID
867 * \retval LB_STATUS_SUCCESS
872 extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list);
875 * \brief BUFFER SIZE of the livebox if it is a buffer type
880 * \retval LB_STATUS_ERROR_INVALID
881 * \retval size of livebox buffer
886 extern int livebox_lbfb_bufsz(struct livebox *handler);
889 * \brief BUFFER SIZE of the progiressive disclosure if it is a buffer type
894 * \retval LB_STATUS_ERROR_INVALID
895 * \retval size of PD buffer
900 extern int livebox_pdfb_bufsz(struct livebox *handler);
903 * \brief Send the content event (for buffer type) to provider(livebox)
911 * \retval LB_STATUS_ERROR_INVALID
912 * \retval LB_STATUS_ERROR_BUSY
913 * \retval LB_STATUS_ERROR_FAULT
914 * \retval LB_STATUS_SUCCESS
917 * \see livebox_access_event
919 extern int livebox_content_event(struct livebox *handler, enum content_event_type type, double x, double y);
922 * \brief Send the access event(for buffer type) to provider(livebox).
932 * \retval LB_STATUS_ERROR_INVALID
933 * \retval LB_STATUS_ERROR_BUSY
934 * \retval LB_STATUS_ERROR_FAULT
935 * \retval LB_STATUS_SUCCESS
938 * \see livebox_content_event
940 extern int livebox_access_event(struct livebox *handler, enum access_event_type type, double x, double y, ret_cb_t cb, void *data);
943 * \brief Do pin up or not.
951 * \retval LB_STATUS_ERROR_INVALID
952 * \retval 1 box is pinned up
953 * \retval 0 box is not pinned up
956 extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data);
959 * \brief Check the PIN-UP status of given handler
965 extern int livebox_is_pinned_up(struct livebox *handler);
968 * \brief Check the PINUP feature availability of the given handler
973 * \retval LB_STATUS_ERROR_INVALID
974 * \retval 1 if the box support Pinup feature
975 * \retval 0 if the box does not support the Pinup feature
980 extern int livebox_has_pinup(struct livebox *handler);
983 * \brief Check the PD existence of given handler
988 * \retval LB_STATUS_ERROR_INVALID
989 * \retval 1 if the box support the PD
990 * \retval 0 if the box has no PD
995 extern int livebox_has_pd(struct livebox *handler);
998 * \brief Create the PD of given handler
1001 * \param[in] handler
1005 * \retval LB_STATUS_SUCCESS
1006 * \retval LB_STATUS_ERROR_INVALID
1007 * \retval LB_STATUS_ERROR_BUSY
1008 * \retval LB_STATUS_ERROR_FAULT
1013 extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data);
1016 * \brief Create the PD of given handler with the relative position from livebox
1019 * \param[in] handler
1020 * \param[in] x 0.0 ~ 1.0
1021 * \param[in] y 0.0 ~ 1.0
1025 * \retval LB_STATUS_SUCCESS
1026 * \retval LB_STATUS_ERROR_INVALID
1027 * \retval LB_STATUS_ERROR_BUSY
1028 * \retval LB_STATUS_ERROR_FAULT
1033 extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data);
1036 * \brief PD position is updated.
1039 * \param[in] handler
1040 * \param[in] x 0.0 ~ 1.0
1041 * \param[in] y 0.0 ~ 1.0
1043 * \retval LB_STATUS_SUCCESS if succeed to send request for updating position of the PD.
1044 * \retval LB_STATUS_ERROR_FAULT
1045 * \retval LB_STATUS_ERROR_INVALID
1050 extern int livebox_move_pd(struct livebox *handler, double x, double y);
1053 * \brief Destroy the PD of given handler if it is created.
1056 * \param[in] handler
1060 * \retval LB_STATUS_ERROR_INVALID
1061 * \retval LB_STATUS_ERROR_FAULT
1062 * \retval LB_STATUS_SUCCESS
1067 extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data);
1070 * \brief Check the create status of given livebox handler
1073 * \param[in] handler
1075 * \retval LB_STATUS_ERROR_INVALID
1076 * \retval 0 PD is not created
1077 * \retval 1 PD is created
1079 extern int livebox_pd_is_created(struct livebox *handler);
1082 * \brief Check the content type of the progressive disclosure of given handler
1085 * \param[in] handler
1087 * \retval PD_TYPE_BUFFER Contents of a PD is based on canvas buffer(shared)
1088 * \retval PD_TYPE_TEXT Contents of a PD is based on formatted text file
1089 * \retval PD_TYPE_PIXMAP Contents of a livebox is shared by the pixmap(depends on X)
1090 * \retval PD_TYPE_INVALID
1093 * \see livebox_pd_type
1095 extern enum livebox_pd_type livebox_pd_type(struct livebox *handler);
1098 * \brief Check the existence of a livebox about given package name
1101 * \param[in] pkgname
1103 * \retval 1 if the box is exists
1104 * \retval 0 if the box is not exists
1109 extern int livebox_is_exists(const char *pkgname);
1112 * \brief Set function table for parsing the text content of a livebox
1115 * \param[in] handler
1118 * \retval LB_STATUS_SUCCESS
1119 * \retval LB_STATUS_ERROR_INVALID
1120 * \see livebox_set_pd_text_handler
1122 extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1125 * \brief Set function table for parsing the text content of a Progressive Disclosure
1128 * \param[in] handler
1131 * \retval LB_STATUS_SUCCESS
1132 * \retval LB_STATUS_ERROR_INVALID
1133 * \see livebox_set_text_handler
1135 extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1138 * \brief Emit a text signal to given livebox only if it is a text type.
1141 * \param[in] handler
1142 * \param[in] emission
1151 * \retval LB_STATUS_ERROR_INVALID
1152 * \retval LB_STATUS_ERROR_FAULT
1153 * \retval LB_STATUS_SUCCESS
1156 extern int livebox_emit_text_signal(struct livebox *handler, const char *emission, const char *source, double sx, double sy, double ex, double ey, ret_cb_t cb, void *data);
1159 * \brief Set a private data pointer to carry it using given handler
1162 * \param[in] handler
1165 * \retval LB_STATUS_SUCCESS
1166 * \retval LB_STATUS_ERROR_INVALID
1169 * \see livebox_get_data
1171 extern int livebox_set_data(struct livebox *handler, void *data);
1174 * \brief Get private data pointer which is carried by given handler
1177 * \param[in] handler
1179 * \retval data pointer
1182 * \see livebox_set_data
1184 extern void *livebox_get_data(struct livebox *handler);
1187 * \brief Subscribe the event for liveboxes only in given cluster and sub-cluster
1190 * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event.
1191 * If you use the "*", value in the category will be ignored.
1192 * \param[in] category "*" can be used for subscribe liveboxes events of all category(sub-cluster) in given "cluster"
1194 * \retval LB_STATUS_ERROR_FAULT
1195 * \retval LB_STATUS_SUCCESS
1198 * \see livebox_unsubscribe_group
1200 extern int livebox_subscribe_group(const char *cluster, const char *category);
1203 * \brief Unsubscribe the event for the liveboxes, but you will receive already added liveboxes event.
1206 * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event.
1207 * If you use the "*", value in the category will be ignored.
1208 * \param[in] category "*" can be used for subscribe all sub-cluster's liveboxes event in given "cluster"
1210 * \retval LB_STATUS_ERROR_FAULT
1211 * \retval LB_STATUS_SUCCESS
1214 * \see livebox_subscribe_group
1216 extern int livebox_unsubscribe_group(const char *cluster, const char *category);
1219 * \brief Refresh the group(cluster/sub-cluser(aka. category))
1222 * \param[in] cluster Cluster ID
1223 * \param[in] category Sub-cluster ID
1224 * \param[in] force 1 if the boxes should be updated even if they are paused
1226 * \retval LB_STATUS_ERROR_INVALID
1227 * \retval LB_STATUS_ERROR_FAULT
1228 * \retval LB_STATUS_SUCCESS
1233 extern int livebox_refresh_group(const char *cluster, const char *category, int force);
1236 * \brief Refresh a livebox
1239 * \param[in] handler
1240 * \param[in] force 1 if the box should be updated even if it is paused
1242 * \retval LB_STATUS_ERROR_INVALID
1243 * \retval LB_STATUS_ERROR_FAULT
1244 * \retval LB_STATUS_SUCCESS
1249 extern int livebox_refresh(struct livebox *handler, int force);
1252 * \brief Pixmap Id of a livebox content
1255 * \param[in] handler
1257 * \retval 0 if the pixmap is not created
1258 * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
1261 * \see livebox_pd_pixmap
1263 extern int livebox_lb_pixmap(const struct livebox *handler);
1266 * \brief Pixmap Id of a PD content
1269 * \param[in] handler
1271 * \retval 0 if the pixmap is not created
1272 * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
1275 * \see livebox_lb_pixmap
1277 extern int livebox_pd_pixmap(const struct livebox *handler);
1283 * \param[in] handler
1287 * \retval LB_STATUS_ERROR_INVALID
1288 * \retval LB_STATUS_ERROR_FAULT
1289 * \retval LB_STATUS_SUCCESS
1292 * \see livebox_release_pd_pixmap
1293 * \see livebox_acquire_lb_pixmap
1296 extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1299 * \brief Release the acquired pixmap ID
1302 * \param[in] handler
1305 * \retval LB_STATUS_ERROR_INVALID
1306 * \retval LB_STATUS_ERROR_FAULT
1307 * \retval LB_STATUS_SUCCESS
1310 * \see livebox_acquire_pd_pixmap
1311 * \see livebox_release_lb_pixmap
1313 extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap);
1319 * \param[in] handler
1323 * \retval LB_STATUS_ERROR_INVALID
1324 * \retval LB_STATUS_ERROR_FAULT
1325 * \retval LB_STATUS_SUCCESS
1328 * \see livebox_release_lb_pixmap
1329 * \see livebox_acquire_pd_pixmap
1332 extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1338 * \param[in] handler
1341 * \retval LB_STATUS_ERROR_INVALID
1342 * \retval LB_STATUS_ERROR_FAULT
1343 * \retval LB_STATUS_SUCCESS
1346 * \see livebox_acquire_lb_pixmap
1347 * \see livebox_release_pd_pixmap
1349 extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap);
1352 * \brief Update the visible state of a livebox
1355 * \param[in] handler Handler of a livebox
1356 * \param[in] state Configure the current visible state of a livebox
1358 * \retval LB_STATUS_ERROR_INVALID
1359 * \retval LB_STATUS_ERROR_BUSY
1360 * \retval LB_STATUS_ERROR_PERMISSION
1361 * \retval LB_STATUS_ERROR_ALREADY
1362 * \retval LB_STATUS_ERROR_FAULT
1363 * \retval LB_STATUS_SUCCESS
1368 extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state);
1371 * \brief Current visible state of a livebox
1374 * \param[in] handler Handler of a livebox
1375 * \return livebox_visible_state
1376 * \retval LB_SHOW Livebox is showed. Default state
1377 * \retval LB_HIDE Livebox is hide, Update timer is not be freezed. but you cannot receive any updates events. you should refresh(reload) the content of a livebox when you make this show again
1378 * \retval LB_HIDE_WITH_PAUSE Livebix is hide, it will paused the update timer, but if a livebox update its contents, update event will come to you
1379 * \retval LB_VISIBLE_ERROR To enlarge the size of this enumeration type
1384 extern enum livebox_visible_state livebox_visibility(struct livebox *handler);
1387 * \brief Set the update mode of current livebox
1390 * if you set 1 for active update mode, you should get buffer without updated event from provider.
1391 * But is passive mode, you have to update content of a box when you get updated event.
1392 * Default is Passive mode.
1393 * \param[in] handler Handler of a livebox
1394 * \param[in] active_update 1 means active update, 0 means passive update (default)
1395 * \param[in] cb Result callback function
1396 * \param[in] data Callback data
1398 * \retval LB_STATUS_ERROR_INVALID
1399 * \retval LB_STATUS_ERROR_BUSY
1400 * \retval LB_STATUS_ERROR_PERMISSION
1401 * \retval LB_STATUS_ERROR_ALREADY
1402 * \retval LB_STATUS_ERROR_FAULT
1403 * \retval LB_STATUS_SUCCESS
1406 extern int livebox_set_update_mode(struct livebox *handler, int active_update, ret_cb_t cb, void *data);
1409 * \brief Is this box in the active update mode?
1412 * \param[in] handler HAndler of a livebox
1414 * \retval 0 if passive mode
1415 * \retval 1 if active mode or error code
1418 extern int livebox_is_active_update(struct livebox *handler);
1421 * \brief Use the manual sync for S/W buffer
1426 * \see livebox_manual_sync
1427 * \see livebox_sync_pd_fb
1428 * \see livebox_sync_lb_fb
1430 extern void livebox_set_manual_sync(int flag);
1433 * \brief Get current mode
1437 * \retval 0 if auto sync
1438 * \retval 1 if manual sync
1439 * \see livebox_set_manual_sync
1440 * \see livebox_sync_pd_fb
1441 * \see livebox_sync_lb_fb
1443 extern int livebox_manual_sync(void);
1446 * \brief Use the frame drop while resizing contents
1451 * \see livebox_frame_drop_for_resizing
1453 extern void livebox_set_frame_drop_for_resizing(int flag);
1456 * \brief Get current mode
1460 * \retval 0 if disabled
1461 * \retval 1 if enabled
1462 * \see livebox_set_frame_drop_for_resizing
1464 extern int livebox_frame_drop_for_resizing(void);
1467 * \brief Sync manually
1472 * \retval 0 if success
1473 * \see livebox_set_manual_sync
1474 * \see livebox_manual_sync
1475 * \see livebox_sync_lb_fb
1477 extern int livebox_sync_pd_fb(struct livebox *handler);
1480 * \brief Sync manually
1485 * \retval 0 if success
1486 * \see livebox_set_manual_sync
1487 * \see livebox_manual_sync
1488 * \see livebox_sync_pd_fb
1490 extern int livebox_sync_lb_fb(struct livebox *handler);