lib/include/shortcut.h

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