src/wrt-installer/wrt_installer_api.h

   1 /*
   2  * Copyright (c) 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  * @file        wrt_installer_api.h
  18  * @author      Chung Jihoon (jihoon.chung@samsung.com)
  19  * @version     1.0
  20  * @brief       This file contains declarations of wrt_installer_api
  21  */
  22
  23 /*
  24  * @defgroup wrt_engine_group WebRunTime engine Library
  25  * @ingroup internet_FW
  26  * Functions to APIs to access wrt-engine
  27  */
  28
  29 #ifndef WRT_INSTALLER_API_H_
  30 #define WRT_INSTALLER_API_H_
  31
  32 #include <string>
  33 #include <stdbool.h>
  34 #include <stddef.h>
  35 #include <wrt_type.h>
  36 #include <pkgmgr_signal_interface.h>
  37 #include <memory>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44  * Callback function type invoked after async init function
  45  */
  46 typedef void (*WrtInstallerInitCallback)(WrtErrStatus status,
  47                                          void *data);
  48
  49 /**
  50  * Callback function type invoked after async functions
  51  */
  52 typedef void (*WrtPluginInstallerStatusCallback)(WrtErrStatus status,
  53                                                  void *data);
  54
  55 /**
  56  * Callback function type invoked after async functions
  57  */
  58 typedef void (*WrtInstallerStatusCallback)(std::string tizenId,
  59                                            WrtErrStatus status,
  60                                            void *data);
  61
  62 /**
  63  * Callback function type invoked after async functions
  64  */
  65 typedef void (*WrtProgressCallback)(float percent,
  66                                     const char *description,
  67                                     void *data);
  68
  69 /**
  70  * Callback function type invoked when all plugin installations are finished
  71  */
  72 typedef void (*WrtAllPluginInstalledCallback)(void *userdata);
  73
  74 typedef struct
  75 {
  76     WrtAllPluginInstalledCallback plugin_installed_cb;
  77     char *plugin_path;
  78     void *user_data;
  79 } wrt_plugin_data;
  80
  81 /**
  82  * @fn int wrt_installer_init(void *userdata, WrtInstallerInitCallback callback)
  83  * @brief Initializes WRT
  84  *
  85  * This method is used to initialize wrt-engine.
  86  * It connects to database, initializes webkit, widget and plugin logic.
  87  *
  88  * @param [in]  userdata - User parameters to be passed to the callback
  89  * @param [in]  callback - The callback function that is launched, after
  90  *                         wrt initialization.
  91  *                         The callback is called in the context of the
  92  *                         application's main loop.
  93  *
  94  * @return 0 on success, -1 on failure
  95  *
  96  * Sample code:
  97  * @code
  98  * int main (int argc, char *argv[])
  99  * {
 100  *     init_loop(argc, argv);
 101  *     printf("Initializing WRT");
 102  *     wrt_init(NULL, &init_cb);
 103  *
 104  *     wait_for_wrt_init();
 105  *     printf("Starting tests");
 106  *
 107  *     int status = DPL_TestRunnerSingleton_Instance().ExecTestRunner(argc,
 108  *                                                                    argv);
 109  *
 110  *     wrt_installer_shutdown();
 111  *     quit_loop();
 112  *     return status;
 113  * }
 114  * @endcode
 115  *
 116  * @see wrt_installer_shutdown
 117  */
 118 typedef enum wrt_widget_install_mode_e
 119 {
 120     /**
 121      * Raw install bit flags
 122      */
 123     WRT_WIM_NOT_INSTALLED = (1 << 0),
 124     WRT_WIM_INCOMING_VERSION_NOT_STD = (1 << 1),
 125     WRT_WIM_EXISTING_VERSION_NOT_STD = (1 << 2),
 126     WRT_WIM_BOTH_VERSIONS_NOT_STD = (1 << 3),
 127     WRT_WIM_EXISTING_VERSION_OLDER = (1 << 4),
 128     WRT_WIM_EXISTING_VERSION_EQUAL = (1 << 5),
 129     WRT_WIM_EXISTING_VERSION_NEWER = (1 << 6),
 130
 131     /**
 132      * Update default policies
 133      */
 134
 135     /* Never update policy
 136      */
 137     WRT_WIM_POLICY_NEVER_UPDATE = WRT_WIM_NOT_INSTALLED,
 138
 139     /* WAC update policy
 140      */
 141     WRT_WIM_POLICY_WAC = WRT_WIM_NOT_INSTALLED |
 142         WRT_WIM_EXISTING_VERSION_OLDER,
 143
 144     /* Always update policy
 145      */
 146     WRT_WIM_POLICY_ALWAYS_INSTALL = WRT_WIM_NOT_INSTALLED |
 147         WRT_WIM_INCOMING_VERSION_NOT_STD |
 148         WRT_WIM_EXISTING_VERSION_NOT_STD |
 149         WRT_WIM_BOTH_VERSIONS_NOT_STD |
 150         WRT_WIM_EXISTING_VERSION_OLDER |
 151         WRT_WIM_EXISTING_VERSION_EQUAL |
 152         WRT_WIM_EXISTING_VERSION_NEWER,
 153
 154     /* Force install policy
 155      */
 156     WRT_WIM_POLICY_FORCE_INSTALL = WRT_WIM_POLICY_ALWAYS_INSTALL,
 157     /* Installation from directory - forced update
 158      */
 159     WRT_WIM_POLICY_DIRECTORY_FORCE_INSTALL
 160 } wrt_widget_update_mode_t;
 161
 162 int wrt_installer_init(void *userdata,
 163                        WrtInstallerInitCallback callback);
 164
 165 /**
 166  * @fn void wrt_installer_shutdown(void)
 167  * @brief Deinitializes WRT
 168  *
 169  * This method is used to deinitialize wrt-engine.
 170  * It deinitializes widget logic, plugin logic, shuts down connection to
 171  * database, switchs back to single thread and does deinit checks.
 172  *
 173  * @return      nothing
 174  *
 175  * Sample code:
 176  * @code
 177  * int main (int argc, char *argv[])
 178  * {
 179  *     init_loop(argc, argv);
 180  *     printf("Initializing WRT");
 181  *     wrt_init(NULL, &init_cb);
 182  *
 183  *     wait_for_wrt_init();
 184  *     printf("Starting tests");
 185  *
 186  *     int status = DPL_TestRunnerSingleton_Instance().ExecTestRunner(argc,
 187  *                                                                    argv);
 188  *
 189  *     wrt_installer_shutdown();
 190  *     quit_loop();
 191  *     return status;
 192  * }
 193  * @endcode
 194  *
 195  * @see wrt_init
 196  */
 197 void wrt_installer_shutdown(void);
 198
 199 /**
 200  * @fn void wrt_install_widget(const char *widget_package_path,
 201  *                      void *user_parameter,
 202  *                      WrtInstallerStatusCallback status_callback,
 203  *                      WrtProgressCallback progress_callback,
 204  *                      wrt_widget_update_mode_t update_mode,
 205  *                      bool quiet,
 206  *                      bool preload);
 207  *
 208  * @brief Installs widget from given path
 209  *
 210  * This method is used to install widget from a given path.
 211  *
 212  * @param [in]  widget_package_path Path of the widget package.
 213  * @param [in]  user_parameter      User parameters to be passed to the callback
 214  * @param [in]  status_cb           Call to this one will be done at the end of
 215  *                                  operation
 216  *                                  The callback is called in the context of the
 217  *                                  application's
 218  * @param [in]  progress_cb         Callback function to get data of install
 219  *                                  progress
 220  *                                  If you don't want to get progress data, this
 221  *                                  should be NULL
 222  * @param [in]  install_mode        Installation mode
 223  * @param [in]  quiet               quiet mode
 224  * @param [in]  preload             preload widget install
 225  * @return                          Nothing (status returned in callback).
 226  *
 227  * Sample code:
 228  * @code
 229  *   wrt_install_widget(path.c_str(),
 230  *                      NULL,
 231  *                      install_cb,
 232  *                      progress_cb,
 233  *                      WRT_WIM_POLICY_WAC,
 234  *                      false,
 235  *                      false);
 236  * @endcode
 237  *
 238  * @see wrt_installer_uninstall_widget
 239  */
 240 void wrt_install_widget(
 241     const char *path,
 242     void *user_parameter,
 243     WrtInstallerStatusCallback status_callback,
 244     WrtProgressCallback progress_callback,
 245     wrt_widget_update_mode_t update_mode,
 246     bool quiet,
 247     bool preload,
 248     std::shared_ptr<PackageManager::IPkgmgrSignal>
 249     pkgmgrInterface
 250     );
 251
 252 /**
 253  * @fn void wrt_installer_uninstall_widget (const char * const tizenAppid,
 254  *                                void* userdata,
 255  *                                WrtInstallerStatusCallback cb)
 256  * @brief Uninstalls widget using its name
 257  *
 258  * This method is used to uninstall the widget specified by its appid.
 259  * The callback function is called when the uninstall operation is done.
 260  *
 261  * @param [in]  tzAppid     - tizen appid
 262  * @param [in]  userdata    - user parameters to be passed to the callback
 263  * @param [in]  status_cb   - Call to this one will be done at the end of
 264  *                            operation
 265  *                            The callback is called in the context of the
 266  *                            application's
 267  * @param [in]  progress_cb - Callback function to get data of install progress
 268  *                            If you don't want to get progress data, this
 269  *                            should be NULL
 270  *
 271  * @return      nothing (status returned in callback).
 272  *
 273  * Sample code:
 274  * @code //TODO SAMPLE
 275  *  wrt_installer_uninstall_widget( appId, NULL, uninstall_cb, progress_cb);
 276  * @endcode
 277  *
 278  * @see wrt_installer_install_widget
 279  */
 280 void wrt_uninstall_widget (
 281     const char * const tzAppid,
 282     void* userdata,
 283     WrtInstallerStatusCallback status_cb,
 284     WrtProgressCallback progress_cb,
 285     std::shared_ptr<PackageManager::IPkgmgrSignal>
 286     pkgmgrSignalInterface);
 287
 288 /**
 289  *  @fn void wrt_install_plugin(const char *pluginDirectory,
 290  *                              void *userData,
 291  *                              WrtInstallerStatusCallback statusCallback,
 292  *                              WrtProgressCallback progressCallback)
 293  *
 294  *  @brief Installs plugin from given path
 295  *
 296  *  This method installs new plugin from specified location and calls a callback
 297  *  function when the operation is done.
 298  *
 299  *  @param [in] pluginDirectory - plugin directory
 300  *  @param [in] userData    - user parameters to be passed to the callback
 301  *  @param [in] statusCallback   - user callback to call after installation
 302  *  @param [in] progressCallback - user callback to call when plugin
 303  *                                 installation progress has changed
 304  *
 305  *  @return nothing (status returned in callback).
 306  *
 307  * Sample code:
 308  * @code
 309  *  wrt_install_plugin("/usr/lib/wrt-plugins/",NULL,NULL,NULL);
 310  * @endcode
 311  *
 312  * @see wrt_install_plugin
 313  */
 314 void wrt_install_plugin(const char *pluginDirectory,
 315                         void *userData,
 316                         WrtPluginInstallerStatusCallback statusCallback,
 317                         WrtProgressCallback progressCallback);
 318
 319 /**
 320  * @brief To install plugins for first excution
 321  *
 322  * This method install plugins
 323  *
 324  * @return nothing
 325  */
 326 void wrt_install_all_plugins(WrtAllPluginInstalledCallback installed_cb,
 327                              void *user_param);
 328
 329 /**
 330  * @brief To initialize for tests
 331  *
 332  * This method is wrt init for tests
 333  *
 334  * @return int
 335  */
 336 int wrt_installer_init_for_tests(void *userdata,
 337                                  WrtInstallerInitCallback callback);
 338
 339 /**
 340  * @brief To shutdown for tests
 341  *
 342  * This method is wrt shutdown for tests
 343  *
 344  * @return int
 345  */
 346 void wrt_installer_shutdown_for_tests();
 347
 348 /**
 349  * @brief wrt_get_widget_by_guid Returns tizenAppid by pkg guid (widgetId)
 350  * @param tzAppid tizen appid argument ot be set
 351  * @param guid guid that we look for
 352  * @return error code
 353  */
 354 WrtErrStatus wrt_get_widget_by_guid(std::string &tzAppid,
 355                                     const std::string guid);
 356 #ifdef __cplusplus
 357 }
 358 #endif
 359
 360 #endif /* WRT_INSTALLER_API_H_ */