4 * Copyright (c) 2012 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Jyotsna Dhumale <jyotsna.a@samsung.com>
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #ifndef __APP2EXT_INTERFACE_H__
23 #define __APP2EXT_INTERFACE_H__
26 * @file app2ext_interface.h
28 * @brief This file declares API of app2ext library
32 * @addtogroup APPLICATION_FRAMEWORK
38 * @section Header to use them:
40 * #include <app2ext_interface.h>
50 #define API __attribute__ ((visibility("default")))
56 * Enum for application installation location
58 typedef enum app2ext_install_location_t {
59 APP2EXT_INTERNAL_MEM = 0,
64 } app2ext_install_location;
67 * Enum for installation/upgrade status[success/failure]
69 typedef enum app2ext_status_t {
70 APP2EXT_STATUS_FAILED = 1,
71 APP2EXT_STATUS_SUCCESS
75 * Enum for directory type
77 typedef enum app2ext_dir_type_t {
83 * Enum for move command
84 * @see app2sd_move_installed_app()
86 typedef enum app2ext_move_type_t {
87 APP2EXT_MOVE_TO_EXT = 1,
88 APP2EXT_MOVE_TO_PHONE,
92 * Enum for command type
93 * @see app2sd_move_installed_app()
95 typedef enum app2sd_cmd_t {
96 APP2SD_PRE_INSTALL = 1,
99 APP2SD_POST_UNINSTALL,
103 APP2SD_APP_TERMINATE,
104 APP2SD_MOVE_APP_TO_MMC,
105 APP2SD_MOVE_APP_TO_PHONE,
106 APP2SD_MIGRATE_LEGACY
110 * Enum for error codes
112 typedef enum app2ext_error_t {
113 APP2EXT_ERROR_INVALID_ARGUMENTS = 2,
115 APP2EXT_ERROR_PRE_UNINSTALL,
116 APP2EXT_ERROR_MMC_STATUS,
117 APP2EXT_ERROR_DB_INITIALIZE,
118 APP2EXT_ERROR_SQLITE_REGISTRY,
119 APP2EXT_ERROR_PASSWD_GENERATION,
120 APP2EXT_ERROR_MMC_INFORMATION,
121 APP2EXT_ERROR_MMC_INSUFFICIENT_MEMORY,
122 APP2EXT_ERROR_DELETE_DIRECTORY,
123 APP2EXT_ERROR_CREATE_SYMLINK,
124 APP2EXT_ERROR_CREATE_DIRECTORY,
125 APP2EXT_ERROR_DELETE_LINK_FILE,
126 APP2EXT_ERROR_PKG_EXISTS,
127 APP2EXT_ERROR_ACCESS_FILE,
128 APP2EXT_ERROR_OPEN_DIR,
129 APP2EXT_ERROR_ALREADY_FILE_PRESENT,
130 APP2EXT_ERROR_FILE_ABSENT,
131 APP2EXT_ERROR_STRCMP_FAILED,
132 APP2EXT_ERROR_INVALID_PACKAGE,
133 APP2EXT_ERROR_CREATE_DIR_ENTRY,
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,
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_KILLAPP_ERROR,
161 APP2EXT_ERROR_NOENTRY,
162 #ifdef TIZEN_FEATURE_APP2SD_DMCRYPT_ENCRYPTION
163 APP2EXT_ERROR_SETUP_DMCRYPT_DEVICE,
164 APP2EXT_ERROR_OPEN_DMCRYPT_DEVICE,
165 APP2EXT_ERROR_CLOSE_DMCRYPT_DEVICE,
166 APP2EXT_ERROR_FIND_ASSOCIATED_DMCRYPT_DEVICE_NODE,
167 APP2EXT_ERROR_DMCRYPT_DEVICE_UNAVAILABLE,
169 APP2EXT_ERROR_ENUM_MAX
173 * @brief : This function type is for a function that is implemented by plugin
174 * and called before application is to be installed.
176 * @param[in] appname application package name which is to be installed
177 * @param[in] dir_list directory structure of the application
178 * This should be polulated by the package manager
179 * before calling pre_install and should be freed after
180 * pre_install returns.
181 * Each node of dir_list is of type app2ext_dir_details
182 * which has members Name(dirname) and Type (RO/RW)
183 * For eg for rpm the dir_list should be populated with
184 * nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
185 * (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
186 * @param[in] size Size of the application
187 * @return 0 if success, error code(>0) if fail
189 typedef int (*app2ext_client_usr_pre_install)(const char *appname, GList* dir_list,
190 int size, uid_t uid);
191 typedef int (*app2ext_client_pre_install)(const char *appname, GList* dir_list,
195 * @brief : This function type is for a function that is implemented by plugin
196 * and called after application installation.
198 * @param[in] appname application package name which is to be installed
199 * @param[in] install_status Installation status (Success/Failure)
200 * [ Enum :APP2EXT_STATUS_SUCCESS,
201 * APP2EXT_STATUS_FAILED]
202 * @return 0 if success, error code(>0) if fail
204 typedef int (*app2ext_client_usr_post_install)(const char *appname,
205 app2ext_status install_status, uid_t uid);
206 typedef int (*app2ext_client_post_install)(const char *appname,
207 app2ext_status install_status);
210 * @brief : This function type is for a function that is implemented by plugin
211 * and called before application upgrade.
213 * @param[in] appname application package name which is to be upgraded
214 * @param[in] dir_list directory structure of the application
215 * This should be polulated by the package manager
216 * before calling pre_upgrade and should be freed after
217 * pre_upgrade returns.
218 * Each node of dir_list is of type app2ext_dir_details
219 * which has members Name(dirname) and Type (RO/RW)
220 * For eg for rpm the dir_list should be populated with
221 * nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
222 * (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
223 * @param[in] size Size of the application
224 * @return 0 if success, error code(>0) if fail
226 typedef int (*app2ext_client_usr_pre_upgrade)(const char *appname, GList* dir_list,
227 int size, uid_t uid);
228 typedef int (*app2ext_client_pre_upgrade)(const char *appname, GList* dir_list,
232 * @brief : This function type is for a function that is implemented by plugin
233 * and called before application upgradation.
235 * @param[in] appname application package name which is to be upgraded
236 * @param[in] upgrade_status Upgrade status (Success/Failure)
237 * [ Enum :APP2EXT_STATUS_SUCCESS,
238 * APP2EXT_STATUS_FAILED]
239 * @return 0 if success, error code(>0) if fail
241 typedef int (*app2ext_client_usr_post_upgrade)(const char *appname,
242 app2ext_status upgrade_status, uid_t uid);
243 typedef int (*app2ext_client_post_upgrade)(const char *appname,
244 app2ext_status upgrade_status);
247 * @brief : This function type is for a function that is implemented by plugin
248 * and called before application uninstallation.
250 * @param[in] appname application package name which is to be uninstalled
251 * @return 0 if success, error code(>0) if fail
253 typedef int (*app2ext_client_usr_pre_uninstall)(const char *appname, uid_t uid);
254 typedef int (*app2ext_client_pre_uninstall)(const char *appname);
257 * @brief : This function type is for a function that is implemented by plugin
258 * and called after application uninstallation.
260 * @param[in] appname application package name which is to be uninstalled
261 * @return 0 if success, error code(>0) if fail
263 typedef int (*app2ext_client_usr_post_uninstall)(const char *appname, uid_t uid);
264 typedef int (*app2ext_client_post_uninstall)(const char *appname);
267 * @brief : This function type is for a function that is implemented by plugin
268 * and called when application is to be moved from extrenal memory
269 *to internal memory or vice versa.
271 * @param[in] appname application package name which is to be moved
272 * @param[in] dir_list directory structure of the application
273 * This should be polulated by the package manager
274 * before calling move and should be freed after
276 * Each node of dir_list is of type app2ext_dir_details
277 * which has members Name(dirname) and Type (RO/RW)
278 * For eg for rpm the dir_list should be populated with
279 * nodes like : (lib, APP2EXT_DIR_RO), (res, APP2EXT_DIR_RO),
280 * (bin, APP2EXT_DIR_RO), (data, APP2EXT_DIR_RW)
281 * @param[in] move_type move type
282 * [Enum: APP2EXT_MOVE_TO_EXT, APP2EXT_MOVE_TO_PHONE]
283 * @return 0 if success, error code(>0) if fail
285 typedef int (*app2ext_client_usr_pre_move)(const char *appname, GList* dir_list,
286 app2ext_move_type move_type, uid_t uid);
287 typedef int (*app2ext_client_pre_move)(const char *appname, GList* dir_list,
288 app2ext_move_type move_type);
289 typedef int (*app2ext_client_usr_post_move)(const char *appname,
290 app2ext_move_type move_type, uid_t uid);
291 typedef int (*app2ext_client_post_move)(const char *appname,
292 app2ext_move_type move_type);
295 * @brief : This function type is for a function that is implemented by plugin
296 * and called to enable application before application launch.
298 * @param[in] appname application package name which is to be enabled
299 * @return 0 if success, error code(>0) if fail
301 typedef int (*app2ext_client_usr_enable)(const char *appname, uid_t uid);
302 typedef int (*app2ext_client_enable)(const char *appname);
305 * @brief : This function type is for a function that is implemented by plugin
306 * and called to enable/disable entire application packages.
308 * @return 0 if success, error code(>0) if fail
310 typedef int (*app2ext_client_enable_full_pkg)(void);
311 typedef int (*app2ext_client_disable_full_pkg)(void);
314 * @brief : This function type is for a function that is implemented by plugin
315 * and called to disable application before application exit.
317 * @param[in] appname application package name which is to be disabled
318 * @return 0 if success, error code(>0) if fail
320 typedef int (*app2ext_client_usr_disable)(const char *appname, uid_t uid);
321 typedef int (*app2ext_client_disable)(const char *appname);
324 * @brief : This function type is for a function that is implemented by plugin
325 * and called after application uninstallation.
327 * @param[in] pkgid application package name which is to be uninstalled
328 * @return 0 if success, error code(>0) if fail
330 typedef int (*app2ext_client_usr_force_clean)(const char *pkgid, uid_t uid);
331 typedef int (*app2ext_client_force_clean)(const char *pkgid);
334 * @brief : This function type is for a function that is implemented by plugin
335 * and called before migration of legacy mount image.
337 * @param[in] pkgid application package name which is to be migrated
338 * @return 0 if success, error code(>0) if fail
340 typedef int (*app2ext_client_usr_pre_migrate_legacy)(const char *pkgid,
344 * @brief : This function type is for a function that is implemented by plugin
345 * and called after migration of legacy mount image.
347 * @param[in] pkgid application package name which is to be migrated
348 * @return 0 if success, error code(>0) if fail
350 typedef int (*app2ext_client_usr_post_migrate_legacy)(const char *pkgid,
354 * @brief : This function type is for a function that is implemented by plugin
355 * and called to migrate legacy mount image.
357 * @param[in] pkgid application package name which is to be migrated
358 * @return 0 if success, error code(>0) if fail
360 typedef int (*app2ext_client_migrate_legacy_all)(void);
363 * @brief : This function type is for a function that is implemented by plugin
364 * and called to get the external image name.
366 * @param[in] pkgid application package name
367 * @param[in] uid target user id
368 * @return the name of external image
369 * @remark the name should be freed after the use.
371 typedef char *(*app2ext_client_usr_getname_image)(const char *pkgid,
375 * @brief : This function type is for a function that is implemented by plugin
376 * and called to get the external image path.
378 * @param[in] pkgid application package name
379 * @param[in] uid target user id
380 * @return the path of external image
381 * @remark the path should be freed after the use.
383 typedef char *(*app2ext_client_usr_get_image_path)(const char *pkgid,
387 * This structure defines the app2ext interfaces.
388 * Plugins have to implement these functions
390 typedef struct app2ext_interface_t {
391 /* for library function */
392 app2ext_client_pre_install client_pre_install;
393 app2ext_client_post_install client_post_install;
394 app2ext_client_pre_upgrade client_pre_upgrade;
395 app2ext_client_post_upgrade client_post_upgrade;
396 app2ext_client_pre_uninstall client_pre_uninstall;
397 app2ext_client_post_uninstall client_post_uninstall;
398 app2ext_client_force_clean client_force_clean;
399 app2ext_client_enable client_enable;
400 app2ext_client_disable client_disable;
401 app2ext_client_enable_full_pkg client_enable_full_pkg;
402 app2ext_client_disable_full_pkg client_disable_full_pkg;
403 app2ext_client_pre_move client_pre_move;
404 app2ext_client_post_move client_post_move;
405 app2ext_client_migrate_legacy_all client_migrate_legacy_all;
407 app2ext_client_usr_pre_install client_usr_pre_install;
408 app2ext_client_usr_post_install client_usr_post_install;
409 app2ext_client_usr_pre_upgrade client_usr_pre_upgrade;
410 app2ext_client_usr_post_upgrade client_usr_post_upgrade;
411 app2ext_client_usr_pre_uninstall client_usr_pre_uninstall;
412 app2ext_client_usr_post_uninstall client_usr_post_uninstall;
413 app2ext_client_usr_force_clean client_usr_force_clean;
414 app2ext_client_usr_enable client_usr_enable;
415 app2ext_client_usr_disable client_usr_disable;
416 app2ext_client_usr_pre_move client_usr_pre_move;
417 app2ext_client_usr_post_move client_usr_post_move;
418 app2ext_client_usr_getname_image client_usr_getname_image;
419 app2ext_client_usr_pre_migrate_legacy client_usr_pre_migrate_legacy;
420 app2ext_client_usr_post_migrate_legacy client_usr_post_migrate_legacy;
421 app2ext_client_usr_get_image_path client_usr_get_image_path;
425 * This structure defines app2ext handle .Each storage type maps to a different plugin
426 * type : storage type,
427 * plugin_handle : plugin handle, need to close dlopen handle
428 * interface : inteface with plugin library
431 app2ext_install_location type;
433 app2ext_interface interface;
437 * This structure defines directory details
438 * name : directory name
439 * type : permission (rw/ro)
443 app2ext_dir_type type;
444 } app2ext_dir_details;
447 * @brief : This API initializes the appropriate plugin based on storage type.
448 * It should be called before installation/uninstallation/upgrade
449 * @param[in] storage_type Location where package should be installed
450 * [Ex: SD card, MicroUSB, Cloud]
451 * @return app2ext_handle pointer if success, NULL if fail
454 API app2ext_handle *app2ext_init(int storage_type);
457 * @brief : This API deinitializes the plugin
458 * This should be called when use of the plugin is completed
459 * @param[in] handle pointer to app2ext_handle which is to be deinitialized
460 * @pre Initialization is done for the storage handle
461 * @return 0 if success, error < 0 if fail
464 API int app2ext_deinit(app2ext_handle *handle);
467 * @brief : This API enable the package which is located in external memory
468 * @param[in] pkgid package id
469 * @param[in] uid target user id of this instruction
470 * @return error < 0 if pkg enable fail
472 API int app2ext_enable_external_pkg(const char *pkgid);
473 API int app2ext_usr_enable_external_pkg(const char *pkgid, uid_t uid);
476 * @brief : This API disable the package which is located in external memory
477 * @param[in] pkgid package id
478 * @param[in] uid target user id of this instruction
479 * @return error < 0 if pkg disable fail
481 API int app2ext_disable_external_pkg(const char *pkgid);
482 API int app2ext_usr_disable_external_pkg(const char *pkgid, uid_t uid);
485 * @brief : This API clean the directory and symbolic link which are made by app2ext
486 * @param[in] pkgid package id
487 * @param[in] uid target user id of this instruction
488 * @return error < 0 if pkg clean fail
490 API int app2ext_force_clean_pkg(const char *pkgid);
491 API int app2ext_usr_force_clean_pkg(const char *pkgid, uid_t uid);
494 * @brief : This API mount/unmount all entries which are located in external memory
495 * @return error < 0 if fail to start enable/disable
497 API int app2ext_enable_all_external_pkgs(void);
498 API int app2ext_disable_all_external_pkgs(void);
501 * @brief : This API migrate all legacy entries which are located in external memory
502 * @return error < 0 if fail to migrate legacy
504 API int app2ext_migrate_legacy_all(void);
507 * @brief : This API get the external image name
508 * @param[in] pkgid application package name
509 * @param[in] uid target user id
510 * @return the name of external image
511 * @remark the name should be freed after the use.
513 API char *app2ext_usr_getname_image(const char *pkgid, uid_t uid);
516 * @brief : This API get the external image path
517 * @param[in] pkgid application package name
518 * @param[in] uid target user id
519 * @return the path of external image
520 * @remark the path should be freed after the use.
522 API char *app2ext_usr_get_image_path(const char *pkgid, uid_t uid);