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 #ifdef LOG_TAG
  55 #undef LOG_TAG
  56 #endif
  57
  58 #define LOG_TAG "APP2EXT"
  59
  60 #ifdef _DEBUG_MODE_
  61 #define app2ext_print(fmt, arg...) LOGD(fmt,##arg)
  62 #else
  63 #define app2ext_print(FMT, ARG...) SLOGD(FMT,##ARG);
  64 #endif
  65
  66 #define APP2EXT_SUCCESS 0
  67 #define MMC_PATH "/opt/storage/sdcard"
  68 #define APP2SD_PATH MMC_PATH"/app2sd/"
  69 #define APP_INSTALLATION_PATH "/opt/usr/apps/"
  70
  71 /**
  72  * Enum for application installation location
  73  */
  74 typedef enum app2ext_install_location_t {
  75         APP2EXT_INTERNAL_MEM = 0,
  76         APP2EXT_SD_CARD,
  77         APP2EXT_MICRO_USB,
  78         APP2EXT_CLOUD,
  79         APP2EXT_NOT_INSTALLED
  80 } app2ext_install_location;
  81
  82 /**
  83  * Enum for installation/upgrade status[success/failure]
  84  */
  85 typedef enum app2ext_status_t {
  86         APP2EXT_STATUS_FAILED = 1,
  87         APP2EXT_STATUS_SUCCESS
  88 } app2ext_status;
  89
  90 /**
  91  * Enum for directory type
  92  */
  93 typedef enum app2ext_dir_type_t {
  94         APP2EXT_DIR_RO,
  95         APP2EXT_DIR_RW,
  96 } app2ext_dir_type;
  97
  98 /**
  99  * Enum for move command
 100  * @see app2sd_move_installed_app()
 101  */
 102 typedef enum app2ext_move_type_t {
 103         APP2EXT_MOVE_TO_EXT = 1,
 104         APP2EXT_MOVE_TO_PHONE
 105 } app2ext_move_type;
 106
 107 /**
 108  * Enum for error codes
 109  */
 110 typedef enum app2ext_error_t {
 111         APP2EXT_ERROR_INVALID_ARGUMENTS = 2,
 112         APP2EXT_ERROR_MOVE,
 113         APP2EXT_ERROR_PRE_UNINSTALL,
 114         APP2EXT_ERROR_MMC_STATUS,
 115         APP2EXT_ERROR_DB_INITIALIZE,
 116         APP2EXT_ERROR_SQLITE_REGISTRY,
 117         APP2EXT_ERROR_PASSWD_GENERATION,
 118         APP2EXT_ERROR_MMC_INFORMATION,
 119         APP2EXT_ERROR_MMC_INSUFFICIENT_MEMORY,
 120         APP2EXT_ERROR_DELETE_DIRECTORY,
 121         APP2EXT_ERROR_CREATE_SYMLINK,
 122         APP2EXT_ERROR_CREATE_DIRECTORY,
 123         APP2EXT_ERROR_DELETE_LINK_FILE,
 124         APP2EXT_ERROR_PKG_EXISTS,
 125         APP2EXT_ERROR_ACCESS_FILE,
 126         APP2EXT_ERROR_OPEN_DIR,
 127         APP2EXT_ERROR_ALREADY_FILE_PRESENT,
 128         APP2EXT_ERROR_FILE_ABSENT,
 129         APP2EXT_ERROR_STRCMP_FAILED,
 130         APP2EXT_ERROR_INVALID_PACKAGE,
 131         APP2EXT_ERROR_CREATE_DIR_ENTRY,
 132         APP2EXT_ERROR_PASSWORD_GENERATION,
 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;
 155
 156 /**
 157  * @brief :This function type is for a function that is implemented by plugin
 158  * and called before application is to be installed.
 159  *
 160  * @param[in]   appname         application package name which is to be installed
 161  * @param[in]   dir_list        directory structure of the application
 162  *                              This should be polulated by the package manager
 163  *                              before calling pre_install and should be freed after
 164  *                              pre_install returns.
 165  *                              Each node of dir_list is of type app2ext_dir_details
 166  *                              which has members Name(dirname) and Type (RO/RW)
 167  *                              For eg for rpm the dir_list should be populated with
 168  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 169                                 (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 170  * @param[in]   size            Size of the application
 171  * @return      0 if success,  error code(>0) if fail
 172  */
 173 typedef int (*app2ext_pre_install)(const char *appname, GList* dir_list, int size);
 174
 175 /**
 176  * @brief :This function type is for a function that is implemented by plugin
 177  * and called after application installation.
 178  *
 179  * @param[in]   appname         application package name which is to be installed
 180  * @param[in]   install_status  Installation status (Success/Failure)
 181  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 182  *                                      APP2EXT_STATUS_FAILED]
 183  * @return      0 if success,  error code(>0) if fail
 184  */
 185 typedef int (*app2ext_post_install)(const char *appname, app2ext_status install_status);
 186
 187 /**
 188  * @brief :This function type is for a function that is implemented by plugin
 189  * and called before application upgrade.
 190  *
 191  * @param[in]   appname         application package name which is to be upgraded
 192  * @param[in]   dir_list        directory structure of the application
 193  *                              This should be polulated by the package manager
 194  *                              before calling pre_upgrade and should be freed after
 195  *                              pre_upgrade returns.
 196  *                              Each node of dir_list is of type app2ext_dir_details
 197  *                              which has members Name(dirname) and Type (RO/RW)
 198  *                              For eg for rpm the dir_list should be populated with
 199  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 200                                 (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 201  * @param[in]   size            Size of the application
 202  * @return      0 if success,  error code(>0) if fail
 203  */
 204 typedef int (*app2ext_pre_upgrade)(const char *appname, GList* dir_list, int size);
 205
 206 /**
 207  * @brief :This function type is for a function that is implemented by plugin
 208  * and called before application upgradation.
 209  *
 210  * @param[in]   appname         application package name which is to be upgraded
 211  * @param[in]   upgrade_status  Upgrade status (Success/Failure)
 212  *                              [ Enum :APP2EXT_STATUS_SUCCESS,
 213  *                                      APP2EXT_STATUS_FAILED]
 214  * @return      0 if success,  error code(>0) if fail
 215  */
 216 typedef int (*app2ext_post_upgrade)(const char *appname, app2ext_status upgrade_status);
 217
 218 /**
 219  * @brief :This function type is for a function that is implemented by plugin
 220  * and called before application uninstallation.
 221  *
 222  * @param[in]   appname         application package name which is to be uninstalled
 223  * @return      0 if success,  error code(>0) if fail
 224  */
 225 typedef int (*app2ext_pre_uninstall)(const char *appname);
 226
 227 /**
 228  * @brief :This function type is for a function that is implemented by plugin
 229  * and called after application uninstallation.
 230  *
 231  * @param[in]   appname         application package name which is to be uninstalled
 232  * @return      0 if success,  error code(>0) if fail
 233  */
 234 typedef int (*app2ext_post_uninstall)(const char *appname);
 235
 236 /**
 237  * @brief :This function type is for a function that is implemented by plugin
 238  * and called when application is to be moved from extrenal memory
 239  *to internal memory or vice versa.
 240  *
 241  * @param[in]   appname         application package name which is to be moved
 242  * @param[in]   dir_list        directory structure of the application
 243  *                              This should be polulated by the package manager
 244  *                              before calling move and should be freed after
 245  *                              move returns.
 246  *                              Each node of dir_list is of type app2ext_dir_details
 247  *                              which has members Name(dirname) and Type (RO/RW)
 248  *                              For eg for rpm the dir_list should be populated with
 249  *                              nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
 250                                 (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
 251  * @param[in]   move_type       move type
 252  *                              [Enum: APP2EXT_MOVE_TO_EXT, APP2EXT_MOVE_TO_PHONE]
 253  * @return      0 if success,  error code(>0) if fail
 254  */
 255 typedef int (*app2ext_move)(const char *appname, GList* dir_list, app2ext_move_type move_type);
 256
 257 /**
 258  * @brief :This function type is for a function that is implemented by plugin
 259  * and called to enable application before application launch.
 260  *
 261  * @param[in]   appname         application package name which is to be enabled
 262  * @return      0 if success,  error code(>0) if fail
 263  */
 264 typedef int (*app2ext_enable)(const char *appname);
 265
 266 /**
 267  * @brief :This function type is for a function that is implemented by plugin
 268  * and called to disable application before application exit.
 269  *
 270  * @param[in]   appname         application package name which is to be disabled
 271  * @return      0 if success,  error code(>0) if fail
 272  */
 273 typedef int (*app2ext_disable)(const char *appname);
 274
 275 /**
 276  * This structure defines the app2ext interfaces. Plugins have to implement these functions
 277  */
 278 typedef struct app2ext_interface_t{
 279         app2ext_pre_install             pre_install;
 280         app2ext_post_install            post_install;
 281         app2ext_pre_upgrade             pre_upgrade;
 282         app2ext_post_upgrade            post_upgrade;
 283         app2ext_pre_uninstall           pre_uninstall;
 284         app2ext_post_uninstall          post_uninstall;
 285         app2ext_move                    move;
 286         app2ext_enable                  enable;
 287         app2ext_disable                 disable;
 288 } app2ext_interface;
 289
 290 /**
 291  * This structure defines app2ext handle .Each storage type maps to a different plugin
 292  * type                         : storage type
 293  * plugin_handle                        : plugin handle
 294  */
 295 typedef struct {
 296         app2ext_install_location        type;
 297         void                    *plugin_handle;
 298         app2ext_interface               interface;
 299 } app2ext_handle;
 300
 301 /**
 302  * This structure defines directory details
 303  * name                 : directory name
 304  * type                 : permission (rw/ro)
 305  */
 306 typedef struct {
 307         char *          name;
 308         app2ext_dir_type        type;
 309 } app2ext_dir_details;
 310
 311 /**
 312  * @brief : This API initializes the appropriate plugin based on storage type.
 313  *      It should be called before installation/uninstallation/upgrade
 314  * @param[in] storage_type      Location where package should be installed
 315  *                              [Ex: SD card, MicroUSB, Cloud]
 316  * @return      app2ext_handle pointer if success, NULL if fail
 317  *
 318  @code
 319  #include <app2ext_interface.h>
 320  app2ext_handle *handle = NULL;
 321  GLIst *dir_list = NULL;
 322  handle = app2ext_init(APP2EXT_SD_CARD); //Initializes SD card plug-in
 323  if(handle)
 324  {
 325         printf("\n SUCCESS");
 326         // Perform package install/uninstall/upgrade/move here
 327         // Packge install example
 328         // Package manager should polulate dir_list with directory structure information of the package
 329         ret = handle->interface.pre_install("com.samsung.calculator", dir_list, 20);
 330         if (ret) {
 331                 printf("\n TC : pre app install API fail. Reason %s", error_list[ret]);
 332                 return -1;
 333         }
 334
 335         // Package manager installs the package
 336
 337         ret = handle->interface.post_install("com.samsung.calculator", APP2EXT_STATUS_SUCCESS);
 338         if (ret) {
 339                 printf("\n TC : post app install API fail Reason %s", error_list[ret]);
 340
 341                 return -1;
 342         }
 343         // Package manager should free dir_list
 344         return;
 345  } else
 346          printf("\n FAILURE");
 347  @endcode
 348  */
 349 API app2ext_handle *app2ext_init(int storage_type);
 350
 351 /**
 352  * @brief : This API deinitializes the plugin
 353  *          This should be called when use of the plugin is completed
 354  * @param[in] handle    pointer to app2ext_handle which is to be deinitialized
 355  * @pre         Initialization is done for the storage handle
 356  * @return      0 if success,  error code(>0) if fail
 357  *
 358  @code
 359  #include <app2ext_interface.h>
 360  app2ext_handle *handle = NULL;
 361  handle = app2ext_init(APP2EXT_SD_CARD); //Initializes SD card plug-in
 362  int ret = -1;
 363  ret = app2ext_deinit(handle); // De-initializes the SD plugin
 364  if(!ret)
 365  {
 366          printf("\n SUCCESS");
 367  }
 368  else
 369  printf("\n FAILURE");
 370  @endcode
 371  */
 372 API int app2ext_deinit(app2ext_handle *handle);
 373
 374 /**
 375  * @brief : This API returns the application location
 376  *                      by refering to package manager DB
 377  *          This should be called to know location of an application
 378  * @param[in] appname   name of the application
 379  * @return      APP2EXT_SD_CARD if app is in SD card,
 380  *              APP2EXT_INTERNAL_MEM if app is in internal memory
 381  *              error code(>0) if fail
 382  *@remarks see app2ext_install_location for more details
 383  @code
 384  #include <app2ext_interface.h>
 385 int ret = -1;
 386
 387 ret = app2ext_get_app_location("com.samsung.calculator");
 388 if (ret == APP2EXT_SD_CARD) {
 389         printf("\n app is in sd card ");
 390 } else if (ret == APP2EXT_INTERNAL_MEM) {
 391         printf("\n app is in internal memory ");
 392 } else {
 393         printf("\napp is not installed");
 394 }
 395  @endcode
 396  */
 397 API int app2ext_get_app_location(const char *appname);
 398
 399 #ifdef __cplusplus
 400 }
 401 #endif
 402 #endif