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] pkgname 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 *pkgname, const char *name, int type, const char *content_info, const char *icon, int pid, 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 shortcut_add_to_home()
  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  *        SHORTCUT_PACKAGE is used for adding a package itself as a shortcut
  76  *        SHORTCUT_DATA is used for adding a shortcut for "content" data.
  77  *        SHORTCUT_FILE is used for adding a shortcut for "file".
  78  */
  79 enum {
  80         SHORTCUT_PACKAGE = 0x0, /**< Launch the package using given pakcage name. */
  81         SHORTCUT_DATA = 0x01, /**< Launch the related package with given data(content_info). */
  82         SHORTCUT_FILE = 0x02, /** < Launch the related package with given filename(content_info). */
  83 };
  84
  85 /**
  86  * @fn int shortcut_set_request_cb(request_cb_t request_cb, void *data)
  87  *
  88  * @brief Homescreen should use this function to service the shortcut creating request.
  89  *
  90  * @par Sync (or) Async:
  91  * This is an asynchronous API.
  92  *
  93  * @par Important Notes:
  94  * - Should be used from the homescreen.
  95  * - Should check the return value of this function
  96  *
  97  * @param[in] request_cb Callback function pointer which will be invoked when add_to_home is requested.
  98  * @param[in] data Callback data to deliver to the callback function.
  99  *
 100  * @return Return Type (int)
 101  * - 0 - callback function is successfully registered
 102  * - < 0 - Failed to register the callback function for request.
 103  *
 104  * @see request_cb_t
 105  *
 106  * @pre - You have to prepare a callback function
 107  *
 108  * @post - If a request is sent from the application, the registered callback will be invoked.
 109  *
 110  * @remarks - None
 111  *
 112  * @par Prospective Clients:
 113  * Homescreen
 114  *
 115  * @par Example
 116  * @code
 117  * #include <shortcut.h>
 118  *
 119  * static int request_cb(const char *pkgname, const char *name, int type, const char *content_info, const char *icon, int pid, void *data)
 120  * {
 121  *      printf("Package name: %s\n", pkgname);
 122  *      printf("Name: %s\n", name);
 123  *      printf("Type: %d\n", type);
 124  *      printf("Content: %s\n", content_info);
 125  *      printf("Icon: %s\n", icon);
 126  *      printf("Requested from: %d\n", pid);
 127  *      printf("CBDATA: %p\n", data);
 128  *      return 0; // returns success.
 129  * }
 130  *
 131  * static int app_create(void *data)
 132  * {
 133  *      shortcut_set_request_cb(request_cb, NULL);
 134  *      return 0;
 135  * }
 136  *
 137  * int main(int argc, char *argv[])
 138  * {
 139  *      appcore....
 140  * }
 141  *
 142  * @endcode
 143  */
 144 extern int shortcut_set_request_cb(request_cb_t request_cb, void *data);
 145
 146 /**
 147  * @fn int shortcut_add_to_home(const char *pkgname, const char *name, int type, const char *content_info, const char *icon, result_cb_t result_cb, void *data)
 148  *
 149  * @brief The application, which supporting the add_to_home feature, should invoke this.
 150  *
 151  * @par Sync (or) Async:
 152  * This is an asynchronous API.
 153  *
 154  * @par Important Notes:
 155  * - Application should check the return value of this function.
 156  * - Application should check the return status from the callback function
 157  * - Application should set the callback function to get the result of this request.
 158  *
 159  * @param[in] pkgname Package name of owner of this shortcut.
 160  * @param[in] name Name for created shortcut icon.
 161  * @param[in] type 3 kinds of types are defined.
 162  * @param[in] content_info Specific information for delivering to the creating shortcut.
 163  * @param[in] icon Absolute path of an icon file
 164  * @param[in] result_cb Callback function pointer which will be invoked after add_to_home request.
 165  * @param[in] data Callback data to deliver to the callback function.
 166  *
 167  * @return Return Type (int)
 168  * - 0 - Succeed to send the request
 169  * - <0 - Failed to send the request
 170  *
 171  * @see result_cb_t
 172  *
 173  * @pre - You have to prepare the callback function
 174  *
 175  * @post - You have to check the return status from callback function which is passed by argument.
 176  *
 177  * @remarks - If a homescreen does not support this feature, you will get proper error code.
 178  *
 179  * @par Prospective Clients:
 180  * Inhouse Apps.
 181  *
 182  * @par Example
 183  * @code
 184  *
 185  * #include <stdio.h>
 186  * #include <shortcut.h>
 187  *
 188  * static int result_cb(int ret, int pid, void *data)
 189  * {
 190  *      if (ret < 0)
 191  *              printf("Failed to add a shortcut: %s\n", perror(ret));
 192  *
 193  *      printf("Processed by the %d\n", pid);
 194  *      return 0;
 195  * }
 196  *
 197  * static int app_create(void *data)
 198  * {
 199  *      shortcut_add_to_home("com.samsung.gallery", "With friends",
 200  *                                      SHORTCUT_DATA, "gallery:0000-0000",
 201  *                                      "/opt/media/Pictures/Friends.jpg", result_cb, NULL);
 202  *      return 0;
 203  * }
 204  *
 205  * int main(int argc, char *argv[])
 206  * {
 207  *      appcore....
 208  * }
 209  *
 210  * @endcode
 211  */
 212 extern int shortcut_add_to_home(const char *pkgname, const char *name, int type, const char *content_info, const char *icon, result_cb_t result_cb, void *data);
 213
 214 extern int add_to_home_shortcut(const char *pkgname, const char *name, int type, const char *content_info, const char *icon, result_cb_t result_cb, void *data);
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif
 221 /* @}
 222  * End of a file
 223  */