From 8c6993c5bbaed8f0897afd1be89a12889e809545 Mon Sep 17 00:00:00 2001 From: "seungha.son" Date: Fri, 16 Dec 2016 14:48:28 +0900 Subject: [PATCH] Fix API description Signed-off-by: seungha.son Change-Id: Ie4813615ba4f84a447f158d11f831c28efc8395d --- doc/shortcut_doc.h | 15 ++- lib/include/shortcut_manager.h | 253 +++++++++++++++++++---------------------- 2 files changed, 124 insertions(+), 144 deletions(-) diff --git a/doc/shortcut_doc.h b/doc/shortcut_doc.h index 3736068..458264b 100755 --- a/doc/shortcut_doc.h +++ b/doc/shortcut_doc.h @@ -15,20 +15,23 @@ * */ + #ifndef __SHORTCUT_DOC_H__ #define __SHORTCUT_DOC_H__ + /** + * @ingroup CAPI_APPLICATION_FRAMEWORK * @defgroup SHORTCUT_MODULE Shortcut * @brief To enhance the Add to home feature. - * - The other for the application developers who should implement the Add to home feature. - * @ingroup CAPI_APPLICATION_FRAMEWORK + * - The other for the application developers who should implement the Add to home feature. * @section SHORTCUT_MODULE_HEADER Required Header - * \#include - * @section SHORTCUT_MODULE_OVERVIEW Overview -It provides function of creating shortcut. -Developers can use the "shortcut_add_to_home" API to create their shortcut to a home screen. + * \#include * + * @section SHORTCUT_MODULE_OVERVIEW Overview + It provides function of creating shortcut. + Developers can use the "shortcut_add_to_home" API to create their shortcut to a home screen. */ + #endif /* __SHORTCUT_DOC_H__ */ diff --git a/lib/include/shortcut_manager.h b/lib/include/shortcut_manager.h index 4e377fd..5683535 100755 --- a/lib/include/shortcut_manager.h +++ b/lib/include/shortcut_manager.h @@ -35,19 +35,20 @@ extern "C" { * @{ */ + /** * @brief Enumeration for shortcut types. * @details Basically, two types of shortcuts are defined. * Every homescreen developer should support these types of shortcuts. - * Or return a proper errno to figure out why the application failed to add a shortcut. + * Or return, a proper errno to figure out why the application failed to add a shortcut. * #LAUNCH_BY_APP is used for adding a package itself as a shortcut. * #LAUNCH_BY_URI is used for adding a shortcut for "uri" data. * @since_tizen 2.3 */ typedef enum _shortcut_type { /**< Use these */ - LAUNCH_BY_APP = 0x00000000, /**< Launch the application itself */ - LAUNCH_BY_URI = 0x00000001, /**< Launch the application with the given data(URI) */ + LAUNCH_BY_APP = 0x00000000, /**< Launch the application itself */ + LAUNCH_BY_URI = 0x00000001, /**< Launch the application with the given data(URI) */ } shortcut_type; /** @@ -55,22 +56,23 @@ typedef enum _shortcut_type { * @since_tizen 2.4 */ typedef enum shortcut_widget_size { - WIDGET_SIZE_DEFAULT = 0x10000000, /* Type mask for the normal mode widget , don't use this value for specific size.*/ - WIDGET_SIZE_1x1 = 0x10010000, /**< 1x1 */ - WIDGET_SIZE_2x1 = 0x10020000, /**< 2x1 */ - WIDGET_SIZE_2x2 = 0x10040000, /**< 2x2 */ - WIDGET_SIZE_4x1 = 0x10080000, /**< 4x1 */ - WIDGET_SIZE_4x2 = 0x10100000, /**< 4x2 */ - WIDGET_SIZE_4x3 = 0x10200000, /**< 4x3 */ - WIDGET_SIZE_4x4 = 0x10400000, /**< 4x4 */ - WIDGET_SIZE_4x5 = 0x11000000, /**< 4x5 */ - WIDGET_SIZE_4x6 = 0x12000000, /**< 4x6 */ + WIDGET_SIZE_DEFAULT = 0x10000000, /* Type mask for the normal mode widget , don't use this value for specific size.*/ + WIDGET_SIZE_1x1 = 0x10010000, /**< 1x1 */ + WIDGET_SIZE_2x1 = 0x10020000, /**< 2x1 */ + WIDGET_SIZE_2x2 = 0x10040000, /**< 2x2 */ + WIDGET_SIZE_4x1 = 0x10080000, /**< 4x1 */ + WIDGET_SIZE_4x2 = 0x10100000, /**< 4x2 */ + WIDGET_SIZE_4x3 = 0x10200000, /**< 4x3 */ + WIDGET_SIZE_4x4 = 0x10400000, /**< 4x4 */ + WIDGET_SIZE_4x5 = 0x11000000, /**< 4x5 */ + WIDGET_SIZE_4x6 = 0x12000000, /**< 4x6 */ WIDGET_SIZE_EASY_DEFAULT = 0x30000000, /* Type mask for the easy mode widget, don't use this value for specific size. */ - WIDGET_SIZE_EASY_1x1 = 0x30010000, /**< Easy mode 1x1 */ - WIDGET_SIZE_EASY_3x1 = 0x30020000, /**< Easy mode 3x2 */ - WIDGET_SIZE_EASY_3x3 = 0x30040000, /**< Easy mode 3x3 */ + WIDGET_SIZE_EASY_1x1 = 0x30010000, /**< Easy mode 1x1 */ + WIDGET_SIZE_EASY_3x1 = 0x30020000, /**< Easy mode 3x2 */ + WIDGET_SIZE_EASY_3x3 = 0x30040000, /**< Easy mode 3x3 */ } shortcut_widget_size_e; + /** * @brief Called to receive the result of shortcut_add_to_home(). * @since_tizen 2.3 @@ -78,18 +80,19 @@ typedef enum shortcut_widget_size { * otherwise it returns an errno * @param[in] data The callback data * @return int @c 0 if there is no error, - * otherwise errno + * otherwise errno * @see shortcut_add_to_home() */ typedef int (*result_cb_t)(int ret, void *data); + /** - * @brief Adds a shortcut to home, asynchronously - * @remarks If a homescreen does not support this feature, you will get a proper error code.\n - * Application must check the return value of this function.\n - * Application must check the return status from the callback function.\n - * Application should set the callback function to get the result of this request. + * @brief Adds a shortcut to home, asynchronously. * @since_tizen 2.3 + * @remarks If a homescreen does not support this feature, you will get a proper error code.\n + * Application must check the return value of this function.\n + * Application must check the return status from the callback function.\n + * Application should set the callback function to get the result of this request. * @privlevel public * @privilege %http://tizen.org/privilege/shortcut * @param[in] name The name of the created shortcut icon @@ -100,8 +103,8 @@ typedef int (*result_cb_t)(int ret, void *data); * otherwise @c 0 * @param[in] result_cb The address of the callback function that is called when the result comes back from the viewer * @param[in] data The callback data that is used in the callback function - * - * @return 0 on success, otherwise a negative error value + * @return @c 0 on success, + * otherwise a negative error value * @retval #SHORTCUT_ERROR_NONE Successful * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory @@ -113,70 +116,61 @@ typedef int (*result_cb_t)(int ret, void *data); * @retval #SHORTCUT_ERROR_EXIST Shortcut is already exist * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem - * * @pre You have to prepare the callback function. - * * @post You have to check the return status from the callback function which is passed by the argument. - * * @see result_cb_t - * * @par Example * @code - * - * #include - * #include - * - * static int result_cb(int ret, int pid, void *data) - * { - * if (ret < 0) - * dlog_print("Failed to add a shortcut: %s\n", perror(ret)); - * - * dlog_print("Processed by the %d\n", pid); - * return 0; - * } - * - * static int app_create(void *data) - * { - * char* data_path = app_get_data_path(); - * int path_len = strlen(data_path)+10; - * char * path = malloc(path_len); - * memset(path, 0, path_len); - * strncat(path, data_path, path_len); - * strncat(path, "Friend.jpg", path_len); - * - * shortcut_add_to_home("With friends", - * LAUNCH_BY_URI, "gallery:0000-0000", - * path, 0, result_cb, NULL); - * free(path); - * - * return 0; - * } - * +#include +#include +static int result_cb(int ret, int pid, void *data) +{ + if (ret < 0) + dlog_print("Failed to add a shortcut: %s\n", perror(ret)); + + dlog_print("Processed by the %d\n", pid); + return 0; +} + +static int app_create(void *data) +{ + char* data_path = app_get_data_path(); + int path_len = strlen(data_path)+10; + char * path = malloc(path_len); + memset(path, 0, path_len); + strncat(path, data_path, path_len); + strncat(path, "Friend.jpg", path_len); + + shortcut_add_to_home("With friends", LAUNCH_BY_URI, "gallery:0000-0000", path, 0, result_cb, NULL); + free(path); + + return 0; +} * @endcode */ int shortcut_add_to_home(const char *name, shortcut_type type, const char *uri, const char *icon, int allow_duplicate, result_cb_t result_cb, void *data); + /** * @brief Adds a widget to home, asynchronously. - * @remarks If a homescreen does not support this feature, you will get a proper error code.\n - * Application must check the return value of this function.\n - * Application must check the return status from the callback function.\n - * Application should set the callback function to get the result of this request. - * * @since_tizen 2.4 + * @remarks If a homescreen does not support this feature, you will get a proper error code.\n + * Application must check the return value of this function.\n + * Application must check the return status from the callback function.\n + * Application should set the callback function to get the result of this request. * @privlevel public * @privilege %http://tizen.org/privilege/shortcut - * - * @param[in] name The name of the created widget. Will be shown when the widget is not prepared. + * @param[in] name The name of the created widget which will be shown when the widget is not prepared * @param[in] size The size of widget - * @param[in] widget_id Widget id - * @param[in] icon The absolute path of an icon file. Will be shown when the widget is not prepared. + * @param[in] widget_id Widget ID + * @param[in] icon The absolute path of an icon file which will be shown when the widget is not prepared * @param[in] period The Update period in seconds - * @param[in] allow_duplicate @c 1 if it accepts the duplicated widget, otherwise @c 0 + * @param[in] allow_duplicate @c 1 if it accepts the duplicated widget, + * otherwise @c 0 * @param[in] result_cb The address of the callback function that is called when the result comes back from the viewer * @param[in] data The callback data that is used in the callback function - * - * @return 0 on success, otherwise a negative error value + * @return @c 0 on success, + * otherwise a negative error value * @retval #SHORTCUT_ERROR_NONE Successful * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory @@ -185,48 +179,45 @@ int shortcut_add_to_home(const char *name, shortcut_type type, const char *uri, * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem - * * @pre You have to prepare the callback function. - * * @post You have to check the return status from the callback function which is passed by the argument. - * * @see result_cb_t * @see shortcut_widget_size_e - * * @par Example * @code - * - * #include - * #include - * #include - * - * #define TIZEN_PATH_MAX 1024 - * - * static int result_cb(int ret, int pid, void *data) - * { - * if (ret < 0) - * dlog_print("Failed to add a widget: %s\n", perror(ret)); - * - * dlog_print("Processed by the %d\n", pid); - * return 0; - * } - * - * static int app_create(void *data) - * { - * char *image_root = NULL; - * char image_path[TIZEN_PATH_MAX] = {0, }; - * storage_get_directory(STORAGE_TYPE_INTERNAL, STORAGE_DIRECTORY_IMAGES, &image_root); - * snprintf(image_path, TIZEN_PATH_MAX, "%s/alter_icon.png", image_root); - * shortcut_add_to_home_widget("alter_name", - * WIDGET_SIZE_1x1, "org.tizen.testwidget", - * image_path, -1.0f, 0, result_cb, NULL); - * return 0; - * } - * +#include +#include +#include + +#define TIZEN_PATH_MAX 1024 +static int result_cb(int ret, int pid, void *data) +{ + if (ret < 0) + dlog_print("Failed to add a widget: %s\n", perror(ret)); + + dlog_print("Processed by the %d\n", pid); + + return 0; +} + +static int app_create(void *data) +{ + char *image_root = NULL; + char image_path[TIZEN_PATH_MAX] = {0,}; + + storage_get_directory(STORAGE_TYPE_INTERNAL, STORAGE_DIRECTORY_IMAGES, &image_root); + snprintf(image_path, TIZEN_PATH_MAX, "%s/alter_icon.png", image_root); + + shortcut_add_to_home_widget("alter_name", WIDGET_SIZE_1x1, "org.tizen.testwidget", + image_path, -1.0f, 0, result_cb, NULL); + + return 0; +} * @endcode */ int shortcut_add_to_home_widget(const char *name, shortcut_widget_size_e size, const char *widget_id, const char *icon, double period, int allow_duplicate, result_cb_t result_cb, void *data); + /** * @brief Removes a shortcut from home, asynchronously. * @details If the callback function registered for a widget, the shortcut deletion is possible. @@ -236,7 +227,6 @@ int shortcut_add_to_home_widget(const char *name, shortcut_widget_size_e size, c * @param[in] name The name of the created shortcut icon * @param[in] result_cb The address of the callback function that is called when the result comes back from the viewer * @param[in] user_data The callback data that is used in the callback function - * * @return 0 on success, otherwise a negative error value * @retval #SHORTCUT_ERROR_NONE Successful * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter @@ -244,20 +234,13 @@ int shortcut_add_to_home_widget(const char *name, shortcut_widget_size_e size, c * @retval #SHORTCUT_ERROR_IO_ERROR I/O Error * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem - * * @pre You have to prepare the callback function. - * * @post You have to check the return status from the callback function which is passed by the argument. - * * @see result_cb_t - * * @par Example * @code - #include -... - int result_cb(int ret, void *data) { if (ret < 0) @@ -266,25 +249,21 @@ int result_cb(int ret, void *data) return 0; } -... - { int result; result = shortcut_remove_from_home("shortcut_name", result_cb, NULL); - if (result != SHORTCUT_ERROR_NONE) { dlog_print("Failed to remove a shortcut: %d\n", result); return result; } -... - } * @endcode */ int shortcut_remove_from_home(const char *name, result_cb_t result_cb, void *user_data); + /** * @brief Called to receive the result of shortcut_get_list(). * @since_tizen 2.4 @@ -299,20 +278,19 @@ int shortcut_remove_from_home(const char *name, result_cb_t result_cb, void *use */ typedef int (*shortcut_list_cb)(const char *package_name, const char *icon, const char *name, const char *extra_key, const char *extra_data, void *user_data); + /** * @brief Gets the preset list of shortcut template from the installed package, synchronously. - * @remarks If a homescreen does not support this feature, you will get a proper error code.\n - * Application must check the return value of this function.\n - * Application must check the return status from the callback function.\n - * Application should set the callback function to get the result of this request. - * * @since_tizen 2.4 + * @remarks If a homescreen does not support this feature, you will get a proper error code.\n + * Application must check the return value of this function.\n + * Application must check the return status from the callback function.\n + * Application should set the callback function to get the result of this request. * @privlevel public * @privilege %http://tizen.org/privilege/shortcut * @param[in] package_name The package name * @param[in] list_cb The callback function to get the shortcut item information * @param[in] data The callback data that is used in the callback function - * * @return The return type (int) * @retval @c N Number of items (call count of the callback function) * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter @@ -327,10 +305,11 @@ typedef int (*shortcut_list_cb)(const char *package_name, const char *icon, cons */ int shortcut_get_list(const char *package_name, shortcut_list_cb list_cb, void *data); + /** * @brief Called to the add_to_home request. * @details The homescreen should define a callback as this type and implement the service code - * for adding a new application shortcut. + * for adding a new application shortcut. * @since_tizen 2.4 * @param[in] package_name The name of package * @param[in] name The name of the created shortcut icon @@ -342,12 +321,13 @@ int shortcut_get_list(const char *package_name, shortcut_list_cb list_cb, void * * otherwise a shourtcut should exist only once * @param[in] data The callback data * @return The result of handling a shortcut creation request\n - * This returns @c 0 if the add_to_home request is handled successfully, - * otherwise it returns a proper errno. + * This returns @c 0 if the add_to_home request is handled successfully, + * otherwise it returns a proper errno * @see shortcut_set_request_cb() */ typedef int (*shortcut_request_cb)(const char *package_name, const char *name, int type, const char *content_info, const char *icon, int pid, double period, int allow_duplicate, void *data); + /** * @brief Called to the shortcut_remove_from_home request. * @since_tizen 3.0 @@ -362,19 +342,20 @@ typedef int (*shortcut_request_cb)(const char *package_name, const char *name, i */ typedef int (*shortcut_remove_cb)(const char *package_name, const char *name, int sender_pid, void *user_data); + /** - * @brief Registers a callback function to listen the add requests from applications. - * @remarks Should be used in the homescreen.\n - * Should check the return value of this function. - * Prospective Clients: Homescreen. + * @brief Registers a callback function to listen requests from applications. * @since_tizen 2.4 + * @remarks Should be used in the homescreen.\n + * Should check the return value of this function. + * Prospective Clients: Homescreen. * @privlevel public * @privilege %http://tizen.org/privilege/shortcut * * @param[in] request_cb The callback function pointer that is invoked when add_to_home is requested * @param[in] data The callback data to deliver to the callback function - * - * @return 0 on success, otherwise a negative error value + * @return @c 0 on success, + * otherwise a negative error value * @retval #SHORTCUT_ERROR_NONE Successful * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory @@ -382,24 +363,23 @@ typedef int (*shortcut_remove_cb)(const char *package_name, const char *name, in * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem * @pre You have to prepare a callback function. - * * @post If a request is sent from the application, the registered callback will be invoked. - * * @see request_cb_t * @see shortcut_error_e */ int shortcut_set_request_cb(shortcut_request_cb request_cb, void *data); + /** * @brief Unregisters a callback for the shortcut request. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/shortcut - * * @see shortcut_set_request_cb */ void shortcut_unset_request_cb(void); + /** * @brief Registers the callback function to listen the remove requests from applications. * @remarks Should be used in the homescreen.\n @@ -408,10 +388,8 @@ void shortcut_unset_request_cb(void); * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/shortcut - * * @param[in] remove_cb The callback function pointer that is invoked when remove_from_home is requested * @param[in] data The callback data to deliver to the callback function - * * @return 0 on success, otherwise a negative error value * @retval #SHORTCUT_ERROR_NONE Successful * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter @@ -420,24 +398,23 @@ void shortcut_unset_request_cb(void); * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem * @pre You have to prepare a callback function. - * * @post If a request is sent from the application, the registered callback will be invoked. - * * @see remove_cb_t * @see shortcut_error_e */ int shortcut_set_remove_cb(shortcut_remove_cb remove_cb, void *data); + /** * @brief Unregisters a callback for the shortcut remove. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/shortcut - * * @see shortcut_set_remove_cb */ void shortcut_unset_remove_cb(void); + /** * @} */ -- 2.7.4