From: Sung-jae Park Date: Tue, 3 Sep 2013 02:41:28 +0000 (+0900) Subject: Update doxygen and error code X-Git-Tag: accepted/tizen/20131022.083701^2~8 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=0c3a14733ad3c1b1c2df8cc4fe1c25b87b6fb59a;hp=7002e79ad47a8908862769c37da1f57cfd6e137a;p=platform%2Fframework%2Fweb%2Flivebox-viewer.git Update doxygen and error code Change-Id: I1165008ea951eb5929f3ba727bbe9d13d9957b78 --- diff --git a/CMakeLists.txt b/CMakeLists.txt index 90f8c1b..fa1ec0e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -66,5 +66,4 @@ SET_DIRECTORY_PROPERTIES(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${PROJECT_NAME} INSTALL(TARGETS ${PROJECT_NAME} DESTINATION ${LIB_INSTALL_DIR}) INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc DESTINATION ${LIB_INSTALL_DIR}/pkgconfig) INSTALL(FILES ${CMAKE_SOURCE_DIR}/include/livebox.h DESTINATION include/${PROJECT_NAME}) -INSTALL(FILES ${CMAKE_SOURCE_DIR}/include/livebox-viewer_PG.h DESTINATION /usr/share/doc/${PROJECT_NAME}) INSTALL(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION /usr/share/license RENAME "lib${PROJECT_NAME}") diff --git a/doc/image/PD.png b/doc/image/PD.png new file mode 100644 index 0000000..ebb7367 Binary files /dev/null and b/doc/image/PD.png differ diff --git a/doc/image/download_folder.png b/doc/image/download_folder.png new file mode 100644 index 0000000..1e5e01b Binary files /dev/null and b/doc/image/download_folder.png differ diff --git a/doc/image/front.jpg b/doc/image/front.jpg new file mode 100644 index 0000000..9d46441 Binary files /dev/null and b/doc/image/front.jpg differ diff --git a/doc/image/image_format.png b/doc/image/image_format.png new file mode 100644 index 0000000..8f79a0c Binary files /dev/null and b/doc/image/image_format.png differ diff --git a/doc/image/message.png b/doc/image/message.png new file mode 100644 index 0000000..4cb7760 Binary files /dev/null and b/doc/image/message.png differ diff --git a/doc/image/preload_folder.png b/doc/image/preload_folder.png new file mode 100644 index 0000000..3dbbf64 Binary files /dev/null and b/doc/image/preload_folder.png differ diff --git a/doc/image/script_format.png b/doc/image/script_format.png new file mode 100644 index 0000000..1fec88a Binary files /dev/null and b/doc/image/script_format.png differ diff --git a/doc/image/stock.png b/doc/image/stock.png new file mode 100644 index 0000000..fd274fe Binary files /dev/null and b/doc/image/stock.png differ diff --git a/doc/image/text_format.png b/doc/image/text_format.png new file mode 100644 index 0000000..b492883 Binary files /dev/null and b/doc/image/text_format.png differ diff --git a/doc/image/twitter.png b/doc/image/twitter.png new file mode 100644 index 0000000..36bce25 Binary files /dev/null and b/doc/image/twitter.png differ diff --git a/doc/image/weather.png b/doc/image/weather.png new file mode 100644 index 0000000..2f41af1 Binary files /dev/null and b/doc/image/weather.png differ diff --git a/doc/livebox-viewer_doc.h b/doc/livebox-viewer_doc.h new file mode 100644 index 0000000..948705e --- /dev/null +++ b/doc/livebox-viewer_doc.h @@ -0,0 +1,125 @@ +/* + * Copyright 2013 Samsung Electronics Co., Ltd + * + * Licensed under the Flora License, Version 1.1 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://floralicense.org/license/ + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/*! + * \ingroup CAPI_LIVEBOX_FRAMEWORK Tizen livebox framework + * \defgroup CAPI_LIVEBOX_VIEWER_MODULE Application Programming Interfaces for the viewer application + * \brief API for livebox viewer (widget screen, home screen, ...) + * \section CAPI_LIVEBOX_VIEWER_MODULE_HEADER Required Header + * \#include + * \section CAPI_LIVEBOX_VIEWER_MODULE_OVERVIEW Overview + * Tizen(SLP) homescreen S/W framework is supporing the live box. (aka widget which is similiar with the android widget) + * + * \image html front.jpg + * + * \subsection WhatIsTheLivebox 1. What is the Livebox + * The live box is the widget of the TIZEN. + * + * It works as a small application displayed on other applications' (such as homescreen, lockscreen, etc ...) view. + * Each live box can have (not a mandatory option) a PD (progressive disclosure) in which more detailed information can be found. + * The content of PD can be exposed when a certain gesture (e.g., flick-down) has been applied to the live box. + * If you are interested in developing a livebox, there are things you should know prior to making any source code for the box. + * To make your live box added to any live box viewer application (e.g., live panel in our case), then you need to create and prepare + * controller(SO file), layout script (EDJE for a PD if necessary), configuration files. + * + * A livebox is managed by data provider, since each SO file of a livebox is loaded on and controlled by data provider using predefined ABI. + * A viewer will receive any livebox's content in forms of "image file", "buffer" or "text" and display the content in various formats on its window. + * A livebox developer needs to make sure that your live box generates desirable content in-time on a explicit update-request or periodic update. + * + * After a data provider loads a livebox's SO file, it then assigns a specific "file name" for the livebox via an argument of a livebox function. + * Since then the livebox just generates content using then given file name. + * Passing an image file (whose name is the previously given name) is the basic method for providing contents to the viewer. + * But if you want play animation or handles user event in real-time, you can use the buffer type. + * + * And you should prepare the content of the Progressive Disclosure. + * The Progressive Dislcosure is only updated by the "buffer" type. so you should prepare the layout script for it. + * If you didn't install any script file for progressive disclosure, the viewer will ignore the "flick down" event from your livebox. + * + * \subsubsection Livebox 1.1 Livebox + * Live box is a default content of your widget. It always displays on the screen and updated periodically. + * It looks like below captured images. + * \image html weather.png Weather Livebox + * \image html stock.png Stock Livebox + * \image html twitter.png Twitter Livebox + * + * \subsubsection ProgressiveDisclosure 1.2 Progressive Disclosure + * \image html PD.png Progressive Disclosure + * Progressive disclosure will be displayed when a user flicks down a livebox. (basically it depends on the implementation of the view applications) + * To supports this, a developer should prepare the layout script (EDJE only for the moment) of the livebox's PD. (or you can use the buffer directly) + * Data provider supports EDJE script but the developer can use various scripts if (which is BIG IF) their interpreters can be implemented based on evas & ecore. + * + * When a layout script has been installed, data provider can load and rendering the given layout on the buffer. + * The content on the buffer can be shared between applications that need to display the content on their window. + * Description data file is necessary to place proper content components in rendered layout. + * Check this page Description Data. + * + * \subsubsection ClusterCategory 1.3 What is the "cluster" and "category" + * The cluster and the sub-cluster is just like the grouping concept. + * It is used for creating/destorying your livebox instance when the data provider receives any context event from the context engine. + * You will only get "user,created" cluster and "default" category(sub cluster) info. + * + * \subsection LiveboxContent 2. How the livebox can draw contents for viewer? + * There are several ways to update the content of a livebox. + * + * \li Image file based content updating + * \li Description file based content updating (with the layout script file) + * \li Buffer based content updating + * + * Each method has specific benefit for implementing the livebox. + * + * \subsubsection ImageFormat 2.1 Via image file + * This is the basic method for providing content of a livebox to the viewer application. + * But this can be used only for the livebox. (Unavailable for the progressive disclosure). + * When your livebox is created, the provider will assign an unique ID for your livebox(it would be a filename). + * You should keep that ID until your livebox is running. The ID will be passed to you via livebox_create function. + * \image html image_format.png + * + * When you need to update the output of your livebox, you should generate the image file using given ID(filename). + * Then the data provider will recognize the event of updated output of a livebox and it will send that event to the viewer to reload it on the screen. + * + * \subsubsection ScriptFormat 2.2 Via layout script + * \image html script_format.png + * This method is supported for static layout & various contents (text & image) + * When you develop your livebox, first design the layout of box content using script (edje is default) + * Then the provider will load it to the content buffer and start rendering. + * After the sciprt is loaded, you can fill it using description data format. + * liblivebox defines description data handling functions. + * + * \subsubsection TextFormat 2.3 Via text data + * \image html text_format.png + * This is the simplified method to update the content of livebox. + * So your box only need to update the text data using description data format. + * Then the viewer will parse it to fill its screen. + * So there is no buffer area, just viewer decide how handles it. + * + * \subsubsection BufferFormat 2.4 Via buffer + * This method is very complex to implement. + * The provider will give a content buffer to you, then your box should render its contents on this buffer. + * This type is only supported for 3rd party livebox such as OSP and WEB. + * Inhouse(EFL) livebox is not able to use this buffer type for the box content. + * + * \subsection PackageNTools 3. How can I get the development packages or tools? + * + * \subsection DevelopLivebox 4. How can I write a new livebox + * + * \subsection TestLivebox 5. How can I test my livebox + * + * \subsection LiveboxDirectory 6. Livebox directory hierachy + * \image html preload_folder.png + * \image html download_folder.png + * + */ + diff --git a/include/livebox-viewer_PG.h b/include/livebox-viewer_PG.h deleted file mode 100644 index 67a71d8..0000000 --- a/include/livebox-viewer_PG.h +++ /dev/null @@ -1,16 +0,0 @@ -/* - * Copyright 2013 Samsung Electronics Co., Ltd - * - * Licensed under the Flora License, Version 1.1 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://floralicense.org/license/ - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - diff --git a/include/livebox.h b/include/livebox.h index 32306df..da6414d 100644 --- a/include/livebox.h +++ b/include/livebox.h @@ -21,19 +21,28 @@ extern "C" { #endif +/*! + * \addtogroup CAPI_LIVEBOX_VIEWER_MODULE + * \{ + */ + +/*! + * \brief + * Structure for a Livebox instance + */ struct livebox; /*! - * \note size list - * 172x172 - * 348x172 - * 348x348 - * 700x348 - * 700x172 - * 700x700 + * \brief + * Use the default update period which is defined in the livebox package manifest. */ #define DEFAULT_PERIOD -1.0f +/*! + * \brief + * Mouse & Key event for buffer type Livebox or PD + * Viewer should send these events to livebox. + */ enum content_event_type { CONTENT_EVENT_MOUSE_DOWN = 0x00000001, /*!< LB mouse down event for livebox */ CONTENT_EVENT_MOUSE_UP = 0x00000002, /*!< LB mouse up event for livebox */ @@ -51,31 +60,36 @@ enum content_event_type { CONTENT_EVENT_PD_MASK = 0x10000000, CONTENT_EVENT_LB_MASK = 0x40000000, - LB_MOUSE_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, - LB_MOUSE_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, - LB_MOUSE_MOVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, - LB_MOUSE_ENTER = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, - LB_MOUSE_LEAVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, + LB_MOUSE_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the livebox */ + LB_MOUSE_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the livebox */ + LB_MOUSE_MOVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Move move on the livebox */ + LB_MOUSE_ENTER = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the livebox */ + LB_MOUSE_LEAVE = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the livebox */ LB_MOUSE_SET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET, LB_MOUSE_UNSET = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET, - PD_MOUSE_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, - PD_MOUSE_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, - PD_MOUSE_MOVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, - PD_MOUSE_ENTER = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, - PD_MOUSE_LEAVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, + PD_MOUSE_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the PD */ + PD_MOUSE_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the PD */ + PD_MOUSE_MOVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Mouse move on the PD */ + PD_MOUSE_ENTER = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the PD */ + PD_MOUSE_LEAVE = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the PD */ PD_MOUSE_SET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET, PD_MOUSE_UNSET = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET, - LB_KEY_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, - LB_KEY_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, + LB_KEY_DOWN = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */ + LB_KEY_UP = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */ - PD_KEY_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, - PD_KEY_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, + PD_KEY_DOWN = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */ + PD_KEY_UP = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */ - CONTENT_EVENT_MAX = 0xFFFFFFFF + CONTENT_EVENT_MAX = 0xFFFFFFFF }; +/*! + * \brief + * Accessibility event for buffer type Livebox or PD. + * These event set are sync'd with Tizen accessibility event set. + */ enum access_event_type { ACCESS_EVENT_PD_MASK = 0x10000000, ACCESS_EVENT_LB_MASK = 0x20000000, @@ -91,16 +105,16 @@ enum access_event_type { ACCESS_EVENT_SCROLL_MOVE = 0x00200000, /*!< LB accessibility scroll move */ ACCESS_EVENT_SCROLL_UP = 0x00400000, /*!< LB accessibility scroll up */ - LB_ACCESS_HIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT, - LB_ACCESS_HIGHLIGHT_NEXT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT, - LB_ACCESS_HIGHLIGHT_PREV = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_PREV, - LB_ACCESS_UNHIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_UNHIGHLIGHT, - LB_ACCESS_ACTIVATE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTIVATE, - LB_ACCESS_ACTION_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_DOWN, - LB_ACCESS_ACTION_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_UP, - LB_ACCESS_SCROLL_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_DOWN, - LB_ACCESS_SCROLL_MOVE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_MOVE, - LB_ACCESS_SCROLL_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_UP, + LB_ACCESS_HIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT, /*!< Access event - Highlight an object in the livebox */ + LB_ACCESS_HIGHLIGHT_NEXT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT, /*!< Access event - Move highlight to the next object in a livebox */ + LB_ACCESS_HIGHLIGHT_PREV = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_PREV, /*!< Access event - Move highlight to the prev object in a livebox */ + LB_ACCESS_UNHIGHLIGHT = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_UNHIGHLIGHT, /*!< Access event - Delete highlight from the livebox */ + LB_ACCESS_ACTIVATE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTIVATE, /*!< Access event - Launch or activate the highlighted object */ + LB_ACCESS_ACTION_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_DOWN, /*!< Access event - down */ + LB_ACCESS_ACTION_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_UP, /*!< Access event - up */ + LB_ACCESS_SCROLL_DOWN = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_DOWN, /*!< Access event - scroll down */ + LB_ACCESS_SCROLL_MOVE = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_MOVE, /*!< Access event - scroll move */ + LB_ACCESS_SCROLL_UP = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_UP, /*!< Access event - scroll up */ PD_ACCESS_HIGHLIGHT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT, PD_ACCESS_HIGHLIGHT_NEXT = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT, @@ -114,7 +128,10 @@ enum access_event_type { PD_ACCESS_SCROLL_UP = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_UP }; -/* Exported to user app */ +/*! + * \brief + * Livebox LB content type + */ enum livebox_lb_type { LB_TYPE_IMAGE = 0x01, /*!< Contents of a livebox is based on the image file */ LB_TYPE_BUFFER = 0x02, /*!< Contents of a livebox is based on canvas buffer(shared) */ @@ -124,6 +141,10 @@ enum livebox_lb_type { LB_TYPE_INVALID = 0xFF }; +/*! + * \brief + * Livebox PD content type + */ enum livebox_pd_type { PD_TYPE_BUFFER = 0x01, /*!< Contents of a PD is based on canvas buffer(shared) */ PD_TYPE_TEXT = 0x02, /*!< Contents of a PD is based on formatted text file */ @@ -132,6 +153,11 @@ enum livebox_pd_type { PD_TYPE_INVALID = 0xFF }; +/*! + * \brief + * Livebox event type. + * These event will be sent from the provider. + */ enum livebox_event_type { /*!< livebox_event_handler_set Event list */ LB_EVENT_LB_UPDATED, /*!< Contents of the given livebox is updated */ LB_EVENT_PD_UPDATED, /*!< Contents of the given pd is updated */ @@ -152,13 +178,13 @@ enum livebox_event_type { /*!< livebox_event_handler_set Event list */ LB_EVENT_HOLD_SCROLL, /*!< If the screen should be freezed */ LB_EVENT_RELEASE_SCROLL, /*!< If the screen can be scrolled */ - LB_EVENT_LB_UPDATE_BEGIN, - LB_EVENT_LB_UPDATE_END, + LB_EVENT_LB_UPDATE_BEGIN, /*!< Livebox LB content update is started */ + LB_EVENT_LB_UPDATE_END, /*!< Livebox LB content update is finished */ - LB_EVENT_PD_UPDATE_BEGIN, - LB_EVENT_PD_UPDATE_END, + LB_EVENT_PD_UPDATE_BEGIN, /*!< Livebox PD content update is started */ + LB_EVENT_PD_UPDATE_END, /*!< Livebox PD content update is finished */ - LB_EVENT_UPDATE_MODE_CHANGED, + LB_EVENT_UPDATE_MODE_CHANGED, /*!< Livebox Update mode is changed */ LB_EVENT_IGNORED /*!< Request is ignored */ }; @@ -168,7 +194,11 @@ enum livebox_fault_type { LB_FAULT_PROVIDER_DISCONNECTED /*!< Provider is disconnected */ }; -enum livebox_visible_state { /*!< Must be sync'd with the provider */ +/*! + * \brief + * Must be sync'd with the provider + */ +enum livebox_visible_state { LB_SHOW = 0x00, /*!< Livebox is showed. Default state */ 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 */ @@ -178,7 +208,7 @@ enum livebox_visible_state { /*!< Must be sync'd with the provider */ }; /*! - * \note + * \brief * TEXT type livebox contents handling opertators. */ struct livebox_script_operators { @@ -199,338 +229,716 @@ struct livebox_script_operators { }; /*! - * \brief Prototype of the return callback of every async functions. - * \param[in] handle - * \param[in] ret - * \param[in] data + * \brief Prototype of the return callback of every async functions + * \details N/A + * \remarks N/A + * \param[in] handle Handle of the livebox instance + * \param[in] ret Result status of operation. LB_STATUS_XXX defined from liblivebox-service + * \param[in] data data for result callback * \return void + * \pre N/A + * \post N/A + * \see livebox_add + * \see livebox_add_with_size + * \see livebox_del + * \see livebox_activate + * \see livebox_resize + * \see livebox_set_group + * \see livebox_set_period + * \see livebox_access_event + * \see livebox_set_pinup + * \see livebox_create_pd + * \see livebox_create_pd_with_position + * \see livebox_destroy_pd + * \see livebox_emit_text_signal + * \see livebox_acquire_pd_pixmap + * \see livebox_acquire_lb_pixmap + * \see livebox_set_update_mode */ typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data); /*! * \brief Initialize the livebox system + * \details N/A + * \remarks N/A * \param[in] disp If you have X Display connection object, you can re-use it. but you should care its life cycle. * It must be alive before call the livebox_fini - * \return int 0 if success or < 0 (errno) - * \sa livebox_fini + * \return int + * \retval LB_STATUS_SUCCESS if success + * \pre N/A + * \post N/A + * \see livebox_fini */ extern int livebox_init(void *disp); /*! * \brief Finalize the livebox system - * \return int 0 if success, -EINVAL if livebox_init is not called. - * \sa livebox_init + * \details N/A + * \remarks N/A + * \return int + * \retval LB_STATUS_SUCCES if success + * \retval LB_STATUS_ERROR_INVALID if livebox_init is not called. + * \pre N/A + * \post N/A + * \see livebox_init */ extern int livebox_fini(void); /*! * \brief Client is paused. - * \return int 0 if success, -EFAULT if it failed to send state(paused) info - * \sa livebox_client_resumed + * \details N/A + * \remarks N/A + * \return int + * \retval LB_STATUS_SUCCESS if success + * \retval LB_STATUS_ERROR_FAULT if it failed to send state(paused) info + * \pre N/A + * \post N/A + * \see livebox_client_resumed */ extern int livebox_client_paused(void); /*! * \brief Client is rfesumed. - * \return int 0 if success, -EFAULT if it failed to send state(resumed) info - * \sa livebox_client_paused + * \details N/A + * \remarks N/A + * \return int + * \retval LB_STATUS_SUCCESS if success + * \retval LB_STATUS_ERROR_FAULT if it failed to send state(resumed) info + * \pre N/A + * \post N/A + * \see livebox_client_paused */ extern int livebox_client_resumed(void); /*! * \brief Add a new livebox + * \details N/A + * \remarks + * Even though you get the livebox handle from return value of this function, + * it is not matured before return callback called. + * You have to use the handle after get the return callback with "ret == LB_STATUS_SUCCESS" * \param[in] pkgname Livebox Id - * \param[in] content Will be passed to the livebox. - * \param[in] cluster - * \param[in] category + * \param[in] content Will be passed to the livebox instance. + * \param[in] cluster Main group + * \param[in] category Sub group * \param[in] period Update period. if you set DEFAULT_PERIOD, the provider will use the default period which is described in the manifest. * \param[in] cb After send the request to the provider, its result will be passed * \param[in] data * \return handle + * \retval NULL if it fails to add a new instance + * \retval handle livebox handle + * \pre N/A + * \post + * \see ret_cb_t + * \see livebox_add_with_size */ 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); + +/*! + * \brief Add a new livebox + * \details + * Normal mode livebox + * 1x1=175x175 + * 2x1=354x175 + * 2x2=354x354 + * 4x1=712x175 + * 4x2=712x354 + * 4x4=712x712 + * + * Extended sizes + * 4x3=712x533 + * 4x5=712x891 + * 4x6=712x1070 + * + * Easy mode livebox + * 21x21=224x215 + * 23x21=680x215 + * 23x23=680x653 + * + * Special livebox + * 0x0=720x1280 + * \remarks + * Even if you get the handle by return value of this function, it is not created instance. + * So you have to deal it as not initialized handle. + * Only it can be initialized after get the return callback with "ret == LB_STATUS_SUCCESS". + * \param[in] pkgname Livebox Id + * \param[in] content Will be passed to the livebox instance. + * \param[in] cluster Main group + * \param[in] category Sub group + * \param[in] period DEFAULT_PERIOD can be used for this. this argument will be used to specify the period of update content of livebox. + * \param[in] type Size type - which are defined from liblivebox-service package. + * \param[in] cb After the request is sent to the master provider, this callback will be called. + * \param[in] data This data will be passed to the callback. + * \return handle + * \retval handle Livebox handle but not yet initialized + * \retval NULL if it fails to create a handle + * \see ret_cb_t + * \see livebox_add + */ 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); /*! * \brief Delete a livebox - * \param[in] handle - * \param[in] ret_cb_t return callback + * \details N/A + * \remarks + * If you call this with uninitialized handle, the return callback will be called synchronously. + * So before return from this function, the return callback will be called first. + * \param[in] handler Handle of a livebox instance + * \param[in] cb return callback * \param[in] data user data for return callback * \return int + * \retval LB_STATUS_ERROR_INVALID Invalid argument + * \retval LB_STATUS_ERROR_BUSY already in process + * \retval LB_STATUS_ERROR_FAULT failed to create a request packet + * \retval LB_STATUS_SUCCESS successfully sent, return callack will be called + * \pre N/A + * \post N/A + * \see ret_cb_t */ extern int livebox_del(struct livebox *handler, ret_cb_t cb, void *data); /*! * \brief Set a livebox events callback + * \details + * To get the events push from the provider, register the event callback using this function + * The callback will be called if there is any events from the provider. + * \remarks N/A * \param[in] cb Event handler * \param[in] data User data for the event handler * \return int - * \sa livebox_unset_event_handler + * \retval LB_STATUS_SUCCESS if succeed to set event handler + * \retval LB_STATUS_ERROR_INVALID Invalid argument + * \retval LB_STATUS_ERROR_MEMORY Not enough memory + * \pre NULL + * \post NULL + * \see livebox_unset_event_handler */ - extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data); /*! * \brief Unset the livebox event handler + * \details N/A + * \remarks N/A * \param[in] cb - * \return void * pointer of 'data' which is registered from the livebox_event_handler_set - * \sa livebox_set_event_handler + * \return void * + * \retval pointer of 'data' which is used with the livebox_set_event_handler + * \pre N/A + * \post N/A + * \see livebox_set_event_handler */ extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data)); /*! - * \note + * \brief Live box fault event handler registeration function * argument list * event, pkgname, filename, funcname - * - * \brief Live box fault event handler registeration function + * \details N/A + * \remarks N/A * \param[in] cb * \param[in] data * \return int - * \sa livebox_unset_fault_handler + * \retval LB_STATUS_SUCCESS if succeed to set fault event handler + * \retval LB_STATUS_ERROR_INVALID Invalid argument + * \retval LB_STATUS_ERROR_MEMORY Not enough memory + * \pre N/A + * \post N/A + * \see livebox_unset_fault_handler */ extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data); /*! * \brief Unset the live box fault event handler + * \details N/A + * \remarks N/A * \param[in] cb - * \return pointer of 'data' - * \sa livebox_set_fault_handler + * \return void * + * \retval pointer of 'data' which is used with the livebox_set_fault_handler + * \pre N/A + * \post N/A + * \see livebox_set_fault_handler */ extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *)); /*! * \brief Activate the faulted livebox. + * \details + * Request result will be back via return callback. + * \remarks + * Even though this function returns SUCCESS, it means just successfully sent a request to provider. + * So you have to check the return callback. and its "ret" argument. * \param[in] pkgname * \param[in] cb * \param[in] data * \return int + * \retval LB_STATUS_SUCCESS Successfully sent a request + * \retval LB_STATUS_ERROR_INVALID Invalid argument + * \retval LB_STATUS_ERROR_FAULT Failed to make a request + * \pre N/A + * \post N/A + * \see ret_cb_t */ extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data); /*! * \brief Resize the livebox + * \details + * Normal mode livebox size + * 1x1=175x175 + * 2x1=354x175 + * 2x2=354x354 + * 4x1=712x175 + * 4x2=712x354 + * 4x4=712x712 + * + * Extended livebox size + * 4x3=712x533 + * 4x5=712x891 + * 4x6=712x1070 + * + * Easy mode livebox size + * 21x21=224x215 + * 23x21=680x215 + * 23x23=680x653 + * + * Special mode livebox size + * 0x0=720x1280 + * \remarks + * You have to check the return callback. * \param[in] handler Handler of a livebox * \param[in] type Type of a livebox size, LB_SIZE_TYPE_1x1, ... * \param[in] cb Result callback of the resize operation. * \param[in] data User data for return callback * \return int + * \retval LB_STATUS_ERROR_INVALID Invalid argument + * \retval LB_STATUS_ERROR_BUSY Previous request of resize is in progress. + * \retval LB_STATUS_ERROR_ALREADY Already resized, there is no differences between current size and requested size. + * \retval LB_STATUS_ERROR_PERMISSION Permission denied, you only have view the content of this box. + * \retval LB_STATUS_ERROR_FAULT Failed to make a request + * \pre N/A + * \post N/A + * \see ret_cb_t */ extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data); /*! * \brief Send the click event for a livebox. + * \details N/A + * \remarks N/A * \param[in] handler Handler of a livebox * \param[in] x Rational X of the content width. * \param[in] y Rational Y of the content height. * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_click(struct livebox *handler, double x, double y); /*! * \brief Change the cluster/sub-cluster name of given livebox handler + * \details N/A + * \remarks N/A * \param[in] handler Handler of a livebox * \param[in] cluster New cluster of a livebox * \param[in] category New category of a livebox * \param[in] cb Result callback for changing the cluster/category of a livebox * \param[in] data User data for the result callback * \return int + * \retval LB_STATUS_SUCCESS Request is successfully sent. the return callback will be called. + * \retval LB_STATUS_ERROR_BUSY previous request is not finished yet. + * \retval LB_STATUS_ERROR_ALREADY group name is same with current one. + * \retval LB_STATUS_ERROR_PERMISSION you have no permission to change property of this livebox instance. + * \retval LB_STATUS_ERROR_FAULT Failed to make a request. + * \pre N/A + * \post N/A + * \see ret_cb_t */ extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data); /*! * \brief Get the cluster and category(sub-cluster) name of given livebox (It is not I18N format, only english) + * \details N/A + * \remarks + * You have to do not release the cluster & category. + * It is allocated inside of given livebox instance, so you can only read it. * \param[in] handler Handler of a livebox * \param[out] cluster Storage(memory) for containing the cluster name * \param[out] category Storage(memory) for containing the category name * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_get_group(struct livebox *handler, char ** const cluster, char ** const category); /*! * \brief Get the period of this livebox handler + * \details N/A + * \remarks + * if this function returns 0.0f, it means the livebox has no update period. + * or the handle is not valid. + * This function only can be works after the return callback of livebox_create fucntion is called. * \param[in] handler Handler of a livebox - * \return double Current update period of a livebox + * \return double + * \retval Current update period of a livebox + * \retval 0.0f it means the box has no update period, or it can returns 0.0 if the handles is not valid. + * \pre N/A + * \post N/A + * \see N/A */ extern double livebox_period(struct livebox *handler); /*! * \brief Change the update period + * \details N/A + * \remarks N/A * \param[in] handler Handler of a livebox * \param[in] period New update period of a livebox * \param[in] cb Result callback of changing the update period of this livebox * \param[in] data User data for the result callback * \return int + * \retval LB_STATUS_SUCCESS + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_BUSY + * \retval LB_STATUS_ERROR_ALREADY + * \retval LB_STATUS_ERROR_FAULT + * \pre N/A + * \post N/A + * \see ret_cb_t */ extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data); /*! * \brief Is this an text type livebox? + * \details N/A + * \remarks N/A * \param[in] handler - * \return content_type + * \return livebox_lb_type + * \retval LB_TYPE_IMAGE Contents of a livebox is based on the image file + * \retval LB_TYPE_BUFFER Contents of a livebox is based on canvas buffer(shared) + * \retval LB_TYPE_TEXT Contents of a livebox is based on formatted text file + * \retval LB_TYPE_PIXMAP Contens of a livebox is shared by the pixmap(depends on X) + * \retval LB_TYPE_INVALID + * \pre N/A + * \post N/A + * \see livebox_lb_type */ extern enum livebox_lb_type livebox_lb_type(struct livebox *handler); /*! * \brief Is this livebox is created by a user? + * \details + * If the livebox instance is created by system this will returns 0. + * \remarks N/A * \param[in] handler * \return int + * \retval LB_STATUS_ERROR_INVALID Invalid argument + * \retval 0 automatically created livebox by the provider + * \retval 1 created by user via livebox_add or livebox_add_with_size + * \pre N/A + * \post N/A + * \see livebox_add + * \see livebox_add_with_size + * \see livebox_set_event_handler */ extern int livebox_is_user(struct livebox *handler); /*! * \brief Get the content information string of given livebox + * \details N/A + * \remarks N/A * \param[in] handler - * \return content + * \return char * + * \retval content_info Livebox content info that can be used again via content_info argument of livebox_add or livebox_add_with_size. + * \pre N/A + * \post N/A + * \see livebox_add + * \see livebox_add_with_size */ extern const char *livebox_content(struct livebox *handler); /*! * \brief Get the sub cluster title string of given livebox + * \details N/A + * \remarks N/A * \param[in] handler - * \return sub cluster title + * \return const char * + * \retval sub cluster name + * \retval NULL + * \pre N/A + * \post N/A + * \see N/A */ extern const char *livebox_category_title(struct livebox *handler); /*! * \brief Get the filename of given livebox, if it is an IMAGE type livebox + * \details N/A + * \remarks N/A * \param[in] handler - * \return filename + * \return const char * + * \retval filename if the livebox type is image this function will give you a abspath of an image file (content is rendered) + * \retval NULL if this has no image file or type is not image file. + * \pre N/A + * \post N/A + * \see N/A */ extern const char *livebox_filename(struct livebox *handler); /*! * \brief Get the package name of given livebox handler + * \details N/A + * \remarks N/A * \param[in] handler - * \return pkgname + * \return const char * + * \retval pkgname package name + * \retval NULL if the handler is not valid + * \pre N/A + * \post N/A + * \see N/A */ extern const char *livebox_pkgname(struct livebox *handler); /*! * \brief Get the priority of a current content. + * \details N/A + * \remarks N/A * \param[in] handler - * \return priority + * \return double + * \retval 0.0f handler is NULL + * \retval -1.0f Handler is not valid (not yet initialized) + * \retval real number between 0.0 and 1.0 + * \pre N/A + * \post N/A + * \see N/A */ extern double livebox_priority(struct livebox *handler); /*! * \brief Acquire the buffer of given livebox (Only for the buffer type) + * \details N/A + * \remarks N/A * \param[in] handler - * \return address of a FB + * \return void * + * \retval address of a FB + * \retval NULL if it fails to get fb address + * \pre N/A + * \post N/A + * \see N/A */ extern void *livebox_acquire_fb(struct livebox *handler); /*! * \brief Release the buffer of a livebox (Only for the buffer type) + * \details N/A + * \remarks N/A * \param[in] buffer * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_acquire_fb */ extern int livebox_release_fb(void *buffer); /*! * \brief Get the reference count of Livebox buffer (Only for the buffer type) + * \details N/A + * \remarks N/A * \param[in] buffer * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval refcnt positive integer including ZERO + * \pre N/A + * \post N/A + * \see livebox_pdfb_refcnt */ extern int livebox_fb_refcnt(void *buffer); /*! * \brief Acquire the buffer of a PD frame (Only for the buffer type) + * \details N/A + * \remarks N/A * \param[in] handler * \return int + * \retval NULL + * \retval adress of buffer of PD + * \pre N/A + * \post N/A + * \see livebox_release_pdfb */ extern void *livebox_acquire_pdfb(struct livebox *handler); /*! * \brief Release the acquired buffer of the PD Frame (Only for the buffer type) + * \details N/A + * \remarks N/A * \param[in] buffer * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_acquire_pdfb */ extern int livebox_release_pdfb(void *buffer); /*! * \brief Reference count of given PD buffer (Only for the buffer type) + * \details N/A + * \remarks N/A * \param[in] buffer * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval reference count + * \pre N/A + * \post N/A + * \see livebox_fb_refcnt */ extern int livebox_pdfb_refcnt(void *buffer); /*! * \brief Get the size of the Livebox + * \details N/A + * \remarks N/A * \param[in] handler - * \param[out] w - * \param[out] h * \return int + * \retval LB_SIZE_TYPE_NxM + * \retval LB_SIZE_TYPE_INVALID + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_size(struct livebox *handler); /*! * \brief Get the size of the Progressive Disclosure + * \details N/A + * \remarks N/A * \param[in] handler * \param[out] w * \param[out] h * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h); /*! * \brief List of supported sizes of given handler + * \details N/A + * \remarks N/A * \param[in] handler * \param[out] cnt - * \param[out] w - * \param[out] h + * \param[out] size_list * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list); /*! * \brief BUFFER SIZE of the livebox if it is a buffer type + * \details N/A + * \remarks N/A * \param[in] handler * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval size of livebox buffer + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_lbfb_bufsz(struct livebox *handler); /*! * \brief BUFFER SIZE of the progiressive disclosure if it is a buffer type + * \details N/A + * \remarks N/A * \param[in] handler * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval size of PD buffer + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_pdfb_bufsz(struct livebox *handler); /*! * \brief Send the content event (for buffer type) to provider(livebox) + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] type * \param[in] x * \param[in] y - * \return + * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_BUSY + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_access_event */ extern int livebox_content_event(struct livebox *handler, enum content_event_type type, double x, double y); /*! * \brief Send the access event(for buffer type) to provider(livebox). + * \details N/A + * \remarks N/A * \param[in] handler - * \param[in] access_event_type + * \param[in] type * \param[in] x * \param[in] y * \param[in] cb * \param[in] data - * \return + * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_BUSY + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_content_event */ extern int livebox_access_event(struct livebox *handler, enum access_event_type type, double x, double y, ret_cb_t cb, void *data); /*! * \brief Do pin up or not. + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] flag * \param[in] cb * \param[in] data * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval 1 box is pinned up + * \retval 0 box is not pinned up + * \see ret_cb_t */ extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data); /*! * \brief Check the PIN-UP status of given handler + * \details N/A + * \remarks N/A * \param[in] handler * \return int */ @@ -538,95 +946,178 @@ extern int livebox_is_pinned_up(struct livebox *handler); /*! * \brief Check the PINUP feature availability of the given handler + * \details N/A + * \remarks N/A * \param[in] handler * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval 1 if the box support Pinup feature + * \retval 0 if the box does not support the Pinup feature + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_has_pinup(struct livebox *handler); /*! * \brief Check the PD existence of given handler + * \details N/A + * \remarks N/A * \param[in] handler * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval 1 if the box support the PD + * \retval 0 if the box has no PD + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_has_pd(struct livebox *handler); /*! * \brief Create the PD of given handler + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] cb * \param[in] data * \return int + * \retval LB_STATUS_SUCCESS + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_BUSY + * \retval LB_STATUS_ERROR_FAULT + * \pre N/A + * \post N/A + * \see ret_cb_t */ extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data); /*! * \brief Create the PD of given handler with the relative position from livebox + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] x 0.0 ~ 1.0 * \param[in] y 0.0 ~ 1.0 * \param[in] cb * \param[in] data * \return int + * \retval LB_STATUS_SUCCESS + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_BUSY + * \retval LB_STATUS_ERROR_FAULT + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data); /*! * \brief PD position is updated. + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] x 0.0 ~ 1.0 * \param[in] y 0.0 ~ 1.0 - * \return int 0 if succeed to send request for updating position of the PD. + * \return int + * \retval LB_STATUS_SUCCESS if succeed to send request for updating position of the PD. + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_ERROR_INVALID + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_move_pd(struct livebox *handler, double x, double y); /*! * \brief Destroy the PD of given handler if it is created. + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] cb * \param[in] data * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see ret_cb_t */ extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data); /*! * \brief Check the create status of given livebox handler + * \details N/A + * \remarks N/A * \param[in] handler * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval 0 PD is not created + * \retval 1 PD is created */ extern int livebox_pd_is_created(struct livebox *handler); /*! * \brief Check the content type of the progressive disclosure of given handler + * \details N/A + * \remarks N/A * \param[in] handler * \return int + * \retval PD_TYPE_BUFFER Contents of a PD is based on canvas buffer(shared) + * \retval PD_TYPE_TEXT Contents of a PD is based on formatted text file + * \retval PD_TYPE_PIXMAP Contents of a livebox is shared by the pixmap(depends on X) + * \retval PD_TYPE_INVALID + * \pre N/A + * \post N/A + * \see livebox_pd_type */ extern enum livebox_pd_type livebox_pd_type(struct livebox *handler); /*! * \brief Check the existence of a livebox about given package name + * \details N/A + * \remarks N/A * \param[in] pkgname * \return int + * \retval 1 if the box is exists + * \retval 0 if the box is not exists + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_is_exists(const char *pkgname); /*! * \brief Set function table for parsing the text content of a livebox + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] ops * \return int + * \retval LB_STATUS_SUCCESS + * \retval LB_STATUS_ERROR_INVALID + * \see livebox_set_pd_text_handler */ extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops); /*! * \brief Set function table for parsing the text content of a Progressive Disclosure + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] ops * \return int + * \retval LB_STATUS_SUCCESS + * \retval LB_STATUS_ERROR_INVALID + * \see livebox_set_text_handler */ extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops); /*! * \brief Emit a text signal to given livebox only if it is a text type. + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] emission * \param[in] source @@ -636,132 +1127,244 @@ extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_s * \param[in] ey * \param[in] cb * \param[in] data + * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \see ret_cb_t */ 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); /*! * \brief Set a private data pointer to carry it using given handler + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] data * \return int + * \retval LB_STATUS_SUCCESS + * \retval LB_STATUS_ERROR_INVALID + * \pre N/A + * \post N/A + * \see livebox_get_data */ extern int livebox_set_data(struct livebox *handler, void *data); /*! * \brief Get private data pointer which is carried by given handler + * \details N/A + * \remarks N/A * \param[in] handler - * \return int + * \return void * + * \retval data pointer + * \pre N/A + * \post N/A + * \see livebox_set_data */ extern void *livebox_get_data(struct livebox *handler); /*! * \brief Subscribe the event for liveboxes only in given cluster and sub-cluster + * \details N/A + * \remarks N/A * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event. * If you use the "*", value in the category will be ignored. * \param[in] category "*" can be used for subscribe liveboxes events of all category(sub-cluster) in given "cluster" - * \return int Success 0, fails error code + * \return int + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_unsubscribe_group */ extern int livebox_subscribe_group(const char *cluster, const char *category); /*! * \brief Unsubscribe the event for the liveboxes, but you will receive already added liveboxes event. + * \details N/A + * \remarks N/A * \param[in] cluster "*" can be used for subscribe all cluster's liveboxes event. * If you use the "*", value in the category will be ignored. * \param[in] category "*" can be used for subscribe all sub-cluster's liveboxes event in given "cluster" - * \return int Success 0, fails error code + * \return int + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_subscribe_group */ extern int livebox_unsubscribe_group(const char *cluster, const char *category); /*! * \brief Refresh the group(cluster/sub-cluser(aka. category)) + * \details N/A + * \remarks N/A * \param[in] cluster Cluster ID * \param[in] category Sub-cluster ID - * \return int Success 0 or negative value + * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_refresh_group(const char *cluster, const char *category); /*! * \brief Refresh a livebox + * \details N/A + * \remarks N/A * \param[in] handler - * \return int Success 0 or negative value + * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_refresh(struct livebox *handler); /*! * \brief Pixmap Id of a livebox content + * \details N/A + * \remarks N/A * \param[in] handler * \return int - * \sa livebox_pd_pixmap + * \retval 0 if the pixmap is not created + * \retval pixmap Pixmap Id need to be casted to (unsigned int) type + * \pre N/A + * \post N/A + * \see livebox_pd_pixmap */ extern int livebox_lb_pixmap(const struct livebox *handler); /*! * \brief Pixmap Id of a PD content + * \details N/A + * \remarks N/A * \param[in] handler * \return int - * \sa livebox_lb_pixmap + * \retval 0 if the pixmap is not created + * \retval pixmap Pixmap Id need to be casted to (unsigned int) type + * \pre N/A + * \post N/A + * \see livebox_lb_pixmap */ extern int livebox_pd_pixmap(const struct livebox *handler); /*! * \brief + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] cb * \param[in] data * \return int - * \sa livebox_release_pd_pixmap - * \sa livebox_acquire_lb_pixmap + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_release_pd_pixmap + * \see livebox_acquire_lb_pixmap + * \see ret_cb_t */ extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data); /*! * \brief Release the acquired pixmap ID + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] pixmap * \return int - * \sa livebox_acquire_pd_pixmap - * \sa livebox_release_lb_pixmap + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_acquire_pd_pixmap + * \see livebox_release_lb_pixmap */ extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap); /*! * \brief + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] cb * \param[in] data * \return int - * \sa livebox_release_lb_pixmap - * \sa livebox_acquire_pd_pixmap + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_release_lb_pixmap + * \see livebox_acquire_pd_pixmap + * \see ret_cb_t */ extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data); /*! * \brief + * \details N/A + * \remarks N/A * \param[in] handler * \param[in] pixmap * \return int - * \sa livebox_acquire_lb_pixmap - * \sa livebox_release_pd_pixmap + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see livebox_acquire_lb_pixmap + * \see livebox_release_pd_pixmap */ extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap); /*! * \brief Update the visible state of a livebox + * \details N/A + * \remarks N/A * \param[in] handler Handler of a livebox * \param[in] state Configure the current visible state of a livebox * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_BUSY + * \retval LB_STATUS_ERROR_PERMISSION + * \retval LB_STATUS_ERROR_ALREADY + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \pre N/A + * \post N/A + * \see N/A */ extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state); /*! * \brief Current visible state of a livebox + * \details N/A + * \remarks N/A * \param[in] handler Handler of a livebox - * \return enum visible state + * \return livebox_visible_state + * \retval LB_SHOW Livebox is showed. Default state + * \retval LB_HIDE Livebox is hide, Update timer is not be freezed. but you cannot receive any updates events. you should refresh(reload) the content of a livebox when you make this show again + * \retval LB_HIDE_WITH_PAUSE Livebix is hide, it will paused the update timer, but if a livebox update its contents, update event will come to you + * \retval LB_VISIBLE_ERROR To enlarge the size of this enumeration type + * \pre N/A + * \post N/A + * \see N/A */ extern enum livebox_visible_state livebox_visibility(struct livebox *handler); /*! * \brief Set the update mode of current livebox + * \details N/A + * \remarks N/A * if you set 1 for active update mode, you should get buffer without updated event from provider. * But is passive mode, you have to update content of a box when you get updated event. * Default is Passive mode. @@ -770,19 +1373,34 @@ extern enum livebox_visible_state livebox_visibility(struct livebox *handler); * \param[in] cb Result callback function * \param[in] data Callback data * \return int + * \retval LB_STATUS_ERROR_INVALID + * \retval LB_STATUS_ERROR_BUSY + * \retval LB_STATUS_ERROR_PERMISSION + * \retval LB_STATUS_ERROR_ALREADY + * \retval LB_STATUS_ERROR_FAULT + * \retval LB_STATUS_SUCCESS + * \see ret_cb_t */ extern int livebox_set_update_mode(struct livebox *handler, int active_update, ret_cb_t cb, void *data); /*! * \brief Is this box in the active update mode? + * \details N/A + * \remarks N/A * \param[in] handler HAndler of a livebox - * \return int 0 if passive mode or 1 if active mode or error code + * \return int + * \retval 0 if passive mode + * \retval 1 if active mode or error code + * \see N/A */ extern int livebox_is_active_update(struct livebox *handler); +/*! + * \} + */ + #ifdef __cplusplus } #endif #endif -/* End of a file */ diff --git a/live.viewer/include/debug.h b/live.viewer/include/debug.h index 5021bfa..2efc6dc 100644 --- a/live.viewer/include/debug.h +++ b/live.viewer/include/debug.h @@ -14,18 +14,6 @@ * limitations under the License. */ -#if !defined(SECURE_LOGD) -#define SECURE_LOGD LOGD -#endif - -#if !defined(SECURE_LOGE) -#define SECURE_LOGE LOGE -#endif - -#if !defined(SECURE_LOGW) -#define SECURE_LOGW LOGW -#endif - #if !defined(FLOG) #define DbgPrint(format, arg...) SECURE_LOGD("[%s/%s:%d] " format, util_basename(__FILE__), __func__, __LINE__, ##arg) #define ErrPrint(format, arg...) SECURE_LOGE("[%s/%s:%d] " format, util_basename(__FILE__), __func__, __LINE__, ##arg) diff --git a/packaging/liblivebox-viewer.spec b/packaging/liblivebox-viewer.spec index 17f3f7a..f26a2dd 100644 --- a/packaging/liblivebox-viewer.spec +++ b/packaging/liblivebox-viewer.spec @@ -57,7 +57,6 @@ mkdir -p %{buildroot}/%{_datarootdir}/license %files devel %defattr(-,root,root,-) %{_includedir}/livebox-viewer/livebox.h -%{_datarootdir}/doc/livebox-viewer/livebox-viewer_PG.h %{_libdir}/pkgconfig/*.pc # End of a file diff --git a/src/fb.c b/src/fb.c index 13f6658..1d9fc75 100644 --- a/src/fb.c +++ b/src/fb.c @@ -458,7 +458,7 @@ int fb_release_buffer(void *data) if (!data) { ErrPrint("buffer data == NIL\n"); - return 0; + return LB_STATUS_ERROR_INVALID; } buffer = container_of(data, struct buffer, data); @@ -507,7 +507,7 @@ int fb_release_buffer(void *data) break; } - return 0; + return LB_STATUS_SUCCESS; } int fb_refcnt(void *data) diff --git a/src/livebox.c b/src/livebox.c index 5834a3e..27d1290 100644 --- a/src/livebox.c +++ b/src/livebox.c @@ -1094,7 +1094,7 @@ EAPI int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *da if (handler->lb.width == w && handler->lb.height == h) { DbgPrint("No changes\n"); - return LB_STATUS_ERROR_ALREADY;; + return LB_STATUS_ERROR_ALREADY; } packet = packet_create("resize", "ssii", handler->pkgname, handler->id, w, h); @@ -2425,7 +2425,7 @@ EAPI int livebox_emit_text_signal(struct livebox *handler, const char *emission, destroy_cb_info(cbinfo); } - return LB_STATUS_ERROR_FAULT; + return ret; } EAPI int livebox_subscribe_group(const char *cluster, const char *category) @@ -2433,7 +2433,7 @@ EAPI int livebox_subscribe_group(const char *cluster, const char *category) struct packet *packet; /*! - * \TODO + * \todo * Validate the group info using DB * If the group info is not valid, do not send this request */ @@ -2452,7 +2452,7 @@ EAPI int livebox_unsubscribe_group(const char *cluster, const char *category) struct packet *packet; /*! - * \TODO + * \todo * Validate the group info using DB * If the group info is not valid, do not send this request * AND Check the subscribed or not too