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