lib/include/shortcut.h

   1 /*
   2  * Copyright 2012  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.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.tizenopensource.org/license
   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 #ifndef __SHORTCUT_H__
  18 #define __SHORTCUT_H__
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /**
  25  * @addtogroup APPLICATION_FRAMEWORK
  26  * @{
  27  */
  28
  29 /**
  30  * @defgroup SHORTCUT Add to home (shortcut)
  31  * @author Sung-jae Park <nicesj.park@samsung.com>
  32  * @version 0.1
  33  * @brief To enhance the Add to home feature. Two types of API set are supported.
  34  *        One for the homescreen developers.
  35  *        The others for the application developers who should implement the Add to home feature.
  36  */
  37
  38 /**
  39  * @brief This function prototype is used to define a callback function for the add_to_home reqeust.
  40  *        The homescreen should define a callback as this type and implementing the service code
  41  *        for adding a new application shortcut.
  42  * @param[in] appid Shortcut is added for this package.
  43  * @param[in] name Name for created shortcut icon.
  44  * @param[in] type 3 kinds of types are defined.
  45  * @param[in] content_info Specific information for creating a new shortcut.
  46  * @param[in] icon Absolute path of an icon file for this shortcut.
  47  * @param[in] pid Process ID of who request add_to_home.
  48  * @param[in] data Callback data.
  49  * @return int Developer should returns the result of handling shortcut creation request.
  50  *             Returns 0, if succeed to handles the add_to_home request, or returns proper errno.
  51  * @see shortcut_set_request_cb
  52  * @pre None
  53  * @post None
  54  * @remarks None
  55  */
  56 typedef int (*request_cb_t)(const char *appid, const char *name, int type, const char *content_info, const char *icon, int pid, double period, void *data);
  57
  58 /**
  59  * @brief This function prototype is used to define for receiving the result of add_to_home.
  60  * @param[in] ret Result value, it could be 0 if succeed to add a shortcut, or errno.
  61  * @param[in] pid Process ID of who handles this add_to_home request.
  62  * @param[in] data Callback data.
  63  * @return int Returns 0, if there is no error or returns errno.
  64  * @see add_to_home_shortcut()
  65  * @pre None
  66  * @post None
  67  * @remarks None
  68  */
  69 typedef int (*result_cb_t)(int ret, int pid, void *data);
  70
  71 /**
  72  * @brief Basically, three types of shortcut is defined.
  73  *        Every homescreen developer should support these types of shortcut.
  74  *        Or returns proper errno to figure out why the application failed to add a shortcut.
  75  *        LAUNCH_BY_PACKAGE is used for adding a package itself as a shortcut
  76  *        LAUNCH_BY_URI is used for adding a shortcut for "uri" data.
  77  */
  78 enum shortcut_type {
  79         /*!< Deprecated type */
  80         SHORTCUT_PACKAGE        = 0x00000000, /**< Launch the package using given pakcage name. */
  81         SHORTCUT_DATA           = 0x00000001, /**< Launch the related package with given data(content_info). */
  82         SHORTCUT_FILE           = 0x00000002, /**< Launch the related package with given filename(content_info). */
  83
  84         /*!< Use these */
  85         LAUNCH_BY_PACKAGE       = 0x00000000, /*!< Launch the package using given pakcage name. */
  86         LAUNCH_BY_URI           = 0x00000001, /*!< Launch the related package with given data(URI). */
  87
  88         LIVEBOX_TYPE_DEFAULT    = 0x10000000,
  89         LIVEBOX_TYPE_1x1        = 0x10010000,
  90         LIVEBOX_TYPE_2x1        = 0x10020000,
  91         LIVEBOX_TYPE_2x2        = 0x10040000,
  92         LIVEBOX_TYPE_4x1        = 0x10080000,
  93         LIVEBOX_TYPE_4x2        = 0x10100000,
  94         LIVEBOX_TYPE_4x3        = 0x10200000,
  95         LIVEBOX_TYPE_4x4        = 0x10400000,
  96         LIVEBOX_TYPE_UNKNOWN    = 0x1FFF0000,
  97 };
  98
  99 #define ADD_TO_HOME_IS_LIVEBOX(type)    (!!((type) & 0x10000000))
 100
 101 /**
 102  * @fn int shortcut_set_request_cb(request_cb_t request_cb, void *data)
 103  *
 104  * @brief Homescreen should use this function to service the shortcut creating request.
 105  *
 106  * @par Sync (or) Async:
 107  * This is an asynchronous API.
 108  *
 109  * @par Important Notes:
 110  * - Should be used from the homescreen.
 111  * - Should check the return value of this function
 112  *
 113  * @param[in] request_cb Callback function pointer which will be invoked when add_to_home is requested.
 114  * @param[in] data Callback data to deliver to the callback function.
 115  *
 116  * @return Return Type (int)
 117  * - 0 - callback function is successfully registered
 118  * - < 0 - Failed to register the callback function for request.
 119  *
 120  * @see request_cb_t
 121  *
 122  * @pre - You have to prepare a callback function
 123  *
 124  * @post - If a request is sent from the application, the registered callback will be invoked.
 125  *
 126  * @remarks - None
 127  *
 128  * @par Prospective Clients:
 129  * Homescreen
 130  *
 131  * @par Example
 132  * @code
 133  * #include <shortcut.h>
 134  *
 135  * static int request_cb(const char *appid, const char *name, int type, const char *content_info, const char *icon, int pid, void *data)
 136  * {
 137  *      printf("Package name: %s\n", appid);
 138  *      printf("Name: %s\n", name);
 139  *      printf("Type: %d\n", type);
 140  *      printf("Content: %s\n", content_info);
 141  *      printf("Icon: %s\n", icon);
 142  *      printf("Requested from: %d\n", pid);
 143  *      printf("CBDATA: %p\n", data);
 144  *      return 0; // returns success.
 145  * }
 146  *
 147  * static int app_create(void *data)
 148  * {
 149  *      shortcut_set_request_cb(request_cb, NULL);
 150  *      return 0;
 151  * }
 152  *
 153  * int main(int argc, char *argv[])
 154  * {
 155  *      appcore....
 156  * }
 157  *
 158  * @endcode
 159  */
 160 extern int shortcut_set_request_cb(request_cb_t request_cb, void *data);
 161
 162 /**
 163  * @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)
 164  *
 165  * @brief The application, which supporting the add_to_home feature, should invoke this.
 166  *
 167  * @par Sync (or) Async:
 168  * This is an asynchronous API.
 169  *
 170  * @par Important Notes:
 171  * - Application should check the return value of this function.
 172  * - Application should check the return status from the callback function
 173  * - Application should set the callback function to get the result of this request.
 174  *
 175  * @param[in] appid Package name of owner of this shortcut.
 176  * @param[in] name Name for created shortcut icon.
 177  * @param[in] type 3 kinds of types are defined.
 178  * @param[in] content_info Specific information for delivering to the creating shortcut.
 179  * @param[in] icon Absolute path of an icon file
 180  * @param[in] result_cb Callback function pointer which will be invoked after add_to_home request.
 181  * @param[in] data Callback data to deliver to the callback function.
 182  *
 183  * @return Return Type (int)
 184  * - 0 - Succeed to send the request
 185  * - <0 - Failed to send the request
 186  *
 187  * @see result_cb_t
 188  *
 189  * @pre - You have to prepare the callback function
 190  *
 191  * @post - You have to check the return status from callback function which is passed by argument.
 192  *
 193  * @remarks - If a homescreen does not support this feature, you will get proper error code.
 194  *
 195  * @par Prospective Clients:
 196  * Inhouse Apps.
 197  *
 198  * @par Example
 199  * @code
 200  *
 201  * #include <stdio.h>
 202  * #include <shortcut.h>
 203  *
 204  * static int result_cb(int ret, int pid, void *data)
 205  * {
 206  *      if (ret < 0)
 207  *              printf("Failed to add a shortcut: %s\n", perror(ret));
 208  *
 209  *      printf("Processed by the %d\n", pid);
 210  *      return 0;
 211  * }
 212  *
 213  * static int app_create(void *data)
 214  * {
 215  *      add_to_home_shortcut("org.tizen.gallery", "With friends",
 216  *                                      SHORTCUT_DATA, "gallery:0000-0000",
 217  *                                      "/opt/media/Pictures/Friends.jpg", result_cb, NULL);
 218  *      return 0;
 219  * }
 220  *
 221  * int main(int argc, char *argv[])
 222  * {
 223  *      appcore....
 224  * }
 225  *
 226  * @endcode
 227  */
 228 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);
 229
 230 extern 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);
 231
 232 extern int add_to_home_livebox(const char *appid, const char *name, int type, const char *content, const char *icon, double period, result_cb_t result_cb, void *data);
 233
 234
 235 /*!
 236  * \brief Number of preview images for homescreen
 237  */
 238 extern int homescreen_get_image_count(const char *appid);
 239 /*!
 240  * \return string allocated in the heap - Path of image
 241  */
 242 extern char *homescreen_get_image(const char *appid, int idx);
 243
 244 /*!
 245  * \brief Description of the homescreen (based on i18n)
 246  */
 247 extern int homescreen_get_description(const char *appid, void (*cb)(const char *appid, const char *icon, const char *name, const char *desc, void *data), void *data);
 248
 249 /*!
 250  * \note
 251  * These two functions are deprecated now.
 252  *
 253  * Please replace the "shortcut_add_to_home" with "add_to_home_shortcut"
 254  * Please replace the "shortcut_add_to_home_with_period" with "add_to_home_livebox"
 255  */
 256 extern int shortcut_add_to_home(const char *appid, const char *name, int type, const char *content, const char *icon, result_cb_t result_cb, void *data) __attribute__ ((deprecated));
 257
 258 extern int shortcut_add_to_home_with_period(const char *appid, const char *name, int type, const char *content, const char *icon, double period, result_cb_t result_cb, void *data) __attribute__ ((deprecated));
 259
 260 #ifdef __cplusplus
 261 }
 262 #endif
 263
 264 #endif
 265 /* @}
 266  * End of a file
 267  */