inc/app2ext_interface.h

   1 /*
   2  * app2ext
   3  *
   4  * Copyright (c) 2012 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jyotsna Dhumale <jyotsna.a@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 #ifndef __APP2EXT_INTERFACE_H__
  23 #define __APP2EXT_INTERFACE_H__
  24
  25 /**
  26  * @file app2ext_interface.h
  27  * @version 0.5
  28  * @brief    This file declares API of app2ext library
  29  */
  30
  31 /**
  32  * @addtogroup APPLICATION_FRAMEWORK
  33  * @{
  34  *
  35  * @defgroup app2ext
  36  * @version    0.5
  37  *
  38  * @section    Header to use them:
  39  * @code
  40  * #include <app2ext_interface.h>
  41  * @endcode
  42  *
  43  */
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 #ifndef API
  50 #define API __attribute__ ((visibility("default")))
  51 #endif
  52
  53 #include <glib.h>
  54
  55 /**
  56  * Enum for application installation location
  57  */
  58 typedef enum app2ext_install_location_t {
  59         APP2EXT_INTERNAL_MEM = 0,
  60         APP2EXT_SD_CARD,
  61         APP2EXT_MICRO_USB,
  62         APP2EXT_CLOUD,
  63         APP2EXT_NOT_INSTALLED
  64 } app2ext_install_location;
  65
  66 /**
  67  * Enum for installation/upgrade status[success/failure]
  68  */
  69 typedef enum app2ext_status_t {
  70         APP2EXT_STATUS_FAILED = 1,
  71         APP2EXT_STATUS_SUCCESS
  72 } app2ext_status;
  73
  74 /**
  75  * Enum for directory type
  76  */
  77 typedef enum app2ext_dir_type_t {
  78         APP2EXT_DIR_RO,
  79         APP2EXT_DIR_RW,
  80 } app2ext_dir_type;
  81
  82 /**
  83  * Enum for move command
  84  * @see app2sd_move_installed_app()
  85  */
  86 typedef enum app2ext_move_type_t {
  87         APP2EXT_MOVE_TO_EXT = 1,
  88         APP2EXT_MOVE_TO_PHONE,
  89 } app2ext_move_type;
  90
  91 /**
  92  * Enum for command type
  93  * @see app2sd_move_installed_app()
  94  */
  95 typedef enum app2sd_cmd_t {
  96         APP2SD_PRE_INSTALL = 1,
  97         APP2SD_POST_INSTALL,
  98         APP2SD_PRE_UNINSTALL,
  99         APP2SD_POST_UNINSTALL,
 100         APP2SD_PRE_UPGRADE,
 101         APP2SD_POST_UPGRADE,
 102         APP2SD_APP_LAUNCH,
 103         APP2SD_APP_TERMINATE,
 104         APP2SD_MOVE_APP_TO_MMC,
 105         APP2SD_MOVE_APP_TO_PHONE
 106 } app2sd_cmd;
 107
 108 /**
 109  * Enum for error codes
 110  */
 111 typedef enum app2ext_error_t {
 112         APP2EXT_ERROR_INVALID_ARGUMENTS = 2,
 113         APP2EXT_ERROR_MOVE,
 114         APP2EXT_ERROR_PRE_UNINSTALL,
 115         APP2EXT_ERROR_MMC_STATUS,
 116         APP2EXT_ERROR_DB_INITIALIZE,
 117         APP2EXT_ERROR_SQLITE_REGISTRY,
 118         APP2EXT_ERROR_PASSWD_GENERATION,
 119         APP2EXT_ERROR_MMC_INFORMATION,
 120         APP2EXT_ERROR_MMC_INSUFFICIENT_MEMORY,
 121         APP2EXT_ERROR_DELETE_DIRECTORY,
 122         APP2EXT_ERROR_CREATE_SYMLINK,
 123         APP2EXT_ERROR_CREATE_DIRECTORY,
 124         APP2EXT_ERROR_DELETE_LINK_FILE,
 125         APP2EXT_ERROR_PKG_EXISTS,
 126         APP2EXT_ERROR_ACCESS_FILE,
 127         APP2EXT_ERROR_OPEN_DIR,
 128         APP2EXT_ERROR_ALREADY_FILE_PRESENT,
 129         APP2EXT_ERROR_FILE_ABSENT,
 130         APP2EXT_ERROR_STRCMP_FAILED,
 131         APP2EXT_ERROR_INVALID_PACKAGE,
 132         APP2EXT_ERROR_CREATE_DIR_ENTRY,
 133         APP2EXT_ERROR_COPY_DIRECTORY,
 134         APP2EXT_ERROR_INVALID_CASE,
 135         APP2EXT_ERROR_SYMLINK_ALREADY_EXISTS,
 136         APP2EXT_ERROR_APPEND_HASH_TO_FILE,
 137         APP2EXT_ERROR_CREATE_DEVICE,
 138         APP2EXT_ERROR_DO_LOSETUP,
 139         APP2EXT_ERROR_CREATE_FS,
 140         APP2EXT_ERROR_MOUNT_PATH,
 141         APP2EXT_ERROR_CLEANUP,
 142         APP2EXT_ERROR_MOUNT,
 143         APP2EXT_ERROR_REMOUNT,
 144         APP2EXT_ERROR_PIPE_CREATION,
 145         APP2EXT_ERROR_LOOPBACK_DEVICE_UNAVAILABLE,
 146         APP2EXT_ERROR_VCONF_REGISTRY,
 147         APP2EXT_ERROR_FIND_ASSOCIATED_DEVICE_NODE,
 148         APP2EXT_ERROR_UNMOUNT,
 149         APP2EXT_ERROR_DELETE_LOOPBACK_DEVICE,
 150         APP2EXT_ERROR_DETACH_LOOPBACK_DEVICE,
 151         APP2EXT_ERROR_ALREADY_MOUNTED,
 152         APP2EXT_ERROR_PLUGIN_INIT_FAILED,
 153         APP2EXT_ERROR_PLUGIN_DEINIT_FAILED,
 154         APP2EXT_ERROR_DBUS_FAILED,
 155         APP2EXT_ERROR_MEMORY_ALLOC_FAILED,
 156         APP2EXT_ERROR_OPERATION_NOT_PERMITTED,
 157         APP2EXT_ERROR_SAME_LOOPBACK_DEVICE_EXISTS,
 158         APP2EXT_ERROR_PKGMGR_ERROR,
 159 #ifdef TIZEN_FEATURE_APP2SD_DMCRYPT_ENCRYPTION
 160         APP2EXT_ERROR_SETUP_DMCRYPT_DEVICE,
 161         APP2EXT_ERROR_OPEN_DMCRYPT_DEVICE,
 162         APP2EXT_ERROR_CLOSE_DMCRYPT_DEVICE,
 163         APP2EXT_ERROR_FIND_ASSOCIATED_DMCRYPT_DEVICE_NODE,
 164         APP2EXT_ERROR_DMCRYPT_DEVICE_UNAVAILABLE,
 165 #endif
 166         APP2EXT_ERROR_ENUM_MAX
 167 } app2ext_error;
 168
 169 /**
 170  * @brief : This function type is for a function that is implemented by plugin
 171  * and called before application is to be installed.
 172  *
 173  * @param[in]   appname         application package name which is to be installed
 174  * @param[in]   dir_list        directory structure of the application
 175  *                              This should be polulated by the package manager
 176  *                              before calling pre_install and should be freed after
 177  *                              pre_install returns.
 178  *                              Each node of dir_list is of type app2ext_dir_details
 179  *                              which has members Name(dirname) and Type (RO/RW)
 180  *                              For eg for rpm the dir_list should be populated with
 181  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 182  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 183  * @param[in]   size            Size of the application
 184  * @return      0 if success, error code(>0) if fail
 185  */
 186 typedef int (*app2ext_client_usr_pre_install)(const char *appname, GList* dir_list,
 187                 int size, uid_t uid);
 188 typedef int (*app2ext_client_pre_install)(const char *appname, GList* dir_list,
 189                 int size);
 190
 191 /**
 192  * @brief : This function type is for a function that is implemented by plugin
 193  * and called after application installation.
 194  *
 195  * @param[in]   appname         application package name which is to be installed
 196  * @param[in]   install_status  Installation status (Success/Failure)
 197  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 198  *                              APP2EXT_STATUS_FAILED]
 199  * @return      0 if success, error code(>0) if fail
 200  */
 201 typedef int (*app2ext_client_usr_post_install)(const char *appname,
 202                 app2ext_status install_status, uid_t uid);
 203 typedef int (*app2ext_client_post_install)(const char *appname,
 204                 app2ext_status install_status);
 205
 206 /**
 207  * @brief : This function type is for a function that is implemented by plugin
 208  * and called before application upgrade.
 209  *
 210  * @param[in]   appname         application package name which is to be upgraded
 211  * @param[in]   dir_list        directory structure of the application
 212  *                              This should be polulated by the package manager
 213  *                              before calling pre_upgrade and should be freed after
 214  *                              pre_upgrade returns.
 215  *                              Each node of dir_list is of type app2ext_dir_details
 216  *                              which has members Name(dirname) and Type (RO/RW)
 217  *                              For eg for rpm the dir_list should be populated with
 218  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 219  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 220  * @param[in]   size            Size of the application
 221  * @return      0 if success,  error code(>0) if fail
 222  */
 223 typedef int (*app2ext_client_usr_pre_upgrade)(const char *appname, GList* dir_list,
 224                 int size, uid_t uid);
 225 typedef int (*app2ext_client_pre_upgrade)(const char *appname, GList* dir_list,
 226                 int size);
 227
 228 /**
 229  * @brief : This function type is for a function that is implemented by plugin
 230  * and called before application upgradation.
 231  *
 232  * @param[in]   appname         application package name which is to be upgraded
 233  * @param[in]   upgrade_status  Upgrade status (Success/Failure)
 234  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 235  *                                      APP2EXT_STATUS_FAILED]
 236  * @return      0 if success, error code(>0) if fail
 237  */
 238 typedef int (*app2ext_client_usr_post_upgrade)(const char *appname,
 239                 app2ext_status upgrade_status, uid_t uid);
 240 typedef int (*app2ext_client_post_upgrade)(const char *appname,
 241                 app2ext_status upgrade_status);
 242
 243 /**
 244  * @brief : This function type is for a function that is implemented by plugin
 245  * and called before application uninstallation.
 246  *
 247  * @param[in]   appname         application package name which is to be uninstalled
 248  * @return      0 if success, error code(>0) if fail
 249  */
 250 typedef int (*app2ext_client_usr_pre_uninstall)(const char *appname, uid_t uid);
 251 typedef int (*app2ext_client_pre_uninstall)(const char *appname);
 252
 253 /**
 254  * @brief : This function type is for a function that is implemented by plugin
 255  * and called after application uninstallation.
 256  *
 257  * @param[in]   appname         application package name which is to be uninstalled
 258  * @return      0 if success, error code(>0) if fail
 259  */
 260 typedef int (*app2ext_client_usr_post_uninstall)(const char *appname, uid_t uid);
 261 typedef int (*app2ext_client_post_uninstall)(const char *appname);
 262
 263 /**
 264  * @brief : This function type is for a function that is implemented by plugin
 265  * and called when application is to be moved from extrenal memory
 266  *to internal memory or vice versa.
 267  *
 268  * @param[in]   appname         application package name which is to be moved
 269  * @param[in]   dir_list        directory structure of the application
 270  *                              This should be polulated by the package manager
 271  *                              before calling move and should be freed after
 272  *                              move returns.
 273  *                              Each node of dir_list is of type app2ext_dir_details
 274  *                              which has members Name(dirname) and Type (RO/RW)
 275  *                              For eg for rpm the dir_list should be populated with
 276  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 277  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 278  * @param[in]   move_type       move type
 279  *                              [Enum: APP2EXT_MOVE_TO_EXT, APP2EXT_MOVE_TO_PHONE]
 280  * @return      0 if success, error code(>0) if fail
 281  */
 282 typedef int (*app2ext_client_usr_pre_move)(const char *appname, GList* dir_list,
 283                 app2ext_move_type move_type, uid_t uid);
 284 typedef int (*app2ext_client_pre_move)(const char *appname, GList* dir_list,
 285                 app2ext_move_type move_type);
 286 typedef int (*app2ext_client_usr_post_move)(const char *appname,
 287                 app2ext_move_type move_type, uid_t uid);
 288 typedef int (*app2ext_client_post_move)(const char *appname,
 289                 app2ext_move_type move_type);
 290
 291 /**
 292  * @brief : This function type is for a function that is implemented by plugin
 293  * and called to enable application before application launch.
 294  *
 295  * @param[in]   appname         application package name which is to be enabled
 296  * @return      0 if success, error code(>0) if fail
 297  */
 298 typedef int (*app2ext_client_usr_enable)(const char *appname, uid_t uid);
 299 typedef int (*app2ext_client_enable)(const char *appname);
 300
 301 /**
 302  * @brief : This function type is for a function that is implemented by plugin
 303  * and called to enable/disable entire application packages.
 304  *
 305  * @return      0 if success, error code(>0) if fail
 306  */
 307 typedef int (*app2ext_client_enable_full_pkg)(void);
 308 typedef int (*app2ext_client_disable_full_pkg)(void);
 309
 310 /**
 311  * @brief : This function type is for a function that is implemented by plugin
 312  * and called to disable application before application exit.
 313  *
 314  * @param[in]   appname         application package name which is to be disabled
 315  * @return      0 if success, error code(>0) if fail
 316  */
 317 typedef int (*app2ext_client_usr_disable)(const char *appname, uid_t uid);
 318 typedef int (*app2ext_client_disable)(const char *appname);
 319
 320 /**
 321  * @brief : This function type is for a function that is implemented by plugin
 322  * and called after application uninstallation.
 323  *
 324  * @param[in]   pkgid           application package name which is to be uninstalled
 325  * @return      0 if success, error code(>0) if fail
 326  */
 327 typedef int (*app2ext_client_usr_force_clean)(const char *pkgid, uid_t uid);
 328 typedef int (*app2ext_client_force_clean)(const char *pkgid);
 329
 330 /**
 331  * This structure defines the app2ext interfaces. Plugins have to implement these functions
 332  */
 333 typedef struct app2ext_interface_t {
 334         /* for library function */
 335         app2ext_client_pre_install              client_pre_install;
 336         app2ext_client_post_install             client_post_install;
 337         app2ext_client_pre_upgrade              client_pre_upgrade;
 338         app2ext_client_post_upgrade             client_post_upgrade;
 339         app2ext_client_pre_uninstall            client_pre_uninstall;
 340         app2ext_client_post_uninstall           client_post_uninstall;
 341         app2ext_client_force_clean              client_force_clean;
 342         app2ext_client_enable                   client_enable;
 343         app2ext_client_disable                  client_disable;
 344         app2ext_client_enable_full_pkg          client_enable_full_pkg;
 345         app2ext_client_disable_full_pkg         client_disable_full_pkg;
 346         app2ext_client_pre_move                 client_pre_move;
 347         app2ext_client_post_move                client_post_move;
 348
 349         app2ext_client_usr_pre_install          client_usr_pre_install;
 350         app2ext_client_usr_post_install         client_usr_post_install;
 351         app2ext_client_usr_pre_upgrade          client_usr_pre_upgrade;
 352         app2ext_client_usr_post_upgrade         client_usr_post_upgrade;
 353         app2ext_client_usr_pre_uninstall        client_usr_pre_uninstall;
 354         app2ext_client_usr_post_uninstall       client_usr_post_uninstall;
 355         app2ext_client_usr_force_clean          client_usr_force_clean;
 356         app2ext_client_usr_enable               client_usr_enable;
 357         app2ext_client_usr_disable              client_usr_disable;
 358         app2ext_client_usr_pre_move             client_usr_pre_move;
 359         app2ext_client_usr_post_move            client_usr_post_move;
 360 } app2ext_interface;
 361
 362 /**
 363  * This structure defines app2ext handle .Each storage type maps to a different plugin
 364  * type                 : storage type,
 365  * plugin_handle        : plugin handle, need to close dlopen handle
 366  * interface            : inteface with plugin library
 367  */
 368 typedef struct {
 369         app2ext_install_location        type;
 370         void                            *plugin_handle;
 371         app2ext_interface               interface;
 372 } app2ext_handle;
 373
 374 /**
 375  * This structure defines directory details
 376  * name                 : directory name
 377  * type                 : permission (rw/ro)
 378  */
 379 typedef struct {
 380         char                    *name;
 381         app2ext_dir_type        type;
 382 } app2ext_dir_details;
 383
 384 /**
 385  * @brief : This API initializes the appropriate plugin based on storage type.
 386  *         It should be called before installation/uninstallation/upgrade
 387  * @param[in] storage_type      Location where package should be installed
 388  *                              [Ex: SD card, MicroUSB, Cloud]
 389  * @return      app2ext_handle pointer if success, NULL if fail
 390  *
 391  */
 392 API app2ext_handle *app2ext_init(int storage_type);
 393
 394 /**
 395  * @brief : This API deinitializes the plugin
 396  *         This should be called when use of the plugin is completed
 397  * @param[in] handle    pointer to app2ext_handle which is to be deinitialized
 398  * @pre         Initialization is done for the storage handle
 399  * @return      0 if success, error < 0 if fail
 400  *
 401  */
 402 API int app2ext_deinit(app2ext_handle *handle);
 403
 404 /**
 405  * @brief : This API returns the application location by refering to package manager DB
 406  *         This should be called to know location of an application package
 407  * @param[in] pkgid     package id
 408  * @param[in] uid       target user id of this instruction
 409  * @return      APP2EXT_SD_CARD if pkg is in SD card,
 410  *              APP2EXT_INTERNAL_MEM if pkg is in internal memory,
 411  *              APP2EXT_NOT_INSTALLED if there is no valid pkg path
 412  *              error < 0 if fail
 413  *@remarks see app2ext_install_location for more details
 414  */
 415 API int app2ext_get_app_location(const char *pkgid);
 416 API int app2ext_usr_get_app_location(const char *pkgid, uid_t uid);
 417
 418 /**
 419  * @brief : This API enable the package which is located in external memory
 420  * @param[in] pkgid     package id
 421  * @param[in] uid       target user id of this instruction
 422  * @return      error < 0 if pkg enable fail
 423  */
 424 API int app2ext_enable_external_pkg(const char *pkgid);
 425 API int app2ext_usr_enable_external_pkg(const char *pkgid, uid_t uid);
 426
 427 /**
 428  * @brief : This API disable the package which is located in external memory
 429  * @param[in] pkgid     package id
 430  * @param[in] uid       target user id of this instruction
 431  * @return      error < 0 if pkg disable fail
 432  */
 433 API int app2ext_disable_external_pkg(const char *pkgid);
 434 API int app2ext_usr_disable_external_pkg(const char *pkgid, uid_t uid);
 435
 436 /**
 437  * @brief : This API clean the directory and symbolic link which are made by app2ext
 438  * @param[in] pkgid     package id
 439  * @param[in] uid       target user id of this instruction
 440  * @return      error < 0 if pkg clean fail
 441  */
 442 API int app2ext_force_clean_pkg(const char *pkgid);
 443 API int app2ext_usr_force_clean_pkg(const char *pkgid, uid_t uid);
 444
 445 /**
 446  * @brief : This API mount/unmount all entries which are located in external memory
 447  * @return      error < 0 if fail to start enable/disable
 448  */
 449 API int app2ext_enable_all_external_pkgs(void);
 450 API int app2ext_disable_all_external_pkgs(void);
 451
 452 #ifdef __cplusplus
 453 }
 454 #endif
 455 #endif