lib/include/shortcut_manager.h

   1 /*
   2  * Copyright (c) 2011 - 2017 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 #include "shortcut_error.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file shortcut_manager.h
  30  * @brief This file declares the API of the libshortcut library.
  31  */
  32
  33 /**
  34  * @addtogroup SHORTCUT_MODULE
  35  * @{
  36  */
  37
  38
  39 /**
  40  * @brief Enumeration for shortcut types.
  41  * @details Basically, two types of shortcuts are defined.
  42  *          Every homescreen developer should support these types of shortcuts.
  43  *          Or return, a proper errno to figure out why the application failed to add a shortcut.
  44  *          #LAUNCH_BY_APP is used for adding a package itself as a shortcut.
  45  *          #LAUNCH_BY_URI is used for adding a shortcut for "uri" data.
  46  * @since_tizen 2.3
  47  */
  48 typedef enum _shortcut_type {
  49         LAUNCH_BY_APP = 0x00000000, /**< Launch the application itself */
  50         LAUNCH_BY_URI = 0x00000001, /**< Launch the application with the given data(URI) */
  51 } shortcut_type;
  52
  53 /**
  54  * @brief Enumeration for sizes of shortcut widget.
  55  * @since_tizen 2.4
  56  */
  57 typedef enum shortcut_widget_size {
  58         WIDGET_SIZE_DEFAULT = 0x10000000, /**< Type mask for the normal mode widget , don't use this value for specific size.*/
  59         WIDGET_SIZE_1x1 = 0x10010000, /**< 1x1 */
  60         WIDGET_SIZE_2x1 = 0x10020000, /**< 2x1 */
  61         WIDGET_SIZE_2x2 = 0x10040000, /**< 2x2 */
  62         WIDGET_SIZE_4x1 = 0x10080000, /**< 4x1 */
  63         WIDGET_SIZE_4x2 = 0x10100000, /**< 4x2 */
  64         WIDGET_SIZE_4x3 = 0x10200000, /**< 4x3 */
  65         WIDGET_SIZE_4x4 = 0x10400000, /**< 4x4 */
  66         WIDGET_SIZE_4x5 = 0x11000000, /**< 4x5 */
  67         WIDGET_SIZE_4x6 = 0x12000000, /**< 4x6 */
  68         WIDGET_SIZE_EASY_DEFAULT = 0x30000000, /**< Type mask for the easy mode widget, don't use this value for specific size. */
  69         WIDGET_SIZE_EASY_1x1 = 0x30010000, /**< Easy mode 1x1 */
  70         WIDGET_SIZE_EASY_3x1 = 0x30020000, /**< Easy mode 3x2 */
  71         WIDGET_SIZE_EASY_3x3 = 0x30040000, /**< Easy mode 3x3 */
  72 } shortcut_widget_size_e;
  73
  74
  75 /**
  76  * @brief Called to receive the result of shortcut_add_to_home().
  77  * @since_tizen 2.3
  78  * @param[in] ret The result value, it could be @c 0 if it succeeds to add a shortcut,
  79  *                otherwise it returns an errno
  80  * @param[in] user_data The callback data
  81  * @return int @c 0 if there is no error,
  82  *             otherwise errno
  83  * @see shortcut_add_to_home()
  84  */
  85 typedef int (*result_cb)(int ret, void *user_data);
  86
  87
  88 /**
  89  * @brief Adds a shortcut to home, asynchronously.
  90  * @since_tizen 2.3
  91  * @privlevel public
  92  * @privilege %http://tizen.org/privilege/shortcut
  93  * @remarks If a homescreen does not support this feature, you will get a proper error code.\n
  94  *          Application must check the return value of this function.\n
  95  *          Application must check the return status from the callback function.\n
  96  *          Application should set the callback function to get the result of this request.
  97  * @param[in] name The name of the created shortcut icon
  98  * @param[in] type The type of shortcuts
  99  * @param[in] uri The specific information for delivering to the viewer for creating a shortcut
 100  * @param[in] icon The absolute path of an icon file
 101  * @param[in] allow_duplicate @c 1 if it accepts the duplicated shortcut,
 102  *                            otherwise @c 0
 103  * @param[in] cb The address of the callback function that is called when the result comes back from the viewer
 104  * @param[in] data The callback data that is used in the callback function
 105  * @return @c 0 on success,
 106  *         otherwise a negative error value
 107  * @retval #SHORTCUT_ERROR_NONE Successful
 108  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 109  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 110  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter
 111  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory
 112  * @retval #SHORTCUT_ERROR_IO_ERROR I/O Error
 113  * @retval #SHORTCUT_ERROR_RESOURCE_BUSY Device or resource busy
 114  * @retval #SHORTCUT_ERROR_NO_SPACE There is no space to add a new shortcut
 115  * @retval #SHORTCUT_ERROR_EXIST Shortcut is already exist
 116  * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error
 117  * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem
 118  * @pre You have to prepare the callback function.
 119  * @post You have to check the return status from the callback function which is passed by the argument.
 120  * @see result_cb()
 121  * @par Example
 122  * @code
 123 #include <stdio.h>
 124 #include <shortcut_manager.h>
 125 static int _result_cb(int ret, int pid, void *data)
 126 {
 127         if (ret < 0)
 128                 dlog_print("Failed to add a shortcut: %s\n", perror(ret));
 129
 130         dlog_print("Processed by the %d\n", pid);
 131         return 0;
 132 }
 133
 134 static int app_create(void *data)
 135 {
 136         char* data_path = app_get_data_path();
 137         int path_len = strlen(data_path)+10;
 138         char * path = malloc(path_len);
 139         memset(path, 0, path_len);
 140         strncat(path, data_path, path_len);
 141         strncat(path, "Friend.jpg", path_len);
 142
 143         shortcut_add_to_home("With friends", LAUNCH_BY_URI, "gallery:0000-0000", path, 0, _result_cb, NULL);
 144         free(path);
 145
 146         return 0;
 147 }
 148  * @endcode
 149  */
 150 int shortcut_add_to_home(const char *name, shortcut_type type, const char *uri, const char *icon, int allow_duplicate, result_cb cb, void *data);
 151
 152
 153 /**
 154  * @brief Adds a widget to home, asynchronously.
 155  * @since_tizen 2.4
 156  * @privlevel public
 157  * @privilege %http://tizen.org/privilege/shortcut
 158  * @remarks If a homescreen does not support this feature, you will get a proper error code.\n
 159  *          Application must check the return value of this function.\n
 160  *          Application must check the return status from the callback function.\n
 161  *          Application should set the callback function to get the result of this request.
 162  * @param[in] name The name of the created widget which will be shown when the widget is not prepared
 163  * @param[in] size The size of widget
 164  * @param[in] widget_id Widget ID
 165  * @param[in] icon The absolute path of an icon file which will be shown when the widget is not prepared
 166  * @param[in] period The Update period in seconds
 167  * @param[in] allow_duplicate @c 1 if it accepts the duplicated widget,
 168  *                            otherwise @c 0
 169  * @param[in] cb The address of the callback function that is called when the result comes back from the viewer
 170  * @param[in] data The callback data that is used in the callback function
 171  * @return @c 0 on success,
 172  *         otherwise a negative error value
 173  * @retval #SHORTCUT_ERROR_NONE Successful
 174  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 175  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 176  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter
 177  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory
 178  * @retval #SHORTCUT_ERROR_IO_ERROR I/O Error
 179  * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error
 180  * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem
 181  * @pre You have to prepare the callback function.
 182  * @post You have to check the return status from the callback function which is passed by the argument.
 183  * @see result_cb()
 184  * @see shortcut_widget_size_e
 185  * @par Example
 186  * @code
 187 #include <stdio.h>
 188 #include <shortcut.h>
 189 #include <storage.h>
 190
 191 #define TIZEN_PATH_MAX 1024
 192 static int _result_cb(int ret, int pid, void *data)
 193 {
 194         if (ret < 0)
 195                 dlog_print("Failed to add a widget: %s\n", perror(ret));
 196
 197         dlog_print("Processed by the %d\n", pid);
 198
 199         return 0;
 200 }
 201
 202 static int app_create(void *data)
 203 {
 204         char *image_root = NULL;
 205         char image_path[TIZEN_PATH_MAX] = {0,};
 206
 207         storage_get_directory(STORAGE_TYPE_INTERNAL, STORAGE_DIRECTORY_IMAGES, &image_root);
 208         snprintf(image_path, TIZEN_PATH_MAX, "%s/alter_icon.png", image_root);
 209
 210         shortcut_add_to_home_widget("alter_name", WIDGET_SIZE_1x1, "org.tizen.testwidget",
 211                                         image_path, -1.0f, 0, _result_cb, NULL);
 212
 213         return 0;
 214 }
 215  * @endcode
 216  */
 217 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 cb, void *data);
 218
 219
 220 /**
 221  * @brief Removes a shortcut from home, asynchronously.
 222  * @details If the callback function registered for a widget, the shortcut deletion is possible.
 223  * @since_tizen 3.0
 224  * @privlevel public
 225  * @privilege %http://tizen.org/privilege/shortcut
 226  * @param[in] name The name of the created shortcut icon
 227  * @param[in] cb The address of the callback function that is called when the result comes back from the viewer
 228  * @param[in] user_data The callback data that is used in the callback function
 229  * @return 0 on success, otherwise a negative error value
 230  * @retval #SHORTCUT_ERROR_NONE Successful
 231  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 232  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 233  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter
 234  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory
 235  * @retval #SHORTCUT_ERROR_IO_ERROR I/O Error
 236  * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem
 237  * @pre You have to prepare the callback function.
 238  * @post You have to check the return status from the callback function which is passed by the argument.
 239  * @see result_cb()
 240  * @par Example
 241  * @code
 242 #include <shortcut_manager.h>
 243
 244 int _result_cb(int ret, void *data)
 245 {
 246         if (ret < 0)
 247                 dlog_print("Failed to remove a shortcut: %d\n", ret);
 248
 249         return 0;
 250 }
 251
 252 {
 253         int result;
 254
 255         result = shortcut_remove_from_home("shortcut_name", _result_cb, NULL);
 256         if (result != SHORTCUT_ERROR_NONE) {
 257                 dlog_print("Failed to remove a shortcut: %d\n", result);
 258                 return result;
 259         }
 260 }
 261
 262  * @endcode
 263  */
 264 int shortcut_remove_from_home(const char *name, result_cb cb, void *user_data);
 265
 266
 267 /**
 268  * @brief Called to receive the result of shortcut_get_list().
 269  * @since_tizen 2.4
 270  * @param[in] package_name The name of package
 271  * @param[in] icon The absolute path of an icon file for this shortcut
 272  * @param[in] name The name of the created shortcut icon
 273  * @param[in] extra_key The user data. A property of shortcut element in manifest file
 274  * @param[in] extra_data The user data. A property of shortcut element in manifest file
 275  * @param[in] user_data The callback user data
 276  * @return SHORTCUT_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop
 277  * @see shortcut_get_list()
 278  */
 279 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);
 280
 281
 282 /**
 283  * @brief Gets the preset list of shortcut template from the installed package, synchronously.
 284  * @since_tizen 2.4
 285  * @privlevel public
 286  * @privilege %http://tizen.org/privilege/shortcut
 287  * @remarks If a homescreen does not support this feature, you will get a proper error code.\n
 288  *          Application must check the return value of this function.\n
 289  *          Application must check the return status from the callback function.\n
 290  *          Application should set the callback function to get the result of this request.
 291  * @param[in] package_name The package name
 292  * @param[in] list_cb The callback function to get the shortcut item information
 293  * @param[in] data The callback data that is used in the callback function
 294  * @return @c N Number of items (call count of the callback function),
 295  *         otherwise a negative error value
 296  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 297  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 298  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter
 299  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory
 300  * @retval #SHORTCUT_ERROR_IO_ERROR I/O Error
 301  * @retval #SHORTCUT_ERROR_FAULT Unrecoverable error
 302  * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem
 303  * @pre You have to prepare the callback function.
 304  * @post You have to check the return status from the callback function which is passed by the argument.
 305  *
 306  */
 307 int shortcut_get_list(const char *package_name, shortcut_list_cb list_cb, void *data);
 308
 309
 310 /**
 311  * @brief Called to the add_to_home request.
 312  * @details The homescreen should define a callback as this type and implement the service code
 313  *          for adding a new application shortcut.
 314  * @since_tizen 2.4
 315  * @param[in] package_name The name of package
 316  * @param[in] name The name of the created shortcut icon
 317  * @param[in] type One of the three defined types
 318  * @param[in] content_info The specific information for creating a new shortcut
 319  * @param[in] icon The absolute path of an icon file for this shortcut
 320  * @param[in] pid The process ID of who request add_to_home
 321  * @param[in] period The Update period in seconds
 322  * @param[in] allow_duplicate @c 1 if the shortcut can be duplicated,
 323  *                            otherwise a shortcut should exist only once
 324  * @param[in] user_data The callback data
 325  * @return The result of handling a shortcut creation request\n
 326  *         This returns @c 0 if the add_to_home request is handled successfully,
 327  *         otherwise it returns a proper errno
 328  * @see shortcut_set_request_cb()
 329  */
 330 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 *user_data);
 331
 332
 333 /**
 334  * @brief Called to the shortcut_remove_from_home() request.
 335  * @since_tizen 3.0
 336  * @param[in] package_name The name of package
 337  * @param[in] name The name of the created shortcut icon
 338  * @param[in] sender_pid The process ID of who request shortcut_remove_from_home()
 339  * @param[in] user_data  The user data passed from the callback register function
 340  * @return The result of handling a shortcut remove request\n
 341  *             This returns @c 0 if the remove_from_home request is handled successfully,
 342  *             otherwise it returns a proper errno.
 343  * @see shortcut_set_remove_cb()
 344  */
 345 typedef int (*shortcut_remove_cb)(const char *package_name, const char *name, int sender_pid, void *user_data);
 346
 347
 348 /**
 349  * @brief Sets a callback function to listen requests from applications.
 350  * @since_tizen 2.4
 351  * @privlevel public
 352  * @privilege %http://tizen.org/privilege/shortcut
 353  * @remarks Should be used in the homescreen.\n
 354  *          Should check the return value of this function.
 355  *          Prospective Clients: Homescreen.
 356  * @param[in] request_cb The callback function pointer that is invoked when add_to_home is requested
 357  * @param[in] data The callback data to deliver to the callback function
 358  * @return @c 0 on success, otherwise a negative error value
 359  * @retval #SHORTCUT_ERROR_NONE Successful
 360  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 361  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 362  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter
 363  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory
 364  * @retval #SHORTCUT_ERROR_IO_ERROR I/O Error
 365  * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem
 366  * @pre You have to prepare a callback function.
 367  * @post If a request is sent from the application, the registered callback will be invoked.
 368  * @see request_cb_t
 369  * @see shortcut_error_e
 370  */
 371 int shortcut_set_request_cb(shortcut_request_cb request_cb, void *data);
 372
 373
 374 /**
 375  * @brief Unsets a callback for the shortcut request.
 376  * @since_tizen 3.0
 377  * @privlevel public
 378  * @privilege %http://tizen.org/privilege/shortcut
 379  * @remarks The specific error code can be obtained using the gat_last_result() method. Error codes are described in Exception section.
 380  * @return None
 381  * @exception #SHORTCUT_ERROR_NONE Successful
 382  * @exception #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 383  * @exception #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 384  * @see shortcut_set_request_cb()
 385  * @see get_last_result()
 386  */
 387 void shortcut_unset_request_cb(void);
 388
 389
 390 /**
 391  * @brief Sets the callback function to listen the remove requests from applications.
 392  * @since_tizen 3.0
 393  * @privlevel public
 394  * @privilege %http://tizen.org/privilege/shortcut
 395  * @remarks Should be used in the homescreen.\n
 396  *          Should check the return value of this function.
 397  *          Prospective Clients: Homescreen.
 398  * @param[in] remove_cb The callback function pointer that is invoked when remove_from_home is requested
 399  * @param[in] data The callback data to deliver to the callback function
 400  * @return 0 on success, otherwise a negative error value
 401  * @retval #SHORTCUT_ERROR_NONE Successful
 402  * @retval #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 403  * @retval #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 404  * @retval #SHORTCUT_ERROR_INVALID_PARAMETER Invalid function parameter
 405  * @retval #SHORTCUT_ERROR_OUT_OF_MEMORY Out of memory
 406  * @retval #SHORTCUT_ERROR_IO_ERROR I/O Error
 407  * @retval #SHORTCUT_ERROR_COMM Connection not established or communication problem
 408  * @pre You have to prepare a callback function.
 409  * @post If a request is sent from the application, the registered callback will be invoked.
 410  * @see shortcut_remove_cb()
 411  * @see shortcut_error_e
 412  */
 413 int shortcut_set_remove_cb(shortcut_remove_cb remove_cb, void *data);
 414
 415
 416 /**
 417  * @brief Unsets a callback for the shortcut remove.
 418  * @since_tizen 3.0
 419  * @privlevel public
 420  * @privilege %http://tizen.org/privilege/shortcut
 421  * @remarks The specific error code can be obtained using the gat_last_result() method. Error codes are described in Exception section.
 422  * @return None
 423  * @exception #SHORTCUT_ERROR_NONE Successful
 424  * @exception #SHORTCUT_ERROR_NOT_SUPPORTED Not supported
 425  * @exception #SHORTCUT_ERROR_PERMISSION_DENIED Permission denied
 426  * @see shortcut_set_remove_cb()
 427  * @see get_last_result()
 428  */
 429 void shortcut_unset_remove_cb(void);
 430
 431
 432 /**
 433  * @}
 434  */
 435
 436 #ifdef __cplusplus
 437 }
 438 #endif
 439
 440 #endif