livebox/include/livebox_product.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_HELPER_PRODUCT_H
  18 #define __LIVEBOX_HELPER_PRODUCT_H
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /**
  25  * @file livebox_product.h
  26  * @brief This file declares API of liblivebox library for product
  27  */
  28
  29 /**
  30  * @addtogroup CAPI_LIVEBOX_HELPER_PRODUCT_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Structure for a livebox buffer defined by a provider.
  36  */
  37 struct livebox_buffer;
  38
  39 extern const int DONE; /**<Return values of livebox programming interfaces: Operation is successfully done.*/
  40
  41 extern const int OUTPUT_UPDATED; /**<Return values of livebox programming interfaces: Contents are updated.*/
  42
  43 extern const int NEED_TO_SCHEDULE; /**<Return values of livebox programming interfaces: Need to call the livebox_need_to_update and livebox_update_content.*/
  44
  45 extern const int FORCE_TO_SCHEDULE; /**<Return values of livebox programming interfaces: Need to do force update.*/
  46
  47 extern const int NEED_TO_CREATE; /**<Return values of livebox programming interfaces: Need to create a new instance.*/
  48
  49 extern const int NEED_TO_DESTROY; /**<Return values of livebox programming interfaces: Need to destroy this instance.*/
  50
  51 extern const int NEED_TO_UPDATE; /**<Return values of livebox programming interfaces: Need to update.*/
  52
  53 extern const int USE_NET; /**<Return values of livebox programming interfaces: Using network.*/
  54
  55 extern const int LB_SYS_EVENT_FONT_CHANGED; /**<System event type: System font is changed.*/
  56
  57 extern const int LB_SYS_EVENT_LANG_CHANGED; /**<System event type: System language is changed.*/
  58
  59 extern const int LB_SYS_EVENT_TIME_CHANGED; /**<System event type: System time is changed.*/
  60
  61 extern const int LB_SYS_EVENT_REGION_CHANGED; /**<System event type: Region changed. */
  62
  63 extern const int LB_SYS_EVENT_TTS_CHANGED; /**< System event type: Accessibility changed. */
  64
  65 extern const int LB_SYS_EVENT_PAUSED; /**<System event type: Livebox is paused.*/
  66
  67 extern const int LB_SYS_EVENT_RESUMED; /**<System event type: Livebox is resumed.*/
  68
  69 extern const int LB_SYS_EVENT_MMC_STATUS_CHANGED; /**<System event type: MMC Status change event.*/
  70
  71 extern const int LB_SYS_EVENT_DELETED;/**<System event type: Livebox instance is removed from a viewer.*/
  72
  73 /**
  74  * @brief Structure for extra event information for livebox_content_event interface function.
  75  */
  76 #if !defined(__SCRIPT_EVENT_INFO)
  77 #define __SCRIPT_EVENT_INFO
  78 /**
  79  * @brief
  80  * Text signal & Content event uses this data structure.
  81  */
  82 struct event_info {
  83         struct pointer {
  84                 double x; /**< X value of current mouse(touch) position */
  85                 double y; /**< Y value of current mouse(touch) position */
  86                 int down; /**< Is it pressed(1) or not(0) */
  87         } pointer;
  88
  89         struct part {
  90                 double sx; /**< Pressed object's left top X */
  91                 double sy; /**< Pressed object's left top Y */
  92                 double ex; /**< Pressed object's right bottom X */
  93                 double ey; /**< Pressed object's right bottom Y */
  94         } part;
  95 };
  96 #endif
  97
  98 /**
  99  * @brief Notifies the updated content to the provider.
 100  * @details Forcedly notifies the updated contents.
 101  *    This function can be used from async callback function to notify the updated content.
 102  * @param[in] id Instance Id which is passed to you via the first parameter of every livebox_XXXX interface functions
 103  * @param[in] is_pd 1 for updating content of PD or 0(for content of LB)
 104  * @privlevel N/P
 105  * @return int type
 106  * @retval #LB_STATUS_ERROR_MEMORY Not enough memory
 107  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 108  * @retval #LB_STATUS_ERROR_IO I/O failed, Cannot access given resource file(id)
 109  * @retval #LB_STATUS_SUCCESS Successfully notified
 110  * @pre This API only can be used after loaded into the data-provider-slave process.
 111  */
 112 extern int livebox_content_is_updated(const char *id, int is_pd);
 113
 114 /**
 115  * @brief Replaces "\n" (new line character) with &lt;br&gt; tag.
 116  * @details This utility function is used to replace all NEW LINE CHARACTER ("\n") with &lt;br&gt; tag.
 117  * @param[in] str Source string
 118  * @privlevel N/P
 119  * @return char * type
 120  * @retval string Allocted in the heap
 121  * @retval @c NULL If it fails to replace string
 122  * @post Returned string must has to be free'd by user manually.
 123  */
 124 extern char *livebox_util_nl2br(const char *str);
 125
 126 /*
 127  * Interfaces for direct buffer management (Available only for the PD area).
 128  */
 129 #ifndef __PROVIDER_BUFFER_H
 130 /**
 131  * @brief Enumeration for value should be sync'd with provider.
 132  */
 133 enum buffer_event {
 134         BUFFER_EVENT_ENTER, /**< Mouse cursor enter */
 135         BUFFER_EVENT_LEAVE, /**< Mouse cursor leave */
 136         BUFFER_EVENT_DOWN, /**< Mouse down */
 137         BUFFER_EVENT_MOVE, /**< Mouse move */
 138         BUFFER_EVENT_UP, /**< Mouse up */
 139
 140         BUFFER_EVENT_KEY_DOWN, /**< Key down */
 141         BUFFER_EVENT_KEY_UP, /**< Key up */
 142         BUFFER_EVENT_KEY_FOCUS_IN, /**< Key focus in */
 143         BUFFER_EVENT_KEY_FOCUS_OUT, /**< Key focus out */
 144
 145         BUFFER_EVENT_HIGHLIGHT, /**< Accessibility - Highlight */
 146         BUFFER_EVENT_HIGHLIGHT_NEXT, /**< Accessibility - Move highlight to next */
 147         BUFFER_EVENT_HIGHLIGHT_PREV, /**< Accessibility - Move highlight to prev */
 148         BUFFER_EVENT_ACTIVATE, /**< Accessibility - Activate the highlighted object */
 149         BUFFER_EVENT_ACTION_UP, /**< Accessibility - Make UP action */
 150         BUFFER_EVENT_ACTION_DOWN, /**< Accessibility - Make Down action */
 151         BUFFER_EVENT_SCROLL_UP, /**< Accessibility - Scroll up */
 152         BUFFER_EVENT_SCROLL_MOVE, /**< Accessibility - Scroll move */
 153         BUFFER_EVENT_SCROLL_DOWN, /**< Accessibility - Scroll down */
 154         BUFFER_EVENT_UNHIGHLIGHT, /**< Accessibility - Remove highlight */
 155
 156         BUFFER_EVENT_ON_HOLD,   /**< To prevent from generating mouse clicked event */
 157         BUFFER_EVENT_OFF_HOLD,  /**< Stopped holding. */
 158         BUFFER_EVENT_ON_SCROLL, /**< On scrolling */
 159         BUFFER_EVENT_OFF_SCROLL, /**< Scrolling stopped */
 160
 161         /* Accessibility event */
 162         BUFFER_EVENT_VALUE_CHANGE,
 163         BUFFER_EVENT_MOUSE,
 164         BUFFER_EVENT_BACK,
 165         BUFFER_EVENT_OVER,
 166         BUFFER_EVENT_READ,
 167         BUFFER_EVENT_ENABLE,
 168         BUFFER_EVENT_DISABLE
 169 };
 170
 171 struct buffer_event_data {
 172         enum buffer_event type; /**< Mouse, Keyboard, Accessibility event type */
 173         double timestamp; /**< Timestamp of events */
 174
 175         union input_data {
 176                 struct mouse {
 177                         int x; /**< If the event type is for accessibility or mouse, coordinates of X for pointer */
 178                         int y; /**< If the event type is for accessibility or mouse, coordinates of Y for pointer */
 179                 } pointer;
 180
 181                 struct access {
 182                         int x;
 183                         int y;
 184                         unsigned int mouse_type;
 185                         unsigned int action_type;
 186                         unsigned int action_by;
 187                         int cycle;
 188                 } access;
 189
 190                 unsigned int keycode; /**< If the event type is for keyboard, the value of keycode */
 191         } info;
 192 };
 193 #endif
 194
 195 /**
 196  * @brief Acquires a buffer for PD or LB, currently only the PD is supported.
 197  * @param[in] id Instance Id which is passed to you via the first parameter of every livebox_XXXX interface functions
 198  * @param[in] is_pd 1 for PD or 0 for livebox
 199  * @param[in] width Width in pixel
 200  * @param[in] height Height in pixel
 201  * @param[in] pixels Size of a pixel in bytes
 202  * @param[in] handler Event handling callback
 203  * @param[in] data User data for event handling callback
 204  * @privlevel platform
 205  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 206  * @return Buffer handle
 207  * @retval @c NULL Failed to acquire buffer
 208  * @retval handler Handle object
 209  * @pre Given instance must be specify its type as buffer. or this API will be fail.
 210  * @post Allocated buffer object must be released via livebox_release_buffer().
 211  * @see livebox_acquire_buffer()
 212  */
 213 extern struct livebox_buffer *livebox_acquire_buffer(const char *id, int is_pd, int width, int height, int pixels, int auto_align, int (*handler)(struct livebox_buffer *, struct buffer_event_data *, void *), void *data);
 214
 215 /**
 216  * @brief Acquires the ID of pixmap resource.
 217  * @details Only if the provider uses pixmap for providing render buffer.
 218  * @remarks Pixmap Id can be destroyed if you call the livebox_release_buffer(). Then this pixmap Id is not guaranteed to use.
 219  * @param[in] handle Buffer handle
 220  * @privlevel N/P
 221  * @return unsigned log type
 222  * @retval positive Pixmap Id
 223  * @retval 0 Failed to get pixmap Id
 224  * @pre The system must be set to use the pixmap method for content sharing.
 225  * @see livebox_acquire_buffer()
 226  */
 227 extern unsigned long livebox_pixmap_id(struct livebox_buffer *handle);
 228
 229 /**
 230  * @brief Releases the buffer of livebox.
 231  * @param[in] handle Buffer handle
 232  * @privlevel platform
 233  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 234  * @return int type
 235  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 236  * @retval #LB_STATUS_SUCCESS Successfully released
 237  * @pre Handle must be created using livebox_acquire_buffer().
 238  * @see livebox_acquire_buffer()
 239  */
 240 extern int livebox_release_buffer(struct livebox_buffer *handle);
 241
 242 /**
 243  * @brief Gets the address of S/W render buffer.
 244  * @details If you try to use this, after livebox_create_hw_buffer(), you will get @c NULL.
 245  * @param[in] handle Buffer handle
 246  * @privlevel platform
 247  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 248  * @return void* address of the render buffer
 249  * @retval @c NULL If it falis to get buffer address
 250  * @retval address If it succeed to get the buffer address
 251  * @see livebox_unref_buffer()
 252  */
 253 extern void *livebox_ref_buffer(struct livebox_buffer *handle);
 254
 255 /**
 256  * @brief Releases the S/W render buffer.
 257  * @param[in] buffer Address of render buffer
 258  * @privlevel platform
 259  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 260  * @return int type
 261  * @retval #LB_STATUS_ERROR_INVALID Invalid handle
 262  * @retval #LB_STATUS_SUCCESS Successfully unreference
 263  * @pre livebox_ref_buffer() must be called.
 264  * @see livebox_ref_buffer()
 265  */
 266 extern int livebox_unref_buffer(void *buffer);
 267
 268 /**
 269  * @brief Synchronizes the updated buffer.
 270  * @details This is only needed for non-H/W accelerated buffer.
 271  * @param[in] handle Buffer handle
 272  * @privlevel platform
 273  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 274  * @return int type
 275  * @retval #LB_STATUS_SUCCESS Successfully sync'd
 276  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 277  * @see livebox_acquire_buffer()
 278  */
 279 extern int livebox_sync_buffer(struct livebox_buffer *handle);
 280
 281 /**
 282  * @brief Requests to schedule the update operation to a provider.
 283  * @param[in] id Instance Id which is passed to you via the first parameter of every livebox_XXXX interface functions
 284  * @privlevel platform
 285  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 286  * @return If succes returns 0 or return less than 0
 287  * @retval #LB_STATUS_SUCCESS Successfully triggered
 288  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 289  * @retval #LB_STATUS_ERROR_MEMORY Not enough memory
 290  * @retval #LB_STATUS_ERROR_NOT_EXIST Given id instance is not exist
 291  */
 292 extern int livebox_request_update(const char *id);
 293
 294 /**
 295  * @brief Checks whether the livebox supports H/W acceleration or not.
 296  * @param[in] handle Buffer handle
 297  * @privlevel N/P
 298  * @return int type
 299  * @retval 1 If the buffer handle support the H/W acceleration buffer
 300  * @retval 0 If it doesn not supported
 301  * @see livebox_acquire_buffer()
 302  */
 303 extern int livebox_support_hw_buffer(struct livebox_buffer *handle);
 304
 305 /**
 306  * @brief Creates the H/W accelerated buffer.
 307  * @param[in] handle Buffer handle
 308  * @privlevel platform
 309  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 310  * @return int type
 311  * @retval #LB_STATUS_ERROR_ALREADY H/W buffer is already created
 312  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 313  * @retval #LB_STATUS_SUCCESS Successfully created
 314  * @pre Must be checked whether the H/W buffer is supported or not.
 315  * @post Must be destroyed if it is not necessary.
 316  * @see livebox_support_hw_buffer()
 317  */
 318 extern int livebox_create_hw_buffer(struct livebox_buffer *handle);
 319
 320 /**
 321  * @brief Destroys the H/W accelerated buffer.
 322  * @param[in] handle Buffer handle
 323  * @privlevel platform
 324  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 325  * @return int type
 326  * @retval #LB_STATUS_SUCCESS Successfully destroyed
 327  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 328  * @pre Must be created h/w buffer using livebox_create_hw_buffer.
 329  * @see livebox_create_hw_buffer()
 330  */
 331 extern int livebox_destroy_hw_buffer(struct livebox_buffer *handle);
 332
 333 /**
 334  * @brief Gets the address of the accelerated H/W buffer.
 335  * @param[in] handle Buffer handle
 336  * @privlevel platform
 337  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 338  * @return void* type
 339  * @retval @c NULL Failed to get H/W accelerated buffer address
 340  * @retval addr H/W accelerated buffer address
 341  * @see livebox_create_hw_buffer()
 342  */
 343 extern void *livebox_buffer_hw_buffer(struct livebox_buffer *handle);
 344
 345 /**
 346  * @brief Get the stride information from the buffer info
 347  * @param[in] handle Buffer handle
 348  * @privlevel N/P
 349  * @return int stride size
 350  * @retval positive_value length of stride
 351  * @return LB_STATUS_ERROR_INVALID Invalid parameter
 352  * @return LB_STATUS_ERROR_FAULT Unrecoverable error
 353  * @see livebox_create_hw_buffer()
 354  */
 355 extern int livebox_buffer_stride(struct livebox_buffer *handle);
 356
 357 /**
 358  * @brief Pre-processes for rendering content.
 359  * @details This is only needed for accessing H/W accelerated buffer.
 360  * @param[in] handle Buffer handle
 361  * @privlevel platform
 362  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 363  * @return int type
 364  * @retval #LB_STATUS_ERROR_INVALID Invalid handle
 365  * @retval #LB_STATUS_SUCCESS Successfully done
 366  * @post livebox_buffer_post_render must be called after the rendering (accessing buffer) is completed.
 367  * @see livebox_support_hw_buffer()
 368  * @see livebox_buffer_post_render()
 369  */
 370 extern int livebox_buffer_pre_render(struct livebox_buffer *handle);
 371
 372 /**
 373  * @brief Post-processes for rendering content.
 374  * @param[in] handle Buffer handle
 375  * @privlevel platform
 376  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 377  * @return If succes returns 0 or return less than 0
 378  * @retval #LB_STATUS_SUCCESS If succeed
 379  * @retval #LB_STATUS_ERROR_INVALID Invalid argument
 380  * @pre livebox_buffer_pre_render must be called.
 381  * @see livebox_support_hw_buffer()
 382  * @see livebox_buffer_pre_render()
 383  */
 384 extern int livebox_buffer_post_render(struct livebox_buffer *handle);
 385
 386 /**
 387  * @brief Sends a request to the viewer (homescreen) to close the PD.
 388  * @details Even though you call this function. the homescreen can ignore it.
 389  * @param[in] pkgname Livebox Package Id
 390  * @param[in] id Instance Id which is passed to you via the first parameter of every livebox_XXXX interface functions
 391  * @param[in] reason LB_STATUS_SUCCESS(0)
 392  * @privlevel platform
 393  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 394  * @return int type
 395  * @retval #LB_STATUS_ERROR_INVALID Invalid parameters
 396  * @retval #LB_STATUS_ERROR_MEMORY Out of memory
 397  * @retval #LB_STATUS_ERROR_FAULT Failed to send a request
 398  * @retval #LB_STATUS_SUCCESS Successfully requested
 399  */
 400 extern int livebox_request_close_pd(const char *pkgname, const char *id, int reason);
 401
 402 /**
 403  * @brief Send a freeze request to the viewer (homescreen)
 404  * @details
 405  *        The viewer will get this request via event callback.
 406  *        Then it should freeze its scroller or stop moving the livebox.
 407  * @remarks If the viewer doesn't care this request, this will has no effect.
 408  * @param[in] pkgname Livebox Package Id
 409  * @param[in] id Instance Id which is passed to you via the first parameter of every livebox_XXXX interface functions
 410  * @privlevel platform
 411  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 412  * @return int type
 413  * @retval #LB_STATUS_ERROR_INVALID Invalid parameters
 414  * @retval #LB_STATUS_ERROR_MEMORY Out of memory
 415  * @retval #LB_STATUS_ERROR_FAULT Failed to send requet
 416  * @retval #LB_STATUS_SUCCESS Successfully requested
 417  * @see livebox_release_scroller()
 418  */
 419 extern int livebox_freeze_scroller(const char *pkgname, const char *id);
 420
 421 /**
 422  * @brief Send a release request to the viewer (homescreen)
 423  * @details
 424  *        The viewer will get this request via event callback.
 425  *        Then it should release its scroller or continue moving the livebox.
 426  * @remarks If the viewer doesn't care this request, this will has no effect.
 427  * @param[in] pkgname Livebox Package Id
 428  * @param[in] id Instance Id which is passed to you via the first parameter of every livebox_XXXX interface functions
 429  * @privlevel platform
 430  * @privilege %http://developer.samsung.com/privilege/core/dynamicbox.provider
 431  * @return int type
 432  * @retval #LB_STATUS_ERROR_INVALID Invalid parameters
 433  * @retval #LB_STATUS_ERROR_MEMORY Out of memory
 434  * @retval #LB_STATUS_ERROR_FAULT Failed to send requet
 435  * @retval #LB_STATUS_SUCCESS Successfully requested
 436  * @see livebox_freeze_scroller()
 437  */
 438 extern int livebox_release_scroller(const char *pkgname, const char *id);
 439
 440 /**
 441  * @brief Get the configuration value for premultiplied alpha.
 442  * @details
 443  *      If the system uses the premultiplied alpha for content,
 444  *      This function will returns 1.
 445  * @remarks This function only works with the inhouse provider.
 446  * @privlevel N/P
 447  * @return status of premultiplied alpha.
 448  * @retval 1 Content rendered with premultiplied alpha.
 449  * @retval 0 Content doesn't rendered with premultiplied alpha.
 450  */
 451 extern int livebox_conf_premultiplied_alpha(void);
 452
 453 /**
 454  * @brief Get the configuration value for AUTO Alignment of canvas buffer.
 455  * @details
 456  *      If the UIFW does not support the STRIDE information for rendering frame,
 457  *      This function will returns 1, then the livebox will automatically aligning the buffer.
 458  * @privlevel N/P
 459  * @return status of auto alignment.
 460  * @retval 1 Content will be automatically aligned by livebox.
 461  * @retval 0 Content will be aligned by UIFW, using stride information.
 462  */
 463 extern int livebox_conf_auto_align(void);
 464
 465 /**
 466  * @}
 467  */
 468
 469 #ifdef __cplusplus
 470 }
 471 #endif
 472
 473 #endif
 474 /* End of a file */