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 package manifest file of a livebox.
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 = 0x00000001, /*!< LB key press */
56 CONTENT_EVENT_KEY_UP = 0x00000002, /*!< LB key release */
57 CONTENT_EVENT_KEY_FOCUS_IN = 0x00000008, /*!< LB key focused in */
58 CONTENT_EVENT_KEY_FOCUS_OUT = 0x00000010, /*!< LB key focused out */
59 CONTENT_EVENT_KEY_SET = 0x00000020, /*!< LB Key, start feeding event by master */
60 CONTENT_EVENT_KEY_UNSET = 0x00000040, /*!< LB key, stop feeding event by master */
62 CONTENT_EVENT_KEY_MASK = 0x80000000,
63 CONTENT_EVENT_MOUSE_MASK = 0x20000000,
64 CONTENT_EVENT_PD_MASK = 0x10000000,
65 CONTENT_EVENT_LB_MASK = 0x40000000,
67 LB_MOUSE_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the livebox */
68 LB_MOUSE_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the livebox */
69 LB_MOUSE_MOVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Move move on the livebox */
70 LB_MOUSE_ENTER = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the livebox */
71 LB_MOUSE_LEAVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the livebox */
72 LB_MOUSE_SET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET, /*!< Mouse event, start feeding event by master */
73 LB_MOUSE_UNSET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET, /*!< Mouse event, stop feeding event by master */
75 PD_MOUSE_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the PD */
76 PD_MOUSE_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the PD */
77 PD_MOUSE_MOVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Mouse move on the PD */
78 PD_MOUSE_ENTER = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the PD */
79 PD_MOUSE_LEAVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the PD */
80 PD_MOUSE_SET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET, /*!< Mouse event, start feeding event by master */
81 PD_MOUSE_UNSET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET, /*!< Mouse event, stop feeding event by master */
83 LB_KEY_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */
84 LB_KEY_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */
85 LB_KEY_SET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_SET, /*!< Key event, start feeding event by master */
86 LB_KEY_UNSET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UNSET, /*!< Key event, stop feeding event by master */
87 LB_KEY_FOCUS_IN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_IN, /*!< Key event, focus in */
88 LB_KEY_FOCUS_OUT = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_OUT, /*!< Key event, foucs out */
90 PD_KEY_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */
91 PD_KEY_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */
92 PD_KEY_SET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_SET, /*!< Key event, start feeding event by master */
93 PD_KEY_UNSET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UNSET, /*!< Key event, stop feeding event by master */
94 PD_KEY_FOCUS_IN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_IN, /*!< Key event, focus in */
95 PD_KEY_FOCUS_OUT = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_OUT, /*!< Key event, focus out */
97 CONTENT_EVENT_MAX = 0xFFFFFFFF
102 * Accessibility event for buffer type Livebox or PD.
103 * These event set are sync'd with Tizen accessibility event set.
105 enum access_event_type {
106 ACCESS_EVENT_PD_MASK = 0x10000000,
107 ACCESS_EVENT_LB_MASK = 0x20000000,
109 ACCESS_EVENT_HIGHLIGHT = 0x00000100, /*!< LB accessibility: Hightlight a object */
110 ACCESS_EVENT_HIGHLIGHT_NEXT = 0x00000200, /*!< LB accessibility: Set highlight to next object */
111 ACCESS_EVENT_HIGHLIGHT_PREV = 0x00000400, /*!< LB accessibility: Set highlight to prev object */
112 ACCESS_EVENT_UNHIGHLIGHT = 0x00000800, /*!< LB accessibility unhighlight */
113 ACCESS_EVENT_ACTIVATE = 0x00001000, /*!< LB accessibility activate */
114 ACCESS_EVENT_ACTION_DOWN = 0x00010000, /*!< LB accessibility value changed */
115 ACCESS_EVENT_ACTION_UP = 0x00020000, /*!< LB accessibility value changed */
116 ACCESS_EVENT_SCROLL_DOWN = 0x00100000, /*!< LB accessibility scroll down */
117 ACCESS_EVENT_SCROLL_MOVE = 0x00200000, /*!< LB accessibility scroll move */
118 ACCESS_EVENT_SCROLL_UP = 0x00400000, /*!< LB accessibility scroll up */
120 LB_ACCESS_HIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT, /*!< Access event - Highlight an object in the livebox */
121 LB_ACCESS_HIGHLIGHT_NEXT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT, /*!< Access event - Move highlight to the next object in a livebox */
122 LB_ACCESS_HIGHLIGHT_PREV = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_PREV, /*!< Access event - Move highlight to the prev object in a livebox */
123 LB_ACCESS_UNHIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_UNHIGHLIGHT, /*!< Access event - Delete highlight from the livebox */
124 LB_ACCESS_ACTIVATE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTIVATE, /*!< Access event - Launch or activate the highlighted object */
125 LB_ACCESS_ACTION_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_DOWN, /*!< Access event - down */
126 LB_ACCESS_ACTION_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_UP, /*!< Access event - up */
127 LB_ACCESS_SCROLL_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_DOWN, /*!< Access event - scroll down */
128 LB_ACCESS_SCROLL_MOVE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_MOVE, /*!< Access event - scroll move */
129 LB_ACCESS_SCROLL_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_UP, /*!< Access event - scroll up */
131 PD_ACCESS_HIGHLIGHT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT, /*!< Access event - Highlight an object in the PD */
132 PD_ACCESS_HIGHLIGHT_NEXT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT, /*!< Access event - Move highlight to the next object in a PD */
133 PD_ACCESS_HIGHLIGHT_PREV = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_PREV, /*!< Access event - Move highlight to the prev object in a PD */
134 PD_ACCESS_UNHIGHLIGHT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_UNHIGHLIGHT, /*!< Access event - Delet highlight from the PD */
135 PD_ACCESS_ACTIVATE = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTIVATE, /*!< Access event - Launch or activate the highlighted object */
136 PD_ACCESS_ACTION_DOWN = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTION_DOWN, /*!< Access event - down */
137 PD_ACCESS_ACTION_UP = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTION_UP, /*!< Access event - up */
138 PD_ACCESS_SCROLL_DOWN = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_DOWN, /*!< Access event - scroll down */
139 PD_ACCESS_SCROLL_MOVE = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_MOVE, /*!< Access event - scroll move */
140 PD_ACCESS_SCROLL_UP = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_UP /*!< Access event - scroll up */
145 * Livebox LB content type
147 enum livebox_lb_type {
148 LB_TYPE_IMAGE = 0x01, /*!< Contents of a livebox is based on the image file */
149 LB_TYPE_BUFFER = 0x02, /*!< Contents of a livebox is based on canvas buffer(shared) */
150 LB_TYPE_TEXT = 0x04, /*!< Contents of a livebox is based on formatted text file */
151 LB_TYPE_PIXMAP = 0x08, /*!< Contens of a livebox is shared by the pixmap(depends on X) */
153 LB_TYPE_INVALID = 0xFF
158 * Livebox PD content type
160 enum livebox_pd_type {
161 PD_TYPE_BUFFER = 0x01, /*!< Contents of a PD is based on canvas buffer(shared) */
162 PD_TYPE_TEXT = 0x02, /*!< Contents of a PD is based on formatted text file */
163 PD_TYPE_PIXMAP = 0x04, /*!< Contents of a livebox is shared by the pixmap(depends on X) */
165 PD_TYPE_INVALID = 0xFF
170 * Livebox event type.
171 * These event will be sent from the provider.
173 enum livebox_event_type { /*!< livebox_event_handler_set Event list */
174 LB_EVENT_LB_UPDATED, /*!< Contents of the given livebox is updated */
175 LB_EVENT_PD_UPDATED, /*!< Contents of the given pd is updated */
177 LB_EVENT_CREATED, /*!< A new livebox is created */
178 LB_EVENT_DELETED, /*!< A livebox is deleted */
180 LB_EVENT_GROUP_CHANGED, /*!< Group (Cluster/Sub-cluster) information is changed */
181 LB_EVENT_PINUP_CHANGED, /*!< PINUP status is changed */
182 LB_EVENT_PERIOD_CHANGED, /*!< Update period is changed */
184 LB_EVENT_LB_SIZE_CHANGED, /*!< Livebox size is changed */
185 LB_EVENT_PD_SIZE_CHANGED, /*!< PD size is changed */
187 LB_EVENT_PD_CREATED, /*!< If a PD is created even if you didn't call the livebox_create_pd API */
188 LB_EVENT_PD_DESTROYED, /*!< If a PD is destroyed even if you didn't call the livebox_destroy_pd API */
190 LB_EVENT_HOLD_SCROLL, /*!< If the screen should be freezed */
191 LB_EVENT_RELEASE_SCROLL, /*!< If the screen can be scrolled */
193 LB_EVENT_LB_UPDATE_BEGIN, /*!< Livebox LB content update is started */
194 LB_EVENT_LB_UPDATE_END, /*!< Livebox LB content update is finished */
196 LB_EVENT_PD_UPDATE_BEGIN, /*!< Livebox PD content update is started */
197 LB_EVENT_PD_UPDATE_END, /*!< Livebox PD content update is finished */
199 LB_EVENT_UPDATE_MODE_CHANGED, /*!< Livebox Update mode is changed */
201 LB_EVENT_REQUEST_CLOSE_PD, /*!< Livebox requests to close the PD */
203 LB_EVENT_IGNORED /*!< Request is ignored */
206 enum livebox_fault_type {
207 LB_FAULT_DEACTIVATED, /*!< Livebox is deactivated by its fault operation */
208 LB_FAULT_PROVIDER_DISCONNECTED /*!< Provider is disconnected */
213 * Must be sync'd with the provider
215 enum livebox_visible_state {
216 LB_SHOW = 0x00, /*!< Livebox is showed. Default state */
217 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 */
219 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 */
221 LB_VISIBLE_ERROR = 0xFFFFFFFF /* To enlarge the size of this enumeration type */
226 * TEXT type livebox contents handling opertators.
228 struct livebox_script_operators {
229 int (*update_begin)(struct livebox *handle); /*!< Content parser is started */
230 int (*update_end)(struct livebox *handle); /*!< Content parser is stopped */
234 * Listed functions will be called when parser meets each typed component
236 int (*update_text)(struct livebox *handle, const char *id, const char *part, const char *data); /*!< Update text content */
237 int (*update_image)(struct livebox *handle, const char *id, const char *part, const char *data, const char *option); /*!< Update image content */
238 int (*update_script)(struct livebox *handle, const char *id, const char *part, const char *file, const char *group); /*!< Update script content */
239 int (*update_signal)(struct livebox *handle, const char *id, const char *emission, const char *signal); /*!< Update signal */
240 int (*update_drag)(struct livebox *handle, const char *id, const char *part, double dx, double dy); /*!< Update drag info */
241 int (*update_info_size)(struct livebox *handle, const char *id, int w, int h); /*!< Update content size */
242 int (*update_info_category)(struct livebox *handle, const char *id, const char *category); /*!< Update content category info */
243 int (*update_access)(struct livebox *handle, const char *id, const char *part, const char *text, const char *option); /*!< Update access information */
244 int (*operate_access)(struct livebox *handle, const char *id, const char *part, const char *operation, const char *option); /*!< Update access operation */
248 * \brief Prototype of the return callback of every async functions
251 * \param[in] handle Handle of the livebox instance
252 * \param[in] ret Result status of operation. LB_STATUS_XXX defined from liblivebox-service
253 * \param[in] data data for result callback
258 * \see livebox_add_with_size
260 * \see livebox_activate
261 * \see livebox_resize
262 * \see livebox_set_group
263 * \see livebox_set_period
264 * \see livebox_access_event
265 * \see livebox_set_pinup
266 * \see livebox_create_pd
267 * \see livebox_create_pd_with_position
268 * \see livebox_destroy_pd
269 * \see livebox_emit_text_signal
270 * \see livebox_acquire_pd_pixmap
271 * \see livebox_acquire_lb_pixmap
272 * \see livebox_set_update_mode
274 typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data);
277 * \brief Initialize the livebox system
280 * This API uses get/setenv APIs.
281 * Those APIs are not thread-safe.
282 * So you have to consider to use the livebox_init_with_options instead of this if you are developing multi-threaded viewer.
283 * \param[in] disp If you have X Display connection object already, you can re-use it. but you should care its life cycle.
284 * It must be alive before call the livebox_fini
286 * \retval LB_STATUS_SUCCESS if success
290 * \see livebox_init_with_options
292 extern int livebox_init(void *disp);
295 * \brief Initialize the livebox system with some options
296 * \details livebox_init function uses environment value to initiate some configurable values
297 * But some application doesn't want to use the env value.
298 * For them, this API will give a chance to set default options using given arguments
300 * \param[in] disp if this display is NULL, the library will try to acquire a new connection with X
301 * \param[in] prevent_overwrite If the content of image type livebox is updated, don't overwrite it(1) or overwrite old file(0)
302 * \param[in] event_filter If the next event comes in this period, ignore it. It is too fast to processing it in time.
303 * \param[in] use_thread Use the receive thread.
304 * \return int Integer, Livebox status code
305 * \retval LB_STATUS_SUCCESS if success
311 extern int livebox_init_with_options(void *disp, int prevent_overwrite, double event_filter, int use_thread);
314 * \brief Finalize the livebox system
318 * \retval LB_STATUS_SUCCES if success
319 * \retval LB_STATUS_ERROR_INVALID if livebox_init is not called.
323 * \see livebox_init_with_options
325 extern int livebox_fini(void);
328 * \brief Notify the status of client to the provider. "it is paused".
332 * \retval LB_STATUS_SUCCESS if success
333 * \retval LB_STATUS_ERROR_FAULT if it failed to send state(paused) info
336 * \see livebox_client_resumed
338 extern int livebox_client_paused(void);
341 * \brief Notify the status of client to the provider. "it is resumed".
345 * \retval LB_STATUS_SUCCESS if success
346 * \retval LB_STATUS_ERROR_FAULT if it failed to send state(resumed) info
349 * \see livebox_client_paused
351 extern int livebox_client_resumed(void);
354 * \brief Add a new livebox
357 * Even though you get the livebox handle from return value of this function,
358 * it is not matured before return callback called.
359 * You have to use the handle after get the return callback with "ret == LB_STATUS_SUCCESS"
360 * \param[in] pkgname Livebox Id
361 * \param[in] content Will be passed to the livebox instance.
362 * \param[in] cluster Main group
363 * \param[in] category Sub group
364 * \param[in] period Update period. if you set DEFAULT_PERIOD, the provider will use the default period which is described in the manifest.
365 * \param[in] cb After send the request to the provider, its result will be passed
368 * \retval NULL if it fails to add a new instance
369 * \retval handle livebox handle
373 * \see livebox_add_with_size
375 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);
378 * \brief Add a new livebox
380 * If the screen size if "1280x720"
381 * Below size lists are used for default.
382 * Or you can find the default sizes in pixel from /usr/share/data-provider-master/resolution.ini
383 * Size types are defined from the liblivebox-service package. (livebox-service.h)
385 * Normal mode livebox
386 * 1x1=175x175, LB_SIZE_TYPE_1x1
387 * 2x1=354x175, LB_SIZE_TYPE_2x1
388 * 2x2=354x354, LB_SIZE_TYPE_2x2
389 * 4x1=712x175, LB_SIZE_TYPE_4x1
390 * 4x2=712x354, LB_SIZE_TYPE_4x2
391 * 4x4=712x712, LB_SIZE_TYPE_4x4
394 * 4x3=712x533, LB_SIZE_TYPE_4x3
395 * 4x5=712x891, LB_SIZE_TYPE_4x5
396 * 4x6=712x1070, LB_SIZE_TYPE_4x6
399 * 21x21=224x215, LB_SIZE_TYPE_EASY_1x1
400 * 23x21=680x215, LB_SIZE_TYPE_EASY_3x1
401 * 23x23=680x653, LB_SIZE_TYPE_EASY_3x3
404 * 0x0=720x1280, LB_SIZE_TYPE_0x0
407 * Even if you get the handle by return value of this function, it is not created instance.
408 * So you have to deal it as not initialized handle.
409 * Only it can be initialized after get the return callback with "ret == LB_STATUS_SUCCESS".
410 * \param[in] pkgname Livebox Id
411 * \param[in] content Will be passed to the livebox instance.
412 * \param[in] cluster Main group
413 * \param[in] category Sub group
414 * \param[in] period DEFAULT_PERIOD can be used for this. this argument will be used to specify the period of update content of livebox.
415 * \param[in] type Size type - which are defined from liblivebox-service package.
416 * \param[in] cb After the request is sent to the master provider, this callback will be called.
417 * \param[in] data This data will be passed to the callback.
419 * \retval handle Livebox handle but not yet initialized
420 * \retval NULL if it fails to create a handle
424 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);
427 * \brief Delete a livebox (deprecated)
430 * If you call this with uninitialized handle, the return callback will be called synchronously.
431 * So before return from this function, the return callback will be called first.
432 * \param[in] handler Handler of a livebox instance
433 * \param[in] cb return callback
434 * \param[in] data user data for return callback
436 * \retval LB_STATUS_ERROR_INVALID Invalid argument
437 * \retval LB_STATUS_ERROR_BUSY already in process
438 * \retval LB_STATUS_ERROR_FAULT failed to create a request packet
439 * \retval LB_STATUS_SUCCESS successfully sent, return callack will be called
444 extern int livebox_del(struct livebox *handler, ret_cb_t cb, void *data);
447 * \brief Delete a livebox (will be replaced with livebox_del)
450 * If you call this with uninitialized handle, the return callback will be called synchronously.
451 * So before return from this function, the return callback will be called first.
452 * \param[in] handler Handler of a livebox instance
453 * \param[in] type Deletion type, LB_DELETE_PERMANENTLY or LB_DELETE_TEMPORARY
454 * \param[in] cb return callback
455 * \param[in] data user data for return callback
457 * \retval LB_STATUS_ERROR_INVALID Invalid argument
458 * \retval LB_STATUS_ERROR_BUSY already in process
459 * \retval LB_STATUS_ERROR_FAULT failed to create a request packet
460 * \retval LB_STATUS_SUCCESS successfully sent, return callack will be called
465 extern int livebox_del_NEW(struct livebox *handler, int type, ret_cb_t cb, void *data);
468 * \brief Set a livebox events callback
470 * To get the events push from the provider, register the event callback using this function
471 * The callback will be called if there is any events from the provider.
473 * \param[in] cb Event handler
474 * \param[in] data User data for the event handler
476 * \retval LB_STATUS_SUCCESS if succeed to set event handler
477 * \retval LB_STATUS_ERROR_INVALID Invalid argument
478 * \retval LB_STATUS_ERROR_MEMORY Not enough memory
481 * \see livebox_unset_event_handler
483 extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data);
486 * \brief Unset the livebox event handler
489 * \param[in] cb Event handler
490 * \return void * Event handler data
491 * \retval pointer of 'data' which is used with the livebox_set_event_handler
494 * \see livebox_set_event_handler
496 extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data));
499 * \brief Live box fault event handler registeration function
501 * event, pkgname, filename, funcname
504 * \param[in] cb Event handler
505 * \param[in] data Event handler data
507 * \retval LB_STATUS_SUCCESS if succeed to set fault event handler
508 * \retval LB_STATUS_ERROR_INVALID Invalid argument
509 * \retval LB_STATUS_ERROR_MEMORY Not enough memory
512 * \see livebox_unset_fault_handler
514 extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data);
517 * \brief Unset the live box fault event handler
520 * \param[in] cb Event handler
521 * \return void * Callback data which is set via livebox_set_fault_handler
522 * \retval pointer of 'data' which is used with the livebox_set_fault_handler
525 * \see livebox_set_fault_handler
527 extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *));
530 * \brief Activate the faulted livebox.
532 * Request result will be back via return callback.
534 * Even though this function returns SUCCESS, it means just successfully sent a request to provider.
535 * So you have to check the return callback. and its "ret" argument.
536 * \param[in] pkgname Package name which should be activated
537 * \param[in] cb Result callback
538 * \param[in] data Callback data
540 * \retval LB_STATUS_SUCCESS Successfully sent a request
541 * \retval LB_STATUS_ERROR_INVALID Invalid argument
542 * \retval LB_STATUS_ERROR_FAULT Failed to make a request
547 extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data);
550 * \brief Resize the livebox
552 * Normal mode livebox size
553 * 1x1=175x175, LB_SIZE_TYPE_1x1
554 * 2x1=354x175, LB_SIZE_TYPE_2x1
555 * 2x2=354x354, LB_SIZE_TYPE_2x2
556 * 4x1=712x175, LB_SIZE_TYPE_4x1
557 * 4x2=712x354, LB_SIZE_TYPE_4x2
558 * 4x4=712x712, LB_SIZE_TYPE_4x4
560 * Extended livebox size
561 * 4x3=712x533, LB_SIZE_TYPE_4x3
562 * 4x5=712x891, LB_SIZE_TYPE_4x5
563 * 4x6=712x1070, LB_SIZE_TYPE_4x6
565 * Easy mode livebox size
566 * 21x21=224x215, LB_SIZE_TYPE_EASY_1x1
567 * 23x21=680x215, LB_SIZE_TYPE_EASY_3x1
568 * 23x23=680x653, LB_SIZE_TYPE_EASY_3x3
570 * Special mode livebox size
571 * 0x0=720x1280, LB_SIZE_TYPE_0x0
573 * You have to check the return callback.
574 * \param[in] handler Handler of a livebox instance
575 * \param[in] type Type of a livebox size, LB_SIZE_TYPE_1x1, ...
576 * \param[in] cb Result callback of the resize operation.
577 * \param[in] data User data for return callback
579 * \retval LB_STATUS_ERROR_INVALID Invalid argument
580 * \retval LB_STATUS_ERROR_BUSY Previous request of resize is in progress.
581 * \retval LB_STATUS_ERROR_ALREADY Already resized, there is no differences between current size and requested size.
582 * \retval LB_STATUS_ERROR_PERMISSION Permission denied, you only have view the content of this box.
583 * \retval LB_STATUS_ERROR_FAULT Failed to make a request
588 extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data);
591 * \brief Send the click event for a livebox.
594 * \param[in] handler Handler of a livebox instance
595 * \param[in] x Rational X of the content width.
596 * \param[in] y Rational Y of the content height.
598 * \retval LB_STATUS_ERROR_INVALID Invalid argument
599 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
600 * \retval LB_STATUS_SUCCESS Successfully done
605 extern int livebox_click(struct livebox *handler, double x, double y);
608 * \brief Change the cluster/sub-cluster name of given livebox handler
611 * \param[in] handler Handler of a livebox instance
612 * \param[in] cluster New cluster of a livebox
613 * \param[in] category New category of a livebox
614 * \param[in] cb Result callback for changing the cluster/category of a livebox
615 * \param[in] data User data for the result callback
617 * \retval LB_STATUS_SUCCESS Request is successfully sent. the return callback will be called.
618 * \retval LB_STATUS_ERROR_BUSY previous request is not finished yet.
619 * \retval LB_STATUS_ERROR_ALREADY group name is same with current one.
620 * \retval LB_STATUS_ERROR_PERMISSION you have no permission to change property of this livebox instance.
621 * \retval LB_STATUS_ERROR_FAULT Failed to make a request.
626 extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data);
629 * \brief Get the cluster and category(sub-cluster) name of given livebox (It is not I18N format, only english)
632 * You have to do not release the cluster & category.
633 * It is allocated inside of given livebox instance, so you can only read it.
634 * \param[in] handler Handler of a livebox instance
635 * \param[out] cluster Storage(memory) for containing the cluster name
636 * \param[out] category Storage(memory) for containing the category name
638 * \retval LB_STATUS_ERROR_INVALID Invalid argument
639 * \retval LB_STATUS_SUCCESS Successfully done
644 extern int livebox_get_group(struct livebox *handler, const char **cluster, const char **category);
647 * \brief Get the period of this livebox handler
650 * if this function returns 0.0f, it means the livebox has no update period.
651 * or the handle is not valid.
652 * This function only can be works after the return callback of livebox_create fucntion is called.
653 * \param[in] handler Handler of a livebox instance
655 * \retval Current update period of a livebox
656 * \retval 0.0f it means the box has no update period, or it can returns 0.0 if the handles is not valid.
661 extern double livebox_period(struct livebox *handler);
664 * \brief Change the update period
667 * \param[in] handler Handler of a livebox instance
668 * \param[in] period New update period of a livebox
669 * \param[in] cb Result callback of changing the update period of this livebox
670 * \param[in] data User data for the result callback
672 * \retval LB_STATUS_SUCCESS Successfully done
673 * \retval LB_STATUS_ERROR_INVALID Invalid argument
674 * \retval LB_STATUS_ERROR_BUSY
675 * \retval LB_STATUS_ERROR_ALREADY
676 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
681 extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data);
684 * \brief Is this an text type livebox?
687 * \param[in] handler Handler of a livebox instance
688 * \return livebox_lb_type
689 * \retval LB_TYPE_IMAGE Contents of a livebox is based on the image file
690 * \retval LB_TYPE_BUFFER Contents of a livebox is based on canvas buffer(shared)
691 * \retval LB_TYPE_TEXT Contents of a livebox is based on formatted text file
692 * \retval LB_TYPE_PIXMAP Contens of a livebox is shared by the pixmap(depends on X)
693 * \retval LB_TYPE_INVALID
696 * \see livebox_lb_type
698 extern enum livebox_lb_type livebox_lb_type(struct livebox *handler);
701 * \brief Is this livebox is created by a user?
703 * If the livebox instance is created by system this will returns 0.
705 * \param[in] handler Handler of a livebox instance
707 * \retval LB_STATUS_ERROR_INVALID Invalid argument
708 * \retval 0 automatically created livebox by the provider
709 * \retval 1 created by user via livebox_add or livebox_add_with_size
713 * \see livebox_add_with_size
714 * \see livebox_set_event_handler
716 extern int livebox_is_user(struct livebox *handler);
719 * \brief Get the content information string of given livebox
722 * \param[in] handler Handler of a livebox instance
723 * \return const char *
724 * \retval content_info Livebox content info that can be used again via content_info argument of livebox_add or livebox_add_with_size.
728 * \see livebox_add_with_size
730 extern const char *livebox_content(struct livebox *handler);
733 * \brief Get the sub cluster title string of given livebox
735 * This API is now used for accessibility.
736 * Each box should set their content as a string to read by TTS.
737 * So if the box has focus on the homescreen, the homescreen will read a text using this API.
739 * The title which is returned by this, the TTS should read it.
740 * But it is just recomended to a homescreen.
741 * So read it or not is depends on implementation of the homescreen.
742 * \param[in] handler Handler of a livebox instance
743 * \return const char *
744 * \retval sub cluster name
750 extern const char *livebox_category_title(struct livebox *handler);
753 * \brief Get the filename of given livebox, if it is an IMAGE type livebox
755 * If the box is developed as image format to represent its contents,
756 * The homescreen should know its image file name.
758 * \param[in] handler Handler of a livebox instance
759 * \return const char *
760 * \retval filename if the livebox type is image this function will give you a abspath of an image file (content is rendered)
761 * \retval NULL if this has no image file or type is not image file.
766 extern const char *livebox_filename(struct livebox *handler);
769 * \brief Get the package name of given livebox handler
772 * \param[in] handler Handler of a livebox instance
773 * \return const char *
774 * \retval pkgname package name
775 * \retval NULL if the handler is not valid
780 extern const char *livebox_pkgname(struct livebox *handler);
783 * \brief Get the priority of a current content.
786 * \param[in] handler Handler of a livebox instance
788 * \retval 0.0f handler is NULL
789 * \retval -1.0f Handler is not valid (not yet initialized)
790 * \retval real number between 0.0 and 1.0
795 extern double livebox_priority(struct livebox *handler);
798 * \brief Acquire the buffer of given livebox (Only for the buffer type)
801 * \param[in] handler Handler of a livebox instance
803 * \retval address of a FB
804 * \retval NULL if it fails to get fb address
809 extern void *livebox_acquire_fb(struct livebox *handler);
812 * \brief Release the buffer of a livebox (Only for the buffer type)
817 * \retval LB_STATUS_ERROR_INVALID Invalid argument
818 * \retval LB_STATUS_SUCCESS Successfully done
821 * \see livebox_acquire_fb
823 extern int livebox_release_fb(void *buffer);
826 * \brief Get the reference count of Livebox buffer (Only for the buffer type)
831 * \retval LB_STATUS_ERROR_INVALID Invalid argument
832 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
833 * \retval refcnt positive integer including ZERO
836 * \see livebox_pdfb_refcnt
838 extern int livebox_fb_refcnt(void *buffer);
841 * \brief Acquire the buffer of a PD frame (Only for the buffer type)
844 * \param[in] handler Handler of a livebox instance
847 * \retval adress of buffer of PD
850 * \see livebox_release_pdfb
852 extern void *livebox_acquire_pdfb(struct livebox *handler);
855 * \brief Release the acquired buffer of the PD Frame (Only for the buffer type)
860 * \retval LB_STATUS_ERROR_INVALID Invalid argument
861 * \retval LB_STATUS_SUCCESS Successfully done
864 * \see livebox_acquire_pdfb
866 extern int livebox_release_pdfb(void *buffer);
869 * \brief Reference count of given PD buffer (Only for the buffer type)
874 * \retval LB_STATUS_ERROR_INVALID Invalid argument
875 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
876 * \retval reference count
879 * \see livebox_fb_refcnt
881 extern int livebox_pdfb_refcnt(void *buffer);
884 * \brief Get the size of the Livebox
887 * \param[in] handler Handler of a livebox instance
889 * \retval LB_SIZE_TYPE_NxM
890 * \retval LB_SIZE_TYPE_INVALID
895 extern int livebox_size(struct livebox *handler);
898 * \brief Get the size of the Progressive Disclosure
901 * \param[in] handler Handler of a livebox instance
905 * \retval LB_STATUS_ERROR_INVALID Invalid argument
906 * \retval LB_STATUS_SUCCESS Successfully done
911 extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h);
914 * \brief List of supported sizes of given handler
917 * \param[in] handler Handler of a livebox instance
919 * \param[out] size_list
921 * \retval LB_STATUS_ERROR_INVALID Invalid argument
922 * \retval LB_STATUS_SUCCESS Successfully done
927 extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list);
930 * \brief BUFFER SIZE of the livebox if it is a buffer type
933 * \param[in] handler Handler of a livebox instance
935 * \retval LB_STATUS_ERROR_INVALID Invalid argument
936 * \retval size of livebox buffer
941 extern int livebox_lbfb_bufsz(struct livebox *handler);
944 * \brief BUFFER SIZE of the progiressive disclosure if it is a buffer type
947 * \param[in] handler Handler of a livebox instance
949 * \retval LB_STATUS_ERROR_INVALID Invalid argument
950 * \retval size of PD buffer
955 extern int livebox_pdfb_bufsz(struct livebox *handler);
958 * \brief Send the content event (for buffer type) to provider(livebox)
960 * \remarks DEPRECATED
961 * Use the livebox_mouse_event function instead of this.
962 * \param[in] handler Handler of a livebox instance
963 * \param[in] type Event type
964 * \param[in] x coordinates of X axis
965 * \param[in] y coordinates of Y axis
967 * \retval LB_STATUS_ERROR_INVALID Invalid argument
968 * \retval LB_STATUS_ERROR_BUSY Previous operaion is not finished yet
969 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
970 * \retval LB_STATUS_SUCCESS Successfully sent
973 * \see livebox_mouse_event
974 * \see livebox_access_event
975 * \see livebox_key_event
977 extern int livebox_content_event(struct livebox *handler, enum content_event_type type, double x, double y);
980 * \brief Send the content event (for buffer type) to provider(livebox)
983 * \param[in] handler Handler of a livebox instance
984 * \param[in] type Event type
985 * \param[in] x coordinates of X axis
986 * \param[in] y coordinates of Y axis
988 * \retval LB_STATUS_ERROR_INVALID Invalid argument
989 * \retval LB_STATUS_ERROR_BUSY Previous operation is not finished yet
990 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
991 * \retval LB_STATUS_SUCCESS Successfully sent
994 * \see livebox_content_event
995 * \see livebox_access_event
996 * \see livebox_key_event
998 extern int livebox_mouse_event(struct livebox *handler, enum content_event_type type, double x, double y);
1001 * \brief Send the access event(for buffer type) to provider(livebox).
1004 * \param[in] handler Handler of a livebox instance
1005 * \param[in] type Event type
1006 * \param[in] x coordinates of X axsis
1007 * \param[in] y coordinates of Y axsis
1008 * \param[in] cb Result callback function
1009 * \param[in] data Callback data
1011 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1012 * \retval LB_STATUS_ERROR_BUSY Previous operation is not finished yet
1013 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1014 * \retval LB_STATUS_SUCCESS Successfully sent
1017 * \see livebox_mouse_event
1018 * \see livebox_key_event
1020 extern int livebox_access_event(struct livebox *handler, enum access_event_type type, double x, double y, ret_cb_t cb, void *data);
1023 * \brief Send the key event(for buffer type) to provider(livebox).
1026 * \param[in] handler Handler of a livebox instance
1027 * \param[in] type Key event type
1028 * \param[in] keycode Code of key
1029 * \param[in] cb Result callback
1030 * \param[in] data Callback data
1032 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1033 * \retval LB_STATUS_ERROR_BUSY Previous operation is not finished yet
1034 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1035 * \retval LB_STATUS_SUCCESS Successfully sent
1038 * \see livebox_mouse_event
1039 * \see livebox_access_event
1041 extern int livebox_key_event(struct livebox *handler, enum content_event_type type, unsigned int keycode, ret_cb_t cb, void *data);
1044 * \brief Do pin up or not.
1046 * If the livebox supports the pinup feature,
1047 * you can freeze the update of given livebox.
1048 * But it is different with pause.
1049 * The box will be updated and it will decide wheter update its content or not when the pinup is on.
1051 * \param[in] handler Handler of a livebox instance
1052 * \param[in] flag Pinup value
1053 * \param[in] cb Result callback
1054 * \param[in] data Callback data
1056 * \retval LB_STATUS_ERROR_INVALID Invalid parameters
1058 * \see livebox_set_visibility
1059 * \see livebox_is_pinned_up
1061 extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data);
1064 * \brief Check the PIN-UP status of given handler
1067 * \param[in] handler Handler of a livebox instance
1069 * \retval LB_STATUS_ERROR_INVALID Invalid parameters
1070 * \retval 1 box is pinned up
1071 * \retval 0 box is not pinned up
1072 * \see livebox_set_pinup
1074 extern int livebox_is_pinned_up(struct livebox *handler);
1077 * \brief Check the PINUP feature availability of the given handler
1080 * \param[in] handler Handler of a livebox instance
1082 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1083 * \retval 1 if the box support Pinup feature
1084 * \retval 0 if the box does not support the Pinup feature
1087 * \see livebox_is_pinned_up
1088 * \see livebox_set_pinup
1090 extern int livebox_has_pinup(struct livebox *handler);
1093 * \brief Check the PD existence of given handler
1096 * \param[in] handler Handler of a livebox instance
1098 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1099 * \retval 1 if the box support the PD
1100 * \retval 0 if the box has no PD
1105 extern int livebox_has_pd(struct livebox *handler);
1108 * \brief Create the PD of given handler
1111 * \param[in] handler Handler of a livebox instance
1112 * \param[in] cb Result callback
1113 * \param[in] data Callback data
1115 * \retval LB_STATUS_SUCCESS Successfully done
1116 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1117 * \retval LB_STATUS_ERROR_BUSY Previous operation is not finished yet
1118 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1122 * \see livebox_create_pd_with_position
1123 * \see livebox_move_pd
1124 * \see livebox_destroy_pd
1126 extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data);
1129 * \brief Create the PD of given handler with the relative position from livebox
1132 * \param[in] handler Handler of a livebox instance
1133 * \param[in] x 0.0 ~ 1.0
1134 * \param[in] y 0.0 ~ 1.0
1135 * \param[in] cb Result callback
1136 * \param[in] data Callback data
1138 * \retval LB_STATUS_SUCCESS Successfully done
1139 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1140 * \retval LB_STATUS_ERROR_BUSY Previous operation is not finished yet
1141 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1144 * \see livebox_create_pd
1145 * \see livebox_destroy_pd
1146 * \see livebox_move_pd
1148 extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data);
1151 * \brief PD position is updated.
1154 * \param[in] handler Handler of a livebox instance
1155 * \param[in] x 0.0 ~ 1.0
1156 * \param[in] y 0.0 ~ 1.0
1158 * \retval LB_STATUS_SUCCESS if succeed to send request for updating position of the PD.
1159 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1160 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1165 extern int livebox_move_pd(struct livebox *handler, double x, double y);
1168 * \brief Destroy the PD of given handler if it is created.
1171 * \param[in] handler Handler of a livebox instance
1175 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1176 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1177 * \retval LB_STATUS_SUCCESS Successfully done
1182 extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data);
1185 * \brief Check the create status of given livebox handler
1188 * \param[in] handler Handler of a livebox instance
1190 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1191 * \retval 0 PD is not created
1192 * \retval 1 PD is created
1194 extern int livebox_pd_is_created(struct livebox *handler);
1197 * \brief Check the content type of the progressive disclosure of given handler
1200 * \param[in] handler Handler of a livebox instance
1202 * \retval PD_TYPE_BUFFER Contents of a PD is based on canvas buffer(shared)
1203 * \retval PD_TYPE_TEXT Contents of a PD is based on formatted text file
1204 * \retval PD_TYPE_PIXMAP Contents of a livebox is shared by the pixmap(depends on X)
1205 * \retval PD_TYPE_INVALID
1208 * \see livebox_pd_type
1210 extern enum livebox_pd_type livebox_pd_type(struct livebox *handler);
1213 * \brief Check the existence of a livebox about given package name
1216 * \param[in] pkgname
1218 * \retval 1 if the box is exists
1219 * \retval 0 if the box is not exists
1224 extern int livebox_is_exists(const char *pkgname);
1227 * \brief Set function table for parsing the text content of a livebox
1230 * \param[in] handler Handler of a livebox instance
1233 * \retval LB_STATUS_SUCCESS Successfully done
1234 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1235 * \see livebox_set_pd_text_handler
1237 extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1240 * \brief Set function table for parsing the text content of a Progressive Disclosure
1243 * \param[in] handler Handler of a livebox instance
1246 * \retval LB_STATUS_SUCCESS Successfully done
1247 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1248 * \see livebox_set_text_handler
1250 extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1253 * \brief Emit a text signal to given livebox only if it is a text type.
1256 * \param[in] handler Handler of a livebox instance
1257 * \param[in] emission Emission string
1258 * \param[in] source Source string
1259 * \param[in] sx start X
1260 * \param[in] sy start Y
1261 * \param[in] ex end X
1262 * \param[in] ey end Y
1263 * \param[in] cb Result callback
1264 * \param[in] data Callback data
1266 * \retval LB_STATUS_ERROR_INVALID Invalid parameters
1267 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1268 * \retval LB_STATUS_SUCCESS Successfully emitted
1271 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);
1274 * \brief Set a private data pointer to carry it using given handler
1277 * \param[in] handler Handler of a livebox instance
1278 * \param[in] data data pointer
1280 * \retval LB_STATUS_SUCCESS Successfully registered
1281 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1284 * \see livebox_get_data
1286 extern int livebox_set_data(struct livebox *handler, void *data);
1289 * \brief Get private data pointer which is carried by given handler
1292 * \param[in] handler Handler of a livebox instance
1294 * \retval data pointer
1295 * \retval NULL if there is not data
1298 * \see livebox_set_data
1300 extern void *livebox_get_data(struct livebox *handler);
1303 * \brief Subscribe the event for liveboxes only in given cluster and sub-cluster
1305 * If you wrote a view-only client.
1306 * you can receive the event of specific liveboxes which are grouped in given cluster/category
1307 * But you cannot modify their attributes (such as size, ...).
1309 * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event.
1310 * If you use the "*", value in the category will be ignored.
1311 * \param[in] category "*" can be used for subscribe liveboxes events of all category(sub-cluster) in given "cluster"
1313 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1314 * \retval LB_STATUS_SUCCESS Successfully requested
1317 * \see livebox_unsubscribe_group
1319 extern int livebox_subscribe_group(const char *cluster, const char *category);
1322 * \brief Unsubscribe the event for the liveboxes, but you will receive already added liveboxes event.
1325 * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event.
1326 * If you use the "*", value in the category will be ignored.
1327 * \param[in] category "*" can be used for subscribe all sub-cluster's liveboxes event in given "cluster"
1329 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1330 * \retval LB_STATUS_SUCCESS Successfully requested
1333 * \see livebox_subscribe_group
1335 extern int livebox_unsubscribe_group(const char *cluster, const char *category);
1338 * \brief Refresh the group(cluster/sub-cluser(aka. category))
1340 * This function will trigger the update of all liveboxes in given cluster/category group
1342 * Basically default livebox system doesn't use the cluster/category concept.
1343 * But you can use it. so if you decide to use it then you can trigger the update of all liveboxes in given group.
1344 * \param[in] cluster Cluster ID
1345 * \param[in] category Sub-cluster ID
1346 * \param[in] force 1 if the boxes should be updated even if they are paused
1348 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1349 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1350 * \retval LB_STATUS_SUCCESS Successfully requested
1353 * \see livebox_refresh
1355 extern int livebox_refresh_group(const char *cluster, const char *category, int force);
1358 * \brief Refresh a livebox
1361 * \param[in] handler Handler of a livebox instance
1362 * \param[in] force 1 if the box should be updated even if it is paused
1364 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1365 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1366 * \retval LB_STATUS_SUCCESS Successfully requested
1369 * \see livebox_refresh_group
1371 extern int livebox_refresh(struct livebox *handler, int force);
1374 * \brief Pixmap Id of a livebox content
1376 * This function doesn't guarantees the life-cycle of the pixmap.
1377 * If the service provider destroy the pixmap, you will not know about it.
1378 * So you should validate it before access it.
1380 * \param[in] handler Handler of a livebox instance
1382 * \retval 0 if the pixmap is not created
1383 * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
1386 * \see livebox_pd_pixmap
1388 extern int livebox_lb_pixmap(const struct livebox *handler);
1391 * \brief Pixmap Id of a PD content
1393 * This function doesn't guarantees the life-cycle of the pixmap.
1394 * If the service provider destroy the pixmap, you will not know about it.
1395 * So you should validate it before access it.
1397 * \param[in] handler Handler of a livebox instance
1399 * \retval 0 if the pixmap is not created
1400 * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
1403 * \see livebox_lb_pixmap
1405 extern int livebox_pd_pixmap(const struct livebox *handler);
1408 * \brief Acquire the pixmap of PD
1410 * After acquire the pixmap of PD, it will not be destroyed
1411 * So if the new update is comming with new pixmap Id, you should release old pixmap manually
1413 * \param[in] handler Handler of a livebox instance
1414 * \param[in] cb Result callback for acquiring request
1415 * \param[in] data Callback Data
1417 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1418 * \retval LB_STATUS_ERROR_FAULT Failed to send a request to the service provider or there is critical error that is unrecoverable
1419 * \retval LB_STATUS_SUCCESS Successfully requested to acquire the pixmap of PD
1422 * \see livebox_release_pd_pixmap
1423 * \see livebox_acquire_lb_pixmap
1426 extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1429 * \brief Release the acquired pixmap ID
1432 * \param[in] handler Handler of a livebox instance
1433 * \param[in] pixmap Pixmap Id to release it
1435 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1436 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1437 * \retval LB_STATUS_SUCCESS Successfully released (request is sent)
1440 * \see livebox_acquire_pd_pixmap
1441 * \see livebox_release_lb_pixmap
1443 extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap);
1446 * \brief Getting the PIXMAP of a livebox
1448 * Even if the render process release the pixmap, the pixmap will be kept before released by livebox_release_lb_pixmap
1449 * You should release the pixmap manually.
1451 * \param[in] handler Handler of a livebox instance
1452 * \param[in] cb Callback function which will be called with result of acquiring lb pixmap
1453 * \param[in] data Callback data
1455 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1456 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1457 * \retval LB_STATUS_SUCCESS Successfully requested
1459 * Livebox service system should support the PIXMAP type buffer.
1460 * The livebox should be designed to use the buffer (script type)
1462 * \see livebox_release_lb_pixmap
1463 * \see livebox_acquire_pd_pixmap
1466 extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1469 * \brief Release the pixmap of a livebox
1471 * After the client gets new pixmap or no more need to keep current pixmap, use this to release it.
1472 * If there is no user for given pixmap, the pixmap will be destroyed.
1474 * \param[in] handler Handler of a livebox instance
1475 * \param[in] pixmap Pixmap Id of given livebox handler
1477 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1478 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1479 * \retval LB_STATUS_SUCCESS Successfully done
1481 * The pixmap should be acquired by livebox_acquire_lb_pixmap
1483 * \see livebox_acquire_lb_pixmap
1484 * \see livebox_release_pd_pixmap
1486 extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap);
1489 * \brief Update the visible state of a livebox
1492 * \param[in] handler Handler of a livebox instance
1493 * \param[in] state Configure the current visible state of a livebox
1495 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1496 * \retval LB_STATUS_ERROR_BUSY
1497 * \retval LB_STATUS_ERROR_PERMISSION
1498 * \retval LB_STATUS_ERROR_ALREADY
1499 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1500 * \retval LB_STATUS_SUCCESS Successfully done
1505 extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state);
1508 * \brief Current visible state of a livebox
1511 * \param[in] handler Handler of a livebox instance
1512 * \return livebox_visible_state
1513 * \retval LB_SHOW Livebox is showed. Default state
1514 * \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
1515 * \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
1516 * \retval LB_VISIBLE_ERROR To enlarge the size of this enumeration type
1521 extern enum livebox_visible_state livebox_visibility(struct livebox *handler);
1524 * \brief Set the update mode of current livebox
1527 * if you set 1 for active update mode, you should get buffer without updated event from provider.
1528 * But is passive mode, you have to update content of a box when you get updated event.
1529 * Default is Passive mode.
1530 * \param[in] handler Handler of a livebox instance
1531 * \param[in] active_update 1 means active update, 0 means passive update (default)
1532 * \param[in] cb Result callback function
1533 * \param[in] data Callback data
1535 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1536 * \retval LB_STATUS_ERROR_BUSY
1537 * \retval LB_STATUS_ERROR_PERMISSION
1538 * \retval LB_STATUS_ERROR_ALREADY
1539 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1540 * \retval LB_STATUS_SUCCESS Successfully done
1545 extern int livebox_set_update_mode(struct livebox *handler, int active_update, ret_cb_t cb, void *data);
1548 * \brief Is this box in the active update mode?
1551 * \param[in] handler Handler of a livebox instance
1553 * \retval 0 if passive mode
1554 * \retval 1 if active mode or error code
1559 extern int livebox_is_active_update(struct livebox *handler);
1562 * \brief Use the manual sync for S/W buffer
1569 * \see livebox_manual_sync
1570 * \see livebox_sync_pd_fb
1571 * \see livebox_sync_lb_fb
1573 extern void livebox_set_manual_sync(int flag);
1576 * \brief Get current mode
1580 * \retval 0 if auto sync
1581 * \retval 1 if manual sync
1584 * \see livebox_set_manual_sync
1585 * \see livebox_sync_pd_fb
1586 * \see livebox_sync_lb_fb
1588 extern int livebox_manual_sync(void);
1591 * \brief Use the frame drop while resizing contents
1594 * \param[in] flag 1 for dropping frames of old size or 0.
1598 * \see livebox_frame_drop_for_resizing
1600 extern void livebox_set_frame_drop_for_resizing(int flag);
1603 * \brief Get current mode
1605 * While resizing the box, viewer doesn't want to know the updaed frames of old size anymore,
1606 * In that case, if this mode is turnned on, the provider will not send the updated event to the viewer about old size.
1607 * So the viewer can reduce its burden to update (or ignore) unnecessary frames
1610 * \retval 0 if it is disabled
1611 * \retval 1 if it is enabled
1614 * \see livebox_set_frame_drop_for_resizing
1616 extern int livebox_frame_drop_for_resizing(void);
1619 * \brief Sync manually
1622 * param[in] handler Handler of a livebox instance
1624 * \retval LB_STATUS_SUCCESS If success
1625 * \retval LB_STATUS_ERROR_INVALID Invalid handle
1628 * \see livebox_set_manual_sync
1629 * \see livebox_manual_sync
1630 * \see livebox_sync_lb_fb
1632 extern int livebox_sync_pd_fb(struct livebox *handler);
1635 * \brief Sync manually
1638 * \param[in] handler Handler of a livebox instance
1640 * \retval LB_STATUS_SUCCESS If success
1641 * \retval LB_STATUS_ERROR_INVALID Invalid handle
1644 * \see livebox_set_manual_sync
1645 * \see livebox_manual_sync
1646 * \see livebox_sync_pd_fb
1648 extern int livebox_sync_lb_fb(struct livebox *handler);
1651 * \brief Getting the alternative icon of given livebox instance.
1652 * \details If the box should be represented as a shortcut icon, this function will get the alternative icon.
1654 * \param[in] handler Handler of a livebox instance
1655 * \return const char *
1656 * \retval address Absolute path of an alternative icon file
1657 * \retval NULL Livebox has no alternative icon file
1660 * \see livebox_alt_name
1662 extern const char *livebox_alt_icon(struct livebox *handler);
1665 * \brief Getting the alternative name of given livebox instance.
1666 * \details If the box should be represented as a shortcut name, this function will get the alternative name.
1668 * \param[in] handler Handler of a livebox instance
1669 * \return const char *
1670 * \retval name Alternative name of a livebox
1671 * \retval NULL Livebox has no alternative name
1674 * \see livebox_alt_icon
1676 extern const char *livebox_alt_name(struct livebox *handler);
1679 * \brief Get the lock for frame buffer.
1681 * This function should be used to prevent from rendering to the frame buffer while reading it.
1682 * And the locking area should be short and must be released ASAP
1683 * Or the render thread will be hang'd.
1685 * \param[in] handler Handler of a livebox instance
1686 * \param[in] is_pd 1 for PD or 0
1688 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1689 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1690 * \retval LB_STATUS_SUCCESS Successfully done
1693 * \see livebox_release_fb_lock
1695 extern int livebox_acquire_fb_lock(struct livebox *handler, int is_pd);
1698 * \brief Release the lock of frame buffer
1700 * This function should be called ASAP after acquire a lock of FB.
1701 * Or the render process will be blocked.
1703 * \param[in] handler Handler of a livebox instance
1704 * \param[in] is_pd 1 for PD or 0
1706 * \retval LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1707 * \retval LB_STATUS_ERROR_INVALID Invalid argument
1708 * \retval LB_STATUS_SUCCESS Successfully done
1711 * \see livebox_acquire_fb_lock
1713 extern int livebox_release_fb_lock(struct livebox *handler, int is_pd);