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