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         APP2EXT_ERROR_KILLAPP_ERROR,
 160 #ifdef TIZEN_FEATURE_APP2SD_DMCRYPT_ENCRYPTION
 161         APP2EXT_ERROR_SETUP_DMCRYPT_DEVICE,
 162         APP2EXT_ERROR_OPEN_DMCRYPT_DEVICE,
 163         APP2EXT_ERROR_CLOSE_DMCRYPT_DEVICE,
 164         APP2EXT_ERROR_FIND_ASSOCIATED_DMCRYPT_DEVICE_NODE,
 165         APP2EXT_ERROR_DMCRYPT_DEVICE_UNAVAILABLE,
 166 #endif
 167         APP2EXT_ERROR_ENUM_MAX
 168 } app2ext_error;
 169
 170 /**
 171  * @brief : This function type is for a function that is implemented by plugin
 172  * and called before application is to be installed.
 173  *
 174  * @param[in]   appname         application package name which is to be installed
 175  * @param[in]   dir_list        directory structure of the application
 176  *                              This should be polulated by the package manager
 177  *                              before calling pre_install and should be freed after
 178  *                              pre_install returns.
 179  *                              Each node of dir_list is of type app2ext_dir_details
 180  *                              which has members Name(dirname) and Type (RO/RW)
 181  *                              For eg for rpm the dir_list should be populated with
 182  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 183  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 184  * @param[in]   size            Size of the application
 185  * @return      0 if success, error code(>0) if fail
 186  */
 187 typedef int (*app2ext_client_usr_pre_install)(const char *appname, GList* dir_list,
 188                 int size, uid_t uid);
 189 typedef int (*app2ext_client_pre_install)(const char *appname, GList* dir_list,
 190                 int size);
 191
 192 /**
 193  * @brief : This function type is for a function that is implemented by plugin
 194  * and called after application installation.
 195  *
 196  * @param[in]   appname         application package name which is to be installed
 197  * @param[in]   install_status  Installation status (Success/Failure)
 198  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 199  *                              APP2EXT_STATUS_FAILED]
 200  * @return      0 if success, error code(>0) if fail
 201  */
 202 typedef int (*app2ext_client_usr_post_install)(const char *appname,
 203                 app2ext_status install_status, uid_t uid);
 204 typedef int (*app2ext_client_post_install)(const char *appname,
 205                 app2ext_status install_status);
 206
 207 /**
 208  * @brief : This function type is for a function that is implemented by plugin
 209  * and called before application upgrade.
 210  *
 211  * @param[in]   appname         application package name which is to be upgraded
 212  * @param[in]   dir_list        directory structure of the application
 213  *                              This should be polulated by the package manager
 214  *                              before calling pre_upgrade and should be freed after
 215  *                              pre_upgrade returns.
 216  *                              Each node of dir_list is of type app2ext_dir_details
 217  *                              which has members Name(dirname) and Type (RO/RW)
 218  *                              For eg for rpm the dir_list should be populated with
 219  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 220  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 221  * @param[in]   size            Size of the application
 222  * @return      0 if success,  error code(>0) if fail
 223  */
 224 typedef int (*app2ext_client_usr_pre_upgrade)(const char *appname, GList* dir_list,
 225                 int size, uid_t uid);
 226 typedef int (*app2ext_client_pre_upgrade)(const char *appname, GList* dir_list,
 227                 int size);
 228
 229 /**
 230  * @brief : This function type is for a function that is implemented by plugin
 231  * and called before application upgradation.
 232  *
 233  * @param[in]   appname         application package name which is to be upgraded
 234  * @param[in]   upgrade_status  Upgrade status (Success/Failure)
 235  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 236  *                                      APP2EXT_STATUS_FAILED]
 237  * @return      0 if success, error code(>0) if fail
 238  */
 239 typedef int (*app2ext_client_usr_post_upgrade)(const char *appname,
 240                 app2ext_status upgrade_status, uid_t uid);
 241 typedef int (*app2ext_client_post_upgrade)(const char *appname,
 242                 app2ext_status upgrade_status);
 243
 244 /**
 245  * @brief : This function type is for a function that is implemented by plugin
 246  * and called before application uninstallation.
 247  *
 248  * @param[in]   appname         application package name which is to be uninstalled
 249  * @return      0 if success, error code(>0) if fail
 250  */
 251 typedef int (*app2ext_client_usr_pre_uninstall)(const char *appname, uid_t uid);
 252 typedef int (*app2ext_client_pre_uninstall)(const char *appname);
 253
 254 /**
 255  * @brief : This function type is for a function that is implemented by plugin
 256  * and called after application uninstallation.
 257  *
 258  * @param[in]   appname         application package name which is to be uninstalled
 259  * @return      0 if success, error code(>0) if fail
 260  */
 261 typedef int (*app2ext_client_usr_post_uninstall)(const char *appname, uid_t uid);
 262 typedef int (*app2ext_client_post_uninstall)(const char *appname);
 263
 264 /**
 265  * @brief : This function type is for a function that is implemented by plugin
 266  * and called when application is to be moved from extrenal memory
 267  *to internal memory or vice versa.
 268  *
 269  * @param[in]   appname         application package name which is to be moved
 270  * @param[in]   dir_list        directory structure of the application
 271  *                              This should be polulated by the package manager
 272  *                              before calling move and should be freed after
 273  *                              move returns.
 274  *                              Each node of dir_list is of type app2ext_dir_details
 275  *                              which has members Name(dirname) and Type (RO/RW)
 276  *                              For eg for rpm the dir_list should be populated with
 277  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 278  *                              (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 279  * @param[in]   move_type       move type
 280  *                              [Enum: APP2EXT_MOVE_TO_EXT, APP2EXT_MOVE_TO_PHONE]
 281  * @return      0 if success, error code(>0) if fail
 282  */
 283 typedef int (*app2ext_client_usr_pre_move)(const char *appname, GList* dir_list,
 284                 app2ext_move_type move_type, uid_t uid);
 285 typedef int (*app2ext_client_pre_move)(const char *appname, GList* dir_list,
 286                 app2ext_move_type move_type);
 287 typedef int (*app2ext_client_usr_post_move)(const char *appname,
 288                 app2ext_move_type move_type, uid_t uid);
 289 typedef int (*app2ext_client_post_move)(const char *appname,
 290                 app2ext_move_type move_type);
 291
 292 /**
 293  * @brief : This function type is for a function that is implemented by plugin
 294  * and called to enable application before application launch.
 295  *
 296  * @param[in]   appname         application package name which is to be enabled
 297  * @return      0 if success, error code(>0) if fail
 298  */
 299 typedef int (*app2ext_client_usr_enable)(const char *appname, uid_t uid);
 300 typedef int (*app2ext_client_enable)(const char *appname);
 301
 302 /**
 303  * @brief : This function type is for a function that is implemented by plugin
 304  * and called to enable/disable entire application packages.
 305  *
 306  * @return      0 if success, error code(>0) if fail
 307  */
 308 typedef int (*app2ext_client_enable_full_pkg)(void);
 309 typedef int (*app2ext_client_disable_full_pkg)(void);
 310
 311 /**
 312  * @brief : This function type is for a function that is implemented by plugin
 313  * and called to disable application before application exit.
 314  *
 315  * @param[in]   appname         application package name which is to be disabled
 316  * @return      0 if success, error code(>0) if fail
 317  */
 318 typedef int (*app2ext_client_usr_disable)(const char *appname, uid_t uid);
 319 typedef int (*app2ext_client_disable)(const char *appname);
 320
 321 /**
 322  * @brief : This function type is for a function that is implemented by plugin
 323  * and called after application uninstallation.
 324  *
 325  * @param[in]   pkgid           application package name which is to be uninstalled
 326  * @return      0 if success, error code(>0) if fail
 327  */
 328 typedef int (*app2ext_client_usr_force_clean)(const char *pkgid, uid_t uid);
 329 typedef int (*app2ext_client_force_clean)(const char *pkgid);
 330
 331 /**
 332  * This structure defines the app2ext interfaces. Plugins have to implement these functions
 333  */
 334 typedef struct app2ext_interface_t {
 335         /* for library function */
 336         app2ext_client_pre_install              client_pre_install;
 337         app2ext_client_post_install             client_post_install;
 338         app2ext_client_pre_upgrade              client_pre_upgrade;
 339         app2ext_client_post_upgrade             client_post_upgrade;
 340         app2ext_client_pre_uninstall            client_pre_uninstall;
 341         app2ext_client_post_uninstall           client_post_uninstall;
 342         app2ext_client_force_clean              client_force_clean;
 343         app2ext_client_enable                   client_enable;
 344         app2ext_client_disable                  client_disable;
 345         app2ext_client_enable_full_pkg          client_enable_full_pkg;
 346         app2ext_client_disable_full_pkg         client_disable_full_pkg;
 347         app2ext_client_pre_move                 client_pre_move;
 348         app2ext_client_post_move                client_post_move;
 349
 350         app2ext_client_usr_pre_install          client_usr_pre_install;
 351         app2ext_client_usr_post_install         client_usr_post_install;
 352         app2ext_client_usr_pre_upgrade          client_usr_pre_upgrade;
 353         app2ext_client_usr_post_upgrade         client_usr_post_upgrade;
 354         app2ext_client_usr_pre_uninstall        client_usr_pre_uninstall;
 355         app2ext_client_usr_post_uninstall       client_usr_post_uninstall;
 356         app2ext_client_usr_force_clean          client_usr_force_clean;
 357         app2ext_client_usr_enable               client_usr_enable;
 358         app2ext_client_usr_disable              client_usr_disable;
 359         app2ext_client_usr_pre_move             client_usr_pre_move;
 360         app2ext_client_usr_post_move            client_usr_post_move;
 361 } app2ext_interface;
 362
 363 /**
 364  * This structure defines app2ext handle .Each storage type maps to a different plugin
 365  * type                 : storage type,
 366  * plugin_handle        : plugin handle, need to close dlopen handle
 367  * interface            : inteface with plugin library
 368  */
 369 typedef struct {
 370         app2ext_install_location        type;
 371         void                            *plugin_handle;
 372         app2ext_interface               interface;
 373 } app2ext_handle;
 374
 375 /**
 376  * This structure defines directory details
 377  * name                 : directory name
 378  * type                 : permission (rw/ro)
 379  */
 380 typedef struct {
 381         char                    *name;
 382         app2ext_dir_type        type;
 383 } app2ext_dir_details;
 384
 385 /**
 386  * @brief : This API initializes the appropriate plugin based on storage type.
 387  *         It should be called before installation/uninstallation/upgrade
 388  * @param[in] storage_type      Location where package should be installed
 389  *                              [Ex: SD card, MicroUSB, Cloud]
 390  * @return      app2ext_handle pointer if success, NULL if fail
 391  *
 392  */
 393 API app2ext_handle *app2ext_init(int storage_type);
 394
 395 /**
 396  * @brief : This API deinitializes the plugin
 397  *         This should be called when use of the plugin is completed
 398  * @param[in] handle    pointer to app2ext_handle which is to be deinitialized
 399  * @pre         Initialization is done for the storage handle
 400  * @return      0 if success, error < 0 if fail
 401  *
 402  */
 403 API int app2ext_deinit(app2ext_handle *handle);
 404
 405 /**
 406  * @brief : This API returns the application location by refering to package manager DB
 407  *         This should be called to know location of an application package
 408  * @param[in] pkgid     package id
 409  * @param[in] uid       target user id of this instruction
 410  * @return      APP2EXT_SD_CARD if pkg is in SD card,
 411  *              APP2EXT_INTERNAL_MEM if pkg is in internal memory,
 412  *              APP2EXT_NOT_INSTALLED if there is no valid pkg path
 413  *              error < 0 if fail
 414  *@remarks see app2ext_install_location for more details
 415  */
 416 API int app2ext_get_app_location(const char *pkgid);
 417 API int app2ext_usr_get_app_location(const char *pkgid, uid_t uid);
 418
 419 /**
 420  * @brief : This API enable the package which is located in external memory
 421  * @param[in] pkgid     package id
 422  * @param[in] uid       target user id of this instruction
 423  * @return      error < 0 if pkg enable fail
 424  */
 425 API int app2ext_enable_external_pkg(const char *pkgid);
 426 API int app2ext_usr_enable_external_pkg(const char *pkgid, uid_t uid);
 427
 428 /**
 429  * @brief : This API disable the package which is located in external memory
 430  * @param[in] pkgid     package id
 431  * @param[in] uid       target user id of this instruction
 432  * @return      error < 0 if pkg disable fail
 433  */
 434 API int app2ext_disable_external_pkg(const char *pkgid);
 435 API int app2ext_usr_disable_external_pkg(const char *pkgid, uid_t uid);
 436
 437 /**
 438  * @brief : This API clean the directory and symbolic link which are made by app2ext
 439  * @param[in] pkgid     package id
 440  * @param[in] uid       target user id of this instruction
 441  * @return      error < 0 if pkg clean fail
 442  */
 443 API int app2ext_force_clean_pkg(const char *pkgid);
 444 API int app2ext_usr_force_clean_pkg(const char *pkgid, uid_t uid);
 445
 446 /**
 447  * @brief : This API mount/unmount all entries which are located in external memory
 448  * @return      error < 0 if fail to start enable/disable
 449  */
 450 API int app2ext_enable_all_external_pkgs(void);
 451 API int app2ext_disable_all_external_pkgs(void);
 452
 453 #ifdef __cplusplus
 454 }
 455 #endif
 456 #endif