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_MIGRATE_LEGACY
 107 } app2sd_cmd;
 108
 109 /**
 110  * Enum for error codes
 111  */
 112 typedef enum app2ext_error_t {
 113         APP2EXT_ERROR_INVALID_ARGUMENTS = 2,
 114         APP2EXT_ERROR_MOVE,
 115         APP2EXT_ERROR_PRE_UNINSTALL,
 116         APP2EXT_ERROR_MMC_STATUS,
 117         APP2EXT_ERROR_DB_INITIALIZE,
 118         APP2EXT_ERROR_SQLITE_REGISTRY,
 119         APP2EXT_ERROR_PASSWD_GENERATION,
 120         APP2EXT_ERROR_MMC_INFORMATION,
 121         APP2EXT_ERROR_MMC_INSUFFICIENT_MEMORY,
 122         APP2EXT_ERROR_DELETE_DIRECTORY,
 123         APP2EXT_ERROR_CREATE_SYMLINK,
 124         APP2EXT_ERROR_CREATE_DIRECTORY,
 125         APP2EXT_ERROR_DELETE_LINK_FILE,
 126         APP2EXT_ERROR_PKG_EXISTS,
 127         APP2EXT_ERROR_ACCESS_FILE,
 128         APP2EXT_ERROR_OPEN_DIR,
 129         APP2EXT_ERROR_ALREADY_FILE_PRESENT,
 130         APP2EXT_ERROR_FILE_ABSENT,
 131         APP2EXT_ERROR_STRCMP_FAILED,
 132         APP2EXT_ERROR_INVALID_PACKAGE,
 133         APP2EXT_ERROR_CREATE_DIR_ENTRY,
 134         APP2EXT_ERROR_COPY_DIRECTORY,
 135         APP2EXT_ERROR_INVALID_CASE,
 136         APP2EXT_ERROR_SYMLINK_ALREADY_EXISTS,
 137         APP2EXT_ERROR_APPEND_HASH_TO_FILE,
 138         APP2EXT_ERROR_CREATE_DEVICE,
 139         APP2EXT_ERROR_DO_LOSETUP,
 140         APP2EXT_ERROR_CREATE_FS,
 141         APP2EXT_ERROR_MOUNT_PATH,
 142         APP2EXT_ERROR_CLEANUP,
 143         APP2EXT_ERROR_MOUNT,
 144         APP2EXT_ERROR_REMOUNT,
 145         APP2EXT_ERROR_PIPE_CREATION,
 146         APP2EXT_ERROR_LOOPBACK_DEVICE_UNAVAILABLE,
 147         APP2EXT_ERROR_VCONF_REGISTRY,
 148         APP2EXT_ERROR_FIND_ASSOCIATED_DEVICE_NODE,
 149         APP2EXT_ERROR_UNMOUNT,
 150         APP2EXT_ERROR_DELETE_LOOPBACK_DEVICE,
 151         APP2EXT_ERROR_DETACH_LOOPBACK_DEVICE,
 152         APP2EXT_ERROR_ALREADY_MOUNTED,
 153         APP2EXT_ERROR_PLUGIN_INIT_FAILED,
 154         APP2EXT_ERROR_PLUGIN_DEINIT_FAILED,
 155         APP2EXT_ERROR_DBUS_FAILED,
 156         APP2EXT_ERROR_MEMORY_ALLOC_FAILED,
 157         APP2EXT_ERROR_OPERATION_NOT_PERMITTED,
 158         APP2EXT_ERROR_SAME_LOOPBACK_DEVICE_EXISTS,
 159         APP2EXT_ERROR_PKGMGR_ERROR,
 160         APP2EXT_ERROR_KILLAPP_ERROR,
 161         APP2EXT_ERROR_NOENTRY,
 162 #ifdef TIZEN_FEATURE_APP2SD_DMCRYPT_ENCRYPTION
 163         APP2EXT_ERROR_SETUP_DMCRYPT_DEVICE,
 164         APP2EXT_ERROR_OPEN_DMCRYPT_DEVICE,
 165         APP2EXT_ERROR_CLOSE_DMCRYPT_DEVICE,
 166         APP2EXT_ERROR_FIND_ASSOCIATED_DMCRYPT_DEVICE_NODE,
 167         APP2EXT_ERROR_DMCRYPT_DEVICE_UNAVAILABLE,
 168 #endif
 169         APP2EXT_ERROR_ENUM_MAX
 170 } app2ext_error;
 171
 172 /**
 173  * @brief : This function type is for a function that is implemented by plugin
 174  * and called before application is to be installed.
 175  *
 176  * @param[in]   appname         application package name which is to be installed
 177  * @param[in]   dir_list        directory structure of the application
 178  *                              This should be polulated by the package manager
 179  *                              before calling pre_install and should be freed after
 180  *                              pre_install returns.
 181  *                              Each node of dir_list is of type app2ext_dir_details
 182  *                              which has members Name(dirname) and Type (RO/RW)
 183  *                              For eg for rpm the dir_list should be populated with
 184  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 185  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 186  * @param[in]   size            Size of the application
 187  * @return      0 if success, error code(>0) if fail
 188  */
 189 typedef int (*app2ext_client_usr_pre_install)(const char *appname, GList* dir_list,
 190                 int size, uid_t uid);
 191 typedef int (*app2ext_client_pre_install)(const char *appname, GList* dir_list,
 192                 int size);
 193
 194 /**
 195  * @brief : This function type is for a function that is implemented by plugin
 196  * and called after application installation.
 197  *
 198  * @param[in]   appname         application package name which is to be installed
 199  * @param[in]   install_status  Installation status (Success/Failure)
 200  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 201  *                              APP2EXT_STATUS_FAILED]
 202  * @return      0 if success, error code(>0) if fail
 203  */
 204 typedef int (*app2ext_client_usr_post_install)(const char *appname,
 205                 app2ext_status install_status, uid_t uid);
 206 typedef int (*app2ext_client_post_install)(const char *appname,
 207                 app2ext_status install_status);
 208
 209 /**
 210  * @brief : This function type is for a function that is implemented by plugin
 211  * and called before application upgrade.
 212  *
 213  * @param[in]   appname         application package name which is to be upgraded
 214  * @param[in]   dir_list        directory structure of the application
 215  *                              This should be polulated by the package manager
 216  *                              before calling pre_upgrade and should be freed after
 217  *                              pre_upgrade returns.
 218  *                              Each node of dir_list is of type app2ext_dir_details
 219  *                              which has members Name(dirname) and Type (RO/RW)
 220  *                              For eg for rpm the dir_list should be populated with
 221  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 222  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 223  * @param[in]   size            Size of the application
 224  * @return      0 if success,  error code(>0) if fail
 225  */
 226 typedef int (*app2ext_client_usr_pre_upgrade)(const char *appname, GList* dir_list,
 227                 int size, uid_t uid);
 228 typedef int (*app2ext_client_pre_upgrade)(const char *appname, GList* dir_list,
 229                 int size);
 230
 231 /**
 232  * @brief : This function type is for a function that is implemented by plugin
 233  * and called before application upgradation.
 234  *
 235  * @param[in]   appname         application package name which is to be upgraded
 236  * @param[in]   upgrade_status  Upgrade status (Success/Failure)
 237  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 238  *                                      APP2EXT_STATUS_FAILED]
 239  * @return      0 if success, error code(>0) if fail
 240  */
 241 typedef int (*app2ext_client_usr_post_upgrade)(const char *appname,
 242                 app2ext_status upgrade_status, uid_t uid);
 243 typedef int (*app2ext_client_post_upgrade)(const char *appname,
 244                 app2ext_status upgrade_status);
 245
 246 /**
 247  * @brief : This function type is for a function that is implemented by plugin
 248  * and called before application uninstallation.
 249  *
 250  * @param[in]   appname         application package name which is to be uninstalled
 251  * @return      0 if success, error code(>0) if fail
 252  */
 253 typedef int (*app2ext_client_usr_pre_uninstall)(const char *appname, uid_t uid);
 254 typedef int (*app2ext_client_pre_uninstall)(const char *appname);
 255
 256 /**
 257  * @brief : This function type is for a function that is implemented by plugin
 258  * and called after application uninstallation.
 259  *
 260  * @param[in]   appname         application package name which is to be uninstalled
 261  * @return      0 if success, error code(>0) if fail
 262  */
 263 typedef int (*app2ext_client_usr_post_uninstall)(const char *appname, uid_t uid);
 264 typedef int (*app2ext_client_post_uninstall)(const char *appname);
 265
 266 /**
 267  * @brief : This function type is for a function that is implemented by plugin
 268  * and called when application is to be moved from extrenal memory
 269  *to internal memory or vice versa.
 270  *
 271  * @param[in]   appname         application package name which is to be moved
 272  * @param[in]   dir_list        directory structure of the application
 273  *                              This should be polulated by the package manager
 274  *                              before calling move and should be freed after
 275  *                              move returns.
 276  *                              Each node of dir_list is of type app2ext_dir_details
 277  *                              which has members Name(dirname) and Type (RO/RW)
 278  *                              For eg for rpm the dir_list should be populated with
 279  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 280  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 281  * @param[in]   move_type       move type
 282  *                              [Enum: APP2EXT_MOVE_TO_EXT, APP2EXT_MOVE_TO_PHONE]
 283  * @return      0 if success, error code(>0) if fail
 284  */
 285 typedef int (*app2ext_client_usr_pre_move)(const char *appname, GList* dir_list,
 286                 app2ext_move_type move_type, uid_t uid);
 287 typedef int (*app2ext_client_pre_move)(const char *appname, GList* dir_list,
 288                 app2ext_move_type move_type);
 289 typedef int (*app2ext_client_usr_post_move)(const char *appname,
 290                 app2ext_move_type move_type, uid_t uid);
 291 typedef int (*app2ext_client_post_move)(const char *appname,
 292                 app2ext_move_type move_type);
 293
 294 /**
 295  * @brief : This function type is for a function that is implemented by plugin
 296  * and called to enable application before application launch.
 297  *
 298  * @param[in]   appname         application package name which is to be enabled
 299  * @return      0 if success, error code(>0) if fail
 300  */
 301 typedef int (*app2ext_client_usr_enable)(const char *appname, uid_t uid);
 302 typedef int (*app2ext_client_enable)(const char *appname);
 303
 304 /**
 305  * @brief : This function type is for a function that is implemented by plugin
 306  * and called to enable/disable entire application packages.
 307  *
 308  * @return      0 if success, error code(>0) if fail
 309  */
 310 typedef int (*app2ext_client_enable_full_pkg)(void);
 311 typedef int (*app2ext_client_disable_full_pkg)(void);
 312
 313 /**
 314  * @brief : This function type is for a function that is implemented by plugin
 315  * and called to disable application before application exit.
 316  *
 317  * @param[in]   appname         application package name which is to be disabled
 318  * @return      0 if success, error code(>0) if fail
 319  */
 320 typedef int (*app2ext_client_usr_disable)(const char *appname, uid_t uid);
 321 typedef int (*app2ext_client_disable)(const char *appname);
 322
 323 /**
 324  * @brief : This function type is for a function that is implemented by plugin
 325  * and called after application uninstallation.
 326  *
 327  * @param[in]   pkgid           application package name which is to be uninstalled
 328  * @return      0 if success, error code(>0) if fail
 329  */
 330 typedef int (*app2ext_client_usr_force_clean)(const char *pkgid, uid_t uid);
 331 typedef int (*app2ext_client_force_clean)(const char *pkgid);
 332
 333 /**
 334  * @brief : This function type is for a function that is implemented by plugin
 335  * and called before migration of legacy mount image.
 336  *
 337  * @param[in]   pkgid           application package name which is to be migrated
 338  * @return      0 if success, error code(>0) if fail
 339  */
 340 typedef int (*app2ext_client_usr_pre_migrate_legacy)(const char *pkgid,
 341                 uid_t uid);
 342
 343 /**
 344  * @brief : This function type is for a function that is implemented by plugin
 345  * and called after migration of legacy mount image.
 346  *
 347  * @param[in]   pkgid           application package name which is to be migrated
 348  * @return      0 if success, error code(>0) if fail
 349  */
 350 typedef int (*app2ext_client_usr_post_migrate_legacy)(const char *pkgid,
 351                 uid_t uid);
 352
 353 /**
 354  * @brief : This function type is for a function that is implemented by plugin
 355  * and called to migrate legacy mount image.
 356  *
 357  * @param[in]   pkgid           application package name which is to be migrated
 358  * @return      0 if success, error code(>0) if fail
 359  */
 360 typedef int (*app2ext_client_migrate_legacy_all)(void);
 361
 362 /**
 363  * @brief : This function type is for a function that is implemented by plugin
 364  * and called to get the external image name.
 365  *
 366  * @param[in]   pkgid           application package name
 367  * @param[in]   uid           target user id
 368  * @return      the name of external image
 369  * @remark      the name should be freed after the use.
 370  */
 371 typedef char *(*app2ext_client_usr_getname_image)(const char *pkgid,
 372                 uid_t uid);
 373
 374 /**
 375  * @brief : This function type is for a function that is implemented by plugin
 376  * and called to get the external image path.
 377  *
 378  * @param[in]   pkgid           application package name
 379  * @param[in]   uid           target user id
 380  * @return      the path of external image
 381  * @remark      the path should be freed after the use.
 382  */
 383 typedef char *(*app2ext_client_usr_get_image_path)(const char *pkgid,
 384                 uid_t uid);
 385
 386 /**
 387  * This structure defines the app2ext interfaces.
 388  * Plugins have to implement these functions
 389  */
 390 typedef struct app2ext_interface_t {
 391         /* for library function */
 392         app2ext_client_pre_install              client_pre_install;
 393         app2ext_client_post_install             client_post_install;
 394         app2ext_client_pre_upgrade              client_pre_upgrade;
 395         app2ext_client_post_upgrade             client_post_upgrade;
 396         app2ext_client_pre_uninstall            client_pre_uninstall;
 397         app2ext_client_post_uninstall           client_post_uninstall;
 398         app2ext_client_force_clean              client_force_clean;
 399         app2ext_client_enable                   client_enable;
 400         app2ext_client_disable                  client_disable;
 401         app2ext_client_enable_full_pkg          client_enable_full_pkg;
 402         app2ext_client_disable_full_pkg         client_disable_full_pkg;
 403         app2ext_client_pre_move                 client_pre_move;
 404         app2ext_client_post_move                client_post_move;
 405         app2ext_client_migrate_legacy_all       client_migrate_legacy_all;
 406
 407         app2ext_client_usr_pre_install          client_usr_pre_install;
 408         app2ext_client_usr_post_install         client_usr_post_install;
 409         app2ext_client_usr_pre_upgrade          client_usr_pre_upgrade;
 410         app2ext_client_usr_post_upgrade         client_usr_post_upgrade;
 411         app2ext_client_usr_pre_uninstall        client_usr_pre_uninstall;
 412         app2ext_client_usr_post_uninstall       client_usr_post_uninstall;
 413         app2ext_client_usr_force_clean          client_usr_force_clean;
 414         app2ext_client_usr_enable               client_usr_enable;
 415         app2ext_client_usr_disable              client_usr_disable;
 416         app2ext_client_usr_pre_move             client_usr_pre_move;
 417         app2ext_client_usr_post_move            client_usr_post_move;
 418         app2ext_client_usr_getname_image        client_usr_getname_image;
 419         app2ext_client_usr_pre_migrate_legacy   client_usr_pre_migrate_legacy;
 420         app2ext_client_usr_post_migrate_legacy  client_usr_post_migrate_legacy;
 421         app2ext_client_usr_get_image_path       client_usr_get_image_path;
 422 } app2ext_interface;
 423
 424 /**
 425  * This structure defines app2ext handle .Each storage type maps to a different plugin
 426  * type                 : storage type,
 427  * plugin_handle        : plugin handle, need to close dlopen handle
 428  * interface            : inteface with plugin library
 429  */
 430 typedef struct {
 431         app2ext_install_location        type;
 432         void                            *plugin_handle;
 433         app2ext_interface               interface;
 434 } app2ext_handle;
 435
 436 /**
 437  * This structure defines directory details
 438  * name                 : directory name
 439  * type                 : permission (rw/ro)
 440  */
 441 typedef struct {
 442         char                    *name;
 443         app2ext_dir_type        type;
 444 } app2ext_dir_details;
 445
 446 /**
 447  * @brief : This API initializes the appropriate plugin based on storage type.
 448  *         It should be called before installation/uninstallation/upgrade
 449  * @param[in] storage_type      Location where package should be installed
 450  *                              [Ex: SD card, MicroUSB, Cloud]
 451  * @return      app2ext_handle pointer if success, NULL if fail
 452  *
 453  */
 454 API app2ext_handle *app2ext_init(int storage_type);
 455
 456 /**
 457  * @brief : This API deinitializes the plugin
 458  *         This should be called when use of the plugin is completed
 459  * @param[in] handle    pointer to app2ext_handle which is to be deinitialized
 460  * @pre         Initialization is done for the storage handle
 461  * @return      0 if success, error < 0 if fail
 462  *
 463  */
 464 API int app2ext_deinit(app2ext_handle *handle);
 465
 466 /**
 467  * @brief : This API enable the package which is located in external memory
 468  * @param[in] pkgid     package id
 469  * @param[in] uid       target user id of this instruction
 470  * @return      error < 0 if pkg enable fail
 471  */
 472 API int app2ext_enable_external_pkg(const char *pkgid);
 473 API int app2ext_usr_enable_external_pkg(const char *pkgid, uid_t uid);
 474
 475 /**
 476  * @brief : This API disable the package which is located in external memory
 477  * @param[in] pkgid     package id
 478  * @param[in] uid       target user id of this instruction
 479  * @return      error < 0 if pkg disable fail
 480  */
 481 API int app2ext_disable_external_pkg(const char *pkgid);
 482 API int app2ext_usr_disable_external_pkg(const char *pkgid, uid_t uid);
 483
 484 /**
 485  * @brief : This API clean the directory and symbolic link which are made by app2ext
 486  * @param[in] pkgid     package id
 487  * @param[in] uid       target user id of this instruction
 488  * @return      error < 0 if pkg clean fail
 489  */
 490 API int app2ext_force_clean_pkg(const char *pkgid);
 491 API int app2ext_usr_force_clean_pkg(const char *pkgid, uid_t uid);
 492
 493 /**
 494  * @brief : This API mount/unmount all entries which are located in external memory
 495  * @return      error < 0 if fail to start enable/disable
 496  */
 497 API int app2ext_enable_all_external_pkgs(void);
 498 API int app2ext_disable_all_external_pkgs(void);
 499
 500 /**
 501  * @brief : This API migrate all legacy entries which are located in external memory
 502  * @return      error < 0 if fail to migrate legacy
 503  */
 504 API int app2ext_migrate_legacy_all(void);
 505
 506 /**
 507  * @brief : This API get the external image name
 508  * @param[in]   pkgid           application package name
 509  * @param[in]   uid           target user id
 510  * @return      the name of external image
 511  * @remark      the name should be freed after the use.
 512  */
 513 API char *app2ext_usr_getname_image(const char *pkgid, uid_t uid);
 514
 515 /**
 516  * @brief : This API get the external image path
 517  * @param[in]   pkgid           application package name
 518  * @param[in]   uid           target user id
 519  * @return      the path of external image
 520  * @remark      the path should be freed after the use.
 521  */
 522 API char *app2ext_usr_get_image_path(const char *pkgid, uid_t uid);
 523
 524 #ifdef __cplusplus
 525 }
 526 #endif
 527 #endif