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  * @addtogroup APPLICATION_FRAMEWORK
  32  * @{
  33  *
  34  * @defgroup app2ext
  35  * @version    0.5
  36  *
  37  * @section    Header to use them:
  38  * @code
  39  * #include <app2ext_interface.h>
  40  * @endcode
  41  *
  42  */
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 #ifndef API
  49 #define API __attribute__ ((visibility("default")))
  50 #endif
  51
  52 #include <dlog/dlog.h>
  53 #include <glib.h>
  54
  55 /* For multi-user support */
  56 #include <tzplatform_config.h>
  57
  58 #ifdef LOG_TAG
  59 #undef LOG_TAG
  60 #endif
  61
  62 #define LOG_TAG "APP2EXT"
  63
  64 #ifdef _DEBUG_MODE_
  65 #define app2ext_print(fmt, arg...) LOGD(fmt,##arg)
  66 #else
  67 #define app2ext_print(FMT, ARG...) SLOGD(FMT,##ARG);
  68 #endif
  69
  70 #define APP2EXT_SUCCESS 0
  71 #define MMC_PATH tzplatform_mkpath(TZ_SYS_STORAGE, "sdcard")
  72 #define APP2SD_PATH tzplatform_mkpath(TZ_SYS_STORAGE, "sdcard/app2sd/")
  73 #define APP_INSTALLATION_PATH tzplatform_mkpath(TZ_USER_APP, "")
  74
  75 /**
  76  * Enum for application installation location
  77  */
  78 typedef enum app2ext_install_location_t {
  79         APP2EXT_INTERNAL_MEM = 0,
  80         APP2EXT_SD_CARD,
  81         APP2EXT_MICRO_USB,
  82         APP2EXT_CLOUD,
  83         APP2EXT_NOT_INSTALLED
  84 } app2ext_install_location;
  85
  86 /**
  87  * Enum for installation/upgrade status[success/failure]
  88  */
  89 typedef enum app2ext_status_t {
  90         APP2EXT_STATUS_FAILED = 1,
  91         APP2EXT_STATUS_SUCCESS
  92 } app2ext_status;
  93
  94 /**
  95  * Enum for directory type
  96  */
  97 typedef enum app2ext_dir_type_t {
  98         APP2EXT_DIR_RO,
  99         APP2EXT_DIR_RW,
 100 } app2ext_dir_type;
 101
 102 /**
 103  * Enum for move command
 104  * @see app2sd_move_installed_app()
 105  */
 106 typedef enum app2ext_move_type_t {
 107         APP2EXT_MOVE_TO_EXT = 1,
 108         APP2EXT_MOVE_TO_PHONE
 109 } app2ext_move_type;
 110
 111 /**
 112  * Enum for error codes
 113  */
 114 typedef enum app2ext_error_t {
 115         APP2EXT_ERROR_INVALID_ARGUMENTS = 2,
 116         APP2EXT_ERROR_MOVE,
 117         APP2EXT_ERROR_PRE_UNINSTALL,
 118         APP2EXT_ERROR_MMC_STATUS,
 119         APP2EXT_ERROR_DB_INITIALIZE,
 120         APP2EXT_ERROR_SQLITE_REGISTRY,
 121         APP2EXT_ERROR_PASSWD_GENERATION,
 122         APP2EXT_ERROR_MMC_INFORMATION,
 123         APP2EXT_ERROR_MMC_INSUFFICIENT_MEMORY,
 124         APP2EXT_ERROR_DELETE_DIRECTORY,
 125         APP2EXT_ERROR_CREATE_SYMLINK,
 126         APP2EXT_ERROR_CREATE_DIRECTORY,
 127         APP2EXT_ERROR_DELETE_LINK_FILE,
 128         APP2EXT_ERROR_PKG_EXISTS,
 129         APP2EXT_ERROR_ACCESS_FILE,
 130         APP2EXT_ERROR_OPEN_DIR,
 131         APP2EXT_ERROR_ALREADY_FILE_PRESENT,
 132         APP2EXT_ERROR_FILE_ABSENT,
 133         APP2EXT_ERROR_STRCMP_FAILED,
 134         APP2EXT_ERROR_INVALID_PACKAGE,
 135         APP2EXT_ERROR_CREATE_DIR_ENTRY,
 136         APP2EXT_ERROR_PASSWORD_GENERATION,
 137         APP2EXT_ERROR_COPY_DIRECTORY,
 138         APP2EXT_ERROR_INVALID_CASE,
 139         APP2EXT_ERROR_SYMLINK_ALREADY_EXISTS,
 140         APP2EXT_ERROR_APPEND_HASH_TO_FILE,
 141         APP2EXT_ERROR_CREATE_DEVICE,
 142         APP2EXT_ERROR_DO_LOSETUP,
 143         APP2EXT_ERROR_CREATE_FS,
 144         APP2EXT_ERROR_MOUNT_PATH,
 145         APP2EXT_ERROR_CLEANUP,
 146         APP2EXT_ERROR_MOUNT,
 147         APP2EXT_ERROR_REMOUNT,
 148         APP2EXT_ERROR_PIPE_CREATION,
 149         APP2EXT_ERROR_LOOPBACK_DEVICE_UNAVAILABLE,
 150         APP2EXT_ERROR_VCONF_REGISTRY,
 151         APP2EXT_ERROR_FIND_ASSOCIATED_DEVICE_NODE,
 152         APP2EXT_ERROR_UNMOUNT,
 153         APP2EXT_ERROR_DELETE_LOOPBACK_DEVICE,
 154         APP2EXT_ERROR_DETACH_LOOPBACK_DEVICE,
 155         APP2EXT_ERROR_ALREADY_MOUNTED,
 156         APP2EXT_ERROR_PLUGIN_INIT_FAILED,
 157         APP2EXT_ERROR_PLUGIN_DEINIT_FAILED
 158 } app2ext_error;
 159
 160 /**
 161  * @brief :This function type is for a function that is implemented by plugin
 162  * and called before application is to be installed.
 163  *
 164  * @param[in]   appname         application package name which is to be installed
 165  * @param[in]   dir_list        directory structure of the application
 166  *                              This should be polulated by the package manager
 167  *                              before calling pre_install and should be freed after
 168  *                              pre_install returns.
 169  *                              Each node of dir_list is of type app2ext_dir_details
 170  *                              which has members Name(dirname) and Type (RO/RW)
 171  *                              For eg for rpm the dir_list should be populated with
 172  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 173                                 (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 174  * @param[in]   size            Size of the application
 175  * @return      0 if success,  error code(>0) if fail
 176  */
 177 typedef int (*app2ext_pre_install)(const char *appname, GList* dir_list, int size);
 178
 179 /**
 180  * @brief :This function type is for a function that is implemented by plugin
 181  * and called after application installation.
 182  *
 183  * @param[in]   appname         application package name which is to be installed
 184  * @param[in]   install_status  Installation status (Success/Failure)
 185  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 186  *                                      APP2EXT_STATUS_FAILED]
 187  * @return      0 if success,  error code(>0) if fail
 188  */
 189 typedef int (*app2ext_post_install)(const char *appname, app2ext_status install_status);
 190
 191 /**
 192  * @brief :This function type is for a function that is implemented by plugin
 193  * and called before application upgrade.
 194  *
 195  * @param[in]   appname         application package name which is to be upgraded
 196  * @param[in]   dir_list        directory structure of the application
 197  *                              This should be polulated by the package manager
 198  *                              before calling pre_upgrade and should be freed after
 199  *                              pre_upgrade returns.
 200  *                              Each node of dir_list is of type app2ext_dir_details
 201  *                              which has members Name(dirname) and Type (RO/RW)
 202  *                              For eg for rpm the dir_list should be populated with
 203  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 204                                 (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 205  * @param[in]   size            Size of the application
 206  * @return      0 if success,  error code(>0) if fail
 207  */
 208 typedef int (*app2ext_pre_upgrade)(const char *appname, GList* dir_list, int size);
 209
 210 /**
 211  * @brief :This function type is for a function that is implemented by plugin
 212  * and called before application upgradation.
 213  *
 214  * @param[in]   appname         application package name which is to be upgraded
 215  * @param[in]   upgrade_status  Upgrade status (Success/Failure)
 216  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 217  *                                      APP2EXT_STATUS_FAILED]
 218  * @return      0 if success,  error code(>0) if fail
 219  */
 220 typedef int (*app2ext_post_upgrade)(const char *appname, app2ext_status upgrade_status);
 221
 222 /**
 223  * @brief :This function type is for a function that is implemented by plugin
 224  * and called before application uninstallation.
 225  *
 226  * @param[in]   appname         application package name which is to be uninstalled
 227  * @return      0 if success,  error code(>0) if fail
 228  */
 229 typedef int (*app2ext_pre_uninstall)(const char *appname);
 230
 231 /**
 232  * @brief :This function type is for a function that is implemented by plugin
 233  * and called after application uninstallation.
 234  *
 235  * @param[in]   appname         application package name which is to be uninstalled
 236  * @return      0 if success,  error code(>0) if fail
 237  */
 238 typedef int (*app2ext_post_uninstall)(const char *appname);
 239
 240 /**
 241  * @brief :This function type is for a function that is implemented by plugin
 242  * and called when application is to be moved from extrenal memory
 243  *to internal memory or vice versa.
 244  *
 245  * @param[in]   appname         application package name which is to be moved
 246  * @param[in]   dir_list        directory structure of the application
 247  *                              This should be polulated by the package manager
 248  *                              before calling move and should be freed after
 249  *                              move returns.
 250  *                              Each node of dir_list is of type app2ext_dir_details
 251  *                              which has members Name(dirname) and Type (RO/RW)
 252  *                              For eg for rpm the dir_list should be populated with
 253  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 254                                 (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 255  * @param[in]   move_type       move type
 256  *                              [Enum: APP2EXT_MOVE_TO_EXT, APP2EXT_MOVE_TO_PHONE]
 257  * @return      0 if success,  error code(>0) if fail
 258  */
 259 typedef int (*app2ext_move)(const char *appname, GList* dir_list, app2ext_move_type move_type);
 260
 261 /**
 262  * @brief :This function type is for a function that is implemented by plugin
 263  * and called to enable application before application launch.
 264  *
 265  * @param[in]   appname         application package name which is to be enabled
 266  * @return      0 if success,  error code(>0) if fail
 267  */
 268 typedef int (*app2ext_enable)(const char *appname);
 269
 270 /**
 271  * @brief :This function type is for a function that is implemented by plugin
 272  * and called to disable application before application exit.
 273  *
 274  * @param[in]   appname         application package name which is to be disabled
 275  * @return      0 if success,  error code(>0) if fail
 276  */
 277 typedef int (*app2ext_disable)(const char *appname);
 278
 279 /**
 280  * This structure defines the app2ext interfaces. Plugins have to implement these functions
 281  */
 282 typedef struct app2ext_interface_t{
 283         app2ext_pre_install             pre_install;
 284         app2ext_post_install            post_install;
 285         app2ext_pre_upgrade             pre_upgrade;
 286         app2ext_post_upgrade            post_upgrade;
 287         app2ext_pre_uninstall           pre_uninstall;
 288         app2ext_post_uninstall          post_uninstall;
 289         app2ext_move                    move;
 290         app2ext_enable                  enable;
 291         app2ext_disable                 disable;
 292 } app2ext_interface;
 293
 294 /**
 295  * This structure defines app2ext handle .Each storage type maps to a different plugin
 296  * type                         : storage type
 297  * plugin_handle                        : plugin handle
 298  */
 299 typedef struct {
 300         app2ext_install_location        type;
 301         void                    *plugin_handle;
 302         app2ext_interface               interface;
 303 } app2ext_handle;
 304
 305 /**
 306  * This structure defines directory details
 307  * name                 : directory name
 308  * type                 : permission (rw/ro)
 309  */
 310 typedef struct {
 311         char *          name;
 312         app2ext_dir_type        type;
 313 } app2ext_dir_details;
 314
 315 /**
 316  * @brief : This API initializes the appropriate plugin based on storage type.
 317  *      It should be called before installation/uninstallation/upgrade
 318  * @param[in] storage_type      Location where package should be installed
 319  *                              [Ex: SD card, MicroUSB, Cloud]
 320  * @return      app2ext_handle pointer if success, NULL if fail
 321  *
 322  @code
 323  #include <app2ext_interface.h>
 324  app2ext_handle *handle = NULL;
 325  GLIst *dir_list = NULL;
 326  handle = app2ext_init(APP2EXT_SD_CARD); //Initializes SD card plug-in
 327  if(handle)
 328  {
 329         printf("\n SUCCESS");
 330         // Perform package install/uninstall/upgrade/move here
 331         // Packge install example
 332         // Package manager should polulate dir_list with directory structure information of the package
 333         ret = handle->interface.pre_install("com.samsung.calculator", dir_list, 20);
 334         if (ret) {
 335                 printf("\n TC : pre app install API fail. Reason %s", error_list[ret]);
 336                 return -1;
 337         }
 338
 339         // Package manager installs the package
 340
 341         ret = handle->interface.post_install("com.samsung.calculator", APP2EXT_STATUS_SUCCESS);
 342         if (ret) {
 343                 printf("\n TC : post app install API fail Reason %s", error_list[ret]);
 344
 345                 return -1;
 346         }
 347         // Package manager should free dir_list
 348         return;
 349  } else
 350          printf("\n FAILURE");
 351  @endcode
 352  */
 353 API app2ext_handle *app2ext_init(int storage_type);
 354
 355 /**
 356  * @brief : This API deinitializes the plugin
 357  *          This should be called when use of the plugin is completed
 358  * @param[in] handle    pointer to app2ext_handle which is to be deinitialized
 359  * @pre         Initialization is done for the storage handle
 360  * @return      0 if success,  error code(>0) if fail
 361  *
 362  @code
 363  #include <app2ext_interface.h>
 364  app2ext_handle *handle = NULL;
 365  handle = app2ext_init(APP2EXT_SD_CARD); //Initializes SD card plug-in
 366  int ret = -1;
 367  ret = app2ext_deinit(handle); // De-initializes the SD plugin
 368  if(!ret)
 369  {
 370          printf("\n SUCCESS");
 371  }
 372  else
 373  printf("\n FAILURE");
 374  @endcode
 375  */
 376 API int app2ext_deinit(app2ext_handle *handle);
 377
 378 /**
 379  * @brief : This API returns the application location
 380  *                      by refering to package manager DB
 381  *          This should be called to know location of an application
 382  * @param[in] appname   name of the application
 383  * @return      APP2EXT_SD_CARD if app is in SD card,
 384  *              APP2EXT_INTERNAL_MEM if app is in internal memory
 385  *              error code(>0) if fail
 386  *@remarks see app2ext_install_location for more details
 387  @code
 388  #include <app2ext_interface.h>
 389 int ret = -1;
 390
 391 ret = app2ext_get_app_location("com.samsung.calculator");
 392 if (ret == APP2EXT_SD_CARD) {
 393         printf("\n app is in sd card ");
 394 } else if (ret == APP2EXT_INTERNAL_MEM) {
 395         printf("\n app is in internal memory ");
 396 } else {
 397         printf("\napp is not installed");
 398 }
 399  @endcode
 400  */
 401 API int app2ext_get_app_location(const char *appname);
 402
 403 /**
 404  * @brief : This API enable the package which is located in external memory
 405  * @param[in] pkgid     package id
 406  * @return      error < 0  if pkg enable fail ,
 407  @code
 408  #include <app2ext_interface.h>
 409 int ret = -1;
 410
 411 ret = app2ext_enable_external_pkg("com.samsung.calculator");
 412 if (ret < 0) {
 413         printf("\n pkg is not enabled ");
 414 } else {
 415         printf("\n pkg is enabled ");
 416 }
 417  @endcode
 418  */
 419 API int app2ext_enable_external_pkg(const char *pkgid);
 420
 421 /**
 422  * @brief : This API disable the package which is located in external memory
 423  * @param[in] pkgid     package id
 424  * @return      error < 0  if pkg enable fail ,
 425  @code
 426  #include <app2ext_interface.h>
 427 int ret = -1;
 428
 429 ret = app2ext_disable_external_pkg("com.samsung.calculator");
 430 if (ret < 0) {
 431         printf("\n pkg is not enabled ");
 432 } else {
 433         printf("\n pkg is enabled ");
 434 }
 435  @endcode
 436  */
 437 API int app2ext_disable_external_pkg(const char *pkgid);
 438
 439 /**
 440  * @brief : This API enable the directory which has package that is located in external memory
 441  * @return      error < 0  if pkg enable fail ,
 442  @code
 443  #include <app2ext_interface.h>
 444 int ret = -1;
 445
 446 ret = app2ext_enable_external_dir();
 447 if (ret < 0) {
 448         printf("\n app2sd dir is not enabled ");
 449 } else {
 450         printf("\n app2sd dir is enabled ");
 451 }
 452  @endcode
 453  */
 454 API int app2ext_enable_external_dir(void);
 455
 456 /**
 457  * @brief : This API disable the directory which has package that is located in external memory
 458  * @return      error < 0  if pkg enable fail ,
 459  @code
 460  #include <app2ext_interface.h>
 461 int ret = -1;
 462
 463 ret = app2ext_enable_external_dir();
 464 if (ret < 0) {
 465         printf("\n app2sd dir is not enabled ");
 466 } else {
 467         printf("\n app2sd dir is enabled ");
 468 }
 469  @endcode
 470  */
 471 API int app2ext_disable_external_dir(void);
 472
 473 #ifdef __cplusplus
 474 }
 475 #endif
 476 #endif