lib/include/shortcut_manager.h

   1 /*
   2  * Copyright (c) 2011 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  *
  16 */
  17
  18 #ifndef __SHORTCUT_MANAGER_H__
  19 #define __SHORTCUT_MANAGER_H__
  20
  21 #include <tizen.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file shortcut_manager.h
  29  * @brief This file declares the API of the libshortcut library.
  30  */
  31
  32 /**
  33  * @addtogroup SHORTCUT_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Enumeration for shortcut types.
  39  * @details Basically, two types of shortcuts are defined.
  40  *          Every homescreen developer should support these types of shortcuts.
  41  *          Or return a proper errno to figure out why the application failed to add a shortcut.
  42  *          #LAUNCH_BY_APP is used for adding a package itself as a shortcut.
  43  *          #LAUNCH_BY_URI is used for adding a shortcut for "uri" data.
  44  * @since_tizen 2.3
  45  */
  46 typedef enum _shortcut_type {
  47         /**< Use these */
  48         LAUNCH_BY_APP   = 0x00000000,   /**< Launch the application itself */
  49         LAUNCH_BY_URI   = 0x00000001,   /**< Launch the application with the given data(URI) */
  50 } shortcut_type;
  51
  52 /**
  53  * @brief Enumeration for values of shortcut response types.
  54  * @since_tizen 2.3
  55  */
  56 enum shortcut_error_e {
  57         SHORTCUT_ERROR_NONE = TIZEN_ERROR_NONE,                         /**< Successfully handled */
  58         SHORTCUT_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,       /**< Shortcut request is not valid, invalid parameter or invalid argument value */
  59         SHORTCUT_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,       /**< Memory is not enough to handle a new request */
  60         SHORTCUT_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR,         /**< Unable to access the file or DB. Check your resource files */
  61         SHORTCUT_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,       /**< Has no permission to add a shortcut */
  62         SHORTCUT_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,       /**< Not supported shortcut */
  63         SHORTCUT_ERROR_RESOURCE_BUSY = TIZEN_ERROR_RESOURCE_BUSY,               /**< Receiver is busy, try again later */
  64         SHORTCUT_ERROR_NO_SPACE = TIZEN_ERROR_SHORTCUT | 0x0001,        /**< There is no space to add a new shortcut */
  65         SHORTCUT_ERROR_EXIST = TIZEN_ERROR_SHORTCUT | 0x0002,           /**< Shortcut is already added */
  66         SHORTCUT_ERROR_FAULT = TIZEN_ERROR_SHORTCUT | 0x0004,           /**< Failed to add a shortcut. Unrecoverable error */
  67         SHORTCUT_ERROR_COMM = TIZEN_ERROR_SHORTCUT | 0x0040             /**< Connection is not established. or there is a problem in the communication */
  68 };
  69
  70 /**
  71  * @brief Enumeration for sizes of shortcut widget.
  72  * @since_tizen 2.4
  73  */
  74 typedef enum shortcut_widget_size {
  75         WIDGET_SIZE_DEFAULT      = 0x10000000,  /* Type mask for the normal mode widget , don't use this value for specific size.*/
  76         WIDGET_SIZE_1x1          = 0x10010000,  /**< 1x1 */
  77         WIDGET_SIZE_2x1          = 0x10020000,  /**< 2x1 */
  78         WIDGET_SIZE_2x2          = 0x10040000,  /**< 2x2 */
  79         WIDGET_SIZE_4x1          = 0x10080000,  /**< 4x1 */
  80         WIDGET_SIZE_4x2          = 0x10100000,  /**< 4x2 */
  81         WIDGET_SIZE_4x3          = 0x10200000,  /**< 4x3 */
  82         WIDGET_SIZE_4x4          = 0x10400000,  /**< 4x4 */
  83         WIDGET_SIZE_4x5          = 0x11000000,  /**< 4x5 */
  84         WIDGET_SIZE_4x6          = 0x12000000,  /**< 4x6 */
  85         WIDGET_SIZE_EASY_DEFAULT = 0x30000000,  /* Type mask for the easy mode widget, don't use this value for specific size. */
  86         WIDGET_SIZE_EASY_1x1     = 0x30010000,  /**< Easy mode 1x1 */
  87         WIDGET_SIZE_EASY_3x1     = 0x30020000,  /**< Easy mode 3x2 */
  88         WIDGET_SIZE_EASY_3x3     = 0x30040000,  /**< Easy mode 3x3 */
  89 } shortcut_widget_size_e;
  90
  91 /**
  92  * @brief Called to receive the result of shortcut_add_to_home().
  93  * @since_tizen 2.3
  94  * @param[in] ret The result value, it could be @c 0 if it succeeds to add a shortcut,
  95  *                otherwise it returns an errno
  96  * @param[in] data The callback data
  97  * @return int @c 0 if there is no error,
  98  *      otherwise errno
  99  * @see shortcut_add_to_home()
 100  */
 101 typedef int (*result_cb_t)(int ret, void *data);
 102
 103 /**
 104  * @brief Adds a shortcut to home, asynchronously
 105  * @remarks If a homescreen does not support this feature, you will get a proper error code.\n
 106  * Application must check the return value of this function.\n
 107  * Application must check the return status from the callback function.\n
 108  * Application should set the callback function to get the result of this request.
 109  * @since_tizen 2.3
 110  * @privlevel public
 111  * @privilege %http://tizen.org/privilege/shortcut
 112  * @param[in] name The name of the created shortcut icon
 113  * @param[in] type The type of shortcuts
 114  * @param[in] uri The specific information for delivering to the viewer for creating a shortcut
 115  * @param[in] icon The absolute path of an icon file
 116  * @param[in] allow_duplicate @c 1 if it accepts the duplicated shortcut,
 117  *                            otherwise @c 0
 118  * @param[in] result_cb The address of the callback function that is called when the result comes back from the viewer
 119  * @param[in] data The callback data that is used in the callback function
 120  *
 121  * @return #SHORTCUT_ERROR_NONE on success, other value on failure
 122  * @retval #SHORTCUT_ERROR_NONE Successful
 123  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid parameter
 124  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory
 125  * @retval #SHORTCUT_ERROR_IO_ERROR I/O error
 126  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 127  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 128  * @retval #SHORTCUT_ERROR_RESOURCE_BUSY Device or resource busy
 129  * @retval #SHORTCUT_ERROR_NO_SPACE No space
 130  * @retval #SHORTCUT_ERROR_EXIST Already exist
 131  * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error
 132  * @retval #SHORTCUT_ERROR_COMM Connection failed
 133  *
 134  * @pre You have to prepare the callback function.
 135  *
 136  * @post You have to check the return status from the callback function which is passed by the argument.
 137  *
 138  * @see result_cb_t
 139  *
 140  * @par Example
 141  * @code
 142  *
 143  * #include <stdio.h>
 144  * #include <shortcut_manager.h>
 145  *
 146  * static int result_cb(int ret, int pid, void *data)
 147  * {
 148  *      if (ret < 0)
 149  *              dlog_print("Failed to add a shortcut: %s\n", perror(ret));
 150  *
 151  *      dlog_print("Processed by the %d\n", pid);
 152  *      return 0;
 153  * }
 154  *
 155  * static int app_create(void *data)
 156  * {
 157  *      char* data_path = app_get_data_path();
 158  *      int path_len = strlen(data_path)+10;
 159  *      char * path = malloc(path_len);
 160  *      memset(path, 0, path_len);
 161  *      strncat(path, data_path, path_len);
 162  *      strncat(path, "Friend.jpg", path_len);
 163  *
 164  *      shortcut_add_to_home("With friends",
 165  *                                      LAUNCH_BY_URI, "gallery:0000-0000",
 166  *                                      path, 0, result_cb, NULL);
 167  *      free(path);
 168  *
 169  *      return 0;
 170  * }
 171  *
 172  * @endcode
 173  */
 174 extern 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);
 175
 176 /**
 177  * @brief Adds a widget to home, asynchronously.
 178  * @remarks If a homescreen does not support this feature, you will get a proper error code.\n
 179  * Application must check the return value of this function.\n
 180  * Application must check the return status from the callback function.\n
 181  * Application should set the callback function to get the result of this request.
 182  *
 183  * @since_tizen 2.4
 184  * @privlevel public
 185  * @privilege %http://tizen.org/privilege/shortcut
 186  *
 187  * @param[in] name The name of the created widget. Will be shown when the widget is not prepared.
 188  * @param[in] size_type The size of widget
 189  * @param[in] widget_id Widget id
 190  * @param[in] icon The absolute path of an icon file. Will be shown when the widget is not prepared.
 191  * @param[in] period The Update period in seconds
 192  * @param[in] allow_duplicate @c 1 if it accepts the duplicated widget, otherwise @c 0
 193  * @param[in] result_cb The address of the callback function that is called when the result comes back from the viewer
 194  * @param[in] data The callback data that is used in the callback function
 195  *
 196  * @return #SHORTCUT_ERROR_NONE on success, other value on failure
 197  * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error
 198  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid parameter or invalid argument value
 199  * @retval #SHORTCUT_ERROR_COMM Connection is not established or there is a problem in the communication
 200  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Memory is not enough to handle a new request
 201  * @retval #SHORTCUT_ERROR_IO_ERROR Unable to access the file or DB  Check your resource files
 202  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Has no permission to add a widget
 203  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Widget is not supported
 204  *
 205  * @pre You have to prepare the callback function.
 206  *
 207  * @post You have to check the return status from the callback function which is passed by the argument.
 208  *
 209  * @see result_cb_t
 210  * @see shortcut_widget_size_e
 211  *
 212  * @par Example
 213  * @code
 214  *
 215  * #include <stdio.h>
 216  * #include <shortcut.h>
 217  * #include <storage.h>
 218  *
 219  * #define TIZEN_PATH_MAX 1024
 220  *
 221  * static int result_cb(int ret, int pid, void *data)
 222  * {
 223  *      if (ret < 0)
 224  *              dlog_print("Failed to add a widget: %s\n", perror(ret));
 225  *
 226  *      dlog_print("Processed by the %d\n", pid);
 227  *      return 0;
 228  * }
 229  *
 230  * static int app_create(void *data)
 231  * {
 232  *      char *image_root = NULL;
 233  *      char image_path[TIZEN_PATH_MAX] = {0, };
 234  *      storage_get_directory(STORAGE_TYPE_INTERNAL, STORAGE_DIRECTORY_IMAGES, &image_root);
 235  *      snprintf(image_path, TIZEN_PATH_MAX, "%s/alter_icon.png", image_root);
 236  *      shortcut_add_to_home_widget("alter_name",
 237  *                                      WIDGET_SIZE_1x1, "org.tizen.testwidget",
 238  *                                      image_path, -1.0f, 0, result_cb, NULL);
 239  *      return 0;
 240  * }
 241  *
 242  * @endcode
 243  */
 244 extern 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);
 245
 246
 247 /**
 248  * @brief Called to receive the result of shortcut_get_list().
 249  * @since_tizen 2.4
 250  * @param[in] package_name The name of package
 251  * @param[in] icon The absolute path of an icon file for this shortcut
 252  * @param[in] name The name of the created shortcut icon
 253  * @param[in] extra_key The user data. A property of shortcut element in manifest file
 254  * @param[in] extra_data The user data. A property of shortcut element in manifest file
 255  * @param[in] user_data The callback user data
 256  * @return SHORTCUT_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop
 257  * @see shortcut_get_list()
 258  */
 259 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);
 260
 261 /**
 262  * @brief Gets the preset list of shortcut template from the installed package, synchronously.
 263  * @remarks If a homescreen does not support this feature, you will get a proper error code.\n
 264  * Application must check the return value of this function.\n
 265  * Application must check the return status from the callback function.\n
 266  * Application should set the callback function to get the result of this request.
 267  *
 268  * @since_tizen 2.4
 269  * @privlevel public
 270  * @privilege %http://tizen.org/privilege/shortcut
 271  * @param[in] package_name The package name
 272  * @param[in] shortcut_list_cb The callback function to get the shortcut item information
 273  * @param[in] data The callback data that is used in the callback function
 274  *
 275  * @return The return type (int)
 276  * @retval @c N Number of items (call count of the callback function)
 277  * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error
 278  * @retval #SHORTCUT_ERROR_IO_ERROR Unable to access the file or DB. Check your resource files
 279  * @pre You have to prepare the callback function.
 280  * @post You have to check the return status from the callback function which is passed by the argument.
 281  *
 282  */
 283 extern int shortcut_get_list(const char *package_name, shortcut_list_cb list_cb, void *data);
 284
 285 /**
 286  * @brief Called to the add_to_home request.
 287  * @details The homescreen should define a callback as this type and implement the service code
 288  *        for adding a new application shortcut.
 289  * @since_tizen 2.4
 290  * @param[in] package_name The name of package
 291  * @param[in] name The name of the created shortcut icon
 292  * @param[in] type One of the three defined types
 293  * @param[in] content_info The specific information for creating a new shortcut
 294  * @param[in] icon The absolute path of an icon file for this shortcut
 295  * @param[in] pid The process ID of who request add_to_home
 296  * @param[in] allow_duplicate @c 1 if the shortcut can be duplicated,
 297  *                            otherwise a shourtcut should exist only once
 298  * @param[in] data The callback data
 299  * @return The result of handling a shortcut creation request\n
 300  *             This returns @c 0 if the add_to_home request is handled successfully,
 301  *             otherwise it returns a proper errno.
 302  * @see shortcut_set_request_cb()
 303  */
 304 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);
 305
 306 /**
 307  * @brief Registers a callback function to listen requests from applications.
 308  * @remarks Should be used in the homescreen.\n
 309  * Should check the return value of this function.
 310   * Prospective Clients: Homescreen.
 311   * @since_tizen 2.4
 312  * @privlevel public
 313  * @privilege %http://tizen.org/privilege/shortcut
 314  *
 315  * @param[in] request_cb The callback function pointer that is invoked when add_to_home is requested
 316  * @param[in] data The callback data to deliver to the callback function
 317  *
 318  * @return #SHORTCUT_ERROR_NONE on success, other value on failure
 319  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Shortcut request is not valid, invalid parameter or invalid argument value
 320  * @retval #SHORTCUT_ERROR_COMM Connection is not established or there is a problem in the communication
 321  * @pre You have to prepare a callback function.
 322  *
 323  * @post If a request is sent from the application, the registered callback will be invoked.
 324  *
 325  * @see request_cb_t
 326  * @see shortcut_error_e
 327  */
 328 extern int shortcut_set_request_cb(shortcut_request_cb request_cb, void *data);
 329
 330
 331 /**
 332  * @}
 333  */
 334
 335 #ifdef __cplusplus
 336 }
 337 #endif
 338
 339 #endif