lib/include/shortcut.h

   1 /*
   2  * Copyright (c) 2000 - 2013 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_H__
  19 #define __SHORTCUT_H__
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * @addtogroup APPLICATION_FRAMEWORK
  27  * @{
  28  */
  29
  30 /**
  31  * @defgroup SHORTCUT Add to home (shortcut)
  32  * @author Sung-jae Park <nicesj.park@samsung.com>
  33  * @version 0.1
  34  * @brief To enhance the Add to home feature. Two types of API set are supported.
  35  *        One for the homescreen developers.
  36  *        The others for the application developers who should implement the Add to home feature.
  37  */
  38
  39 /**
  40  * @brief This function prototype is used to define a callback function for the add_to_home reqeust.
  41  *        The homescreen should define a callback as this type and implementing the service code
  42  *        for adding a new application shortcut.
  43  * @param[in] appid Shortcut is added for this package.
  44  * @param[in] name Name for created shortcut icon.
  45  * @param[in] type 3 kinds of types are defined.
  46  * @param[in] content_info Specific information for creating a new shortcut.
  47  * @param[in] icon Absolute path of an icon file for this shortcut.
  48  * @param[in] pid Process ID of who request add_to_home.
  49  * @param[in] allow_duplicate 1 if shortcut can be duplicated or a shourtcut should be exists only one.
  50  * @param[in] data Callback data.
  51  * @return int Developer should returns the result of handling shortcut creation request.
  52  *             Returns 0, if succeed to handles the add_to_home request, or returns proper errno.
  53  * @see shortcut_set_request_cb
  54  * @pre None
  55  * @post None
  56  * @remarks None
  57  */
  58 typedef int (*request_cb_t)(const char *appid, const char *name, int type, const char *content_info, const char *icon, int pid, double period, int allow_duplicate, void *data);
  59
  60 /**
  61  * @brief This function prototype is used to define for receiving the result of add_to_home.
  62  * @param[in] ret Result value, it could be 0 if succeed to add a shortcut, or errno.
  63  * @param[in] pid Process ID of who handles this add_to_home request.
  64  * @param[in] data Callback data.
  65  * @return int Returns 0, if there is no error or returns errno.
  66  * @see add_to_home_shortcut()
  67  * @pre None
  68  * @post None
  69  * @remarks None
  70  */
  71 typedef int (*result_cb_t)(int ret, int pid, void *data);
  72
  73 /**
  74  * @brief Basically, three types of shortcut is defined.
  75  *        Every homescreen developer should support these types of shortcut.
  76  *        Or returns proper errno to figure out why the application failed to add a shortcut.
  77  *        LAUNCH_BY_PACKAGE is used for adding a package itself as a shortcut
  78  *        LAUNCH_BY_URI is used for adding a shortcut for "uri" data.
  79  */
  80 enum shortcut_type {
  81         /*!< Deprecated type */
  82         SHORTCUT_PACKAGE        = 0x00000000, /**< Launch the package using given pakcage name. */
  83         SHORTCUT_DATA           = 0x00000001, /**< Launch the related package with given data(content_info). */
  84         SHORTCUT_FILE           = 0x00000002, /**< Launch the related package with given filename(content_info). */
  85
  86         /*!< Use these */
  87         LAUNCH_BY_PACKAGE       = 0x00000000, /*!< Launch the package using given pakcage name. */
  88         LAUNCH_BY_URI           = 0x00000001, /*!< Launch the related package with given data(URI). */
  89
  90         SHORTCUT_REMOVE         = 0x40000000, /*!< Remove a shortcut */
  91         LIVEBOX_REMOVE          = 0x80000000, /*!< Remove a livebox */
  92
  93         LIVEBOX_TYPE_DEFAULT      = 0x10000000,
  94         LIVEBOX_TYPE_EASY_DEFAULT = 0x30000000,
  95         LIVEBOX_TYPE_1x1          = 0x10010000,
  96         LIVEBOX_TYPE_2x1          = 0x10020000,
  97         LIVEBOX_TYPE_2x2          = 0x10040000,
  98         LIVEBOX_TYPE_4x1          = 0x10080000,
  99         LIVEBOX_TYPE_4x2          = 0x10100000,
 100         LIVEBOX_TYPE_4x3          = 0x10200000,
 101         LIVEBOX_TYPE_4x4          = 0x10400000,
 102         LIVEBOX_TYPE_4x5          = 0x11000000,
 103         LIVEBOX_TYPE_4x6          = 0x12000000,
 104         LIVEBOX_TYPE_EASY_1x1     = 0x30010000,
 105         LIVEBOX_TYPE_EASY_3x1     = 0x30020000,
 106         LIVEBOX_TYPE_EASY_3x3     = 0x30040000,
 107         LIVEBOX_TYPE_UNKNOWN      = 0x1FFF0000,
 108 };
 109
 110 enum shortcut_response {
 111         SHORTCUT_SUCCESS = 0x00000000, /*!< Successfully handled */
 112         SHORTCUT_ERROR = 0x80000000,    /*!< MSB(1). Check this using SHORTCUT_STATUS_IS_ERROR macro  */
 113         SHORTCUT_ERROR_NO_SPACE = SHORTCUT_ERROR | 0x0001, /*!< There is no space to add new shortcut */
 114         SHORTCUT_ERROR_EXIST = SHORTCUT_ERROR | 0x0002, /*!< Shortcut is already added */
 115         SHORTCUT_ERROR_FAULT = SHORTCUT_ERROR | 0x0004, /*!< Failed to add a shortcut. Unrecoverable error */
 116         SHORTCUT_ERROR_UNSUPPORTED = SHORTCUT_ERROR | 0x0008, /*!< Unsupported shortcut */
 117         SHORTCUT_ERROR_BUSY = SHORTCUT_ERROR | 0x0010, /*!< Receiver is busy, try again later */
 118         SHORTCUT_ERROR_INVALID = SHORTCUT_ERROR | 0x0020, /*!< Shortcut request is not valid, invalid parameter or invalid argument value */
 119         SHORTCUT_ERROR_COMM = SHORTCUT_ERROR | 0x0040, /*!< Connection is not estabilished. or there is a problem of communication */
 120         SHORTCUT_ERROR_MEMORY = SHORTCUT_ERROR | 0x0080, /*!< Memory is not enough to handle new request */
 121         SHORTCUT_ERROR_IO = SHORTCUT_ERROR | 0x0100, /*!< Unable to access file or DB. Check your resource files */
 122
 123         SHORTCUT_STATUS_CARED = 0x08000000, /*!< Shortcut status is already cared. check this using SHORTCUT_STATUS_IS_CARED macro */
 124 };
 125
 126 #define ADD_TO_HOME_IS_LIVEBOX(type)    (!!((type) & 0x10000000))
 127 #define ADD_TO_HOME_IS_REMOVE_REQUEST(type)     (!!((type) & SHORTCUT_REMOVE))
 128
 129 #define SHORTCUT_STATUS_IS_ERROR(type)  (!!((type) & SHORTCUT_ERROR))
 130 #define SHORTCUT_STATUS_IS_CARED(type)  (!!((type) & SHORTCUT_STATUS_CARED))
 131 #define SHORTCUT_ERROR_CODE(type)       (type & ~SHORTCUT_STATUS_CARED)
 132
 133 /**
 134  * @fn int shortcut_set_request_cb(request_cb_t request_cb, void *data)
 135  *
 136  * @brief Homescreen should use this function to service the shortcut creating request.
 137  *
 138  * @par Sync (or) Async:
 139  * This is an asynchronous API.
 140  *
 141  * @par Important Notes:
 142  * - Should be used from the homescreen.
 143  * - Should check the return value of this function
 144  *
 145  * @param[in] request_cb Callback function pointer which will be invoked when add_to_home is requested.
 146  * @param[in] data Callback data to deliver to the callback function.
 147  *
 148  * @return Return Type (int)
 149  * - 0 - callback function is successfully registered
 150  * - < 0 - Failed to register the callback function for request.
 151  *
 152  * @see request_cb_t
 153  *
 154  * @pre - You have to prepare a callback function
 155  *
 156  * @post - If a request is sent from the application, the registered callback will be invoked.
 157  *
 158  * @remarks - None
 159  *
 160  * @par Prospective Clients:
 161  * Homescreen
 162  *
 163  * @par Example
 164  * @code
 165  * #include <shortcut.h>
 166  *
 167  * static int request_cb(const char *appid, const char *name, int type, const char *content_info, const char *icon, int pid, void *data)
 168  * {
 169  *      printf("Package name: %s\n", appid);
 170  *      printf("Name: %s\n", name);
 171  *      printf("Type: %d\n", type);
 172  *      printf("Content: %s\n", content_info);
 173  *      printf("Icon: %s\n", icon);
 174  *      printf("Requested from: %d\n", pid);
 175  *      printf("CBDATA: %p\n", data);
 176  *      return 0; // returns success.
 177  * }
 178  *
 179  * static int app_create(void *data)
 180  * {
 181  *      shortcut_set_request_cb(request_cb, NULL);
 182  *      return 0;
 183  * }
 184  *
 185  * int main(int argc, char *argv[])
 186  * {
 187  *      appcore....
 188  * }
 189  *
 190  * @endcode
 191  */
 192 extern int shortcut_set_request_cb(request_cb_t request_cb, void *data);
 193
 194 /**
 195  * @fn int add_to_home_shortcut(const char *appid, const char *name, int type, const char *content_info, const char *icon, result_cb_t result_cb, void *data)
 196  *
 197  * @brief The application, which supporting the add_to_home feature, should invoke this.
 198  *
 199  * @par Sync (or) Async:
 200  * This is an asynchronous API.
 201  *
 202  * @par Important Notes:
 203  * - Application should check the return value of this function.
 204  * - Application should check the return status from the callback function
 205  * - Application should set the callback function to get the result of this request.
 206  *
 207  * @param[in] appid Package name of owner of this shortcut.
 208  * @param[in] name Name for created shortcut icon.
 209  * @param[in] type 3 kinds of types are defined.
 210  * @param[in] content_info Specific information for delivering to the creating shortcut.
 211  * @param[in] icon Absolute path of an icon file
 212  * @param[in] allow_duplicate set 1 If accept the duplicated shortcut or 0
 213  * @param[in] result_cb Callback function pointer which will be invoked after add_to_home request.
 214  * @param[in] data Callback data to deliver to the callback function.
 215  *
 216  * @return Return Type (int)
 217  * - 0 - Succeed to send the request
 218  * - <0 - Failed to send the request
 219  *
 220  * @see result_cb_t
 221  *
 222  * @pre - You have to prepare the callback function
 223  *
 224  * @post - You have to check the return status from callback function which is passed by argument.
 225  *
 226  * @remarks - If a homescreen does not support this feature, you will get proper error code.
 227  *
 228  * @par Prospective Clients:
 229  * Inhouse Apps.
 230  *
 231  * @par Example
 232  * @code
 233  *
 234  * #include <stdio.h>
 235  * #include <shortcut.h>
 236  *
 237  * static int result_cb(int ret, int pid, void *data)
 238  * {
 239  *      if (ret < 0)
 240  *              printf("Failed to add a shortcut: %s\n", perror(ret));
 241  *
 242  *      printf("Processed by the %d\n", pid);
 243  *      return 0;
 244  * }
 245  *
 246  * static int app_create(void *data)
 247  * {
 248  *      add_to_home_shortcut("org.tizen.gallery", "With friends",
 249  *                                      SHORTCUT_DATA, "gallery:0000-0000",
 250  *                                      "/opt/media/Pictures/Friends.jpg", 0, result_cb, NULL);
 251  *      return 0;
 252  * }
 253  *
 254  * int main(int argc, char *argv[])
 255  * {
 256  *      appcore....
 257  * }
 258  *
 259  * @endcode
 260  */
 261 extern int shortcut_get_list(const char *appid, int (*cb)(const char *appid, const char *icon, const char *name, const char *extra_key, const char *extra_data, void *data), void *data);
 262
 263 extern int add_to_home_shortcut(const char *appid, const char *name, int type, const char *content_info, const char *icon, int allow_duplicate, result_cb_t result_cb, void *data);
 264
 265 extern int add_to_home_livebox(const char *appid, const char *name, int type, const char *content, const char *icon, double period, int allow_duplicate, result_cb_t result_cb, void *data);
 266
 267 extern int add_to_home_remove_shortcut(const char *appid, const char *name, const char *content_info, result_cb_t result_cb, void *data);
 268
 269 extern int add_to_home_remove_livebox(const char *appid, const char *name, result_cb_t result_cb, void *data);
 270
 271 #ifdef __cplusplus
 272 }
 273 #endif
 274
 275 #endif
 276 /* @}
 277  * End of a file
 278  */