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