Improved error reporting if loading capture configuration file fails

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index e702fc3bea5dc7ab4f8280cd3080ac40a3b18c88..81e8f09c656f8260d80c47d267bd0c8e21bd13de 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -1002,7 +1002,7 @@ union wimlib_progress_info {
                 * integrity checks.  */
                uint64_t total_bytes;
 
-               /** The number of bytes that have been processed so far.  This
+               /** The number of bytes that have been checksummed so far.  This
                 * starts at 0 and ends at @p total_bytes.  */
                uint64_t completed_bytes;
 
@@ -1010,8 +1010,8 @@ union wimlib_progress_info {
                 * integrity-checked region is divided into.  */
                uint32_t total_chunks;
 
-               /** The number of chunks that have been processed so far.  This
-                * starts at 0 and ends at @p total_chunks.  */
+               /** The number of chunks that have been checksummed so far.
+                * This starts at 0 and ends at @p total_chunks.  */
                uint32_t completed_chunks;
 
                /** The size of each individually checksummed "chunk" in the
@@ -2451,6 +2451,7 @@ enum wimlib_error_code {
        WIMLIB_ERR_NOT_A_MOUNTPOINT                   = 80,
        WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT           = 81,
        WIMLIB_ERR_FVE_LOCKED_VOLUME                  = 82,
+       WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG      = 83,
 };
 
 
@@ -2564,15 +2565,9 @@ wimlib_add_image(WIMStruct *wim,
  * capture</b> for full details on how this mode works.
  *
  * 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_FLAG_NTFS was specified in @p add_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.)
+ * 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.
  */
 extern int
 wimlib_add_image_multisource(WIMStruct *wim,
@@ -4073,9 +4068,9 @@ wimlib_set_print_errors(bool show_messages);
  * @param wim
  *     Pointer to the ::WIMStruct for a WIM.
  * @param info
- *     A struct ::wimlib_wim_info that contains the information to set.  Only
- *     the information explicitly specified in the @p which flags need be
- *     valid.
+ *     Pointer to a ::wimlib_wim_info structure that contains the information
+ *     to set.  Only the information explicitly specified in the @p which flags
+ *     need be valid.
  * @param which
  *     Flags that specify which information to set.  This is a bitwise OR of
  *     ::WIMLIB_CHANGE_READONLY_FLAG, ::WIMLIB_CHANGE_GUID,
@@ -4250,20 +4245,16 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
  *     Windows-only: One of the "add" commands attempted to add files from an
  *     encrypted BitLocker volume that hasn't yet been unlocked.
  * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
- *     The capture configuration structure specified for an add command was
- *     invalid.
+ *     The contents of a capture configuration file were invalid.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  *     @p image did not exist in @p wim.
  * @retval ::WIMLIB_ERR_INVALID_OVERLAY
  *     Attempted to perform an add command that conflicted with previously
  *     existing files in the WIM when an overlay was attempted.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
- *     An unknown operation type was specified in the update commands; or,
- *     attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set
- *     in the @p add_flags, but the same image had previously already been
- *     added from an NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and
- *     ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @p add_flags for one add
- *     command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were
+ *     An unknown operation type was specified in the update commands; or, both
+ *     ::WIMLIB_ADD_FLAG_RPFIX and ::WIMLIB_ADD_FLAG_NORPFIX were specified in
+ *     the @p add_flags for one add command; or ::WIMLIB_ADD_FLAG_RPFIX were
  *     specified in the @p add_flags for an add command in which @p
  *     wim_target_path was not the root directory of the WIM image.
  * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA
@@ -4301,6 +4292,8 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
  * @retval ::WIMLIB_ERR_STAT
  *     While executing an add command, failed to get attributes for a file or
  *     directory.
+ * @retval ::WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG
+ *     A capture configuration file could not be read.
  * @retval ::WIMLIB_ERR_UNSUPPORTED
  *     ::WIMLIB_ADD_FLAG_NTFS was specified in the @p add_flags for an update
  *     command, but wimlib was configured with the @c --without-ntfs-3g flag;