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_EASY_DEFAULT = 0x30000000,
  91         LIVEBOX_TYPE_1x1          = 0x10010000,
  92         LIVEBOX_TYPE_2x1          = 0x10020000,
  93         LIVEBOX_TYPE_2x2          = 0x10040000,
  94         LIVEBOX_TYPE_4x1          = 0x10080000,
  95         LIVEBOX_TYPE_4x2          = 0x10100000,
  96         LIVEBOX_TYPE_4x3          = 0x10200000,
  97         LIVEBOX_TYPE_4x4          = 0x10400000,
  98         LIVEBOX_TYPE_EASY_1x1     = 0x30010000,
  99         LIVEBOX_TYPE_EASY_3x1     = 0x30020000,
 100         LIVEBOX_TYPE_EASY_3x3     = 0x30040000,
 101         LIVEBOX_TYPE_UNKNOWN      = 0x1FFF0000,
 102 };
 103
 104 #define ADD_TO_HOME_IS_LIVEBOX(type)    (!!((type) & 0x10000000))
 105
 106 /**
 107  * @fn int shortcut_set_request_cb(request_cb_t request_cb, void *data)
 108  *
 109  * @brief Homescreen should use this function to service the shortcut creating request.
 110  *
 111  * @par Sync (or) Async:
 112  * This is an asynchronous API.
 113  *
 114  * @par Important Notes:
 115  * - Should be used from the homescreen.
 116  * - Should check the return value of this function
 117  *
 118  * @param[in] request_cb Callback function pointer which will be invoked when add_to_home is requested.
 119  * @param[in] data Callback data to deliver to the callback function.
 120  *
 121  * @return Return Type (int)
 122  * - 0 - callback function is successfully registered
 123  * - < 0 - Failed to register the callback function for request.
 124  *
 125  * @see request_cb_t
 126  *
 127  * @pre - You have to prepare a callback function
 128  *
 129  * @post - If a request is sent from the application, the registered callback will be invoked.
 130  *
 131  * @remarks - None
 132  *
 133  * @par Prospective Clients:
 134  * Homescreen
 135  *
 136  * @par Example
 137  * @code
 138  * #include <shortcut.h>
 139  *
 140  * static int request_cb(const char *appid, const char *name, int type, const char *content_info, const char *icon, int pid, void *data)
 141  * {
 142  *      printf("Package name: %s\n", appid);
 143  *      printf("Name: %s\n", name);
 144  *      printf("Type: %d\n", type);
 145  *      printf("Content: %s\n", content_info);
 146  *      printf("Icon: %s\n", icon);
 147  *      printf("Requested from: %d\n", pid);
 148  *      printf("CBDATA: %p\n", data);
 149  *      return 0; // returns success.
 150  * }
 151  *
 152  * static int app_create(void *data)
 153  * {
 154  *      shortcut_set_request_cb(request_cb, NULL);
 155  *      return 0;
 156  * }
 157  *
 158  * int main(int argc, char *argv[])
 159  * {
 160  *      appcore....
 161  * }
 162  *
 163  * @endcode
 164  */
 165 extern int shortcut_set_request_cb(request_cb_t request_cb, void *data);
 166
 167 /**
 168  * @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)
 169  *
 170  * @brief The application, which supporting the add_to_home feature, should invoke this.
 171  *
 172  * @par Sync (or) Async:
 173  * This is an asynchronous API.
 174  *
 175  * @par Important Notes:
 176  * - Application should check the return value of this function.
 177  * - Application should check the return status from the callback function
 178  * - Application should set the callback function to get the result of this request.
 179  *
 180  * @param[in] appid Package name of owner of this shortcut.
 181  * @param[in] name Name for created shortcut icon.
 182  * @param[in] type 3 kinds of types are defined.
 183  * @param[in] content_info Specific information for delivering to the creating shortcut.
 184  * @param[in] icon Absolute path of an icon file
 185  * @param[in] result_cb Callback function pointer which will be invoked after add_to_home request.
 186  * @param[in] data Callback data to deliver to the callback function.
 187  *
 188  * @return Return Type (int)
 189  * - 0 - Succeed to send the request
 190  * - <0 - Failed to send the request
 191  *
 192  * @see result_cb_t
 193  *
 194  * @pre - You have to prepare the callback function
 195  *
 196  * @post - You have to check the return status from callback function which is passed by argument.
 197  *
 198  * @remarks - If a homescreen does not support this feature, you will get proper error code.
 199  *
 200  * @par Prospective Clients:
 201  * Inhouse Apps.
 202  *
 203  * @par Example
 204  * @code
 205  *
 206  * #include <stdio.h>
 207  * #include <shortcut.h>
 208  *
 209  * static int result_cb(int ret, int pid, void *data)
 210  * {
 211  *      if (ret < 0)
 212  *              printf("Failed to add a shortcut: %s\n", perror(ret));
 213  *
 214  *      printf("Processed by the %d\n", pid);
 215  *      return 0;
 216  * }
 217  *
 218  * static int app_create(void *data)
 219  * {
 220  *      add_to_home_shortcut("org.tizen.gallery", "With friends",
 221  *                                      SHORTCUT_DATA, "gallery:0000-0000",
 222  *                                      "/opt/media/Pictures/Friends.jpg", result_cb, NULL);
 223  *      return 0;
 224  * }
 225  *
 226  * int main(int argc, char *argv[])
 227  * {
 228  *      appcore....
 229  * }
 230  *
 231  * @endcode
 232  */
 233 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);
 234
 235 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);
 236
 237 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);
 238
 239
 240 /*!
 241  * \brief Number of preview images for homescreen
 242  */
 243 extern int homescreen_get_image_count(const char *appid);
 244 /*!
 245  * \return string allocated in the heap - Path of image
 246  */
 247 extern char *homescreen_get_image(const char *appid, int idx);
 248
 249 /*!
 250  * \brief Description of the homescreen (based on i18n)
 251  */
 252 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);
 253
 254 /*!
 255  * \note
 256  * These two functions are deprecated now.
 257  *
 258  * Please replace the "shortcut_add_to_home" with "add_to_home_shortcut"
 259  * Please replace the "shortcut_add_to_home_with_period" with "add_to_home_livebox"
 260  */
 261 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));
 262
 263 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));
 264
 265 #ifdef __cplusplus
 266 }
 267 #endif
 268
 269 #endif
 270 /* @}
 271  * End of a file
 272  */