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)(std::string tizenId,
  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     /* Installation from directory - forced update
 156      */
 157     WRT_WIM_POLICY_DIRECTORY_FORCE_INSTALL
 158 } wrt_widget_update_mode_t;
 159
 160 int wrt_installer_init(void *userdata,
 161         WrtInstallerInitCallback callback);
 162
 163 /**
 164  * @fn void wrt_installer_shutdown(void)
 165  * @brief Deinitializes WRT
 166  *
 167  * This method is used to deinitialize wrt-engine.
 168  * It deinitializes widget logic, plugin logic, shuts down connection to
 169  * database, switchs back to single thread and does deinit checks.
 170  *
 171  * @return      nothing
 172  *
 173  * Sample code:
 174  * @code
 175  * int main (int argc, char *argv[])
 176  * {
 177  *     init_loop(argc, argv);
 178  *     printf("Initializing WRT");
 179  *     wrt_init(NULL, &init_cb);
 180  *
 181  *     wait_for_wrt_init();
 182  *     printf("Starting tests");
 183  *
 184  *     int status = DPL_TestRunnerSingleton_Instance().ExecTestRunner(argc,
 185  *                                                                    argv);
 186  *
 187  *     wrt_installer_shutdown();
 188  *     quit_loop();
 189  *     return status;
 190  * }
 191  * @endcode
 192  *
 193  * @see wrt_init
 194  */
 195 void wrt_installer_shutdown(void);
 196
 197 /**
 198  * @fn void wrt_install_widget(const char *widget_package_path,
 199  *                      void *user_parameter,
 200  *                      WrtInstallerStatusCallback status_callback,
 201  *                      WrtProgressCallback progress_callback,
 202  *                      wrt_widget_update_mode_t update_mode);
 203  *
 204  * @brief Installs widget from given path
 205  *
 206  * This method is used to install widget from a given path.
 207  *
 208  * @param [in]  widget_package_path Path of the widget package.
 209  * @param [in]  user_parameter      User parameters to be passed to the callback
 210  * @param [in]  status_cb           Call to this one will be done at the end of
 211  *                                  operation
 212  *                                  The callback is called in the context of the
 213  *                                  application's
 214  * @param [in]  progress_cb         Callback function to get data of install
 215  *                                  progress
 216  *                                  If you don't want to get progress data, this
 217  *                                  should be NULL
 218  * @param [in]  install_mode        Installation mode
 219  * @return                          Nothing (status returned in callback).
 220  *
 221  * Sample code:
 222  * @code
 223  *   wrt_install_widget(path.c_str(),
 224  *                      NULL,
 225  *                      install_cb,
 226  *                      progress_cb,
 227  *                      WRT_WIM_POLICY_WAC);
 228  * @endcode
 229  *
 230  * @see wrt_installer_uninstall_widget
 231  */
 232 void wrt_install_widget(const char *path,
 233         void *user_parameter,
 234         WrtInstallerStatusCallback status_callback,
 235         WrtProgressCallback progress_callback,
 236         wrt_widget_update_mode_t update_mode,
 237         bool quiet);
 238
 239 /**
 240  * @fn void wrt_installer_uninstall_widget (const char * const pkg_name,
 241  *                                void* userdata,
 242  *                                WrtInstallerStatusCallback cb)
 243  * @brief Uninstalls widget using its name
 244  *
 245  * This method is used to uninstall the widget specified by its pkgname.
 246  * The callback function is called when the uninstall operation is done.
 247  *
 248  * @param [in]  pkg_name    - package name
 249  * @param [in]  userdata    - user parameters to be passed to the callback
 250  * @param [in]  status_cb   - Call to this one will be done at the end of
 251  *                            operation
 252  *                            The callback is called in the context of the
 253                               application's
 254  * @param [in]  progress_cb - Callback function to get data of install progress
 255  *                            If you don't want to get progress data, this
 256  *                            should be NULL
 257  *
 258  * @return      nothing (status returned in callback).
 259  *
 260  * Sample code:
 261  * @code //TODO SAMPLE
 262  *  wrt_installer_uninstall_widget( appId, NULL, uninstall_cb, progress_cb);
 263  * @endcode
 264  *
 265  * @see wrt_installer_install_widget
 266  */
 267 void wrt_uninstall_widget (const char * const pkg_name,
 268         void* userdata,
 269         WrtInstallerStatusCallback status_cb,
 270         WrtProgressCallback progress_cb);
 271
 272 /**
 273  *  @fn void wrt_install_plugin(const char *pluginDirectory,
 274  *                              void *userData,
 275  *                              WrtInstallerStatusCallback statusCallback,
 276  *                              WrtProgressCallback progressCallback)
 277  *
 278  *  @brief Installs plugin from given path
 279  *
 280  *  This method installs new plugin from specified location and calls a callback
 281  *  function when the operation is done.
 282  *
 283  *  @param [in] pluginDirectory - plugin directory
 284  *  @param [in] userData    - user parameters to be passed to the callback
 285  *  @param [in] statusCallback   - user callback to call after installation
 286  *  @param [in] progressCallback - user callback to call when plugin
 287  *                                 installation progress has changed
 288  *
 289  *  @return nothing (status returned in callback).
 290  *
 291  * Sample code:
 292  * @code
 293  *  wrt_install_plugin("/usr/lib/wrt-plugins/",NULL,NULL,NULL);
 294  * @endcode
 295  *
 296  * @see wrt_install_plugin
 297  */
 298 void wrt_install_plugin(const char *pluginDirectory,
 299         void *userData,
 300         WrtPluginInstallerStatusCallback statusCallback,
 301         WrtProgressCallback progressCallback);
 302
 303 /**
 304  * @brief To install plugins for first excution
 305  *
 306  * This method install plugins
 307  *
 308  * @return nothing
 309  */
 310 void wrt_install_all_plugins(WrtAllPluginInstalledCallback installed_cb,
 311         void *user_param);
 312
 313 /**
 314  * @brief To initialize for tests
 315  *
 316  * This method is wrt init for tests
 317  *
 318  * @return int
 319  */
 320 int wrt_installer_init_for_tests(void *userdata,
 321         WrtInstallerInitCallback callback);
 322
 323 /**
 324  * @brief To shutdown for tests
 325  *
 326  * This method is wrt shutdown for tests
 327  *
 328  * @return int
 329  */
 330 void wrt_installer_shutdown_for_tests();
 331
 332 /**
 333  * @brief wrt_get_widget_by_guid Returns pkgname by pkg guid (widgetId)
 334  * @param pkgname pkgname argument ot be set
 335  * @param guid guid that we look for
 336  * @return error code
 337  */
 338 WrtErrStatus wrt_get_widget_by_guid(std::string &pkgname, const std::string guid);
 339 #ifdef __cplusplus
 340 }
 341 #endif
 342
 343 #endif /* WRT_INSTALLER_API_H_ */