X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=0b46a8cc0ce216186a744ca083f2348b521b2217;hp=1de5d045801bb5eeb09300a748c1a8d9e932cc6b;hb=63b76b34c79107cba091d1ea62e304d2666ec86d;hpb=7bde3fc590afbdef8f71cd7f8ccbd24172bffc63 diff --git a/src/wimlib.h b/src/wimlib.h index 1de5d045..0b46a8cc 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2012 Eric Biggers + * Copyright (C) 2012, 2013 Eric Biggers * * This file is part of wimlib, a library for working with WIM files. * @@ -31,9 +31,11 @@ * * \section intro Introduction * - * This is the documentation for the library interface of wimlib 1.2.5. If you + * This is the documentation for the library interface of wimlib 1.2.7. If you * have installed wimlib and want to know how to use the @c imagex program, - * please see the man pages instead. + * please see the man pages instead. Also: the actual project page where you + * can download the source code for the library is at https://sourceforge.net/projects/wimlib. * * wimlib is a C library to read, write, and mount archive files in the Windows * Imaging Format (WIM files). These files are normally created using the @c @@ -117,8 +119,14 @@ * message being printed. * * wimlib is thread-safe as long as different ::WIMStruct's are used, except for - * the fact that wimlib_set_print_errors() and wimlib_set_memory_allocator() - * both apply globally. + * the following exceptions: + * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally. + * - You also must call wimlib_global_init() in the main thread to avoid any + * race conditions with one-time allocations of memory. + * - wimlib_mount_image(), while it can be used to mount multiple WIMs + * concurrently in the same process, will daemonize the entire process when it + * does so for the first time. This includes changing the working directory + * to the root directory. * * To open an existing WIM, use wimlib_open_wim(). * @@ -215,9 +223,14 @@ #include #include +/** Major version of the library (for example, the 1 in 1.2.5). */ #define WIMLIB_MAJOR_VERSION 1 + +/** Minor version of the library (for example, the 2 in 1.2.5). */ #define WIMLIB_MINOR_VERSION 2 -#define WIMLIB_PATCH_VERSION 5 + +/** Patch version of the library (for example, the 5 in 1.2.5). */ +#define WIMLIB_PATCH_VERSION 7 /** * Opaque structure that represents a WIM file. This is an in-memory structure @@ -403,6 +416,11 @@ union wimlib_progress_info { /** True iff @a cur_path is being excluded from the image * capture due to the capture configuration file. */ bool excluded; + + /** Target path in the WIM. Only valid on messages + * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and + * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ + const char *wim_target_path; } scan; /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, @@ -541,12 +559,30 @@ union wimlib_progress_info { typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, const union wimlib_progress_info *info); +/** An array of these structures is passed to wimlib_add_image_multisource() to + * specify the sources from which to create a WIM image. */ +struct wimlib_capture_source { + /** Absolute or relative path to a file or directory on the external + * filesystem to be included in the WIM image. */ + char *fs_source_path; + + /** Destination path in the WIM image. Leading and trailing slashes are + * ignored. The empty string or @c NULL means the root directory of the + * WIM image. */ + char *wim_target_path; + + /** Reserved; set to 0. */ + long reserved; +}; + /***************************** * WIMLIB_ADD_IMAGE_FLAG_* * *****************************/ -/** Directly capture a NTFS volume rather than a generic directory */ +/** Directly capture a NTFS volume rather than a generic directory. This flag + * cannot be combined with ::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE or + * ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA. */ #define WIMLIB_ADD_IMAGE_FLAG_NTFS 0x00000001 /** Follow symlinks; archive and dump the files they point to. Cannot be used @@ -561,6 +597,14 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, /** Mark the image being added as the bootable image of the WIM. */ #define WIMLIB_ADD_IMAGE_FLAG_BOOT 0x00000008 +/** Store the UNIX owner, group, and mode. This is done by adding a special + * alternate data stream to each regular file, symbolic link, and directory to + * contain this information. Please note that this flag is for convenience + * only; Microsoft's version of imagex.exe will not understand this special + * information. This flag cannot be combined with ::WIMLIB_ADD_IMAGE_FLAG_NTFS. + * */ +#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA 0x00000010 + /****************************** * WIMLIB_EXPORT_FLAG_* * ******************************/ @@ -593,6 +637,10 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, /** Read the WIM file sequentially while extracting the image. */ #define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010 +/** Extract special UNIX data captured with ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA. + * Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */ +#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020 + /****************************** * WIMLIB_MOUNT_FLAG_* * ******************************/ @@ -614,6 +662,14 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, * file name, a colon, then the alternate file stream name. */ #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010 +/** Use UNIX file owners, groups, and modes if available in the WIM (see + * ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA). */ +#define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020 + +/** Allow other users to see the mounted filesystem. (this passes the @c + * allow_other option to FUSE mount) */ +#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 + /****************************** * WIMLIB_OPEN_FLAG_* * ******************************/ @@ -678,6 +734,9 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, * See the documentation for each wimlib function to see specifically what error * codes can be returned by a given function, and what they mean. */ +/* Note: these are currently in alphabetic order, but new error codes should be + * added at the end to maintain a compatible ABI, except when it's being broken + * anyway. */ enum wimlib_error_code { WIMLIB_ERR_SUCCESS = 0, WIMLIB_ERR_ALREADY_LOCKED, @@ -733,6 +792,7 @@ enum wimlib_error_code { WIMLIB_ERR_UNSUPPORTED, WIMLIB_ERR_WRITE, WIMLIB_ERR_XML, + WIMLIB_ERR_INVALID_OVERLAY, }; @@ -773,8 +833,8 @@ enum wimlib_error_code { * NULL, a default string is used. Please see the manual page for * imagex capture for more information. * @param config_len - * Length of the string @a config in bytes. Ignored if @a config is @c - * NULL. + * Length of the string @a config in bytes, not including an optional + * null-terminator. Ignored if @a config is @c NULL. * @param add_image_flags * Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG. * @param progress_func @@ -830,6 +890,37 @@ extern int wimlib_add_image(WIMStruct *wim, const char *source, size_t config_len, int add_image_flags, wimlib_progress_func_t progress_func); +/** This function is equivalent to wimlib_add_image() except it allows for + * multiple sources to be combined into a single WIM image. This is done by + * specifying the @a sources and @a num_sources parameters instead of the @a + * source parameter of wimlib_add_image(). The rest of the parameters are the + * same as wimlib_add_image(). See the documentation for imagex capture + * for full details on how this mode works. + * + * Additional note: @a sources is not a @c const parameter and you cannot + * assume that its contents are valid after this function returns. You must + * save pointers to the strings in these structures if you need to free them + * later, and/or save copies if needed. + * + * In addition to the error codes that wimlib_add_image() can return, + * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY + * when trying to overlay a non-directory on a directory or when otherwise + * trying to overlay multiple conflicting files to the same location in the WIM + * image. It will also return ::WIMLIB_ERR_INVALID_PARAM if + * ::WIMLIB_ADD_IMAGE_FLAG_NTFS was specified in @a add_image_flags but there + * was not exactly one capture source with the target being the root directory. + * (In this respect, there is no advantage to using + * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting + * NTFS mode.) */ +extern int wimlib_add_image_multisource(WIMStruct *w, + struct wimlib_capture_source *sources, + size_t num_sources, + const char *name, + const char *config_str, + size_t config_len, + int add_image_flags, + wimlib_progress_func_t progress_func); + /** * Creates a ::WIMStruct for a new WIM file. * @@ -1089,11 +1180,13 @@ extern int wimlib_export_image(WIMStruct *src_wim, int src_image, * invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM * @a target was @c NULL, or both ::WIMLIB_EXTRACT_FLAG_HARDLINK and - * ::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags, or + * ::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags; or * both ::WIMLIB_EXTRACT_FLAG_NTFS and either * ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK were - * specified in @a extract_flags, or ::WIMLIB_EXTRACT_FLAG_NTFS was - * specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES. + * specified in @a extract_flags; or ::WIMLIB_EXTRACT_FLAG_NTFS was + * specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES; or + * both ::WIMLIB_EXTRACT_FLAG_NTFS and ::WIMLIB_EXTRACT_FLAG_UNIX_DATA were + * specified in @a extract_flag. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH * The SHA1 message digest of an extracted stream did not match the SHA1 * message digest given in the WIM file. @@ -1292,8 +1385,8 @@ extern int wimlib_get_part_number(const WIMStruct *wim, int *total_parts_ret); * @retval ::WIMLIB_ERR_NOMEM * Could not allocate memory. * @retval ::WIMLIB_ERR_ICONV_NOT_AVAILABLE - * wimlib was configured --without-libntfs-3g at compilation time, and at - * runtime the iconv() set of functions did not seem to be available, + * wimlib was configured @c --without-libntfs-3g at compilation time, and + * at runtime the @c iconv() set of functions did not seem to be available, * perhaps due to missing files in the C library installation. * * If this function is not called or returns nonzero, then it will not be safe @@ -1376,7 +1469,7 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name); * Note: wimlib_export_image() can provide similar functionality to * wimlib_join(), since it is possible to export all images from a split WIM. */ -extern int wimlib_join(const char **swms, unsigned num_swms, +extern int wimlib_join(const char * const *swms, unsigned num_swms, const char *output_path, int swm_open_flags, int wim_write_flags, wimlib_progress_func_t progress_func); @@ -1384,9 +1477,8 @@ extern int wimlib_join(const char **swms, unsigned num_swms, /** * Mounts an image in a WIM file on a directory read-only or read-write. * - * The calling thread will be daemonized to service the filesystem, and this - * function will not return until the image is unmounted, unless an error occurs - * before the filesystem is successfully mounted. + * Unless ::WIMLIB_MOUNT_FLAG_DEBUG is specified or an early error occurs, the + * process shall be daemonized. * * If the mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), * modifications to the WIM are staged in a temporary directory. @@ -1456,7 +1548,7 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * @retval ::WIMLIB_ERR_INVALID_PARAM * @a image is shared among multiple ::WIMStruct's as a result of a call to * wimlib_export_image(), or @a image has been added with - * wimlib_add_image() or wimlib_add_image_from_ntfs_volume(). + * wimlib_add_image(). * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE * The metadata resource for @a image in @a wim is invalid. * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA @@ -2076,9 +2168,9 @@ extern int wimlib_unmount_image(const char *dir, int unmount_flags, * @a image does not specify a single existing image in @a wim, and is not * ::WIMLIB_ALL_IMAGES. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH - * A file that had previously been scanned for inclusion in the WIM by the - * wimlib_add_image() or wimlib_add_image_from_ntfs_volume() functions was - * concurrently modified, so it failed the SHA1 message digest check. + * A file that had previously been scanned for inclusion in the WIM by + * wimlib_add_image() was concurrently modified, so it failed the SHA1 + * message digest check. * @retval ::WIMLIB_ERR_INVALID_PARAM * @a path was @c NULL. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE