2 * Copyright 2013 Samsung Electronics Co., Ltd
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
8 * http://floralicense.org/license/
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.
17 #ifndef __LIVEBOX_HELPER_H
18 #define __LIVEBOX_HELPER_H
27 * \addtogroup CAPI_LIVEBOX_HELPER_MODULE
32 * \brief Defined by provider
34 struct livebox_buffer;
38 * Return values of livebox programming interfaces.
42 * Operation is successfully done
44 extern const int DONE;
50 extern const int OUTPUT_UPDATED;
54 * Need to call the livebox_need_to_update and livebox_update_content
56 extern const int NEED_TO_SCHEDULE;
59 * Need to do force update
61 extern const int FORCE_TO_SCHEDULE;
65 * Need to create a new instance
67 extern const int NEED_TO_CREATE;
71 * Need to destroy this instance
73 extern const int NEED_TO_DESTROY;
79 extern const int NEED_TO_UPDATE;
85 extern const int USE_NET;
89 * System font is changed
91 extern const int LB_SYS_EVENT_FONT_CHANGED;
95 * System language is changed
97 extern const int LB_SYS_EVENT_LANG_CHANGED;
101 * System time is changed
103 extern const int LB_SYS_EVENT_TIME_CHANGED;
109 extern const int LB_SYS_EVENT_REGION_CHANGED;
115 extern const int LB_SYS_EVENT_PAUSED;
121 extern const int LB_SYS_EVENT_RESUMED;
125 * MMC Status change event
127 extern const int LB_SYS_EVENT_MMC_STATUS_CHANGED;
133 extern const int LB_SYS_EVENT_DELETED;
139 #define LB_DESC_TYPE_COLOR "color"
145 #define LB_DESC_TYPE_TEXT "text"
151 #define LB_DESC_TYPE_IMAGE "image"
157 #define LB_DESC_TYPE_SIGNAL "signal"
163 #define LB_DESC_TYPE_INFO "info"
169 #define LB_DESC_TYPE_DRAG "drag"
175 #define LB_DESC_TYPE_SCRIPT "script"
179 * ACCESSIBILITY INFORMATION BLOCK
181 #define LB_DESC_TYPE_ACCESS "access"
185 * Accessibility operation.
187 #define LB_DESC_TYPE_ACCESS_OPERATION "access,operation"
191 * Set highlight on specified part
193 #define LB_DESC_DATA_ACCESS_OPERATION_HL_SET "set,hl"
197 * Remove highlight from specified part
199 #define LB_DESC_DATA_ACCESS_OPERATION_HL_UNSET "unset,hl"
203 * Move the highlight to next part
205 #define LB_DESC_DATA_ACCESS_OPERATION_HL_NEXT "next,hl"
209 * Move the highlight to previous part
211 #define LB_DESC_DATA_ACCESS_OPERATION_HL_PREV "prev,hl"
215 * Reset the chain of accessibility highlight list.
217 #define LB_DESC_DATA_ACCESS_OPERATION_RESET "reset,focus"
221 * Specify the highligt move option.
222 * If the highlight list reaches to the last object, move back to the first object.
224 #define LB_DESC_OPTION_ACCESS_HL_LOOP "cycle"
228 * [Default] Specify the highlight move option.
229 * If the highlight list reaches to the last object(or the first object),
230 * the "prev,hl", "next,hl" will be failed.
232 #define LB_DESC_OPTION_ACCESS_HL_NOLOOP "no,cycle"
236 * Extra event informatino for livebox_content_event interface function
244 } pointer; /*!< Down/Up state and mouse position */
251 } part; /*!< Geometry of event received part */
256 * Livebox description data handle structure.
261 * \brief Update a description file.
262 * \details explain api more detail
263 * \remarks must be used only by Inhouse livebox
264 * \param[in] filename
267 * \retval Handle of desc instance
268 * \pre Should be loaded by data-provider-slave
269 * \post Should be destroyed(flushed) using livebox_desc_close API
270 * \see livebox_desc_close
272 extern struct livebox_desc *livebox_desc_open(const char *filename, int for_pd);
275 * \brief Complete the description file updating
276 * \details Only if this API is called, the description data will be applied to the content of livebox(or PD).
277 * \remarks must be used only by Inhouse livebox
278 * \param[in] handle Handle which is created by livebox_desc_open function
280 * \retval LB_STATUS_SUCCESS If the flushing description data is successfully done.
281 * \retval LB_STATUS_ERROR_INVALID If the given handle is not valid.
282 * \pre handle must be created by livebox_desc_open
283 * \post Handle must not be used after return from this function
284 * \see livebox_desc_open
286 extern int livebox_desc_close(struct livebox_desc *handle);
290 * Set the category information of current description data
292 * Create a new description block for updating category information of layout object
294 * \param[in] handle Handle which is created by livebox_desc_open function
295 * \param[in] id Id string of target object.
296 * \param[in] category Category string that will be used by layout object
298 * \retval LB_STATUS_ERROR_INVALID Invalid handle
299 * \retval LB_STATUS_ERROR_MEMORY Memory is not enough to add this block
300 * \retval index Index(>=0) of added block, which can be used by livebox_desc_set_id
301 * \pre Must be called after create a handle using livebox_desc_open.
303 * \see livebox_desc_set_id
305 extern int livebox_desc_set_category(struct livebox_desc *handle, const char *id, const char *category);
309 * Set the content size
311 * Set the content size of layout
313 * \param[in] handle Handle which is created by livebox_desc_open function
314 * \param[in] id Id string of target object.
315 * \param[in] w Width in pixel
316 * \param[in] h Height in pixel
318 * \retval LB_STATUS_ERROR_INVALID Invalid argument
319 * \retval LB_STATUS_ERROR_MEMORY Not enough memory to add a new block
320 * \retval index Index(>=0) of added block Successfully added
323 * \see livebox_desc_open
324 * \see livebox_desc_set_id
326 extern int livebox_desc_set_size(struct livebox_desc *handle, const char *id, int w, int h);
330 * Set the target id of given block
331 * Only available for the script block
335 * \param[in] handle Handle which is created by livebox_desc_open function
336 * \param[in] idx Index of target block
337 * \param[in] id Id String which will be used by other livebox_desc_XXX functions
339 * \retval LB_STATUS_SUCCESS Id is successfully updated for given idx of desc block
340 * \retval LB_STATUS_ERROR_INVALID Invalid argument
341 * \retval LB_STATUS_ERROR_NOT_EXIST Given index of desc block is not exists
342 * \pre desc block should be exists which has given index "idx"
343 * \post specified Id string("id") can be used by other livebox_desc_XXXX functions
344 * \see livebox_desc_open
345 * \see livebox_desc_set_id
347 extern int livebox_desc_set_id(struct livebox_desc *handle, int idx, const char *id);
350 * \brief Add a new block
353 * \param[in] handle Handle which is created by livebox_desc_open function
354 * \param[in] id ID of source script object
355 * \param[in] type image|text|script|signal|...
356 * \param[in] part target part to update with given content(data)
357 * \param[in] data content for specified part
358 * \param[in] option option for the block. (script: group, image: option, ...)
359 * \return idx Index of current description block
360 * \retval LB_STATUS_ERROR_INVALID Invalid argument
361 * \retval LB_STATUS_ERROR_MEMORY Not enough memory to add a new desc block
362 * \retval Index index(>=0) of added desc block
363 * \pre handle must be created using livebox_desc_open
365 * \see livebox_desc_set_id
366 * \see livebox_desc_del_block
368 extern int livebox_desc_add_block(struct livebox_desc *handle, const char *id, const char *type, const char *part, const char *data, const char *option);
371 * \brief Delete a added block
373 * If you discard the added desc block, use this API and the index of created desc block.
375 * \param[in] handle Handle which is created by livebox_desc_open function
376 * \param[in] idx Index of added block, returned from livebox_desc_add_block, livebox_desc_set_size, livebox_desc_set_category, ...
378 * \retval LB_STATUS_SUCCESS Successfully deleted
379 * \retval LB_STATUS_ERROR_NOT_EXIST Given index of desc block is not exists
380 * \pre index must be exists.
382 * \see livebox_desc_add_block
383 * \see livebox_desc_open
385 extern int livebox_desc_del_block(struct livebox_desc *handle, int idx);
388 * \brief Notify the updated content to the provider.
390 * Forcely notify the updated contents.
391 * This function can be used from async callback function to notify the updated content.
393 * \param[in] id Instance Id which is passed to you via the first parameter of every livebox_XXXX interface functions.
394 * \param[in] is_pd 1 for updating content of PD or 0(for content of LB).
396 * \retval LB_STATUS_ERROR_MEMORY Not enough memory
397 * \retval LB_STATUS_ERROR_INVALID Invalid argument
398 * \retval LB_STATUS_ERROR_IO I/O failed, Cannot access given resource file(id)
399 * \retval LB_STATUS_SUCCESS Successfully notified
400 * \pre This API only can be used after loaded into the data-provider-slave process.
404 extern int livebox_content_is_updated(const char *id, int is_pd);
407 * \brief Replace "\n"(new line character) with <br>
409 * This utility function is used to replace all NEW LINE CHARACTER("\n") with <br> tag.
411 * \param[in] str Source string
413 * \retval String that is allocted in the heap
414 * \retval NULL if it fails to replace string
416 * \post Returned string must has to be free'd by user manually.
419 extern char *livebox_util_nl2br(const char *str);
424 * Interfaces for direct buffer management (Available only for the PD area)
426 #ifndef __PROVIDER_BUFFER_H
429 * This enumeration value should be sync'd with provider
432 BUFFER_EVENT_ENTER, /*!< Mouse cursor enter */
433 BUFFER_EVENT_LEAVE, /*!< Mouse cursor leave */
434 BUFFER_EVENT_DOWN, /*!< Mouse down */
435 BUFFER_EVENT_MOVE, /*!< Mouse move */
436 BUFFER_EVENT_UP, /*!< Mouse up */
438 BUFFER_EVENT_KEY_DOWN, /*!< Key down */
439 BUFFER_EVENT_KEY_UP, /*!< Key up */
440 BUFFER_EVENT_KEY_FOCUS_IN, /*!< Key focus in */
441 BUFFER_EVENT_KEY_FOCUS_OUT, /*!< Key focus out */
443 BUFFER_EVENT_HIGHLIGHT, /*!< Accessibility - Highlight */
444 BUFFER_EVENT_HIGHLIGHT_NEXT, /*!< Accessibility - Move highlight to next */
445 BUFFER_EVENT_HIGHLIGHT_PREV, /*!< Accessibility - Move highlight to prev */
446 BUFFER_EVENT_ACTIVATE, /*!< Accessibility - Activate the highlighted object */
447 BUFFER_EVENT_ACTION_UP, /*!< Accessibility - Make UP action */
448 BUFFER_EVENT_ACTION_DOWN, /*!< Accessibility - Make Down action */
449 BUFFER_EVENT_SCROLL_UP, /*!< Accessibility - Scroll up */
450 BUFFER_EVENT_SCROLL_MOVE, /*!< Accessibility - Scroll move */
451 BUFFER_EVENT_SCROLL_DOWN, /*!< Accessibility - Scroll down */
452 BUFFER_EVENT_UNHIGHLIGHT, /*!< Accessibility - Remove highlight */
454 BUFFER_EVENT_ON_HOLD, /*!< To prevent from generating mouse clicked event */
455 BUFFER_EVENT_OFF_HOLD, /*!< Stopped holding. */
456 BUFFER_EVENT_ON_SCROLL, /*!< On scrolling */
457 BUFFER_EVENT_OFF_SCROLL /*!< Scrolling stopped */
460 struct buffer_event_data {
461 enum buffer_event type; /*!< Mouse, Keyboard, Accessibility event type */
462 double timestamp; /*!< Timestamp of events */
466 int x; /*!< If the event type is for accessibility or mouse, coordinates of X for pointer */
467 int y; /*!< If the event type is for accessibility or mouse, coordinates of Y for pointer */
470 unsigned int keycode; /*!< If the event type is for keyboard, the value of keycode */
477 * Acquire a buffer for PD or LB, Currently, we only supporting the PD.
480 * \param[in] id Id of a livebox instance
481 * \param[in] is_pd 1 for PD or 0 for livebox
482 * \param[in] width Width in pixel
483 * \param[in] height Height in pixel
484 * \param[in] handler Event handling callback
485 * \param[in] data user data for event handling callback
486 * \return handler Buffer handle
487 * \retval NULL Failed to acquire buffer
488 * \retval Handle object
490 * Given instance must be specify its type as buffer. or this API will be fail
492 * Allocated buffer object must be released via livebox_release_Buffer
493 * \see livebox_release_buffer
494 * \sa livebox_acquire_buffer_NEW
496 extern struct livebox_buffer *livebox_acquire_buffer(const char *id, int is_pd, int width, int height, int (*handler)(struct livebox_buffer *, enum buffer_event, double, double, double, void *), void *data);
497 extern struct livebox_buffer *livebox_acquire_buffer_NEW(const char *id, int is_pd, int width, int height, int pixels, int (*handler)(struct livebox_buffer *, struct buffer_event_data *, void *), void *data);
500 * \brief Acquire the ID of pixmap resource
501 * Only if the provider uses pixmap for providing render buffer.
503 * \remarks Pixmap Id can be destroyed if you call the livebox_release_buffer. than this pixmap Id is not guaranteed to use.
504 * \param[in] handle Buffer handle
506 * \retval positive Pixmap Id
507 * \retval 0 failed to get pixmap Id.
508 * \pre The system must be set to use the pixmap method for content sharing
510 * \see livebox_acquire_buffer
512 extern unsigned long livebox_pixmap_id(struct livebox_buffer *handle);
515 * \brief Release the buffer of livebox
518 * \param[in] handle Buffer handle
520 * \retval LB_STATUS_ERROR_INVALID Invalid argument
521 * \retval LB_STATUS_SUCCESS Successfully released
522 * \pre handle must be created using livebox_acquire_buffer.
524 * \see livebox_acquire_buffer
525 * \sa livebox_release_buffer_NEW
527 extern int livebox_release_buffer(struct livebox_buffer *handle);
528 extern int livebox_release_buffer_NEW(struct livebox_buffer *handle);
531 * \brief Get the address of S/W render buffer.
532 * If you try to use this, after create_hw_buffer, you will get NULL
535 * \param[in] handle Buffer handle
536 * \return void* address of the render buffer
537 * \retval NULL if it falis to get buffer address
538 * \retval address if it succeed to get the buffer address
541 * \see livebox_unref_buffer
543 extern void *livebox_ref_buffer(struct livebox_buffer *handle);
546 * \brief Release the S/W render buffer.
549 * \param[in] buffer Address of render buffer
551 * \retval LB_STATUS_ERROR_INVALID Invalid handle
552 * \retval LB_STATUS_SUCCESS Successfully unref'd
553 * \pre livebox_ref_buffer must be called
555 * \see livebox_ref_buffer
557 extern int livebox_unref_buffer(void *buffer);
560 * \brief Sync the updated buffer
561 * This is only needed for non-H/W accelerated buffer
564 * \param[in] handle Buffer handle
566 * \retval LB_STATUS_SUCCESS Successfully sync'd
567 * \retval LB_STATUS_ERROR_INVALID Invalid argument
570 * \see livebox_acquire_buffer
572 extern int livebox_sync_buffer(struct livebox_buffer *handle);
575 * \brief Request schedule the update operation to a provider.
578 * \param[in] id Livebox Id
579 * \return int 0 if succeed or errno < 0
580 * \retval LB_STATUS_SUCCESS Successfully triggered
581 * \retval LB_STATUS_ERROR_INVALID Invalid argument
582 * \retval LB_STATUS_ERROR_MEMORY Not enough memory
583 * \retval LB_STATUS_ERROR_NOT_EXIST Given id instance is not exist
588 extern int livebox_request_update(const char *id);
591 * \brief Checking wether the livebox support H/W acceleration or not.
594 * \param[in] handle Buffer handle.
596 * \retval 1 if the buffer handle support the H/W acceleration buffer
597 * \retval 0 if it doesn not supported
600 * \see livebox_acquire_buffer
602 extern int livebox_support_hw_buffer(struct livebox_buffer *handle);
605 * \brief Create the H/W accelerated buffer.
606 * \details Create the H/W accelerated buffer
608 * \param[in] handle Buffer handle
610 * \retval LB_STATUS_ERROR_ALREADY H/W buffer is already created
611 * \retval LB_STATUS_ERROR_INVALID Invalid argument
612 * \retval LB_STATUS_SUCCESS Successfully created
613 * \pre Must be checked whether the H/W buffer is supported or not.
614 * \post Must be destroyed if it is not necessary
615 * \see livebox_support_hw_buffer
617 extern int livebox_create_hw_buffer(struct livebox_buffer *handle);
620 * \brief Destroy the H/W accelerated buffer.
623 * \param[in] handle Buffer handle
625 * \retval LB_STATUS_SUCCESS Successfully destroyed
626 * \retval LB_STATUS_ERROR_INVALID Invalid argument
627 * \pre Must be created h/w buffer using livebox_create_hw_buffer
629 * \see livebox_create_hw_buffer
631 extern int livebox_destroy_hw_buffer(struct livebox_buffer *handle);
634 * \brief Get the address of accelerated H/W buffer
637 * \param[in] handle Buffer handle
639 * \retval NULL failed to get H/W accelerated buffer address
640 * \retval addr H/W accelerated buffer address
643 * \see livebox_create_hw_buffer
645 extern void *livebox_buffer_hw_buffer(struct livebox_buffer *handle);
648 * \brief Pre-processing for rendering content.
649 * This is only needed for accessing H/W accelerated buffer.
652 * \param[in] handle Buffer handle
654 * \retval LB_STATUS_ERROR_INVALID Invalid handle
655 * \retval LB_STATUS_SUCCESS Successfully done
657 * \post livebox_buffer_post_render must be called after the rendering (accessing buffer) is completed.
658 * \see livebox_support_hw_buffer
659 * \see livebox_buffer_post_render
661 extern int livebox_buffer_pre_render(struct livebox_buffer *handle);
664 * \brief Post-processing for rendering content.
667 * \param[in] handle Buffer handle
668 * \return integer 0 if succeed or errno < 0
669 * \retval LB_STATUS_SUCCESS if succeed
670 * \retval LB_STATUS_ERROR_INVALID Invalid argument
671 * \pre livebox_buffer_pre_render must be called
673 * \see livebox_support_hw_buffer
674 * \see livebox_buffer_pre_render
676 extern int livebox_buffer_post_render(struct livebox_buffer *handle);
680 * Deprecated API set.
681 extern Evas_Object *livebox_snapshot_window_add(const char *id, int size_type);
682 extern int livebox_snapshot_window_flush(Evas_Object *snapshot_win, double timeout, void (*flush_cb)(Evas_Object *snapshot_window, const char *id, int status, void *data), void *data);
683 extern int livebox_snapshot_window_del(Evas_Object *snapshot_win);
687 * \brief Create an Evas_Object to create a elm_win object
688 * \details Creating a new Evas_Object using livebox frame buffer.
690 * \param[in] id Instance Id
691 * \param[in] is_pd 1 if this object is created for PD or 0 (for LB)
692 * \return Evas_Object* Evas Object
693 * \retval Address Valid evas object
694 * \retval NULL failed to create
697 * \see livebox_set_elm_window
699 extern Evas_Object *livebox_get_evas_object(const char *id, int is_pd);
702 * \brief Send a request to the viewer (homescreen) to close the PD.
703 * \details Even though you call this function. the homescreen can ignore it.
705 * \param[in] pkgname Livebox Package Id
706 * \param[in] id Livebox Instance Id
707 * \param[in] reason LB_STATUS_SUCCESS(0)
709 * \retval LB_STATUS_ERROR_INVALID Invalid parameters
710 * \retval LB_STATUS_ERROR_MEMORY Out of memory
711 * \retval LB_STATUS_ERROR_FAULT Failed to send a request
712 * \retval LB_STATUS_SUCCESS Successfully requested
717 extern int livebox_request_close_pd(const char *pkgname, const char *id, int reason);
720 * \brief Send a freeze request to the viewer (homescreen)
722 * The viewer will get this request via event callback.
723 * Then it should freeze its scroller or stop moving the livebox.
724 * \remarks If the viewer doesn't care this request, this will has no effect.
725 * \param[in] pkgname Livebox Package Id
726 * \param[in] id Livebox Instance Id
728 * \retval LB_STATUS_ERROR_INVALID Invalid parameters
729 * \retval LB_STATUS_ERROR_MEMORY Out of memory
730 * \retval LB_STATUS_ERROR_FAULT Failed to send requet
731 * \retval LB_STATUS_SUCCESS Successfully requested
734 * \see livebox_release_scroller
736 extern int livebox_freeze_scroller(const char *pkgname, const char *id);
739 * \brief Send a release request to the viewer (homescreen)
741 * The viewer will get this request via event callback.
742 * Then it should release its scroller or continue moving the livebox.
743 * \remarks If the viewer doesn't care this request, this will has no effect.
744 * \param[in] pkgname Livebox Package Id
745 * \param[in] id Livebox Instance Id
746 * \retval LB_STATUS_ERROR_INVALID Invalid parameters
747 * \retval LB_STATUS_ERROR_MEMORY Out of memory
748 * \retval LB_STATUS_ERROR_FAULT Failed to send requet
749 * \retval LB_STATUS_SUCCESS Successfully requested
752 * \see livebox_freeze_scroller
754 extern int livebox_release_scroller(const char *pkgname, const char *id);
757 * \brief Get the configuration status of premultiplied alpha.
759 * If the system uses the premultiplied alpha for content,
760 * This function will returns 1.
761 * \remarks This function only works with the inhouse provider.
762 * \return status of premultiplied alpha.
763 * \retval 1 Content rendered with premultiplied alpha.
764 * \retval 0 Content doesn't rendered with premultiplied alpha.
766 extern int livebox_conf_premultiplied_alpha(void);