include/livebox.h

   1 /*
   2  * Copyright 2012  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.0 (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://www.tizenopensource.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 struct livebox;
  25
  26 /*!
  27  * \note size list
  28  * 172x172
  29  * 348x172
  30  * 348x348
  31  * 700x348
  32  * 700x172
  33  * 700x700
  34  */
  35 #define DEFAULT_PERIOD -1.0f
  36
  37 enum content_event_type {
  38         LB_MOUSE_DOWN = 0x0001, /*!< LB mouse down event for livebox */
  39         LB_MOUSE_UP = 0x0002, /*!< LB mouse up event for livebox */
  40         LB_MOUSE_MOVE = 0x0004, /*!< LB mouse move event for livebox */
  41         LB_MOUSE_ENTER = 0x0008, /*!< LB mouse enter event for livebox */
  42         LB_MOUSE_LEAVE = 0x0010, /*!< LB mouse leave event for livebox */
  43
  44         PD_MOUSE_DOWN = 0x0100, /*!< PD mouse down event for livebox */
  45         PD_MOUSE_UP = 0x0200, /*!< PD mouse up event for livebox */
  46         PD_MOUSE_MOVE = 0x0400, /*!< PD mouse move event for livebox */
  47         PD_MOUSE_ENTER = 0x0800, /*!< PD mouse enter event for livebox */
  48         PD_MOUSE_LEAVE = 0x1000, /*!< PD mouse leave event for livebox */
  49
  50         PD_EVENT_MAX = 0xFFFFFFFF,
  51 };
  52
  53 /* Exported to user app */
  54 enum livebox_lb_type {
  55         LB_TYPE_IMAGE = 0x01, /*!< Contents of a livebox is based on the image file */
  56         LB_TYPE_BUFFER = 0x02, /*!< Contents of a livebox is based on canvas buffer(shared) */
  57         LB_TYPE_TEXT = 0x04, /*!< Contents of a livebox is based on formatted text file */
  58         LB_TYPE_PIXMAP = 0x08, /*!< Contens of a livebox is shared by the pixmap(depends on X) */
  59
  60         LB_TYPE_INVALID = 0xFF,
  61 };
  62
  63 enum livebox_pd_type {
  64         PD_TYPE_BUFFER = 0x01, /*!< Contents of a PD is based on canvas buffer(shared) */
  65         PD_TYPE_TEXT = 0x02, /*!< Contents of a PD is based on formatted text file */
  66         PD_TYPE_PIXMAP = 0x04, /*!< Contents of a livebox is shared by the pixmap(depends on X) */
  67
  68         PD_TYPE_INVALID = 0xFF,
  69 };
  70
  71 enum livebox_event_type { /*!< livebox_event_handler_set Event list */
  72         LB_EVENT_LB_UPDATED, /*!< Contents of the given livebox is updated */
  73         LB_EVENT_PD_UPDATED, /*!< Contents of the given pd is updated */
  74
  75         LB_EVENT_CREATED, /*!< A new livebox is created */
  76         LB_EVENT_DELETED, /*!< A livebox is deleted */
  77
  78         LB_EVENT_GROUP_CHANGED, /*!< Group (Cluster/Sub-cluster) information is changed */
  79         LB_EVENT_PINUP_CHANGED, /*!< PINUP status is changed */
  80         LB_EVENT_PERIOD_CHANGED, /*!< Update period is changed */
  81
  82         LB_EVENT_PD_CREATED, /*!< If a PD is created even if you didn't call the livebox_create_pd API */
  83         LB_EVENT_PD_DESTROYED, /*!< If a PD is destroyed even if you didn't call the livebox_destroy_pd API */
  84
  85         LB_EVENT_IGNORED, /*!< Request is ignored */
  86 };
  87
  88 enum livebox_fault_type {
  89         LB_FAULT_DEACTIVATED, /*!< Livebox is deactivated by its fault operation */
  90         LB_FAULT_PROVIDER_DISCONNECTED, /*!< Provider is disconnected */
  91 };
  92
  93 enum livebox_visible_state { /*!< Must be sync'd with the provider */
  94         LB_SHOW = 0x00, /*!< Livebox is showed. Default state */
  95         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 */
  96
  97         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 */
  98
  99         LB_VISIBLE_ERROR = 0xFFFFFFFF, /* To enlarge the size of this enumeration type */
 100 };
 101
 102 /*!
 103  * \note
 104  * TEXT type livebox contents handling opertators.
 105  */
 106 struct livebox_script_operators {
 107         int (*update_begin)(struct livebox *handle); /*!< Content parser is started */
 108         int (*update_end)(struct livebox *handle); /*!< Content parser is stopped */
 109
 110         /*!
 111          * \brief
 112          * Listed functions will be called when parser meets each typed component
 113          */
 114         int (*update_text)(struct livebox *handle, const char *id, const char *part, const char *data); /*!< Update text content */
 115         int (*update_image)(struct livebox *handle, const char *id, const char *part, const char *data); /*!< Update image content */
 116         int (*update_script)(struct livebox *handle, const char *id, const char *part, const char *file, const char *group); /*!< Update script content */
 117         int (*update_signal)(struct livebox *handle, const char *id, const char *emission, const char *signal); /*!< Update signal */
 118         int (*update_drag)(struct livebox *handle, const char *id, const char *part, double dx, double dy); /*!< Update drag info */
 119         int (*update_info_size)(struct livebox *handle, const char *id, int w, int h); /*!< Update content size */
 120         int (*update_info_category)(struct livebox *handle, const char *id, const char *category); /*!< Update content category info */
 121 };
 122
 123 /*!
 124  * \brief Prototype of the return callback of every async functions.
 125  * \param[in] handle
 126  * \param[in] ret
 127  * \param[in] data
 128  * \return void
 129  */
 130 typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data);
 131
 132 /*!
 133  * \brief Initialize the livebox system
 134  * \param[in] disp
 135  * \return int
 136  */
 137 extern int livebox_init(void *disp);
 138
 139 /*!
 140  * \brief Finalize the livebox system
 141  * \return int
 142  */
 143 extern int livebox_fini(void);
 144
 145 /*!
 146  * \brief Add a new livebox
 147  * \param[in] pkgname
 148  * \param[in] content
 149  * \param[in] cluster
 150  * \param[in] category
 151  * \param[in] period
 152  * \param[in] cb
 153  * \param[in] data
 154  * \return handle
 155  */
 156 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);
 157 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);
 158
 159 /*!
 160  * \brief Delete a livebox
 161  * \param[in] handle
 162  * \param[in] ret_cb_t return callback
 163  * \param[in] data user data for return callback
 164  * \return int
 165  */
 166 extern int livebox_del(struct livebox *handler, ret_cb_t cb, void *data);
 167
 168 /*!
 169  * \brief Set a livebox events callback
 170  * \param[in] cb Event handler
 171  * \param[in] data User data for the event handler
 172  * \return int
 173  * \sa livebox_unset_event_handler
 174  */
 175
 176 extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data);
 177
 178 /*!
 179  * \brief Unset the livebox event handler
 180  * \param[in] cb
 181  * \return void * pointer of 'data' which is registered from the livebox_event_handler_set
 182  * \sa livebox_set_event_handler
 183  */
 184 extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data));
 185
 186 /*!
 187  * \note
 188  *   argument list
 189  *      event, pkgname, filename, funcname
 190  *
 191  * \brief Live box fault event handler registeration function
 192  * \param[in] cb
 193  * \param[in] data
 194  * \return int
 195  * \sa livebox_unset_fault_handler
 196  */
 197 extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data);
 198
 199 /*!
 200  * \brief Unset the live box fault event handler
 201  * \param[in] cb
 202  * \return pointer of 'data'
 203  * \sa livebox_set_fault_handler
 204  */
 205 extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *));
 206
 207 /*!
 208  * \brief Activate the faulted livebox.
 209  * \param[in] pkgname
 210  * \param[in] cb
 211  * \param[in] data
 212  * \return int
 213  */
 214 extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data);
 215
 216 /*!
 217  * \brief Resize the livebox
 218  * \param[in] handler Handler of a livebox
 219  * \param[in] type Type of a livebox size, LB_SIZE_TYPE_1x1, ...
 220  * \param[in] cb Result callback of the resize operation.
 221  * \param[in] data User data for return callback
 222  * \return int
 223  */
 224 extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data);
 225
 226 /*!
 227  * \brief Send the click event for a livebox.
 228  * \param[in] handler Handler of a livebox
 229  * \param[in] x Rational X of the content width.
 230  * \param[in] y Rational Y of the content height.
 231  * \return int
 232  */
 233 extern int livebox_click(struct livebox *handler, double x, double y);
 234
 235 /*!
 236  * \brief Change the cluster/sub-cluster name of given livebox handler
 237  * \param[in] handler Handler of a livebox
 238  * \param[in] cluster New cluster of a livebox
 239  * \param[in] category New category of a livebox
 240  * \param[in] cb Result callback for changing the cluster/category of a livebox
 241  * \param[in] data User data for the result callback
 242  * \return int
 243  */
 244 extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data);
 245
 246 /*!
 247  * \brief Get the cluster and category(sub-cluster) name of given livebox (It is not I18N format, only english)
 248  * \param[in] handler Handler of a livebox
 249  * \param[out] cluster Storage(memory) for containing the cluster name
 250  * \param[out] category Storage(memory) for containing the category name
 251  * \return int
 252  */
 253 extern int livebox_get_group(struct livebox *handler, char ** const cluster, char ** const category);
 254
 255 /*!
 256  * \brief Get the period of this livebox handler
 257  * \param[in] handler Handler of a livebox
 258  * \return double Current update period of a livebox
 259  */
 260 extern double livebox_period(struct livebox *handler);
 261
 262 /*!
 263  * \brief Change the update period
 264  * \param[in] handler Handler of a livebox
 265  * \param[in] period New update period of a livebox
 266  * \param[in] cb Result callback of changing the update period of this livebox
 267  * \param[in] data User data for the result callback
 268  * \return int
 269  */
 270 extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data);
 271
 272 /*!
 273  * \brief Is this an text type livebox?
 274  * \param[in] handler
 275  * \return content_type
 276  */
 277 extern enum livebox_lb_type livebox_lb_type(struct livebox *handler);
 278
 279 /*!
 280  * \brief Is this livebox is created by a user?
 281  * \param[in] handler
 282  * \return int
 283  */
 284 extern int livebox_is_user(struct livebox *handler);
 285
 286 /*!
 287  * \brief Get the content information string of given livebox
 288  * \param[in] handler
 289  * \return content
 290  */
 291 extern const char *livebox_content(struct livebox *handler);
 292
 293 /*!
 294  * \brief Get the sub cluster title string of given livebox
 295  * \param[in] handler
 296  * \return sub cluster title
 297  */
 298 extern const char *livebox_category_title(struct livebox *handler);
 299
 300 /*!
 301  * \brief Get the filename of given livebox, if it is an IMAGE type livebox
 302  * \param[in] handler
 303  * \return filename
 304  */
 305 extern const char *livebox_filename(struct livebox *handler);
 306
 307 /*!
 308  * \brief Get the package name of given livebox handler
 309  * \param[in] handler
 310  * \return pkgname
 311  */
 312 extern const char *livebox_pkgname(struct livebox *handler);
 313
 314 /*!
 315  * \brief Get the priority of a current content.
 316  * \param[in] handler
 317  * \return priority
 318  */
 319 extern double livebox_priority(struct livebox *handler);
 320
 321 /*!
 322  * \brief Acquire the buffer of given livebox (Only for the buffer type)
 323  * \param[in] handler
 324  * \return address of a FB
 325  */
 326 extern void *livebox_acquire_fb(struct livebox *handler);
 327
 328 /*!
 329  * \brief Release the buffer of a livebox (Only for the buffer type)
 330  * \param[in] buffer
 331  * \return int
 332  */
 333 extern int livebox_release_fb(void *buffer);
 334
 335 /*!
 336  * \brief Get the reference count of Livebox buffer (Only for the buffer type)
 337  * \param[in] buffer
 338  * \return int
 339  */
 340 extern int livebox_fb_refcnt(void *buffer);
 341
 342 /*!
 343  * \brief Acquire the buffer of a PD frame (Only for the buffer type)
 344  * \param[in] handler
 345  * \return int
 346  */
 347 extern void *livebox_acquire_pdfb(struct livebox *handler);
 348
 349 /*!
 350  * \brief Release the acquired buffer of the PD Frame (Only for the buffer type)
 351  * \param[in] buffer
 352  * \return int
 353  */
 354 extern int livebox_release_pdfb(void *buffer);
 355
 356 /*!
 357  * \brief Reference count of given PD buffer (Only for the buffer type)
 358  * \param[in] buffer
 359  * \return int
 360  */
 361 extern int livebox_pdfb_refcnt(void *buffer);
 362
 363 /*!
 364  * \brief Get the size of the Livebox
 365  * \param[in] handler
 366  * \param[out] w
 367  * \param[out] h
 368  * \return int
 369  */
 370 extern int livebox_size(struct livebox *handler);
 371
 372 /*!
 373  * \brief Get the size of the Progressive Disclosure
 374  * \param[in] handler
 375  * \param[out] w
 376  * \param[out] h
 377  * \return int
 378  */
 379 extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h);
 380
 381 /*!
 382  * \brief List of supported sizes of given handler
 383  * \param[in] handler
 384  * \param[out] cnt
 385  * \param[out] w
 386  * \param[out] h
 387  * \return int
 388  */
 389 extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list);
 390
 391 /*!
 392  * \brief BUFFER SIZE of the livebox if it is a buffer type
 393  * \param[in] handler
 394  * \return int
 395  */
 396 extern int livebox_lbfb_bufsz(struct livebox *handler);
 397
 398 /*!
 399  * \brief BUFFER SIZE of the progiressive disclosure if it is a buffer type
 400  * \param[in] handler
 401  * \return int
 402  */
 403 extern int livebox_pdfb_bufsz(struct livebox *handler);
 404
 405 /*!
 406  * \brief Send the content event (for buffer type) to provider(livebox)
 407  * \param[in] handler
 408  * \param[in] type
 409  * \param[in] x
 410  * \param[in] y
 411  */
 412 extern int livebox_content_event(struct livebox *handler, enum content_event_type type, double x, double y);
 413
 414 /*!
 415  * \brief Do pin up or not.
 416  * \param[in] handler
 417  * \param[in] flag
 418  * \param[in] cb
 419  * \param[in] data
 420  * \return int
 421  */
 422 extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data);
 423
 424 /*!
 425  * \brief Check the PIN-UP status of given handler
 426  * \param[in] handler
 427  * \return int
 428  */
 429 extern int livebox_is_pinned_up(struct livebox *handler);
 430
 431 /*!
 432  * \brief Check the PINUP feature availability of the given handler
 433  * \param[in] handler
 434  * \return int
 435  */
 436 extern int livebox_has_pinup(struct livebox *handler);
 437
 438 /*!
 439  * \brief Check the PD existence of given handler
 440  * \param[in] handler
 441  * \return int
 442  */
 443 extern int livebox_has_pd(struct livebox *handler);
 444
 445 /*!
 446  * \brief Create the PD of given handler
 447  * \param[in] handler
 448  * \param[in] cb
 449  * \param[in] data
 450  * \return int
 451  */
 452 extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data);
 453
 454 /*!
 455  * \brief Create the PD of given handler with the relative position from livebox
 456  * \param[in] handler
 457  * \param[in] x 0.0 ~ 1.0
 458  * \param[in] y 0.0 ~ 1.0
 459  * \param[in] cb
 460  * \param[in] data
 461  * \return int
 462  */
 463 extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data);
 464
 465 /*!
 466  * \brief Destroy the PD of given handler if it is created.
 467  * \param[in] handler
 468  * \param[in] cb
 469  * \param[in] data
 470  * \return int
 471  */
 472 extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data);
 473
 474 /*!
 475  * \brief Check the create status of given livebox handler
 476  * \param[in] handler
 477  * \return int
 478  */
 479 extern int livebox_pd_is_created(struct livebox *handler);
 480
 481 /*!
 482  * \brief Check the content type of the progressive disclosure of given handler
 483  * \param[in] handler
 484  * \return int
 485  */
 486 extern enum livebox_pd_type livebox_pd_type(struct livebox *handler);
 487
 488 /*!
 489  * \brief Check the existence of a livebox about given package name
 490  * \param[in] pkgname
 491  * \return int
 492  */
 493 extern int livebox_is_exists(const char *pkgname);
 494
 495 /*!
 496  * \brief Set function table for parsing the text content of a livebox
 497  * \param[in] handler
 498  * \param[in] ops
 499  * \return int
 500  */
 501 extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
 502
 503 /*!
 504  * \brief Set function table for parsing the text content of a Progressive Disclosure
 505  * \param[in] handler
 506  * \param[in] ops
 507  * \return int
 508  */
 509 extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
 510
 511 /*!
 512  * \brief Emit a text signal to given livebox only if it is a text type.
 513  * \param[in] handler
 514  * \param[in] emission
 515  * \param[in] source
 516  * \param[in] sx
 517  * \param[in] sy
 518  * \param[in] ex
 519  * \param[in] ey
 520  * \param[in] cb
 521  * \param[in] data
 522  */
 523 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);
 524
 525 /*!
 526  * \brief Set a private data pointer to carry it using given handler
 527  * \param[in] handler
 528  * \param[in] data
 529  * \return int
 530  */
 531 extern int livebox_set_data(struct livebox *handler, void *data);
 532
 533 /*!
 534  * \brief Get private data pointer which is carried by given handler
 535  * \param[in] handler
 536  * \return int
 537  */
 538 extern void *livebox_get_data(struct livebox *handler);
 539
 540 /*!
 541  * \brief Subscribe the event for liveboxes only in given cluster and sub-cluster
 542  * \param[in] cluster   "*" can be used for subscribe all cluster's liveboxes event.
 543  *                      If you use the "*", value in the category will be ignored.
 544  * \param[in] category  "*" can be used for subscribe liveboxes events of all category(sub-cluster) in given "cluster"
 545  * \return int Success 0, fails error code
 546  */
 547 extern int livebox_subscribe_group(const char *cluster, const char *category);
 548
 549 /*!
 550  * \brief Unsubscribe the event for the liveboxes, but you will receive already added liveboxes event.
 551  * \param[in] cluster   "*" can be used for subscribe all cluster's liveboxes event.
 552  *                      If you use the "*", value in the category will be ignored.
 553  * \param[in] category  "*" can be used for subscribe all sub-cluster's liveboxes event in given "cluster"
 554  * \return int Success 0, fails error code
 555  */
 556 extern int livebox_unsubscribe_group(const char *cluster, const char *category);
 557
 558 /*!
 559  * \brief Refresh the group(cluster/sub-cluser(aka. category))
 560  * \param[in] cluster Cluster ID
 561  * \param[in] category Sub-cluster ID
 562  * \return int Success 0 or negative value
 563  */
 564 extern int livebox_refresh_group(const char *cluster, const char *category);
 565
 566 /*!
 567  * \brief Pixmap Id of a livebox content
 568  * \param[in] handler
 569  * \return int
 570  * \sa livebox_pd_pixmap
 571  */
 572 extern int livebox_lb_pixmap(const struct livebox *handler);
 573
 574 /*!
 575  * \brief Pixmap Id of a PD content
 576  * \param[in] handler
 577  * \return int
 578  * \sa livebox_lb_pixmap
 579  */
 580 extern int livebox_pd_pixmap(const struct livebox *handler);
 581
 582 /*!
 583  * \brief
 584  * \param[in] handler
 585  * \param[in] cb
 586  * \param[in] data
 587  * \return int
 588  * \sa livebox_release_pd_pixmap
 589  * \sa livebox_acquire_lb_pixmap
 590  */
 591 extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
 592
 593 /*!
 594  * \brief Release the acquired pixmap ID
 595  * \param[in] handler
 596  * \param[in] pixmap
 597  * \return int
 598  * \sa livebox_acquire_pd_pixmap
 599  * \sa livebox_release_lb_pixmap
 600  */
 601 extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap);
 602
 603 /*!
 604  * \brief
 605  * \param[in] handler
 606  * \param[in] cb
 607  * \param[in] data
 608  * \return int
 609  * \sa livebox_release_lb_pixmap
 610  * \sa livebox_acquire_pd_pixmap
 611  */
 612 extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
 613
 614 /*!
 615  * \brief
 616  * \param[in] handler
 617  * \param[in] pixmap
 618  * \return int
 619  * \sa livebox_acquire_lb_pixmap
 620  * \sa livebox_release_pd_pixmap
 621  */
 622 extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap);
 623
 624 /*!
 625  * \brief Update the visible state of a livebox
 626  * \param[in] handler Handler of a livebox
 627  * \param[in] state Configure the current visible state of a livebox
 628  * \return int
 629  */
 630 extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state);
 631
 632 /*!
 633  * \brief Current visible state of a livebox
 634  * \param[in] handler Handler of a livebox
 635  * \return enum visible state
 636  */
 637 extern enum livebox_visible_state livebox_visibility(struct livebox *handler);
 638
 639 #ifdef __cplusplus
 640 }
 641 #endif
 642
 643 #endif
 644 /* End of a file */