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