X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=132233ff4b3f8d6ebc18c60245bc4bee14f48133;hp=197f9b65320dd8fe25da8832ac14fcaca8bd2e42;hb=61ac5994e9fe3666d1c057dafca8c79406c59077;hpb=da295f258b60e1593de305385c0669eac4b76644 diff --git a/include/wimlib.h b/include/wimlib.h index 197f9b65..132233ff 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -1319,6 +1319,22 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * set the readonly flag on the on-disk WIM file. */ #define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100 +/** Do not include non-metadata resources already present in other WIMs. This + * flag can be used to write a "delta" WIM after resources from the WIM on which + * the delta is to be based were referenced with + * wimlib_reference_resource_files() or wimlib_reference_resources(). */ +#define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS 0x00000200 + +/** Asserts that for writes of all WIM images, all streams needed for the WIM + * are already present (not in external resource WIMs) and their reference + * counts are correct, so the code does not need to recalculate which streams + * are referenced. This is for optimization purposes only, since with this flag + * specified, the metadata resources may not need to be decompressed and parsed. + * + * This flag can be passed to wimlib_write() and wimlib_write_to_fd(), but is + * already implied for wimlib_overwrite(). */ +#define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 + /** * @name Init flags * @@ -1787,9 +1803,10 @@ wimlib_delete_image(WIMStruct *wim, int image); * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND * A resource that needed to be exported could not be found in either the * source or destination WIMs. This error can occur if, for example, @p - * src_wim is part of a split WIM but resources from the other split WIM - * parts were not referenced with wimlib_reference_resources() or - * wimlib_reference_resource_files(). + * src_wim is part of a split WIM but needed resources from the other split + * WIM parts were not referenced with wimlib_reference_resources() or + * wimlib_reference_resource_files() before the call to + * wimlib_export_image(). * @retval ::WIMLIB_ERR_WIM_IS_READONLY * @p dest_wim is considered read-only because of any of the reasons * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS @@ -2594,8 +2611,9 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * If non-NULL, a function that will be called periodically with the * progress of the current operation. * - * @return 0 on success; nonzero on error. This function may return any value - * returned by wimlib_write() as well as the following error codes: + * @return 0 on success; nonzero on error. This function may return most error + * codes returned by wimlib_write() as well as the following error codes: + * * @retval ::WIMLIB_ERR_ALREADY_LOCKED * The WIM was going to be modified in-place (with no temporary file), but * an exclusive advisory lock on the on-disk WIM file could not be acquired @@ -2717,18 +2735,17 @@ wimlib_reference_resource_files(WIMStruct *wim, * @param ref_flags * Currently ignored (set to 0). * - * @return 0 on success; nonzero on error. On success, the ::WIMStruct's - * specified in @p resource_wims should be considered "don't touch" until either - * wimlib_free() is called on @p wim, or wimlib_unreference_resources() is - * called to unreference them. + * @return 0 on success; nonzero on error. On success, the ::WIMStruct's of the + * @p resource_wims are referenced internally by @p wim and must not be freed + * with wimlib_free() or overwritten with wimlib_overwrite() until @p wim has + * been freed with wimlib_free(), or immediately before freeing @p wim with + * wimlib_free(). * * @retval ::WIMLIB_ERR_INVALID_PARAM * @p wim was @c NULL, or @p num_resource_wims was nonzero but @p - * resource_wims was @c NULL, or @p wim did not contain metadata resources, - * or an entry in @p resource_wims was @p NULL, or an entry in @p - * resource_wims was already referenced by a call to this function without - * a corresponding call to wimlib_free() on the metadata WIM, or - * wimlib_unreference_resources(). + * resource_wims was @c NULL, or an entry in @p resource_wims was @p NULL. + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate memory. */ extern int wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, @@ -2740,14 +2757,16 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, * intervening time. This is designed to be used in incremental backups of the * same filesystem or directory tree. * - * This function compares the directory tree of the newly added image against - * that of the old image. Any files that are present in both the newly added - * image and the old image and have timestamps that indicate they haven't been - * modified are deemed not to have been modified. Such files will not be read - * from the filesystem when the WIM is being written or overwritten. Note that - * these unchanged files will still be "archived" and will be logically present - * in the new image; the optimization is that they don't need to actually be - * read from the filesystem because the WIM already contains them. + * This function compares the metadata of the directory tree of the newly added + * image against that of the old image. Any files that are present in both the + * newly added image and the old image and have timestamps that indicate they + * haven't been modified are deemed not to have been modified and have their + * SHA1 message digest copied from the old image. Because of this and because + * WIM uses single-instance streams, such files need not be read from the + * filesystem when the WIM is being written or overwritten. Note that these + * unchanged files will still be "archived" and will be logically present in the + * new image; the optimization is that they don't need to actually be read from + * the filesystem because the WIM already contains them. * * This function is provided to optimize incremental backups. The resulting WIM * file will still be the same regardless of whether this function is called. @@ -2766,6 +2785,9 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, * 1-based index in the WIM of the newly added image. This image can have * been added with wimlib_add_image() or wimlib_add_image_multisource(), or * wimlib_add_empty_image() followed by wimlib_update_image(). + * @param template_wim + * The ::WIMStruct for the WIM containing the template image. This can be + * the same as @p wim, or it can be a different ::WIMStruct. * @param template_image * 1-based index in the WIM of a template image that reflects a prior state * of the directory tree being captured. @@ -2799,8 +2821,8 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, */ extern int wimlib_reference_template_image(WIMStruct *wim, int new_image, - int template_image, int flags, - wimlib_progress_func_t progress_func); + WIMStruct *template_wim, int template_image, + int flags, wimlib_progress_func_t progress_func); /** * Translates a string specifying the name or number of an image in the WIM into @@ -3113,30 +3135,6 @@ wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags, wimlib_progress_func_t progress_func); -/** - * Unreferences resources previously referenced with - * wimlib_reference_resources(). - * - * Calling this is not necessary (or even possible) if the higher-level function - * wimlib_reference_resource_files() is used. - * - * @param wim - * See corresponding parameter to wimlib_reference_resources(). - * @param resource_wims - * See corresponding parameter to wimlib_reference_resources(). - * @param num_resource_wims - * See corresponding parameter to wimlib_reference_resources(). - * - * @return 0 on success; nonzero on error. - * - * @retval ::WIMLIB_ERR_INVALID_PARAM - * Not all entries in @p resource_wims specify valid ::WIMStruct's that are - * referenced by @p wim. - */ -extern int -wimlib_unreference_resources(WIMStruct *wim, WIMStruct **resource_wims, - unsigned num_resource_wims); - /** * Update a WIM image by adding, deleting, and/or renaming files or directories. * @@ -3302,6 +3300,12 @@ wimlib_update_image(WIMStruct *wim, * with @p wim, or some file resources in @p wim refer to files in the * outside filesystem, and a read error occurred when reading one of these * files. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * A stream that needed to be written could not be found in the stream + * lookup table of @p wim. This error can occur if, for example, @p wim is + * part of a split WIM but needed resources from the other split WIM parts + * were not referenced with wimlib_reference_resources() or + * wimlib_reference_resource_files() before the call to wimlib_write(). * @retval ::WIMLIB_ERR_WRITE * An error occurred when trying to write data to the new WIM file. *