livebox-viewer/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  * @file livebox.h
  26  * @brief This file declares API of liblivebox-viewer library
  27  */
  28
  29 /**
  30  * @addtogroup CAPI_LIVEBOX_VIEWER_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief
  36  * Structure for a Livebox instance.
  37  */
  38 struct livebox;
  39
  40 /**
  41  * @brief Definition for a default update period for Livebox (defined in the package manifest file).
  42  */
  43 #define DEFAULT_PERIOD -1.0f
  44
  45 /**
  46  * @brief Enumeration for Mouse & Key event for buffer type Livebox or PD.
  47  * @details Viewer should send these events to livebox.
  48  */
  49 enum content_event_type {
  50         CONTENT_EVENT_MOUSE_DOWN        = 0x00000001, /**< LB mouse down event for livebox */
  51         CONTENT_EVENT_MOUSE_UP          = 0x00000002, /**< LB mouse up event for livebox */
  52         CONTENT_EVENT_MOUSE_MOVE        = 0x00000004, /**< LB mouse move event for livebox */
  53         CONTENT_EVENT_MOUSE_ENTER       = 0x00000008, /**< LB mouse enter event for livebox */
  54         CONTENT_EVENT_MOUSE_LEAVE       = 0x00000010, /**< LB mouse leave event for livebox */
  55         CONTENT_EVENT_MOUSE_SET         = 0x00000020, /**< LB mouse set auto event for livebox */
  56         CONTENT_EVENT_MOUSE_UNSET       = 0x00000040, /**< LB mouse unset auto event for livebox */
  57
  58         CONTENT_EVENT_KEY_DOWN          = 0x00000001, /**< LB key press */
  59         CONTENT_EVENT_KEY_UP            = 0x00000002, /**< LB key release */
  60         CONTENT_EVENT_KEY_FOCUS_IN      = 0x00000008, /**< LB key focused in */
  61         CONTENT_EVENT_KEY_FOCUS_OUT     = 0x00000010, /**< LB key focused out */
  62         CONTENT_EVENT_KEY_SET           = 0x00000020, /**< LB Key, start feeding event by master */
  63         CONTENT_EVENT_KEY_UNSET         = 0x00000040, /**< LB key, stop feeding event by master */
  64
  65         CONTENT_EVENT_ON_SCROLL         = 0x00000080, /**< LB On scrolling */
  66         CONTENT_EVENT_ON_HOLD           = 0x00000100, /**< LB On holding */
  67         CONTENT_EVENT_OFF_SCROLL        = 0x00000200, /**< LB Stop scrolling */
  68         CONTENT_EVENT_OFF_HOLD          = 0x00000400, /**< LB Stop holding */
  69
  70         CONTENT_EVENT_KEY_MASK          = 0x80000000, /**< Mask value for key event */
  71         CONTENT_EVENT_MOUSE_MASK        = 0x20000000, /**< Mask value for mouse event */
  72         CONTENT_EVENT_PD_MASK           = 0x10000000, /**< Mask value for PD event */
  73         CONTENT_EVENT_LB_MASK           = 0x40000000, /**< Mask value for LB event */
  74
  75         LB_MOUSE_ON_SCROLL              = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_ON_SCROLL, /**< Mouse event occurs while scrolling */
  76         LB_MOUSE_ON_HOLD                = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_ON_HOLD, /**< Mouse event occurs on holding */
  77         LB_MOUSE_OFF_SCROLL             = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_OFF_SCROLL, /**< Scrolling stopped */
  78         LB_MOUSE_OFF_HOLD               = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_OFF_HOLD, /**< Holding stopped */
  79
  80         LB_MOUSE_DOWN                   = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /**< Mouse down on the livebox */
  81         LB_MOUSE_UP                     = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /**< Mouse up on the livebox */
  82         LB_MOUSE_MOVE                   = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /**< Move move on the livebox */
  83         LB_MOUSE_ENTER                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /**< Mouse enter to the livebox */
  84         LB_MOUSE_LEAVE                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /**< Mouse leave from the livebox */
  85         LB_MOUSE_SET                    = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET, /**< Mouse event, start feeding event by master */
  86         LB_MOUSE_UNSET                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET, /**< Mouse event, stop feeding event by master */
  87
  88         PD_MOUSE_ON_SCROLL              = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_ON_SCROLL, /**< Mouse event occurs while scrolling */
  89         PD_MOUSE_ON_HOLD                = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_ON_HOLD, /**< Mouse event occurs on holding */
  90         PD_MOUSE_OFF_SCROLL             = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_OFF_SCROLL, /**< Scrolling stopped */
  91         PD_MOUSE_OFF_HOLD               = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_OFF_HOLD, /**< Holding stopped */
  92
  93         PD_MOUSE_DOWN                   = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /**< Mouse down on the PD */
  94         PD_MOUSE_UP                     = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /**< Mouse up on the PD */
  95         PD_MOUSE_MOVE                   = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /**< Mouse move on the PD */
  96         PD_MOUSE_ENTER                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /**< Mouse enter to the PD */
  97         PD_MOUSE_LEAVE                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /**< Mouse leave from the PD */
  98         PD_MOUSE_SET                    = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET, /**< Mouse event, start feeding event by master */
  99         PD_MOUSE_UNSET                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET, /**< Mouse event, stop feeding event by master */
 100
 101         LB_KEY_DOWN                     = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /**< Key down on the livebox */
 102         LB_KEY_UP                       = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /**< Key up on the livebox */
 103         LB_KEY_SET                      = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_SET, /**< Key event, start feeding event by master */
 104         LB_KEY_UNSET                    = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UNSET, /**< Key event, stop feeding event by master */
 105         LB_KEY_FOCUS_IN                 = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_IN, /**< Key event, focus in */
 106         LB_KEY_FOCUS_OUT                = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_OUT, /**< Key event, foucs out */
 107
 108         PD_KEY_DOWN                     = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /**< Key down on the livebox */
 109         PD_KEY_UP                       = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /**< Key up on the livebox */
 110         PD_KEY_SET                      = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_SET, /**< Key event, start feeding event by master */
 111         PD_KEY_UNSET                    = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UNSET, /**< Key event, stop feeding event by master */
 112         PD_KEY_FOCUS_IN                 = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_IN, /**< Key event, focus in */
 113         PD_KEY_FOCUS_OUT                = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_FOCUS_OUT, /**< Key event, focus out */
 114
 115         CONTENT_EVENT_MAX               = 0xFFFFFFFF /**< Unknown event */
 116 };
 117
 118 /**
 119  * @brief Enumeration for Accessibility event for buffer type Livebox or PD.
 120  * @details These events are sync'd with Tizen accessibility event set.
 121  */
 122 enum access_event_type {
 123         ACCESS_EVENT_PD_MASK            = 0x10000000, /**< PD Accessibility event mask */
 124         ACCESS_EVENT_LB_MASK            = 0x20000000, /**< LB Accessibility event mask */
 125
 126         ACCESS_EVENT_HIGHLIGHT          = 0x00000100, /**< LB accessibility: Hightlight a object */
 127         ACCESS_EVENT_HIGHLIGHT_NEXT     = 0x00000200, /**< LB accessibility: Set highlight to next object */
 128         ACCESS_EVENT_HIGHLIGHT_PREV     = 0x00000400, /**< LB accessibility: Set highlight to prev object */
 129         ACCESS_EVENT_UNHIGHLIGHT        = 0x00000800, /**< LB accessibility unhighlight */
 130         ACCESS_EVENT_ACTIVATE           = 0x00001000, /**< LB accessibility activate */
 131         ACCESS_EVENT_ACTION_DOWN        = 0x00010000, /**< LB accessibility value changed */
 132         ACCESS_EVENT_ACTION_UP          = 0x00020000, /**< LB accessibility value changed */
 133         ACCESS_EVENT_SCROLL_DOWN        = 0x00100000, /**< LB accessibility scroll down */
 134         ACCESS_EVENT_SCROLL_MOVE        = 0x00200000, /**< LB accessibility scroll move */
 135         ACCESS_EVENT_SCROLL_UP          = 0x00400000, /**< LB accessibility scroll up */
 136
 137         LB_ACCESS_HIGHLIGHT             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT,        /**< Access event - Highlight an object in the livebox */
 138         LB_ACCESS_HIGHLIGHT_NEXT        = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT,   /**< Access event - Move highlight to the next object in a livebox */
 139         LB_ACCESS_HIGHLIGHT_PREV        = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_PREV,   /**< Access event - Move highlight to the prev object in a livebox */
 140         LB_ACCESS_UNHIGHLIGHT           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_UNHIGHLIGHT,      /**< Access event - Delete highlight from the livebox */
 141         LB_ACCESS_ACTIVATE              = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTIVATE,         /**< Access event - Launch or activate the highlighted object */
 142         LB_ACCESS_ACTION_DOWN           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_DOWN,      /**< Access event - down */
 143         LB_ACCESS_ACTION_UP             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_UP,        /**< Access event - up */
 144         LB_ACCESS_SCROLL_DOWN           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_DOWN,      /**< Access event - scroll down */
 145         LB_ACCESS_SCROLL_MOVE           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_MOVE,      /**< Access event - scroll move */
 146         LB_ACCESS_SCROLL_UP             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_UP,        /**< Access event - scroll up */
 147
 148         PD_ACCESS_HIGHLIGHT             = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT,        /**< Access event - Highlight an object in the PD */
 149         PD_ACCESS_HIGHLIGHT_NEXT        = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT,   /**< Access event - Move highlight to the next object in a PD */
 150         PD_ACCESS_HIGHLIGHT_PREV        = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_PREV,   /**< Access event - Move highlight to the prev object in a PD */
 151         PD_ACCESS_UNHIGHLIGHT           = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_UNHIGHLIGHT,      /**< Access event - Delet highlight from the PD */
 152         PD_ACCESS_ACTIVATE              = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTIVATE,         /**< Access event - Launch or activate the highlighted object */
 153         PD_ACCESS_ACTION_DOWN           = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTION_DOWN,      /**< Access event - down */
 154         PD_ACCESS_ACTION_UP             = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_ACTION_UP,        /**< Access event - up */
 155         PD_ACCESS_SCROLL_DOWN           = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_DOWN,      /**< Access event - scroll down */
 156         PD_ACCESS_SCROLL_MOVE           = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_MOVE,      /**< Access event - scroll move */
 157         PD_ACCESS_SCROLL_UP             = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_UP         /**< Access event - scroll up */
 158 };
 159
 160 /**
 161  * @brief Enumeration for Livebox LB content type.
 162  */
 163 enum livebox_lb_type {
 164         LB_TYPE_IMAGE = 0x01, /**< Contents of a livebox is based on the image file */
 165         LB_TYPE_BUFFER = 0x02, /**< Contents of a livebox is based on canvas buffer(shared) */
 166         LB_TYPE_TEXT = 0x04, /**< Contents of a livebox is based on formatted text file */
 167         LB_TYPE_PIXMAP = 0x08, /**< Contens of a livebox is shared by the pixmap(depends on X) */
 168         LB_TYPE_ELEMENTARY = 0x10, /**< Using Elementary for sharing content & event */
 169         LB_TYPE_INVALID = 0xFF /**< Unknown LB type */
 170 };
 171
 172 /**
 173  * @brief Enumeration for Livebox PD content type.
 174  */
 175 enum livebox_pd_type {
 176         PD_TYPE_BUFFER = 0x01, /**< Contents of a PD is based on canvas buffer(shared) */
 177         PD_TYPE_TEXT = 0x02, /**< Contents of a PD is based on formatted text file */
 178         PD_TYPE_PIXMAP = 0x04, /**< Contents of a livebox is shared by the pixmap(depends on X) */
 179         PD_TYPE_ELEMENTARY = 0x08, /**< Using Elementary for sharing content & event */
 180         PD_TYPE_INVALID = 0xFF /**< Unknown PD type */
 181 };
 182
 183 /**
 184  * @brief Enumeration for Livebox event type.
 185  * @details These events will be sent from the provider.
 186  */
 187 enum livebox_event_type { /**< livebox_event_handler_set Event list */
 188         LB_EVENT_LB_UPDATED, /**< Contents of the given livebox is updated */
 189         LB_EVENT_PD_UPDATED, /**< Contents of the given pd is updated */
 190
 191         LB_EVENT_CREATED, /**< A new livebox is created */
 192         LB_EVENT_DELETED, /**< A livebox is deleted */
 193
 194         LB_EVENT_GROUP_CHANGED, /**< Group (Cluster/Sub-cluster) information is changed */
 195         LB_EVENT_PINUP_CHANGED, /**< PINUP status is changed */
 196         LB_EVENT_PERIOD_CHANGED, /**< Update period is changed */
 197
 198         LB_EVENT_LB_SIZE_CHANGED, /**< Livebox size is changed */
 199         LB_EVENT_PD_SIZE_CHANGED, /**< PD size is changed */
 200
 201         LB_EVENT_PD_CREATED, /**< If a PD is created even if you didn't call the livebox_create_pd API */
 202         LB_EVENT_PD_DESTROYED, /**< If a PD is destroyed even if you didn't call the livebox_destroy_pd API */
 203
 204         LB_EVENT_HOLD_SCROLL, /**< If the screen should be freezed */
 205         LB_EVENT_RELEASE_SCROLL, /**< If the screen can be scrolled */
 206
 207         LB_EVENT_LB_UPDATE_BEGIN, /**< Livebox LB content update is started */
 208         LB_EVENT_LB_UPDATE_END, /**< Livebox LB content update is finished */
 209
 210         LB_EVENT_PD_UPDATE_BEGIN, /**< Livebox PD content update is started */
 211         LB_EVENT_PD_UPDATE_END, /**< Livebox PD content update is finished */
 212
 213         LB_EVENT_UPDATE_MODE_CHANGED, /**< Livebox Update mode is changed */
 214
 215         LB_EVENT_REQUEST_CLOSE_PD, /**< Livebox requests to close the PD */
 216
 217         LB_EVENT_IGNORED /**< Request is ignored */
 218 };
 219
 220 /**
 221  * @brief Enumeration for Livebox option types.
 222  */
 223 enum livebox_option_type {
 224         LB_OPTION_MANUAL_SYNC,                  /**< Sync manually */
 225         LB_OPTION_FRAME_DROP_FOR_RESIZE,        /**< Drop frames while resizing */
 226         LB_OPTION_SHARED_CONTENT,               /**< Use only one real instance for multiple fake instances if user creates it using same content */
 227
 228         LB_OPTION_ERROR = 0xFFFFFFFF            /**< To specify the size of this enumeration type */
 229 };
 230
 231 enum livebox_fault_type {
 232         LB_FAULT_DEACTIVATED, /*!< Livebox is deactivated by its fault operation */
 233         LB_FAULT_PROVIDER_DISCONNECTED /*!< Provider is disconnected */
 234 };
 235
 236 /**
 237  * @brief Enumeration for Livebox visible states.
 238  * @details Must be sync'd with a provider.
 239  */
 240 enum livebox_visible_state {
 241         LB_SHOW = 0x00, /**< Livebox is shown. Default state */
 242         LB_HIDE = 0x01, /**< Livebox is hidden, Update timer will not be freezed. but you cannot receive any updates events. */
 243
 244         LB_HIDE_WITH_PAUSE = 0x02, /**< Livebix is hidden, it will pause the update timer, but if a livebox updates its contents, update event will be triggered */
 245
 246         LB_VISIBLE_ERROR = 0xFFFFFFFF /**< To specify the size of this enumeration type */
 247 };
 248
 249 /**
 250  * @brief Structure for TEXT type livebox contents handling opertators.
 251  */
 252 struct livebox_script_operators {
 253         int (*update_begin)(struct livebox *handle); /**< Content parser is started */
 254         int (*update_end)(struct livebox *handle); /**< Content parser is finished */
 255
 256         /* Listed functions will be called when parser meets each typed content */
 257         int (*update_text)(struct livebox *handle, const char *id, const char *part, const char *data); /**< Update text content */
 258         int (*update_image)(struct livebox *handle, const char *id, const char *part, const char *data, const char *option); /**< Update image content */
 259         int (*update_script)(struct livebox *handle, const char *id, const char *new_id, const char *part, const char *file, const char *group); /**< Update script content */
 260         int (*update_signal)(struct livebox *handle, const char *id, const char *emission, const char *signal); /**< Update signal */
 261         int (*update_drag)(struct livebox *handle, const char *id, const char *part, double dx, double dy); /**< Update drag info */
 262         int (*update_info_size)(struct livebox *handle, const char *id, int w, int h); /**< Update content size */
 263         int (*update_info_category)(struct livebox *handle, const char *id, const char *category); /**< Update content category info */
 264         int (*update_access)(struct livebox *handle, const char *id, const char *part, const char *text, const char *option); /**< Update access information */
 265         int (*operate_access)(struct livebox *handle, const char *id, const char *part, const char *operation, const char *option); /**< Update access operation */
 266         int (*update_color)(struct livebox *handle, const char *id, const char *part, const char *data); /**< Update color */
 267 };
 268
 269 /**
 270  * @brief Called for every async function.
 271  * @details Prototype of the return callback of every async functions.
 272  * @param[in] handle Handle of the livebox instance
 273  * @param[in] ret Result status of operation (LB_STATUS_XXX defined from liblivebox-service)
 274  * @param[in] data Data for result callback
 275  * @return void
 276  * @see livebox_add()
 277  * @see livebox_del()
 278  * @see livebox_activate()
 279  * @see livebox_resize()
 280  * @see livebox_set_group()
 281  * @see livebox_set_period()
 282  * @see livebox_access_event()
 283  * @see livebox_set_pinup()
 284  * @see livebox_create_pd()
 285  * @see livebox_create_pd_with_position()
 286  * @see livebox_destroy_pd()
 287  * @see livebox_emit_text_signal()
 288  * @see livebox_acquire_pd_pixmap()
 289  * @see livebox_acquire_lb_pixmap()
 290  * @see livebox_set_update_mode()
 291  */
 292 typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data);
 293
 294 /**
 295  * @brief Initializes the livebox system.
 296  * @remarks This API uses get/setenv APIs.
 297  *   Those APIs are not thread-safe.
 298  *   So you have to consider to use the livebox_init_with_options instead of this if you are developing multi-threaded viewer.
 299  * @param[in] disp X Display connection object (If you have X Display connection object already, you can re-use it. But you should care its life cycle.
 300  *                 It must be alive before calling livebox_fini())
 301  * @return int
 302  * @retval #LB_STATUS_SUCCESS if success
 303  * @see livebox_fini()
 304  * @see livebox_init_with_options()
 305  */
 306 extern int livebox_init(void *disp);
 307
 308 /**
 309  * @brief Initializes the livebox system with some options.
 310  * @details livebox_init function uses environment value to initiate some configurable values.
 311  *          But some applications do not want to use the env value.
 312  *          For them, this API will give a chance to set default options using given arguments.
 313  * @param[in] disp Display (if @a disp is @c NULL, the library will try to acquire a new connection with X)
 314  * @param[in] prevent_overwrite Overwrite flag (when the content of an image type livebox is updated, it will be overwriten (0) or not (1))
 315  * @param[in] event_filter If the next event comes in this period, ignore it. It is too fast to processing it in time // need to be elaborated
 316  * @param[in] use_thread Use the receive thread // need to be elaborated
 317  * @privlevel platform
 318  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 319  * @return int Integer, Livebox status code
 320  * @retval #LB_STATUS_SUCCESS if success
 321  * @see livebox_init()
 322  * @see livebox_fini()
 323  */
 324 extern int livebox_init_with_options(void *disp, int prevent_overwrite, double event_filter, int use_thread);
 325
 326 /**
 327  * @brief Finalizes the livebox system.
 328  * @privlevel platform
 329  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 330  * @return int
 331  * @retval #LB_STATUS_SUCCES if success
 332  * @retval #LB_STATUS_ERROR_INVALID if livebox_init is not called
 333  * @see livebox_init()
 334  * @see livebox_init_with_options()
 335  */
 336 extern int livebox_fini(void);
 337
 338 /**
 339  * @brief Notifies the status of a client ("it is paused") to the provider.
 340  * @privlevel platform
 341  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 342  * @return int
 343  * @retval #LB_STATUS_SUCCESS if success
 344  * @retval #LB_STATUS_ERROR_FAULT if it failed to send state (paused) info
 345  * @see livebox_client_resumed()
 346  */
 347 extern int livebox_client_paused(void);
 348
 349 /**
 350  * @brief Notifies the status of client ("it is resumed") to the provider.
 351  * @privlevel platform
 352  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 353  * @return int
 354  * @retval #LB_STATUS_SUCCESS if success
 355  * @retval #LB_STATUS_ERROR_FAULT if it failed to send state (resumed) info
 356  * @see livebox_client_paused()
 357  */
 358 extern int livebox_client_resumed(void);
 359
 360 /**
 361  * @brief Adds a new livebox.
 362  * @details If the screen size is "1280x720", the below size lists are used for default.
 363  * Or you can find the default sizes in pixel from /usr/share/data-provider-master/resolution.ini.
 364  * Size types are defined from the liblivebox-service package (livebox-service.h).
 365  *
 366  * Normal mode livebox
 367  * 1x1=175x175, #LB_SIZE_TYPE_1x1
 368  * 2x1=354x175, #LB_SIZE_TYPE_2x1
 369  * 2x2=354x354, #LB_SIZE_TYPE_2x2
 370  * 4x1=712x175, #LB_SIZE_TYPE_4x1
 371  * 4x2=712x354, #LB_SIZE_TYPE_4x2
 372  * 4x4=712x712, #LB_SIZE_TYPE_4x4
 373  *
 374  * Extended sizes
 375  * 4x3=712x533, #LB_SIZE_TYPE_4x3
 376  * 4x5=712x891, #LB_SIZE_TYPE_4x5
 377  * 4x6=712x1070, #LB_SIZE_TYPE_4x6
 378  *
 379  * Easy mode livebox
 380  * 21x21=224x215, #LB_SIZE_TYPE_EASY_1x1
 381  * 23x21=680x215, #LB_SIZE_TYPE_EASY_3x1
 382  * 23x23=680x653, #LB_SIZE_TYPE_EASY_3x3
 383  *
 384  * Special livebox
 385  * 0x0=720x1280, #LB_SIZE_TYPE_0x0
 386  *
 387  * @remarks
 388  *    Even if you get a handle from the return value of this function, it is not a created instance.
 389  *    So you have to consider it as a not initialized handle.
 390  *    It can be initialized only after getting the return callback with "ret == #LB_STATUS_SUCCESS"
 391  * @param[in] pkgname Livebox Id
 392  * @param[in] content Contents that will be passed to the livebox instance
 393  * @param[in] cluster Main group
 394  * @param[in] category Sub group
 395  * @param[in] period Update period (@c DEFAULT_PERIOD can be used for this; this argument will be used to specify the period of updating contents of a livebox)
 396  * @param[in] type Size type (defined from liblivebox-service package)
 397  * @param[in] cb After the request is sent to the master provider, this callback will be called
 398  * @param[in] data This data will be passed to the callback
 399  * @privlevel platform
 400  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 401  * @return handle
 402  * @retval Handle Livebox handle but not yet initialized
 403  * @retval @c NULL if it fails to create a handle
 404  * @see ret_cb_t
 405  */
 406 extern struct livebox *livebox_add(const char *pkgname, const char *content, const char *cluster, const char *category, double period, int type, ret_cb_t cb, void *data);
 407
 408 /**
 409  * @brief Deletes a livebox (will replace livebox_del).
 410  * @remarks If you call this with an uninitialized handle, the return callback will be called synchronously.
 411  *    So before returning from this function, the return callback will be called first.
 412  * @param[in] handler Handler of a livebox instance
 413  * @param[in] type Deletion type (LB_DELETE_PERMANENTLY or LB_DELETE_TEMPORARY)
 414  * @param[in] cb Return callback
 415  * @param[in] data User data for return callback
 416  * @privlevel platform
 417  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 418  * @return int
 419  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 420  * @retval #LB_STATUS_ERROR_BUSY Already in process
 421  * @retval #LB_STATUS_ERROR_FAULT Failed to create a request packet
 422  * @retval #LB_STATUS_SUCCESS Successfully sent, return callack will be called
 423  * @see ret_cb_t
 424  */
 425 extern int livebox_del(struct livebox *handler, int type, ret_cb_t cb, void *data);
 426
 427 /**
 428  * @brief Sets a livebox events callback.
 429  * @details To get the event push from the provider, register the event callback using this function.
 430  *    The callback will be called if there is any event from the provider.
 431  * @param[in] cb Event handler
 432  * @param[in] data User data for the event handler
 433  * @privlevel N/P
 434  * @return int
 435  * @retval #LB_STATUS_SUCCESS If succeed to set event handler
 436  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 437  * @retval #LB_STATUS_ERROR_MEMORY Not enough memory
 438  * @see livebox_unset_event_handler()
 439  */
 440 extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data);
 441
 442 /**
 443  * @brief Unsets the livebox event handler.
 444  * @param[in] cb Event handler
 445  * @privlevel N/P
 446  * @return void * Event handler data
 447  * @retval pointer Pointer of 'data' which is used with the livebox_set_event_handler
 448  * @see livebox_set_event_handler()
 449  */
 450 extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data));
 451
 452 /**
 453  * @brief Registers the livebox fault event handler.
 454  * @details Argument list: event, pkgname, filename, funcname.
 455  * @param[in] cb Event handler
 456  * @param[in] data Event handler data
 457  * @privlevel N/P
 458  * @return int
 459  * @retval #LB_STATUS_SUCCESS If succeed to set fault event handler
 460  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 461  * @retval #LB_STATUS_ERROR_MEMORY Not enough memory
 462  * @see livebox_unset_fault_handler()
 463  */
 464 extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data);
 465
 466 /**
 467  * @brief Unsets the livebox fault event handler.
 468  * @param[in] cb Event handler
 469  * @privlevel N/P
 470  * @return void * Callback data which is set via livebox_set_fault_handler
 471  * @retval pointer Pointer of 'data' which is used with the livebox_set_fault_handler
 472  * @see livebox_set_fault_handler()
 473  */
 474 extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *));
 475
 476 /**
 477  * @brief Activates the faulted livebox.
 478  * @details Request result will be returned via return callback.
 479  * @remarks Even though this function returns SUCCESS, it means that it just successfully sent a request to the provider.
 480  *    So you have to check the return callback and its "ret" argument.
 481  * @param[in] pkgname Package name which should be activated
 482  * @param[in] cb Result callback
 483  * @param[in] data Callback data
 484  * @privlevel platform
 485  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 486  * @return int type
 487  * @retval #LB_STATUS_SUCCESS Successfully sent a request
 488  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 489  * @retval #LB_STATUS_ERROR_FAULT Failed to make a request
 490  * @see ret_cb_t
 491  */
 492 extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data);
 493
 494 /**
 495  * @brief Resizes the livebox.
 496  * @details
 497  * Normal mode livebox size
 498  * 1x1=175x175, LB_SIZE_TYPE_1x1
 499  * 2x1=354x175, LB_SIZE_TYPE_2x1
 500  * 2x2=354x354, LB_SIZE_TYPE_2x2
 501  * 4x1=712x175, LB_SIZE_TYPE_4x1
 502  * 4x2=712x354, LB_SIZE_TYPE_4x2
 503  * 4x4=712x712, LB_SIZE_TYPE_4x4
 504  *
 505  * Extended livebox size
 506  * 4x3=712x533, LB_SIZE_TYPE_4x3
 507  * 4x5=712x891, LB_SIZE_TYPE_4x5
 508  * 4x6=712x1070, LB_SIZE_TYPE_4x6
 509  *
 510  * Easy mode livebox size
 511  * 21x21=224x215, LB_SIZE_TYPE_EASY_1x1
 512  * 23x21=680x215, LB_SIZE_TYPE_EASY_3x1
 513  * 23x23=680x653, LB_SIZE_TYPE_EASY_3x3
 514  *
 515  * Special mode livebox size
 516  * 0x0=720x1280, LB_SIZE_TYPE_0x0
 517  * @remarks You have to check the return callback.
 518  * @param[in] handler Handler of a livebox instance
 519  * @param[in] type Type of a livebox size (e.g., LB_SIZE_TYPE_1x1, ...)
 520  * @param[in] cb Result callback of the resize operation
 521  * @param[in] data User data for return callback
 522  * @privlevel platform
 523  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 524  * @return int type
 525  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 526  * @retval #LB_STATUS_ERROR_BUSY Previous request of resize is in progress
 527  * @retval #LB_STATUS_ERROR_ALREADY Already resized, there is no differences between current size and requested size
 528  * @retval #LB_STATUS_ERROR_PERMISSION Permission denied, you only have view the content of this box
 529  * @retval #LB_STATUS_ERROR_FAULT Failed to make a request
 530  * @see ret_cb_t
 531  */
 532 extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data);
 533
 534 /**
 535  * @brief Sends the click event for a livebox.
 536  * @param[in] handler Handler of a livebox instance
 537  * @param[in] x Rational X of the content width
 538  * @param[in] y Rational Y of the content height
 539  * @privlevel platform
 540  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 541  * @return int
 542  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 543  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 544  * @retval #LB_STATUS_SUCCESS Successfully done
 545  */
 546 extern int livebox_click(struct livebox *handler, double x, double y);
 547
 548 /**
 549  * @brief Changes the cluster/sub-cluster name of the given livebox handler.
 550  * @param[in] handler Handler of a livebox instance
 551  * @param[in] cluster New cluster of a livebox
 552  * @param[in] category New category of a livebox
 553  * @param[in] cb Result callback for changing the cluster/category of a livebox
 554  * @param[in] data User data for the result callback
 555  * @privlevel platform
 556  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 557  * @return int
 558  * @retval #LB_STATUS_SUCCESS Request is successfully sent. the return callback will be called
 559  * @retval #LB_STATUS_ERROR_BUSY Previous request is not finished yet
 560  * @retval #LB_STATUS_ERROR_ALREADY Group name is same with current one
 561  * @retval #LB_STATUS_ERROR_PERMISSION You have no permission to change property of this livebox instance
 562  * @retval #LB_STATUS_ERROR_FAULT Failed to make a request
 563  * @see ret_cb_t
 564  */
 565 extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data);
 566
 567 /**
 568  * @brief Gets the cluster and category (sub-cluster) name of the given livebox (it is not I18N format, only English).
 569  * @remarks You have to do not release the cluster & category.
 570  *    It is allocated inside of a given livebox instance, so you can only read it.
 571  * @param[in] handler Handler of a livebox instance
 572  * @param[out] cluster Storage(memory) for containing the cluster name
 573  * @param[out] category Storage(memory) for containing the category name
 574  * @privlevel N/P
 575  * @return int
 576  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 577  * @retval #LB_STATUS_SUCCESS Successfully done
 578  */
 579 extern int livebox_get_group(struct livebox *handler, const char **cluster, const char **category);
 580
 581 /**
 582  * @brief Gets the period of the livebox handler.
 583  * @remarks If this function returns 0.0f, it means the livebox has no update period or the handle is not valid.
 584  *    This function only works after the return callback of livebox_create fucntion is called.
 585  * @param[in] handler Handler of a livebox instance
 586  * @privlevel N/P
 587  * @return double
 588  * @retval Current update period of a livebox
 589  * @retval 0.0f This means the box has no update period or the handles is not valid
 590  */
 591 extern double livebox_period(struct livebox *handler);
 592
 593 /**
 594  * @brief Changes the update period.
 595  * @param[in] handler Handler of a livebox instance
 596  * @param[in] period New update period of a livebox
 597  * @param[in] cb Result callback of changing the update period of this livebox
 598  * @param[in] data User data for the result callback
 599  * @privlevel platform
 600  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 601  * @return int
 602  * @retval #LB_STATUS_SUCCESS Successfully done
 603  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 604  * @retval #LB_STATUS_ERROR_BUSY
 605  * @retval #LB_STATUS_ERROR_ALREADY
 606  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 607  * @see ret_cb_t
 608  */
 609 extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data);
 610
 611 /**
 612  * @brief Checks whether the given livebox is a text type or not.
 613  * @param[in] handler Handler of a livebox instance
 614  * @privlevel N/P
 615  * @return livebox_lb_type
 616  * @retval #LB_TYPE_IMAGE Contents of a livebox is based on the image file
 617  * @retval #LB_TYPE_BUFFER Contents of a livebox is based on canvas buffer(shared)
 618  * @retval #LB_TYPE_TEXT Contents of a livebox is based on formatted text file
 619  * @retval #LB_TYPE_PIXMAP Contens of a livebox is shared by the pixmap(depends on X)
 620  * @retval #LB_TYPE_INVALID
 621  * @see livebox_lb_type()
 622  */
 623 extern enum livebox_lb_type livebox_lb_type(struct livebox *handler);
 624
 625 /**
 626  * @brief Checks if the given livebox is created by user or not.
 627  * @details If the livebox instance is created by a system this will return 0.
 628  * @param[in] handler Handler of a livebox instance
 629  * @privlevel N/P
 630  * @return int
 631  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 632  * @retval 0 Automatically created livebox by the provider
 633  * @retval 1 Created by user via livebox_add()
 634  * @see livebox_add()
 635  * @see livebox_set_event_handler()
 636  */
 637 extern int livebox_is_user(struct livebox *handler);
 638
 639 /**
 640  * @brief Gets content information string of the given livebox.
 641  * @param[in] handler Handler of a livebox instance
 642  * @privlevel N/P
 643  * @return const char *
 644  * @retval content_info Livebox content info that can be used again via content_info argument of livebox_add()
 645  * @see livebox_add()
 646  */
 647 extern const char *livebox_content(struct livebox *handler);
 648
 649 /**
 650  * @brief Gets the sub cluster title string of the given livebox.
 651  * @details This API is now used for accessibility.
 652  *  Each box should set their content as a string to be read by TTS.
 653  *  So if the box has focused on the homescreen, the homescreen will read text using this API.
 654  * @remarks The title returned by this API is read by TTS.
 655  *  But it is just recomended to a homescreen.
 656  *  So, to read it or not depends on implementation of the homescreen.
 657  * @param[in] handler Handler of a livebox instance
 658  * @privlevel N/P
 659  * @return const char *
 660  * @retval sub Cluster name
 661  * @retval @c NULL
 662  */
 663 extern const char *livebox_category_title(struct livebox *handler);
 664
 665 /**
 666  * @brief Gets the filename of the given livebox, if it is an IMAGE type livebox.
 667  * @details If the box is developed as image format to represent its contents, the homescreen should know its image file name.
 668  * @param[in] handler Handler of a livebox instance
 669  * @privlevel N/P
 670  * @return const char *
 671  * @retval filename If the livebox type is image this function will give you a abs-path of an image file (content is rendered)
 672  * @retval @c NULL If this has no image file or type is not image file.
 673  */
 674 extern const char *livebox_filename(struct livebox *handler);
 675
 676 /**
 677  * @brief Gets the package name of the given livebox handler.
 678  * @param[in] handler Handler of a livebox instance
 679  * @privlevel N/P
 680  * @return const char *
 681  * @retval pkgname Package name
 682  * @retval @c NULL If the handler is not valid
 683  */
 684 extern const char *livebox_pkgname(struct livebox *handler);
 685
 686 /**
 687  * @brief Gets the priority of a current content.
 688  * @param[in] handler Handler of a livebox instance
 689  * @privlevel N/P
 690  * @return double
 691  * @retval 0.0f Handler is @c NULL
 692  * @retval -1.0f Handler is not valid (not yet initialized)
 693  * @retval real Number between 0.0 and 1.0
 694  */
 695 extern double livebox_priority(struct livebox *handler);
 696
 697 /**
 698  * @brief Acquires the buffer of a given livebox (only for the buffer type).
 699  * @param[in] handler Handler of a livebox instance
 700  * @privlevel platform
 701  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 702  * @return void *
 703  * @retval address Address of a FB
 704  * @retval @c NULL If it fails to get fb address
 705  */
 706 extern void *livebox_acquire_fb(struct livebox *handler);
 707
 708 /**
 709  * @brief Releases the buffer of a livebox (only for the buffer type).
 710  * @param[in] buffer Buffer
 711  * @privlevel platform
 712  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 713  * @return int
 714  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 715  * @retval #LB_STATUS_SUCCESS Successfully done
 716  * @see livebox_acquire_fb()
 717  */
 718 extern int livebox_release_fb(void *buffer);
 719
 720 /**
 721  * @brief Gets the reference count of Livebox buffer (only for the buffer type).
 722  * @param[in] buffer Buffer
 723  * @privlevel N/P
 724  * @return int
 725  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 726  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 727  * @retval refcnt Positive integer including ZERO
 728  * @see livebox_pdfb_refcnt()
 729  */
 730 extern int livebox_fb_refcnt(void *buffer);
 731
 732 /**
 733  * @brief Acquires the buffer of a PD frame (only for the buffer type).
 734  * @param[in] handler Handler of a livebox instance
 735  * @privlevel platform
 736  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 737  * @return int
 738  * @retval @c NULL
 739  * @retval adress Address of a buffer of PD
 740  * @see livebox_release_pdfb()
 741  */
 742 extern void *livebox_acquire_pdfb(struct livebox *handler);
 743
 744 /**
 745  * @brief Releases the acquired buffer of the PD Frame (only for the buffer type).
 746  * @param[in] buffer Buffer
 747  * @privlevel platform
 748  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 749  * @return int
 750  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 751  * @retval #LB_STATUS_SUCCESS Successfully done
 752  * @see livebox_acquire_pdfb()
 753  */
 754 extern int livebox_release_pdfb(void *buffer);
 755
 756 /**
 757  * @brief Gets the reference count of a given PD buffer (only for the buffer type).
 758  * @param[in] buffer Buffer
 759  * @privlevel N/P
 760  * @return int
 761  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 762  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 763  * @retval reference Reference count
 764  * @see livebox_fb_refcnt()
 765  */
 766 extern int livebox_pdfb_refcnt(void *buffer);
 767
 768 /**
 769  * @brief Gets the size of the Livebox.
 770  * @param[in] handler Handler of a livebox instance
 771  * @privlevel N/P
 772  * @return int
 773  * @retval #LB_SIZE_TYPE_NxM
 774  * @retval #LB_SIZE_TYPE_INVALID
 775  */
 776 extern int livebox_size(struct livebox *handler);
 777
 778 /**
 779  * @brief Gets the size of the Progressive Disclosure.
 780  * @param[in] handler Handler of a livebox instance
 781  * @param[out] w
 782  * @param[out] h
 783  * @privlevel N/P
 784  * @return int type
 785  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 786  * @retval #LB_STATUS_SUCCESS Successfully done
 787  */
 788 extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h);
 789
 790 /**
 791  * @brief Gets a list of the supported sizes of a given handler.
 792  * @param[in] handler Handler of a livebox instance
 793  * @param[out] cnt
 794  * @param[out] size_list
 795  * @privlevel N/P
 796  * @return int type
 797  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 798  * @retval #LB_STATUS_SUCCESS Successfully done
 799  */
 800 extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list);
 801
 802 /**
 803  * @brief Gets BUFFER SIZE of the livebox if it is a buffer type.
 804  * @param[in] handler Handler of a livebox instance
 805  * @privlevel N/P
 806  * @return int
 807  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 808  * @retval size Size of livebox buffer
 809  */
 810 extern int livebox_lbfb_bufsz(struct livebox *handler);
 811
 812 /**
 813  * @brief Gets BUFFER SIZE of the progiressive disclosure if it is a buffer type.
 814  * @param[in] handler Handler of a livebox instance
 815  * @privlevel N/P
 816  * @return int
 817  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 818  * @retval size Size of PD buffer
 819  */
 820 extern int livebox_pdfb_bufsz(struct livebox *handler);
 821
 822 /**
 823  * @brief Sends a content event (for buffer type) to the provider (livebox).
 824  * @param[in] handler Handler of a livebox instance
 825  * @param[in] type Event type
 826  * @param[in] x Coordinates of X axis
 827  * @param[in] y Coordinates of Y axis
 828  * @privlevel platform
 829  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 830  * @return int
 831  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 832  * @retval #LB_STATUS_ERROR_BUSY Previous operation is not finished yet
 833  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 834  * @retval #LB_STATUS_SUCCESS Successfully sent
 835  * @see livebox_access_event()
 836  * @see livebox_key_event()
 837  */
 838 extern int livebox_mouse_event(struct livebox *handler, enum content_event_type type, double x, double y);
 839
 840 /**
 841  * @brief Sends an access event (for buffer type) to the provider (livebox).
 842  * @param[in] handler Handler of a livebox instance
 843  * @param[in] type Event type
 844  * @param[in] x Coordinates of X axsis
 845  * @param[in] y Coordinates of Y axsis
 846  * @param[in] cb Result callback function
 847  * @param[in] data Callback data
 848  * @privlevel platform
 849  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 850  * @return int
 851  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 852  * @retval #LB_STATUS_ERROR_BUSY Previous operation is not finished yet
 853  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 854  * @retval #LB_STATUS_SUCCESS Successfully sent
 855  * @see livebox_mouse_event()
 856  * @see livebox_key_event()
 857  */
 858 extern int livebox_access_event(struct livebox *handler, enum access_event_type type, double x, double y, ret_cb_t cb, void *data);
 859
 860 /**
 861  * @brief Sends a key event (for buffer type) to the provider (livebox).
 862  * @param[in] handler Handler of a livebox instance
 863  * @param[in] type Key event type
 864  * @param[in] keycode Code of key
 865  * @param[in] cb Result callback
 866  * @param[in] data Callback data
 867  * @privlevel platform
 868  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 869  * @return int
 870  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 871  * @retval #LB_STATUS_ERROR_BUSY Previous operation is not finished yet
 872  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 873  * @retval #LB_STATUS_SUCCESS Successfully sent
 874  * @see livebox_mouse_event()
 875  * @see livebox_access_event()
 876  */
 877 extern int livebox_key_event(struct livebox *handler, enum content_event_type type, unsigned int keycode, ret_cb_t cb, void *data);
 878
 879 /**
 880  * @brief Sets pin-up status of the given handler.
 881  * @details If the livebox supports the pinup feature,
 882  *   you can freeze the update of the given livebox.
 883  *   But it is different from pause.
 884  *   The box will be updated and it will decide wheter update its content or not when the pinup is on.
 885  * @param[in] handler Handler of a livebox instance
 886  * @param[in] flag Pinup value
 887  * @param[in] cb Result callback
 888  * @param[in] data Callback data
 889  * @privlevel platform
 890  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 891  * @return int
 892  * @retval #LB_STATUS_ERROR_INVALID Invalid parameters
 893  * @see ret_cb_t
 894  * @see livebox_set_visibility()
 895  * @see livebox_is_pinned_up()
 896  */
 897 extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data);
 898
 899 /**
 900  * @brief Checks the PIN-UP status of the given handler.
 901  * @param[in] handler Handler of a livebox instance
 902  * @privlevel N/P
 903  * @return int
 904  * @retval #LB_STATUS_ERROR_INVALID Invalid parameters
 905  * @retval 1 Box is pinned up
 906  * @retval 0 Box is not pinned up
 907  * @see livebox_set_pinup()
 908  */
 909 extern int livebox_is_pinned_up(struct livebox *handler);
 910
 911 /**
 912  * @brief Checks the availability of the PIN-UP feature for the given handler.
 913  * @param[in] handler Handler of a livebox instance
 914  * @privlevel N/P
 915  * @return int
 916  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 917  * @retval 1 If the box support Pinup feature
 918  * @retval 0 If the box does not support the Pinup feature
 919  * @see livebox_is_pinned_up()
 920  * @see livebox_set_pinup()
 921  */
 922 extern int livebox_has_pinup(struct livebox *handler);
 923
 924 /**
 925  * @brief Checks the existence of PD for the given handler.
 926  * @param[in] handler Handler of a livebox instance
 927  * @privlevel N/P
 928  * @return int
 929  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 930  * @retval 1 If the box support the PD
 931  * @retval 0 If the box has no PD
 932  */
 933 extern int livebox_has_pd(struct livebox *handler);
 934
 935 /**
 936  * @brief Creates PD of the given handler.
 937  * @param[in] handler Handler of a livebox instance
 938  * @param[in] cb Result callback
 939  * @param[in] data Callback data
 940  * @privlevel platform
 941  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 942  * @return int
 943  * @retval #LB_STATUS_SUCCESS Successfully done
 944  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 945  * @retval #LB_STATUS_ERROR_BUSY Previous operation is not finished yet
 946  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 947  * @see ret_cb_t
 948  * @see livebox_create_pd_with_position()
 949  * @see livebox_move_pd()
 950  * @see livebox_destroy_pd()
 951  */
 952 extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data);
 953
 954 /**
 955  * @brief Creates PD of the given handler with the relative position from livebox.
 956  * @param[in] handler Handler of a livebox instance
 957  * @param[in] x 0.0 ~ 1.0
 958  * @param[in] y 0.0 ~ 1.0
 959  * @param[in] cb Result callback
 960  * @param[in] data Callback data
 961  * @privlevel platform
 962  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 963  * @return int
 964  * @retval #LB_STATUS_SUCCESS Successfully done
 965  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 966  * @retval #LB_STATUS_ERROR_BUSY Previous operation is not finished yet
 967  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 968  * @see livebox_create_pd()
 969  * @see livebox_destroy_pd()
 970  * @see livebox_move_pd()
 971  */
 972 extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data);
 973
 974 /**
 975  * @brief Updates a position of the given PD.
 976  * @param[in] handler Handler of a livebox instance
 977  * @param[in] x 0.0 ~ 1.0
 978  * @param[in] y 0.0 ~ 1.0
 979  * @privlevel platform
 980  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 981  * @return int
 982  * @retval #LB_STATUS_SUCCESS If sending a request for updating position of the PD has been done successfully
 983  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 984  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 985  */
 986 extern int livebox_move_pd(struct livebox *handler, double x, double y);
 987
 988 /**
 989  * @brief Destroys the PD of the given handler if it is created.
 990  * @param[in] handler Handler of a livebox instance
 991  * @param[in] cb
 992  * @param[in] data
 993  * @privlevel platform
 994  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.viewer
 995  * @return int
 996  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 997  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
 998  * @retval #LB_STATUS_SUCCESS Successfully done
 999  * @see ret_cb_t
1000  */
1001 extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data);
1002
1003 /**
1004  * @brief Checks the create status of the given livebox handler.
1005  * @param[in] handler Handler of a livebox instance
1006  * @privlevel N/P
1007  * @return int
1008  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1009  * @retval 0 PD is not created
1010  * @retval 1 PD is created
1011  */
1012 extern int livebox_pd_is_created(struct livebox *handler);
1013
1014 /**
1015  * @brief Checks the content type of a progressive disclosure of the given handler.
1016  * @param[in] handler Handler of a livebox instance
1017  * @privlevel N/P
1018  * @return int
1019  * @retval #PD_TYPE_BUFFER Contents of a PD is based on canvas buffer(shared)
1020  * @retval #PD_TYPE_TEXT Contents of a PD is based on formatted text file
1021  * @retval #PD_TYPE_PIXMAP Contents of a livebox is shared by the pixmap(depends on X)
1022  * @retval #PD_TYPE_INVALID
1023  * @see livebox_pd_type()
1024  */
1025 extern enum livebox_pd_type livebox_pd_type(struct livebox *handler);
1026
1027 /**
1028  * @brief Checks the existence of a livebox about the given package name.
1029  * @param[in] pkgname Package name
1030  * @privlevel platform
1031  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.info
1032  * @return int
1033  * @retval 1 If the box exists
1034  * @retval 0 If the box does not exist
1035  */
1036 extern int livebox_is_exists(const char *pkgname);
1037
1038 /**
1039  * @brief Sets a function table for parsing the text content of a livebox.
1040  * @param[in] handler Handler of a livebox instance
1041  * @param[in] ops
1042  * @privlevel N/P
1043  * @return int
1044  * @retval #LB_STATUS_SUCCESS Successfully done
1045  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1046  * @see livebox_set_pd_text_handler()
1047  */
1048 extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1049
1050 /**
1051  * @brief Sets a function table for parsing the text content of a Progressive Disclosure.
1052  * @param[in] handler Handler of a livebox instance
1053  * @param[in] ops
1054  * @privlevel N/P
1055  * @return int
1056  * @retval #LB_STATUS_SUCCESS Successfully done
1057  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1058  * @see livebox_set_text_handler()
1059  */
1060 extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
1061
1062 /**
1063  * @brief Emits a text signal to the given livebox only if it is a text type.
1064  * @param[in] handler Handler of a livebox instance
1065  * @param[in] emission Emission string
1066  * @param[in] source Source string
1067  * @param[in] sx Start X
1068  * @param[in] sy Start Y
1069  * @param[in] ex End X
1070  * @param[in] ey End Y
1071  * @param[in] cb Result callback
1072  * @param[in] data Callback data
1073  * @privlevel platform
1074  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1075  * @return int
1076  * @retval #LB_STATUS_ERROR_INVALID Invalid parameters
1077  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1078  * @retval #LB_STATUS_SUCCESS Successfully emitted
1079  * @see ret_cb_t
1080  */
1081 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);
1082
1083 /**
1084  * @brief Sets a private data pointer to carry it using the given handler.
1085  * @param[in] handler Handler of a livebox instance
1086  * @param[in] data Data pointer
1087  * @privlevel N/P
1088  * @return int
1089  * @retval #LB_STATUS_SUCCESS Successfully registered
1090  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1091  * @see livebox_get_data()
1092  */
1093 extern int livebox_set_data(struct livebox *handler, void *data);
1094
1095 /**
1096  * @brief Gets a private data pointer which is carried by a given handler.
1097  * @param[in] handler Handler of a livebox instance
1098  * @privlevel N/P
1099  * @return void *
1100  * @retval data Data pointer
1101  * @retval @c NULL If there is no data
1102  * @see livebox_set_data()
1103  */
1104 extern void *livebox_get_data(struct livebox *handler);
1105
1106 /**
1107  * @brief Subscribes an event for liveboxes only in a given cluster and sub-cluster.
1108  * @details If you wrote a view-only client,
1109  *   you can receive the event of specific liveboxes which belong to a given cluster/category.
1110  *   But you cannot modify their attributes (such as size, ...).
1111  * @param[in] cluster   Cluster ("*" can be used for subscribe all cluster's liveboxes event; If you use the "*", value in the category will be ignored)
1112  * @param[in] category Category ("*" can be used for subscribe liveboxes events of all category(sub-cluster) in a given "cluster")
1113  * @privlevel platform
1114  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1115  * @return int
1116  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1117  * @retval #LB_STATUS_SUCCESS Successfully requested
1118  * @see livebox_unsubscribe_group()
1119  */
1120 extern int livebox_subscribe_group(const char *cluster, const char *category);
1121
1122 /**
1123  * @brief Unsubscribes an event for the liveboxes, but you will receive already added liveboxes events.
1124  * @param[in] cluster Cluster("*" can be used for subscribe all cluster's liveboxes event; If you use the "*", value in the category will be ignored)
1125  * @param[in] category Category ("*" can be used for subscribe all sub-cluster's liveboxes event in a given "cluster")
1126  * @privlevel platform
1127  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1128  * @return int
1129  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1130  * @retval #LB_STATUS_SUCCESS Successfully requested
1131  * @see livebox_subscribe_group()
1132  */
1133 extern int livebox_unsubscribe_group(const char *cluster, const char *category);
1134
1135 /**
1136  * @brief Refreshes the group (cluster/sub-cluser (aka. category)).
1137  * @details This function will trigger the update of all liveboxes in a given cluster/category group.
1138  * @remarks Basically, a default livebox system doesn't use the cluster/category concept.
1139  *    But you can use it. So if you decide to use it, then you can trigger the update of all liveboxes in the given group.
1140  * @param[in] cluster Cluster ID
1141  * @param[in] category Sub-cluster ID
1142  * @param[in] force 1 if the boxes should be updated even if they are paused
1143  * @privlevel platform
1144  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1145  * @return int
1146  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1147  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1148  * @retval #LB_STATUS_SUCCESS Successfully requested
1149  * @see livebox_refresh()
1150  */
1151 extern int livebox_refresh_group(const char *cluster, const char *category, int force);
1152
1153 /**
1154  * @brief Refreshes a livebox.
1155  * @param[in] handler Handler of a livebox instance
1156  * @param[in] force 1 if the box should be updated even if it is paused
1157  * @privlevel platform
1158  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1159  * @return int
1160  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1161  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1162  * @retval #LB_STATUS_SUCCESS Successfully requested
1163  * @see livebox_refresh_group()
1164  */
1165 extern int livebox_refresh(struct livebox *handler, int force);
1166
1167 /**
1168  * @brief Gets Pixmap Id of a livebox content.
1169  * @details This function doesn't guarantee the life-cycle of the pixmap.
1170  *   If the service provider destroyed the pixmap, you will not know about it.
1171  *   So you should validate it before accessing it.
1172  * @param[in] handler Handler of a livebox instance
1173  * @privlevel N/P
1174  * @return int
1175  * @retval 0 If the pixmap is not created
1176  * @retval pixmap Pixmap Id need to be casted to (unsigned int) type
1177  * @see livebox_pd_pixmap()
1178  */
1179 extern int livebox_lb_pixmap(const struct livebox *handler);
1180
1181 /**
1182  * @brief Gets Pixmap Id of a PD content.
1183  * @details This function doesn't guarantee the life-cycle of the pixmap.
1184  *   If the service provider destroyed the pixmap, you will not know about it.
1185  *   So you should validate it before accessing it.
1186  * @param[in] handler Handler of a livebox instance
1187  * @privlevel N/P
1188  * @return int
1189  * @retval 0 If the pixmap is not created
1190  * @retval pixmap Pixmap Id need to be casted to (unsigned int) type
1191  * @see livebox_lb_pixmap()
1192  */
1193 extern int livebox_pd_pixmap(const struct livebox *handler);
1194
1195 /**
1196  * @brief Acquires the pixmap of PD.
1197  * @details After acquiring the pixmap of PD, it will not be destroyed.
1198  *   So if the new update is comming with a new pixmap Id, you should release old pixmap manually.
1199  * @param[in] handler Handler of a livebox instance
1200  * @param[in] cb Result callback for acquiring request
1201  * @param[in] data Callback Data
1202  * @privlevel platform
1203  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1204  * @return int
1205  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1206  * @retval #LB_STATUS_ERROR_FAULT Failed to send a request to the service provider or there is critical error that is unrecoverable
1207  * @retval #LB_STATUS_SUCCESS Successfully requested to acquire the pixmap of PD
1208  * @see livebox_release_pd_pixmap()
1209  * @see livebox_acquire_lb_pixmap()
1210  * @see ret_cb_t
1211  */
1212 extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1213
1214 /**
1215  * @brief Releases the acquired pixmap ID.
1216  * @param[in] handler Handler of a livebox instance
1217  * @param[in] pixmap Pixmap Id to release it
1218  * @privlevel platform
1219  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1220  * @return int
1221  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1222  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1223  * @retval #LB_STATUS_SUCCESS Successfully released (request is sent)
1224  * @see livebox_acquire_pd_pixmap()
1225  * @see livebox_release_lb_pixmap()
1226  */
1227 extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap);
1228
1229 /**
1230  * @brief Gets the PIXMAP of a livebox.
1231  * @details Even if a render process releases the pixmap, the pixmap will be kept before being released by livebox_release_lb_pixmap.
1232  *   You should release the pixmap manually.
1233  * @param[in] handler Handler of a livebox instance
1234  * @param[in] cb Callback function which will be called with result of acquiring lb pixmap
1235  * @param[in] data Callback data
1236  * @privlevel platform
1237  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1238  * @return int
1239  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1240  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1241  * @retval #LB_STATUS_SUCCESS Successfully requested
1242  * @pre Livebox service system should support the PIXMAP type buffer.
1243  *   The livebox should be designed to use the buffer (script type).
1244  * @see livebox_release_lb_pixmap()
1245  * @see livebox_acquire_pd_pixmap()
1246  * @see ret_cb_t
1247  */
1248 extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
1249
1250 /**
1251  * @brief Releases the pixmap of a livebox.
1252  * @details After a client gets a new pixmap or does not need to keep the current pixmap anymore, use this function to release it.
1253  *   If there is no user for a given pixmap, the pixmap will be destroyed.
1254  * @param[in] handler Handler of a livebox instance
1255  * @param[in] pixmap Pixmap Id of given livebox handler
1256  * @privlevel platform
1257  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1258  * @return int
1259  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1260  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1261  * @retval #LB_STATUS_SUCCESS Successfully done
1262  * @pre The pixmap should be acquired by livebox_acquire_lb_pixmap
1263  * @see livebox_acquire_lb_pixmap()
1264  * @see livebox_release_pd_pixmap()
1265  */
1266 extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap);
1267
1268 /**
1269  * @brief Updates a visible state of the livebox.
1270  * @param[in] handler Handler of a livebox instance
1271  * @param[in] state Configure the current visible state of a livebox
1272  * @privlevel platform
1273  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1274  * @return int
1275  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1276  * @retval #LB_STATUS_ERROR_BUSY
1277  * @retval #LB_STATUS_ERROR_PERMISSION
1278  * @retval #LB_STATUS_ERROR_ALREADY
1279  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1280  * @retval #LB_STATUS_SUCCESS Successfully done
1281  */
1282 extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state);
1283
1284 /**
1285  * @brief Gets the current visible state of a livebox.
1286  * @param[in] handler Handler of a livebox instance
1287  * @privlevel N/P
1288  * @return livebox_visible_state
1289  * @retval #LB_SHOW Livebox is shown (Default state)
1290  * @retval #LB_HIDE Livebox is hidden, Update timer is not frozen (but a user cannot receive any updated events; a user should refresh(reload) the content of a livebox when a user make this show again)
1291  * @retval #LB_HIDE_WITH_PAUSE Livebox is hidden, it will pause the update timer, but if a livebox updates its contents, update event will occur
1292  * @retval #LB_VISIBLE_ERROR To enlarge the size of this enumeration type
1293  */
1294 extern enum livebox_visible_state livebox_visibility(struct livebox *handler);
1295
1296 /**
1297  * @brief Sets an update mode of the current livebox.
1298  * @details If you set 1 for active update mode, you should get a buffer without updated event from provider.
1299  *   But if it is passive mode, you have to update content of a box when you get updated events.
1300  *   Default is Passive mode.
1301  * @param[in] handler Handler of a livebox instance
1302  * @param[in] active_update 1 means active update, 0 means passive update (default)
1303  * @param[in] cb Result callback function
1304  * @param[in] data Callback data
1305  * @privlevel platform
1306  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1307  * @return int
1308  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1309  * @retval #LB_STATUS_ERROR_BUSY
1310  * @retval #LB_STATUS_ERROR_PERMISSION
1311  * @retval #LB_STATUS_ERROR_ALREADY
1312  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1313  * @retval #LB_STATUS_SUCCESS Successfully done
1314  * @see ret_cb_t
1315  */
1316 extern int livebox_set_update_mode(struct livebox *handler, int active_update, ret_cb_t cb, void *data);
1317
1318 /**
1319  * @brief Checks the active update mode of the given livebox.
1320  * @param[in] handler Handler of a livebox instance
1321  * @privlevel N/P
1322  * @return int
1323  * @retval 0 If passive mode
1324  * @retval 1 If active mode or error code
1325  */
1326 extern int livebox_is_active_update(struct livebox *handler);
1327
1328 /**
1329  * @brief Syncs manually
1330  * param[in] handler Handler of a livebox instance
1331  * @privlevel platform
1332  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1333  * @return void
1334  * @retval #LB_STATUS_SUCCESS If success
1335  * @retval #LB_STATUS_ERROR_INVALID Invalid handle
1336  * @see livebox_set_manual_sync()
1337  * @see livebox_manual_sync()
1338  * @see livebox_sync_lb_fb()
1339  */
1340 extern int livebox_sync_pd_fb(struct livebox *handler);
1341
1342 /**
1343  * @brief Syncs manually
1344  * @param[in] handler Handler of a livebox instance
1345  * @privlevel platform
1346  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1347  * @return void
1348  * @retval #LB_STATUS_SUCCESS If success
1349  * @retval #LB_STATUS_ERROR_INVALID Invalid handle
1350  * @see livebox_set_manual_sync()
1351  * @see livebox_manual_sync()
1352  * @see livebox_sync_pd_fb()
1353  */
1354 extern int livebox_sync_lb_fb(struct livebox *handler);
1355
1356 /**
1357  * @brief Gets an alternative icon of the given livebox instance.
1358  * @details If the box should be represented as a shortcut icon, this function will get the alternative icon.
1359  * @param[in] handler Handler of a livebox instance
1360  * @privlevel N/P
1361  * @return const char *
1362  * @retval address Absolute path of an alternative icon file
1363  * @retval @c NULL Livebox has no alternative icon file
1364  * @see livebox_alt_name()
1365  */
1366 extern const char *livebox_alt_icon(struct livebox *handler);
1367
1368 /**
1369  * @brief Gets an alternative name of the given livebox instance.
1370  * @details If the box should be represented as a shortcut name, this function will get the alternative name.
1371  * @param[in] handler Handler of a livebox instance
1372  * @privlevel N/P
1373  * @return const char *
1374  * @retval name Alternative name of a livebox
1375  * @retval @c NULL Livebox has no alternative name
1376  * @see livebox_alt_icon()
1377  */
1378 extern const char *livebox_alt_name(struct livebox *handler);
1379
1380 /**
1381  * @brief Gets a lock for a frame buffer.
1382  * @details This function should be used to prevent from rendering to the frame buffer while reading it.
1383  *   And the locking area should be short and must be released ASAP, or the render thread will be hanged.
1384  * @param[in] handler Handler of a livebox instance
1385  * @param[in] is_pd 1 for PD or 0
1386  * @privlevel platform
1387  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1388  * @return int
1389  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1390  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1391  * @retval #LB_STATUS_SUCCESS Successfully done
1392  * @see livebox_release_fb_lock()
1393  */
1394 extern int livebox_acquire_fb_lock(struct livebox *handler, int is_pd);
1395
1396 /**
1397  * @brief Releases a lock of the frame buffer.
1398  * @details This function should be called ASAP after acquiring a lock of FB, or the render process will be blocked.
1399  * @param[in] handler Handler of a livebox instance
1400  * @param[in] is_pd 1 for PD or 0
1401  * @privlevel platform
1402  * @privileve %http://developer.samsung.com/privilege/core/dynamicbox.viewer
1403  * @return int
1404  * @retval #LB_STATUS_ERROR_FAULT Unrecoverable error occurred
1405  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
1406  * @retval #LB_STATUS_SUCCESS Successfully done
1407  * @see livebox_acquire_fb_lock()
1408  */
1409 extern int livebox_release_fb_lock(struct livebox *handler, int is_pd);
1410
1411 /**
1412  * @brief Sets options for controlling a livebox sub-system.
1413  * @details
1414  *   LB_OPTION_FRAME_DROP_FOR_RESIZE
1415  *     While resizing the box, viewer doesn't want to know the updated frames of an old size content anymore.
1416  *     In that case, turn this on, the provider will not send the updated event to the viewer about an old content.
1417  *     So the viewer can reduce its burden to update unnecessary frames.
1418  *   LB_OPTION_MANUAL_SYNC
1419  *     If you don't want to update frames automatically, or you want only reload the frames by your hands, (manually)
1420  *     Turn this on.
1421  *     After turnning it on, you should sync it using livebox_sync_pd_fb and livebox_sync_lb_pfb.
1422  *   LB_OPTION_SHARED_CONTENT
1423  *     If this option is turnned on, even though you create a new livebox,
1424  *     if there are already added same instances that have same contents, the instance will not be created again.
1425  *     Instead of creating a new instance, a viewer will provide an old instance with a new handle.
1426  * @param[in] option Option which will be affected by this call
1427  * @param[in] state New value for given option
1428  * @privlevel N/P
1429  * @return int
1430  * @retval #LB_STATUS_ERROR_INVALID Unknown option
1431  * @retval #LB_STATUS_ERROR_FAULT Failed to change the state of option
1432  * @retval #LB_STATUS_SUCCESS Successfully changed
1433  * @see livebox_get_option()
1434  * @see livebox_sync_pd_fb()
1435  * @see livebox_sync_lb_fb()
1436  */
1437 extern int livebox_set_option(enum livebox_option_type option, int state);
1438
1439 /**
1440  * @brief Gets options of a livebox sub-system.
1441  * @param[in] option Type of option
1442  * @privlevel N/P
1443  * @return int
1444  * @retval #LB_STATUS_ERROR_INVALID Invalid option
1445  * @retval #LB_STATUS_ERROR_FAULT Failed to get option
1446  * @retval >=0 Value of given option (must be >=0)
1447  * @see livebox_set_option()
1448  */
1449 extern int livebox_option(enum livebox_option_type option);
1450
1451
1452 /**
1453  * @brief Set a handler for launching an app for auto-launch feature
1454  * @details If a user clicks a box, and the box uses auto-launch option, the launcher_handler will be called.
1455  * @param[in] launch_handler Handler for launching an app manually
1456  * @param[in] data Callback data which will be given a data for launch_handler
1457  * @privlevel N/P
1458  * @return int type
1459  * @retval #LB_STATUS_SUCCESS Succeed to set new handler. there is no other cases
1460  */
1461 extern int livebox_set_auto_launch_handler(int (*launch_handler)(struct livebox *handler, const char *appid, void *data), void *data);
1462
1463 /**
1464  * @}
1465  */
1466
1467 #ifdef __cplusplus
1468 }
1469 #endif
1470
1471 #endif