include/livebox.h

   1 /*
   2  * Copyright 2013  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.1 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://floralicense.org/license/
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __LIVEBOX_H
  18 #define __LIVEBOX_H
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /*!
  25  * \addtogroup CAPI_LIVEBOX_VIEWER_MODULE
  26  * \{
  27  */
  28
  29 /*!
  30  * \brief
  31  * Structure for a Livebox instance
  32  */
  33 struct livebox;
  34
  35 /*!
  36  * \brief
  37  * Use the default update period which is defined in the livebox package manifest.
  38  */
  39 #define DEFAULT_PERIOD -1.0f
  40
  41 /*!
  42  * \brief
  43  * Mouse & Key event for buffer type Livebox or PD
  44  * Viewer should send these events to livebox.
  45  */
  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 */
  54
  55         CONTENT_EVENT_KEY_DOWN          = 0x00100000, /*!< LB key press */
  56         CONTENT_EVENT_KEY_UP            = 0x00200000, /*!< LB key release */
  57
  58         CONTENT_EVENT_KEY_MASK          = 0x80000000,
  59         CONTENT_EVENT_MOUSE_MASK        = 0x20000000,
  60         CONTENT_EVENT_PD_MASK           = 0x10000000,
  61         CONTENT_EVENT_LB_MASK           = 0x40000000,
  62
  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,
  70
  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,
  78
  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 */
  81
  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 */
  84
  85         CONTENT_EVENT_MAX               = 0xFFFFFFFF
  86 };
  87
  88 /*!
  89  * \brief
  90  * Accessibility event for buffer type Livebox or PD.
  91  * These event set are sync'd with Tizen accessibility event set.
  92  */
  93 enum access_event_type {
  94         ACCESS_EVENT_PD_MASK            = 0x10000000,
  95         ACCESS_EVENT_LB_MASK            = 0x20000000,
  96
  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 */
 107
 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 */
 118
 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
 129 };
 130
 131 /*!
 132  * \brief
 133  * Livebox LB content type
 134  */
 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) */
 140
 141         LB_TYPE_INVALID = 0xFF
 142 };
 143
 144 /*!
 145  * \brief
 146  * Livebox PD content type
 147  */
 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) */
 152
 153         PD_TYPE_INVALID = 0xFF
 154 };
 155
 156 /*!
 157  * \brief
 158  * Livebox event type.
 159  * These event will be sent from the provider.
 160  */
 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 */
 164
 165         LB_EVENT_CREATED, /*!< A new livebox is created */
 166         LB_EVENT_DELETED, /*!< A livebox is deleted */
 167
 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 */
 171
 172         LB_EVENT_LB_SIZE_CHANGED, /*!< Livebox size is changed */
 173         LB_EVENT_PD_SIZE_CHANGED, /*!< PD size is changed */
 174
 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 */
 177
 178         LB_EVENT_HOLD_SCROLL, /*!< If the screen should be freezed */
 179         LB_EVENT_RELEASE_SCROLL, /*!< If the screen can be scrolled */
 180
 181         LB_EVENT_LB_UPDATE_BEGIN, /*!< Livebox LB content update is started */
 182         LB_EVENT_LB_UPDATE_END, /*!< Livebox LB content update is finished */
 183
 184         LB_EVENT_PD_UPDATE_BEGIN, /*!< Livebox PD content update is started */
 185         LB_EVENT_PD_UPDATE_END, /*!< Livebox PD content update is finished */
 186
 187         LB_EVENT_UPDATE_MODE_CHANGED, /*!< Livebox Update mode is changed */
 188
 189         LB_EVENT_IGNORED /*!< Request is ignored */
 190 };
 191
 192 enum livebox_fault_type {
 193         LB_FAULT_DEACTIVATED, /*!< Livebox is deactivated by its fault operation */
 194         LB_FAULT_PROVIDER_DISCONNECTED /*!< Provider is disconnected */
 195 };
 196
 197 /*!
 198  * \brief
 199  * Must be sync'd with the provider
 200  */
 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 */
 204
 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 */
 206
 207         LB_VISIBLE_ERROR = 0xFFFFFFFF /* To enlarge the size of this enumeration type */
 208 };
 209
 210 /*!
 211  * \brief
 212  * TEXT type livebox contents handling opertators.
 213  */
 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 */
 217
 218         /*!
 219          * \brief
 220          * Listed functions will be called when parser meets each typed component
 221          */
 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 };
 230
 231 /*!
 232  * \brief Prototype of the return callback of every async functions
 233  * \details N/A
 234  * \remarks N/A
 235  * \param[in] handle Handle of the livebox instance
 236  * \param[in] ret Result status of operation. LB_STATUS_XXX defined from liblivebox-service
 237  * \param[in] data data for result callback
 238  * \return void
 239  * \pre N/A
 240  * \post N/A
 241  * \see livebox_add
 242  * \see livebox_add_with_size
 243  * \see livebox_del
 244  * \see livebox_activate
 245  * \see livebox_resize
 246  * \see livebox_set_group
 247  * \see livebox_set_period
 248  * \see livebox_access_event
 249  * \see livebox_set_pinup
 250  * \see livebox_create_pd
 251  * \see livebox_create_pd_with_position
 252  * \see livebox_destroy_pd
 253  * \see livebox_emit_text_signal
 254  * \see livebox_acquire_pd_pixmap
 255  * \see livebox_acquire_lb_pixmap
 256  * \see livebox_set_update_mode
 257  */
 258 typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data);
 259
 260 /*!
 261  * \brief Initialize the livebox system
 262  * \details N/A
 263  * \remarks N/A
 264  * \param[in] disp If you have X Display connection object, you can re-use it. but you should care its life cycle.
 265  *                 It must be alive before call the livebox_fini
 266  * \return int
 267  * \retval LB_STATUS_SUCCESS if success
 268  * \pre N/A
 269  * \post N/A
 270  * \see livebox_fini
 271  */
 272 extern int livebox_init(void *disp);
 273
 274 /*!
 275  * \brief Initialize the livebox system with some options
 276  * \details livebox_init function uses environment value to initiate some configurable values
 277  *          But some application doesn't want to use the env value.
 278  *          For them, this API will give a chance to set default options using given arguments
 279  * \remarks N/A
 280  * \param[in] disp
 281  * \param[in] prevent_overwrite
 282  * \param[in] event_filter
 283  * \return int
 284  * \retval LB_STATUS_SUCCESS if success
 285  * \pre N/A
 286  * \post N/A
 287  * \see livebox_init
 288  * \see livebox_fini
 289  */
 290 extern int livebox_init_with_options(void *disp, int prevent_overwrite, double event_filter);
 291
 292 /*!
 293  * \brief Finalize the livebox system
 294  * \details N/A
 295  * \remarks N/A
 296  * \return int
 297  * \retval LB_STATUS_SUCCES if success
 298  * \retval LB_STATUS_ERROR_INVALID if livebox_init is not called.
 299  * \pre N/A
 300  * \post N/A
 301  * \see livebox_init
 302  */
 303 extern int livebox_fini(void);
 304
 305 /*!
 306  * \brief Client is paused.
 307  * \details N/A
 308  * \remarks N/A
 309  * \return int
 310  * \retval LB_STATUS_SUCCESS if success
 311  * \retval LB_STATUS_ERROR_FAULT if it failed to send state(paused) info
 312  * \pre N/A
 313  * \post N/A
 314  * \see livebox_client_resumed
 315  */
 316 extern int livebox_client_paused(void);
 317
 318 /*!
 319  * \brief Client is rfesumed.
 320  * \details N/A
 321  * \remarks N/A
 322  * \return int
 323  * \retval LB_STATUS_SUCCESS if success
 324  * \retval LB_STATUS_ERROR_FAULT if it failed to send state(resumed) info
 325  * \pre N/A
 326  * \post N/A
 327  * \see livebox_client_paused
 328  */
 329 extern int livebox_client_resumed(void);
 330
 331 /*!
 332  * \brief Add a new livebox
 333  * \details N/A
 334  * \remarks
 335  *    Even though you get the livebox handle from return value of this function,
 336  *    it is not matured before return callback called.
 337  *    You have to use the handle after get the return callback with "ret == LB_STATUS_SUCCESS"
 338  * \param[in] pkgname Livebox Id
 339  * \param[in] content Will be passed to the livebox instance.
 340  * \param[in] cluster Main group
 341  * \param[in] category Sub group
 342  * \param[in] period Update period. if you set DEFAULT_PERIOD, the provider will use the default period which is described in the manifest.
 343  * \param[in] cb After send the request to the provider, its result will be passed
 344  * \param[in] data
 345  * \return handle
 346  * \retval NULL if it fails to add a new instance
 347  * \retval handle livebox handle
 348  * \pre N/A
 349  * \post
 350  * \see ret_cb_t
 351  * \see livebox_add_with_size
 352  */
 353 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);
 354
 355 /*!
 356  * \brief Add a new livebox
 357  * \details
 358  * Normal mode livebox
 359  * 1x1=175x175
 360  * 2x1=354x175
 361  * 2x2=354x354
 362  * 4x1=712x175
 363  * 4x2=712x354
 364  * 4x4=712x712
 365  *
 366  * Extended sizes
 367  * 4x3=712x533
 368  * 4x5=712x891
 369  * 4x6=712x1070
 370  *
 371  * Easy mode livebox
 372  * 21x21=224x215
 373  * 23x21=680x215
 374  * 23x23=680x653
 375  *
 376  * Special livebox
 377  * 0x0=720x1280
 378  * \remarks
 379  *    Even if you get the handle by return value of this function, it is not created instance.
 380  *    So you have to deal it as not initialized handle.
 381  *    Only it can be initialized after get the return callback with "ret == LB_STATUS_SUCCESS".
 382  * \param[in] pkgname Livebox Id
 383  * \param[in] content Will be passed to the livebox instance.
 384  * \param[in] cluster Main group
 385  * \param[in] category Sub group
 386  * \param[in] period DEFAULT_PERIOD can be used for this. this argument will be used to specify the period of update content of livebox.
 387  * \param[in] type Size type - which are defined from liblivebox-service package.
 388  * \param[in] cb After the request is sent to the master provider, this callback will be called.
 389  * \param[in] data This data will be passed to the callback.
 390  * \return handle
 391  * \retval handle Livebox handle but not yet initialized
 392  * \retval NULL if it fails to create a handle
 393  * \see ret_cb_t
 394  * \see livebox_add
 395  */
 396 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);
 397
 398 /*!
 399  * \brief Delete a livebox
 400  * \details N/A
 401  * \remarks
 402  *    If you call this with uninitialized handle, the return callback will be called synchronously.
 403  *    So before return from this function, the return callback will be called first.
 404  * \param[in] handler Handle of a livebox instance
 405  * \param[in] cb return callback
 406  * \param[in] data user data for return callback
 407  * \return int
 408  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 409  * \retval LB_STATUS_ERROR_BUSY already in process
 410  * \retval LB_STATUS_ERROR_FAULT failed to create a request packet
 411  * \retval LB_STATUS_SUCCESS successfully sent, return callack will be called
 412  * \pre N/A
 413  * \post N/A
 414  * \see ret_cb_t
 415  */
 416 extern int livebox_del(struct livebox *handler, ret_cb_t cb, void *data);
 417
 418 /*!
 419  * \brief Set a livebox events callback
 420  * \details
 421  *    To get the events push from the provider, register the event callback using this function
 422  *    The callback will be called if there is any events from the provider.
 423  * \remarks N/A
 424  * \param[in] cb Event handler
 425  * \param[in] data User data for the event handler
 426  * \return int
 427  * \retval LB_STATUS_SUCCESS if succeed to set event handler
 428  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 429  * \retval LB_STATUS_ERROR_MEMORY Not enough memory
 430  * \pre NULL
 431  * \post NULL
 432  * \see livebox_unset_event_handler
 433  */
 434 extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data);
 435
 436 /*!
 437  * \brief Unset the livebox event handler
 438  * \details N/A
 439  * \remarks N/A
 440  * \param[in] cb
 441  * \return void *
 442  * \retval pointer of 'data' which is used with the livebox_set_event_handler
 443  * \pre N/A
 444  * \post N/A
 445  * \see livebox_set_event_handler
 446  */
 447 extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data));
 448
 449 /*!
 450  * \brief Live box fault event handler registeration function
 451  *   argument list
 452  *      event, pkgname, filename, funcname
 453  * \details N/A
 454  * \remarks N/A
 455  * \param[in] cb
 456  * \param[in] data
 457  * \return int
 458  * \retval LB_STATUS_SUCCESS if succeed to set fault event handler
 459  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 460  * \retval LB_STATUS_ERROR_MEMORY Not enough memory
 461  * \pre N/A
 462  * \post N/A
 463  * \see livebox_unset_fault_handler
 464  */
 465 extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data);
 466
 467 /*!
 468  * \brief Unset the live box fault event handler
 469  * \details N/A
 470  * \remarks N/A
 471  * \param[in] cb
 472  * \return void *
 473  * \retval pointer of 'data' which is used with the livebox_set_fault_handler
 474  * \pre N/A
 475  * \post N/A
 476  * \see livebox_set_fault_handler
 477  */
 478 extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *));
 479
 480 /*!
 481  * \brief Activate the faulted livebox.
 482  * \details
 483  *    Request result will be back via return callback.
 484  * \remarks
 485  *    Even though this function returns SUCCESS, it means just successfully sent a request to provider.
 486  *    So you have to check the return callback. and its "ret" argument.
 487  * \param[in] pkgname
 488  * \param[in] cb
 489  * \param[in] data
 490  * \return int
 491  * \retval LB_STATUS_SUCCESS Successfully sent a request
 492  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 493  * \retval LB_STATUS_ERROR_FAULT Failed to make a request
 494  * \pre N/A
 495  * \post N/A
 496  * \see ret_cb_t
 497  */
 498 extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data);
 499
 500 /*!
 501  * \brief Resize the livebox
 502  * \details
 503  * Normal mode livebox size
 504  * 1x1=175x175
 505  * 2x1=354x175
 506  * 2x2=354x354
 507  * 4x1=712x175
 508  * 4x2=712x354
 509  * 4x4=712x712
 510  *
 511  * Extended livebox size
 512  * 4x3=712x533
 513  * 4x5=712x891
 514  * 4x6=712x1070
 515  *
 516  * Easy mode livebox size
 517  * 21x21=224x215
 518  * 23x21=680x215
 519  * 23x23=680x653
 520  *
 521  * Special mode livebox size
 522  * 0x0=720x1280
 523  * \remarks
 524  *    You have to check the return callback.
 525  * \param[in] handler Handler of a livebox
 526  * \param[in] type Type of a livebox size, LB_SIZE_TYPE_1x1, ...
 527  * \param[in] cb Result callback of the resize operation.
 528  * \param[in] data User data for return callback
 529  * \return int
 530  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 531  * \retval LB_STATUS_ERROR_BUSY Previous request of resize is in progress.
 532  * \retval LB_STATUS_ERROR_ALREADY Already resized, there is no differences between current size and requested size.
 533  * \retval LB_STATUS_ERROR_PERMISSION Permission denied, you only have view the content of this box.
 534  * \retval LB_STATUS_ERROR_FAULT Failed to make a request
 535  * \pre N/A
 536  * \post N/A
 537  * \see ret_cb_t
 538  */
 539 extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data);
 540
 541 /*!
 542  * \brief Send the click event for a livebox.
 543  * \details N/A
 544  * \remarks N/A
 545  * \param[in] handler Handler of a livebox
 546  * \param[in] x Rational X of the content width.
 547  * \param[in] y Rational Y of the content height.
 548  * \return int
 549  * \retval LB_STATUS_ERROR_INVALID
 550  * \retval LB_STATUS_ERROR_FAULT
 551  * \retval LB_STATUS_SUCCESS
 552  * \pre N/A
 553  * \post N/A
 554  * \see N/A
 555  */
 556 extern int livebox_click(struct livebox *handler, double x, double y);
 557
 558 /*!
 559  * \brief Change the cluster/sub-cluster name of given livebox handler
 560  * \details N/A
 561  * \remarks N/A
 562  * \param[in] handler Handler of a livebox
 563  * \param[in] cluster New cluster of a livebox
 564  * \param[in] category New category of a livebox
 565  * \param[in] cb Result callback for changing the cluster/category of a livebox
 566  * \param[in] data User data for the result callback
 567  * \return int
 568  * \retval LB_STATUS_SUCCESS Request is successfully sent. the return callback will be called.
 569  * \retval LB_STATUS_ERROR_BUSY previous request is not finished yet.
 570  * \retval LB_STATUS_ERROR_ALREADY group name is same with current one.
 571  * \retval LB_STATUS_ERROR_PERMISSION you have no permission to change property of this livebox instance.
 572  * \retval LB_STATUS_ERROR_FAULT Failed to make a request.
 573  * \pre N/A
 574  * \post N/A
 575  * \see ret_cb_t
 576  */
 577 extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data);
 578
 579 /*!
 580  * \brief Get the cluster and category(sub-cluster) name of given livebox (It is not I18N format, only english)
 581  * \details N/A
 582  * \remarks
 583  *    You have to do not release the cluster & category.
 584  *    It is allocated inside of given livebox instance, so you can only read it.
 585  * \param[in] handler Handler of a livebox
 586  * \param[out] cluster Storage(memory) for containing the cluster name
 587  * \param[out] category Storage(memory) for containing the category name
 588  * \return int
 589  * \retval LB_STATUS_ERROR_INVALID
 590  * \retval LB_STATUS_SUCCESS
 591  * \pre N/A
 592  * \post N/A
 593  * \see N/A
 594  */
 595 extern int livebox_get_group(struct livebox *handler, char ** const cluster, char ** const category);
 596
 597 /*!
 598  * \brief Get the period of this livebox handler
 599  * \details N/A
 600  * \remarks
 601  *    if this function returns 0.0f, it means the livebox has no update period.
 602  *    or the handle is not valid.
 603  *    This function only can be works after the return callback of livebox_create fucntion is called.
 604  * \param[in] handler Handler of a livebox
 605  * \return double
 606  * \retval Current update period of a livebox
 607  * \retval 0.0f it means the box has no update period, or it can returns 0.0 if the handles is not valid.
 608  * \pre N/A
 609  * \post N/A
 610  * \see N/A
 611  */
 612 extern double livebox_period(struct livebox *handler);
 613
 614 /*!
 615  * \brief Change the update period
 616  * \details N/A
 617  * \remarks N/A
 618  * \param[in] handler Handler of a livebox
 619  * \param[in] period New update period of a livebox
 620  * \param[in] cb Result callback of changing the update period of this livebox
 621  * \param[in] data User data for the result callback
 622  * \return int
 623  * \retval LB_STATUS_SUCCESS
 624  * \retval LB_STATUS_ERROR_INVALID
 625  * \retval LB_STATUS_ERROR_BUSY
 626  * \retval LB_STATUS_ERROR_ALREADY
 627  * \retval LB_STATUS_ERROR_FAULT
 628  * \pre N/A
 629  * \post N/A
 630  * \see ret_cb_t
 631  */
 632 extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data);
 633
 634 /*!
 635  * \brief Is this an text type livebox?
 636  * \details N/A
 637  * \remarks N/A
 638  * \param[in] handler
 639  * \return livebox_lb_type
 640  * \retval LB_TYPE_IMAGE Contents of a livebox is based on the image file
 641  * \retval LB_TYPE_BUFFER Contents of a livebox is based on canvas buffer(shared)
 642  * \retval LB_TYPE_TEXT Contents of a livebox is based on formatted text file
 643  * \retval LB_TYPE_PIXMAP Contens of a livebox is shared by the pixmap(depends on X)
 644  * \retval LB_TYPE_INVALID
 645  * \pre N/A
 646  * \post N/A
 647  * \see livebox_lb_type
 648  */
 649 extern enum livebox_lb_type livebox_lb_type(struct livebox *handler);
 650
 651 /*!
 652  * \brief Is this livebox is created by a user?
 653  * \details
 654  *    If the livebox instance is created by system this will returns 0.
 655  * \remarks N/A
 656  * \param[in] handler
 657  * \return int
 658  * \retval LB_STATUS_ERROR_INVALID Invalid argument
 659  * \retval 0 automatically created livebox by the provider
 660  * \retval 1 created by user via livebox_add or livebox_add_with_size
 661  * \pre N/A
 662  * \post N/A
 663  * \see livebox_add
 664  * \see livebox_add_with_size
 665  * \see livebox_set_event_handler
 666  */
 667 extern int livebox_is_user(struct livebox *handler);
 668
 669 /*!
 670  * \brief Get the content information string of given livebox
 671  * \details N/A
 672  * \remarks N/A
 673  * \param[in] handler
 674  * \return char *
 675  * \retval content_info Livebox content info that can be used again via content_info argument of livebox_add or livebox_add_with_size.
 676  * \pre N/A
 677  * \post N/A
 678  * \see livebox_add
 679  * \see livebox_add_with_size
 680  */
 681 extern const char *livebox_content(struct livebox *handler);
 682
 683 /*!
 684  * \brief Get the sub cluster title string of given livebox
 685  * \details N/A
 686  * \remarks N/A
 687  * \param[in] handler
 688  * \return const char *
 689  * \retval sub cluster name
 690  * \retval NULL
 691  * \pre N/A
 692  * \post N/A
 693  * \see N/A
 694  */
 695 extern const char *livebox_category_title(struct livebox *handler);
 696
 697 /*!
 698  * \brief Get the filename of given livebox, if it is an IMAGE type livebox
 699  * \details N/A
 700  * \remarks N/A
 701  * \param[in] handler
 702  * \return const char *
 703  * \retval filename if the livebox type is image this function will give you a abspath of an image file (content is rendered)
 704  * \retval NULL if this has no image file or type is not image file.
 705  * \pre N/A
 706  * \post N/A
 707  * \see N/A
 708  */
 709 extern const char *livebox_filename(struct livebox *handler);
 710
 711 /*!
 712  * \brief Get the package name of given livebox handler
 713  * \details N/A
 714  * \remarks N/A
 715  * \param[in] handler
 716  * \return const char *
 717  * \retval pkgname package name
 718  * \retval NULL if the handler is not valid
 719  * \pre N/A
 720  * \post N/A
 721  * \see N/A
 722  */
 723 extern const char *livebox_pkgname(struct livebox *handler);
 724
 725 /*!
 726  * \brief Get the priority of a current content.
 727  * \details N/A
 728  * \remarks N/A
 729  * \param[in] handler
 730  * \return double
 731  * \retval 0.0f handler is NULL
 732  * \retval -1.0f Handler is not valid (not yet initialized)
 733  * \retval real number between 0.0 and 1.0
 734  * \pre N/A
 735  * \post N/A
 736  * \see N/A
 737  */
 738 extern double livebox_priority(struct livebox *handler);
 739
 740 /*!
 741  * \brief Acquire the buffer of given livebox (Only for the buffer type)
 742  * \details N/A
 743  * \remarks N/A
 744  * \param[in] handler
 745  * \return void *
 746  * \retval address of a FB
 747  * \retval NULL if it fails to get fb address
 748  * \pre N/A
 749  * \post N/A
 750  * \see N/A
 751  */
 752 extern void *livebox_acquire_fb(struct livebox *handler);
 753
 754 /*!
 755  * \brief Release the buffer of a livebox (Only for the buffer type)
 756  * \details N/A
 757  * \remarks N/A
 758  * \param[in] buffer
 759  * \return int
 760  * \retval LB_STATUS_ERROR_INVALID
 761  * \retval LB_STATUS_SUCCESS
 762  * \pre N/A
 763  * \post N/A
 764  * \see livebox_acquire_fb
 765  */
 766 extern int livebox_release_fb(void *buffer);
 767
 768 /*!
 769  * \brief Get the reference count of Livebox buffer (Only for the buffer type)
 770  * \details N/A
 771  * \remarks N/A
 772  * \param[in] buffer
 773  * \return int
 774  * \retval LB_STATUS_ERROR_INVALID
 775  * \retval LB_STATUS_ERROR_FAULT
 776  * \retval refcnt positive integer including ZERO
 777  * \pre N/A
 778  * \post N/A
 779  * \see livebox_pdfb_refcnt
 780  */
 781 extern int livebox_fb_refcnt(void *buffer);
 782
 783 /*!
 784  * \brief Acquire the buffer of a PD frame (Only for the buffer type)
 785  * \details N/A
 786  * \remarks N/A
 787  * \param[in] handler
 788  * \return int
 789  * \retval NULL
 790  * \retval adress of buffer of PD
 791  * \pre N/A
 792  * \post N/A
 793  * \see livebox_release_pdfb
 794  */
 795 extern void *livebox_acquire_pdfb(struct livebox *handler);
 796
 797 /*!
 798  * \brief Release the acquired buffer of the PD Frame (Only for the buffer type)
 799  * \details N/A
 800  * \remarks N/A
 801  * \param[in] buffer
 802  * \return int
 803  * \retval LB_STATUS_ERROR_INVALID
 804  * \retval LB_STATUS_SUCCESS
 805  * \pre N/A
 806  * \post N/A
 807  * \see livebox_acquire_pdfb
 808  */
 809 extern int livebox_release_pdfb(void *buffer);
 810
 811 /*!
 812  * \brief Reference count of given PD buffer (Only for the buffer type)
 813  * \details N/A
 814  * \remarks N/A
 815  * \param[in] buffer
 816  * \return int
 817  * \retval LB_STATUS_ERROR_INVALID
 818  * \retval LB_STATUS_ERROR_FAULT
 819  * \retval reference count
 820  * \pre N/A
 821  * \post N/A
 822  * \see livebox_fb_refcnt
 823  */
 824 extern int livebox_pdfb_refcnt(void *buffer);
 825
 826 /*!
 827  * \brief Get the size of the Livebox
 828  * \details N/A
 829  * \remarks N/A
 830  * \param[in] handler
 831  * \return int
 832  * \retval LB_SIZE_TYPE_NxM
 833  * \retval LB_SIZE_TYPE_INVALID
 834  * \pre N/A
 835  * \post N/A
 836  * \see N/A
 837  */
 838 extern int livebox_size(struct livebox *handler);
 839
 840 /*!
 841  * \brief Get the size of the Progressive Disclosure
 842  * \details N/A
 843  * \remarks N/A
 844  * \param[in] handler
 845  * \param[out] w
 846  * \param[out] h
 847  * \return int
 848  * \retval LB_STATUS_ERROR_INVALID
 849  * \retval LB_STATUS_SUCCESS
 850  * \pre N/A
 851  * \post N/A
 852  * \see N/A
 853  */
 854 extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h);
 855
 856 /*!
 857  * \brief List of supported sizes of given handler
 858  * \details N/A
 859  * \remarks N/A
 860  * \param[in] handler
 861  * \param[out] cnt
 862  * \param[out] size_list
 863  * \return int
 864  * \retval LB_STATUS_ERROR_INVALID
 865  * \retval LB_STATUS_SUCCESS
 866  * \pre N/A
 867  * \post N/A
 868  * \see N/A
 869  */
 870 extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list);
 871
 872 /*!
 873  * \brief BUFFER SIZE of the livebox if it is a buffer type
 874  * \details N/A
 875  * \remarks N/A
 876  * \param[in] handler
 877  * \return int
 878  * \retval LB_STATUS_ERROR_INVALID
 879  * \retval size of livebox buffer
 880  * \pre N/A
 881  * \post N/A
 882  * \see N/A
 883  */
 884 extern int livebox_lbfb_bufsz(struct livebox *handler);
 885
 886 /*!
 887  * \brief BUFFER SIZE of the progiressive disclosure if it is a buffer type
 888  * \details N/A
 889  * \remarks N/A
 890  * \param[in] handler
 891  * \return int
 892  * \retval LB_STATUS_ERROR_INVALID
 893  * \retval size of PD buffer
 894  * \pre N/A
 895  * \post N/A
 896  * \see N/A
 897  */
 898 extern int livebox_pdfb_bufsz(struct livebox *handler);
 899
 900 /*!
 901  * \brief Send the content event (for buffer type) to provider(livebox)
 902  * \details N/A
 903  * \remarks N/A
 904  * \param[in] handler
 905  * \param[in] type
 906  * \param[in] x
 907  * \param[in] y
 908  * \return int
 909  * \retval LB_STATUS_ERROR_INVALID
 910  * \retval LB_STATUS_ERROR_BUSY
 911  * \retval LB_STATUS_ERROR_FAULT
 912  * \retval LB_STATUS_SUCCESS
 913  * \pre N/A
 914  * \post N/A
 915  * \see livebox_access_event
 916  */
 917 extern int livebox_content_event(struct livebox *handler, enum content_event_type type, double x, double y);
 918
 919 /*!
 920  * \brief Send the access event(for buffer type) to provider(livebox).
 921  * \details N/A
 922  * \remarks N/A
 923  * \param[in] handler
 924  * \param[in] type
 925  * \param[in] x
 926  * \param[in] y
 927  * \param[in] cb
 928  * \param[in] data
 929  * \return int
 930  * \retval LB_STATUS_ERROR_INVALID
 931  * \retval LB_STATUS_ERROR_BUSY
 932  * \retval LB_STATUS_ERROR_FAULT
 933  * \retval LB_STATUS_SUCCESS
 934  * \pre N/A
 935  * \post N/A
 936  * \see livebox_content_event
 937  */
 938 extern int livebox_access_event(struct livebox *handler, enum access_event_type type, double x, double y, ret_cb_t cb, void *data);
 939
 940 /*!
 941  * \brief Do pin up or not.
 942  * \details N/A
 943  * \remarks N/A
 944  * \param[in] handler
 945  * \param[in] flag
 946  * \param[in] cb
 947  * \param[in] data
 948  * \return int
 949  * \retval LB_STATUS_ERROR_INVALID
 950  * \retval 1 box is pinned up
 951  * \retval 0 box is not pinned up
 952  * \see ret_cb_t
 953  */
 954 extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data);
 955
 956 /*!
 957  * \brief Check the PIN-UP status of given handler
 958  * \details N/A
 959  * \remarks N/A
 960  * \param[in] handler
 961  * \return int
 962  */
 963 extern int livebox_is_pinned_up(struct livebox *handler);
 964
 965 /*!
 966  * \brief Check the PINUP feature availability of the given handler
 967  * \details N/A
 968  * \remarks N/A
 969  * \param[in] handler
 970  * \return int
 971  * \retval LB_STATUS_ERROR_INVALID
 972  * \retval 1 if the box support Pinup feature
 973  * \retval 0 if the box does not support the Pinup feature
 974  * \pre N/A
 975  * \post N/A
 976  * \see N/A
 977  */
 978 extern int livebox_has_pinup(struct livebox *handler);
 979
 980 /*!
 981  * \brief Check the PD existence of given handler
 982  * \details N/A
 983  * \remarks N/A
 984  * \param[in] handler
 985  * \return int
 986  * \retval LB_STATUS_ERROR_INVALID
 987  * \retval 1 if the box support the PD
 988  * \retval 0 if the box has no PD
 989  * \pre N/A
 990  * \post N/A
 991  * \see N/A
 992  */
 993 extern int livebox_has_pd(struct livebox *handler);
 994
 995 /*!
 996  * \brief Create the PD of given handler
 997  * \details N/A
 998  * \remarks N/A
 999  * \param[in] handler
1000  * \param[in] cb
1001  * \param[in] data
1002  * \return int
1003  * \retval LB_STATUS_SUCCESS
1004  * \retval LB_STATUS_ERROR_INVALID
1005  * \retval LB_STATUS_ERROR_BUSY
1006  * \retval LB_STATUS_ERROR_FAULT
1007  * \pre N/A
1008  * \post N/A
1009  * \see ret_cb_t
1010  */
1011 extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data);
1012
1013 /*!
1014  * \brief Create the PD of given handler with the relative position from livebox
1015  * \details N/A
1016  * \remarks N/A
1017  * \param[in] handler
1018  * \param[in] x 0.0 ~ 1.0
1019  * \param[in] y 0.0 ~ 1.0
1020  * \param[in] cb
1021  * \param[in] data
1022  * \return int
1023  * \retval LB_STATUS_SUCCESS
1024  * \retval LB_STATUS_ERROR_INVALID
1025  * \retval LB_STATUS_ERROR_BUSY
1026  * \retval LB_STATUS_ERROR_FAULT
1027  * \pre N/A
1028  * \post N/A
1029  * \see N/A
1030  */
1031 extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data);
1032
1033 /*!
1034  * \brief PD position is updated.
1035  * \details N/A
1036  * \remarks N/A
1037  * \param[in] handler
1038  * \param[in] x 0.0 ~ 1.0
1039  * \param[in] y 0.0 ~ 1.0
1040  * \return int
1041  * \retval LB_STATUS_SUCCESS if succeed to send request for updating position of the PD.
1042  * \retval LB_STATUS_ERROR_FAULT
1043  * \retval LB_STATUS_ERROR_INVALID
1044  * \pre N/A
1045  * \post N/A
1046  * \see N/A
1047  */
1048 extern int livebox_move_pd(struct livebox *handler, double x, double y);
1049
1050 /*!
1051  * \brief Destroy the PD of given handler if it is created.
1052  * \details N/A
1053  * \remarks N/A
1054  * \param[in] handler
1055  * \param[in] cb
1056  * \param[in] data
1057  * \return int
1058  * \retval LB_STATUS_ERROR_INVALID
1059  * \retval LB_STATUS_ERROR_FAULT
1060  * \retval LB_STATUS_SUCCESS
1061  * \pre N/A
1062  * \post N/A
1063  * \see ret_cb_t
1064  */
1065 extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data);
1066
1067 /*!
1068  * \brief Check the create status of given livebox handler
1069  * \details N/A
1070  * \remarks N/A
1071  * \param[in] handler
1072  * \return int
1073  * \retval LB_STATUS_ERROR_INVALID
1074  * \retval 0 PD is not created
1075  * \retval 1 PD is created
1076  */
1077 extern int livebox_pd_is_created(struct livebox *handler);
1078
1079 /*!
1080  * \brief Check the content type of the progressive disclosure of given handler
1081  * \details N/A
1082  * \remarks N/A
1083  * \param[in] handler
1084  * \return int
1085  * \retval PD_TYPE_BUFFER Contents of a PD is based on canvas buffer(shared)
1086  * \retval PD_TYPE_TEXT Contents of a PD is based on formatted text file
1087  * \retval PD_TYPE_PIXMAP Contents of a livebox is shared by the pixmap(depends on X)
1088  * \retval PD_TYPE_INVALID
1089  * \pre N/A
1090  * \post N/A
1091  * \see livebox_pd_type
1092  */
1093 extern enum livebox_pd_type livebox_pd_type(struct livebox *handler);
1094
1095 /*!
1096  * \brief Check the existence of a livebox about given package name
1097  * \details N/A
1098  * \remarks N/A
1099  * \param[in] pkgname
1100  * \return int
1101  * \retval 1 if the box is exists
1102  * \retval 0 if the box is not exists
1103  * \pre N/A
1104  * \post N/A
1105  * \see N/A
1106  */
1107 extern int livebox_is_exists(const char *pkgname);
1108
1109 /*!
1110  * \brief Set function table for parsing the text content of a livebox
1111  * \details N/A
1112  * \remarks N/A
1113  * \param[in] handler
1114  * \param[in] ops
1115  * \return int
1116  * \retval LB_STATUS_SUCCESS
1117  * \retval LB_STATUS_ERROR_INVALID
1118  * \see livebox_set_pd_text_handler
1119  */
1120 extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1121
1122 /*!
1123  * \brief Set function table for parsing the text content of a Progressive Disclosure
1124  * \details N/A
1125  * \remarks N/A
1126  * \param[in] handler
1127  * \param[in] ops
1128  * \return int
1129  * \retval LB_STATUS_SUCCESS
1130  * \retval LB_STATUS_ERROR_INVALID
1131  * \see livebox_set_text_handler
1132  */
1133 extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1134
1135 /*!
1136  * \brief Emit a text signal to given livebox only if it is a text type.
1137  * \details N/A
1138  * \remarks N/A
1139  * \param[in] handler
1140  * \param[in] emission
1141  * \param[in] source
1142  * \param[in] sx
1143  * \param[in] sy
1144  * \param[in] ex
1145  * \param[in] ey
1146  * \param[in] cb
1147  * \param[in] data
1148  * \return int
1149  * \retval LB_STATUS_ERROR_INVALID
1150  * \retval LB_STATUS_ERROR_FAULT
1151  * \retval LB_STATUS_SUCCESS
1152  * \see ret_cb_t
1153  */
1154 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);
1155
1156 /*!
1157  * \brief Set a private data pointer to carry it using given handler
1158  * \details N/A
1159  * \remarks N/A
1160  * \param[in] handler
1161  * \param[in] data
1162  * \return int
1163  * \retval LB_STATUS_SUCCESS
1164  * \retval LB_STATUS_ERROR_INVALID
1165  * \pre N/A
1166  * \post N/A
1167  * \see livebox_get_data
1168  */
1169 extern int livebox_set_data(struct livebox *handler, void *data);
1170
1171 /*!
1172  * \brief Get private data pointer which is carried by given handler
1173  * \details N/A
1174  * \remarks N/A
1175  * \param[in] handler
1176  * \return void *
1177  * \retval data pointer
1178  * \pre N/A
1179  * \post N/A
1180  * \see livebox_set_data
1181  */
1182 extern void *livebox_get_data(struct livebox *handler);
1183
1184 /*!
1185  * \brief Subscribe the event for liveboxes only in given cluster and sub-cluster
1186  * \details N/A
1187  * \remarks N/A
1188  * \param[in] cluster   "*" can be used for subscribe all cluster's liveboxes event.
1189  *                      If you use the "*", value in the category will be ignored.
1190  * \param[in] category  "*" can be used for subscribe liveboxes events of all category(sub-cluster) in given "cluster"
1191  * \return int
1192  * \retval LB_STATUS_ERROR_FAULT
1193  * \retval LB_STATUS_SUCCESS
1194  * \pre N/A
1195  * \post N/A
1196  * \see livebox_unsubscribe_group
1197  */
1198 extern int livebox_subscribe_group(const char *cluster, const char *category);
1199
1200 /*!
1201  * \brief Unsubscribe the event for the liveboxes, but you will receive already added liveboxes event.
1202  * \details N/A
1203  * \remarks N/A
1204  * \param[in] cluster   "*" can be used for subscribe all cluster's liveboxes event.
1205  *                      If you use the "*", value in the category will be ignored.
1206  * \param[in] category  "*" can be used for subscribe all sub-cluster's liveboxes event in given "cluster"
1207  * \return int
1208  * \retval LB_STATUS_ERROR_FAULT
1209  * \retval LB_STATUS_SUCCESS
1210  * \pre N/A
1211  * \post N/A
1212  * \see livebox_subscribe_group
1213  */
1214 extern int livebox_unsubscribe_group(const char *cluster, const char *category);
1215
1216 /*!
1217  * \brief Refresh the group(cluster/sub-cluser(aka. category))
1218  * \details N/A
1219  * \remarks N/A
1220  * \param[in] cluster Cluster ID
1221  * \param[in] category Sub-cluster ID
1222  * \return int
1223  * \retval LB_STATUS_ERROR_INVALID
1224  * \retval LB_STATUS_ERROR_FAULT
1225  * \retval LB_STATUS_SUCCESS
1226  * \pre N/A
1227  * \post N/A
1228  * \see N/A
1229  */
1230 extern int livebox_refresh_group(const char *cluster, const char *category);
1231
1232 /*!
1233  * \brief Refresh a livebox
1234  * \details N/A
1235  * \remarks N/A
1236  * \param[in] handler
1237  * \return int
1238  * \retval LB_STATUS_ERROR_INVALID
1239  * \retval LB_STATUS_ERROR_FAULT
1240  * \retval LB_STATUS_SUCCESS
1241  * \pre N/A
1242  * \post N/A
1243  * \see N/A
1244  */
1245 extern int livebox_refresh(struct livebox *handler);
1246
1247 /*!
1248  * \brief Pixmap Id of a livebox content
1249  * \details N/A
1250  * \remarks N/A
1251  * \param[in] handler
1252  * \return int
1253  * \retval 0 if the pixmap is not created
1254  * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
1255  * \pre N/A
1256  * \post N/A
1257  * \see livebox_pd_pixmap
1258  */
1259 extern int livebox_lb_pixmap(const struct livebox *handler);
1260
1261 /*!
1262  * \brief Pixmap Id of a PD content
1263  * \details N/A
1264  * \remarks N/A
1265  * \param[in] handler
1266  * \return int
1267  * \retval 0 if the pixmap is not created
1268  * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
1269  * \pre N/A
1270  * \post N/A
1271  * \see livebox_lb_pixmap
1272  */
1273 extern int livebox_pd_pixmap(const struct livebox *handler);
1274
1275 /*!
1276  * \brief
1277  * \details N/A
1278  * \remarks N/A
1279  * \param[in] handler
1280  * \param[in] cb
1281  * \param[in] data
1282  * \return int
1283  * \retval LB_STATUS_ERROR_INVALID
1284  * \retval LB_STATUS_ERROR_FAULT
1285  * \retval LB_STATUS_SUCCESS
1286  * \pre N/A
1287  * \post N/A
1288  * \see livebox_release_pd_pixmap
1289  * \see livebox_acquire_lb_pixmap
1290  * \see ret_cb_t
1291  */
1292 extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1293
1294 /*!
1295  * \brief Release the acquired pixmap ID
1296  * \details N/A
1297  * \remarks N/A
1298  * \param[in] handler
1299  * \param[in] pixmap
1300  * \return int
1301  * \retval LB_STATUS_ERROR_INVALID
1302  * \retval LB_STATUS_ERROR_FAULT
1303  * \retval LB_STATUS_SUCCESS
1304  * \pre N/A
1305  * \post N/A
1306  * \see livebox_acquire_pd_pixmap
1307  * \see livebox_release_lb_pixmap
1308  */
1309 extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap);
1310
1311 /*!
1312  * \brief
1313  * \details N/A
1314  * \remarks N/A
1315  * \param[in] handler
1316  * \param[in] cb
1317  * \param[in] data
1318  * \return int
1319  * \retval LB_STATUS_ERROR_INVALID
1320  * \retval LB_STATUS_ERROR_FAULT
1321  * \retval LB_STATUS_SUCCESS
1322  * \pre N/A
1323  * \post N/A
1324  * \see livebox_release_lb_pixmap
1325  * \see livebox_acquire_pd_pixmap
1326  * \see ret_cb_t
1327  */
1328 extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1329
1330 /*!
1331  * \brief
1332  * \details N/A
1333  * \remarks N/A
1334  * \param[in] handler
1335  * \param[in] pixmap
1336  * \return int
1337  * \retval LB_STATUS_ERROR_INVALID
1338  * \retval LB_STATUS_ERROR_FAULT
1339  * \retval LB_STATUS_SUCCESS
1340  * \pre N/A
1341  * \post N/A
1342  * \see livebox_acquire_lb_pixmap
1343  * \see livebox_release_pd_pixmap
1344  */
1345 extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap);
1346
1347 /*!
1348  * \brief Update the visible state of a livebox
1349  * \details N/A
1350  * \remarks N/A
1351  * \param[in] handler Handler of a livebox
1352  * \param[in] state Configure the current visible state of a livebox
1353  * \return int
1354  * \retval LB_STATUS_ERROR_INVALID
1355  * \retval LB_STATUS_ERROR_BUSY
1356  * \retval LB_STATUS_ERROR_PERMISSION
1357  * \retval LB_STATUS_ERROR_ALREADY
1358  * \retval LB_STATUS_ERROR_FAULT
1359  * \retval LB_STATUS_SUCCESS
1360  * \pre N/A
1361  * \post N/A
1362  * \see N/A
1363  */
1364 extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state);
1365
1366 /*!
1367  * \brief Current visible state of a livebox
1368  * \details N/A
1369  * \remarks N/A
1370  * \param[in] handler Handler of a livebox
1371  * \return livebox_visible_state
1372  * \retval LB_SHOW Livebox is showed. Default state
1373  * \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
1374  * \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
1375  * \retval LB_VISIBLE_ERROR To enlarge the size of this enumeration type
1376  * \pre N/A
1377  * \post N/A
1378  * \see N/A
1379  */
1380 extern enum livebox_visible_state livebox_visibility(struct livebox *handler);
1381
1382 /*!
1383  * \brief Set the update mode of current livebox
1384  * \details N/A
1385  * \remarks N/A
1386  *        if you set 1 for active update mode, you should get buffer without updated event from provider.
1387  *        But is passive mode, you have to update content of a box when you get updated event.
1388  *        Default is Passive mode.
1389  * \param[in] handler Handler of a livebox
1390  * \param[in] active_update 1 means active update, 0 means passive update (default)
1391  * \param[in] cb Result callback function
1392  * \param[in] data Callback data
1393  * \return int
1394  * \retval LB_STATUS_ERROR_INVALID
1395  * \retval LB_STATUS_ERROR_BUSY
1396  * \retval LB_STATUS_ERROR_PERMISSION
1397  * \retval LB_STATUS_ERROR_ALREADY
1398  * \retval LB_STATUS_ERROR_FAULT
1399  * \retval LB_STATUS_SUCCESS
1400  * \see ret_cb_t
1401  */
1402 extern int livebox_set_update_mode(struct livebox *handler, int active_update, ret_cb_t cb, void *data);
1403
1404 /*!
1405  * \brief Is this box in the active update mode?
1406  * \details N/A
1407  * \remarks N/A
1408  * \param[in] handler HAndler of a livebox
1409  * \return int
1410  * \retval 0 if passive mode
1411  * \retval 1 if active mode or error code
1412  * \see N/A
1413  */
1414 extern int livebox_is_active_update(struct livebox *handler);
1415
1416 extern void livebox_set_manual_sync(int flag);
1417
1418 extern int livebox_manual_sync(void);
1419
1420 extern void livebox_set_frame_drop_for_resizing(int flag);
1421
1422 extern int livebox_frame_drop_for_resizing(void);
1423
1424 extern int livebox_sync_pd_fb(struct livebox *handler);
1425
1426 extern int livebox_sync_lb_fb(struct livebox *handler);
1427
1428 /*!
1429  * \}
1430  */
1431
1432 #ifdef __cplusplus
1433 }
1434 #endif
1435
1436 #endif