/// <summary>
/// Gets information about an image within the .wim (Windows image) file.
/// </summary>
/// <param name="wimHandle">Either a <see cref="WimHandle"/> returned from <see cref="CreateFile"/>, <see cref="LoadImage"/>, or <see cref="CaptureImage"/>.</param>
/// <returns>A <see cref="String"/> object containing XML information about the volume image.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static string GetImageInformationAsString(WimHandle wimHandle)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// Stores the native pointer to the Unicode xml
IntPtr imageInfoPtr = IntPtr.Zero;
try
{
// Call the native function
if (!NativeMethods.WIMGetImageInformation(wimHandle, out imageInfoPtr, out DWORD _))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
// Marshal the buffer as a Unicode string and remove the Unicode file marker
return(Marshal.PtrToStringUni(imageInfoPtr)?.Substring(1));
}
finally
{
// Free the native pointer
Marshal.FreeHGlobal(imageInfoPtr);
}
}
/// <summary>
/// Returns the number of volume images stored in an image file.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a .wim file returned by <see cref="CreateFile"/>.</param>
/// <returns>A <see cref="WimInfo"/> object containing information about the image file.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static WimInfo GetAttributes(WimHandle wimHandle)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// Calculate the size of the buffer needed
uint wimInfoSize = (DWORD)Marshal.SizeOf(typeof(WimgApi.WIM_INFO));
// Allocate a buffer to receive the native struct
IntPtr wimInfoPtr = Marshal.AllocHGlobal((int)wimInfoSize);
try
{
// Call the native function
if (!WimgApi.NativeMethods.WIMGetAttributes(wimHandle, wimInfoPtr, wimInfoSize))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
// Return a new instance of a WimInfo class which will marshal the struct
return(new WimInfo(wimInfoPtr));
}
finally
{
// Free memory
Marshal.FreeHGlobal(wimInfoPtr);
}
}
/// <summary>
/// Stores information about an image in the Windows® image (.wim) file.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of an image returned by the <see cref="CreateFile"/>, <see cref="LoadImage"/>, or <see cref="CaptureImage"/> methods.</param>
/// <param name="imageInfoXml">A <see cref="String"/> object that contains information about the volume image.</param>
/// <exception cref="ArgumentNullException"><paramref name="wimHandle"/> or <paramref name="imageInfoXml"/> is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
/// <remarks>If the wimHandle parameter is from the <see cref="CreateFile"/> method, then the XML data must be enclosed by <WIM></WIM> tags. If the input handle is from the <see cref="LoadImage"/> or <see cref="CaptureImage"/> methods, then the XML data must be enclosed by <IMAGE></IMAGE> tags.</remarks>
public static void SetImageInformation(WimHandle wimHandle, string imageInfoXml)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if imageInfoXml is null
if (imageInfoXml == null)
{
throw new ArgumentNullException(nameof(imageInfoXml));
}
// Append a unicode file marker to the xml as a string
string imageInfo = $"\uFEFF{imageInfoXml}";
// Allocate enough memory for the info
IntPtr imageInfoPtr = Marshal.StringToHGlobalUni(imageInfo);
try
{
// Call the native function
if (!WimgApi.NativeMethods.WIMSetImageInformation(wimHandle, imageInfoPtr, (DWORD)(imageInfo.Length + 1) * 2))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
finally
{
// Free the string buffer
Marshal.FreeHGlobal(imageInfoPtr);
}
}
/// <summary>
/// Loads a volume image from a Windows® image (.wim) file.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a .wim file returned by the <see cref="CreateFile"/> method.</param>
/// <param name="index">The one-based index of the image to load. An image file may store multiple images.</param>
/// <returns>A <see cref="WimHandle"/> representing the volume image.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
/// <exception cref="IndexOutOfRangeException">index is less than 1
/// -or-
/// index is greater than the number of images in the Windows® imaging file.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
/// <remarks>You must call the <see cref="SetTemporaryPath"/> method before calling the <see cref="LoadImage"/> method so the image metadata can be extracted and processed from the temporary location.</remarks>
public static WimHandle LoadImage(WimHandle wimHandle, int index)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if the specified index is valid
if (index < 1 || index > WimgApi.GetImageCount(wimHandle))
{
throw new IndexOutOfRangeException($"There is no image at index {index}.");
}
// Call the native function
WimHandle imageHandle = WimgApi.NativeMethods.WIMLoadImage(wimHandle, (DWORD)index);
if (imageHandle == null || imageHandle.IsInvalid)
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
// Return the image handle
return(imageHandle);
}
/// <summary>
/// Un-registers the specified callback for the <see cref="WimHandle" />.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle" /> of a windows image file.</param>
/// <param name="messageCallback">The <see cref="WimMessageCallback" /> method to un-register.</param>
/// <returns><c>true</c> if the callback was successfully un-registered, otherwise <c>false</c>.</returns>
/// <exception cref="ArgumentNullException">wimHandle or messageCallback is null.</exception>
public bool UnregisterCallback(WimHandle wimHandle, WimMessageCallback messageCallback)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if messageCallback is null
if (messageCallback == null)
{
throw new ArgumentNullException(nameof(messageCallback));
}
// See if the callback isn't registered
if (!IsCallbackRegistered(wimHandle, messageCallback))
{
return(false);
}
// Remove the callback from the list
_registeredCallbacksByHandle[wimHandle].Remove(messageCallback);
// See if the dictionary for the wimHandle is now empty
if (_registeredCallbacksByHandle[wimHandle].Count == 0)
{
// Remove the wimHandle dictionary item
_registeredCallbacksByHandle.Remove(wimHandle);
}
return(true);
}
/// <summary>
/// Extracts a file from within a Windows® image (.wim) file to a specified location.
/// </summary>
/// <param name="imageHandle">A <see cref="WimHandle"/> opened by the <see cref="LoadImage"/> method.</param>
/// <param name="sourceFile">The path to a file inside the image.</param>
/// <param name="destinationFile">The full file path of the directory where the image path is to be extracted.</param>
/// <exception cref="ArgumentNullException">imageHandle, sourceFile, or destinationFile is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static void ExtractImagePath(WimHandle imageHandle, string sourceFile, string destinationFile)
{
// See if imageHandle is null
if (imageHandle == null)
{
throw new ArgumentNullException(nameof(imageHandle));
}
// See if sourceFile is null
if (sourceFile == null)
{
throw new ArgumentNullException(nameof(sourceFile));
}
// See if destinationFile is null
if (destinationFile == null)
{
throw new ArgumentNullException(nameof(destinationFile));
}
// Call the native function
if (!WimgApi.NativeMethods.WIMExtractImagePath(imageHandle, sourceFile, destinationFile, 0))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
/// <summary>
/// Mounts an image in a Windows® image (.wim) file to the specified directory.
/// </summary>
/// <param name="imageHandle">A <see cref="WimHandle"/> of a a volume image returned by the <see cref="LoadImage"/> or <see cref="CaptureImage"/> method. The WIM file must have been opened with <see cref="WimFileAccess.Mount"/> flag in call to <see cref="CreateFile"/>.</param>
/// <param name="mountPath">The full file path of the directory to which the .wim file has to be mounted.</param>
/// <param name="options">Specifies how the file is to be treated and what features are to be used.</param>
/// <exception cref="ArgumentNullException">imageHandle or mountPath is null.</exception>
/// <exception cref="DirectoryNotFoundException">mountPath does not exist.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
/// <remarks>This method maps the contents of the given image in a .wim file to the specified mount directory. After the successful completion of this operation, users or applications can access the contents of the image mapped under the mount directory. The WIM file containing the image must be opened with <see cref="WimFileAccess.Mount"/> access. Use the <see cref="UnmountImage(WimHandle)"/> method to unmount the image from the mount directory.</remarks>
public static void MountImage(WimHandle imageHandle, string mountPath, WimMountImageOptions options)
{
// See if imageHandle is null
if (imageHandle == null)
{
throw new ArgumentNullException(nameof(imageHandle));
}
// See if mountPath is null
if (mountPath == null)
{
throw new ArgumentNullException(nameof(mountPath));
}
// See if mount path does not exist
if (!Directory.Exists(mountPath))
{
throw new DirectoryNotFoundException($"Could not find a part of the path '{mountPath}'");
}
// Call the native function
if (!WimgApi.NativeMethods.WIMMountImageHandle(imageHandle, mountPath, (DWORD)options))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
/// <summary>
/// Enables the <see cref="ApplyImage"/> and <see cref="CaptureImage"/> methods to use alternate .wim files for file resources. This can enable optimization of storage when multiple images are captured with similar data.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a .wim (Windows image) file returned by the <see cref="CreateFile"/> method.</param>
/// <param name="path">The path of the .wim file to be added to the reference list.</param>
/// <param name="mode">Specifies whether the .wim file is added to the reference list or replaces other entries.</param>
/// <param name="options">Specifies options when adding the .wim file to the reference list.</param>
/// <exception cref="ArgumentNullException">wimHandle is null
/// -or-
/// mode is not WimSetReferenceMode.Replace and path is null.</exception>
/// <exception cref="FileNotFoundException">path does not exist.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
/// <remarks>If <c>null</c> is passed in for the path parameter and <see cref="WimSetReferenceMode.Replace"/> is passed for the mode parameter, then the reference list is completely cleared, and no file resources are extracted during the <see cref="ApplyImage"/> method.</remarks>
public static void SetReferenceFile(WimHandle wimHandle, string path, WimSetReferenceMode mode, WimSetReferenceOptions options)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if not replacing and path is null
if (mode != WimSetReferenceMode.Replace && path == null)
{
throw new ArgumentNullException(nameof(path));
}
// See if path does not exist
if (!File.Exists(path))
{
throw new FileNotFoundException($"Could not find part of the path '{path}'");
}
// Call the native function
if (!WimgApi.NativeMethods.WIMSetReferenceFile(wimHandle, path, (DWORD)mode | (DWORD)options))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
/// <summary>
/// Sets the location where temporary imaging files are to be stored.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a .wim file returned by the <see cref="CreateFile"/> method.</param>
/// <param name="path">The path where temporary image (.wim) files are to be stored during capture or application. This is the directory where the image is captured or applied.</param>
/// <exception cref="ArgumentNullException">wimHandle or path is null.</exception>
/// <exception cref="DirectoryNotFoundException">path does not exist.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static void SetTemporaryPath(WimHandle wimHandle, string path)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if path is null
if (path == null)
{
throw new ArgumentNullException(nameof(path));
}
// See if path does not exist
if (!Directory.Exists(path))
{
throw new DirectoryNotFoundException($"Could not find part of the path '{path}'");
}
// Call the native function
if (!WimgApi.NativeMethods.WIMSetTemporaryPath(wimHandle, path))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
/// <summary>
/// Gets information about a mounted image.
/// </summary>
/// <param name="mountPath">The full file path of the directory to which the .wim file has been mounted.</param>
/// <returns>A <see cref="WimMountInfo" /> object containing information about the mounted image.</returns>
public static WimMountInfo GetMountInfo(string mountPath)
{
// Stores the handle to the image
//
WimHandle imageHandle = null;
try
{
// Get a mounted image handle
//
// ReSharper disable once UnusedVariable
using (WimHandle wimHandle = WimgApi.GetMountedImageHandle(mountPath, true, out imageHandle))
{
// Return the mounted image info from the handle
//
return(WimgApi.GetMountedImageInfoFromHandle(imageHandle));
}
}
finally
{
// Clean up
//
imageHandle?.Dispose();
}
}
/// <summary>
/// Enables a large Windows® image (.wim) file to be split into smaller parts for replication or storage on smaller forms of media.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a .wim file returned by <see cref="CreateFile"/>.</param>
/// <param name="partPath">The path of the first file piece of the spanned set.</param>
/// <param name="partSize">The size of the initial piece of the spanned set. This value will also be the default size used for subsequent pieces.</param>
/// <exception cref="ArgumentNullException">wimHandle or partPath is null.</exception>
/// <exception cref="DirectoryNotFoundException">Directory of partPath does not exist.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static void SplitFile(WimHandle wimHandle, string partPath, long partSize)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if partPath is null
if (partPath == null)
{
throw new ArgumentNullException(nameof(partPath));
}
// See if the directory of partPath does not exist
//
// ReSharper disable once AssignNullToNotNullAttribute
if (!Directory.Exists(Path.GetDirectoryName(partPath)))
{
throw new DirectoryNotFoundException($"Could not find part of the path '{Path.GetDirectoryName(partPath)}'");
}
// Create a copy of part size so it can be safely passed by reference
long partSizeCopy = partSize;
// Call the native function
if (!WimgApi.NativeMethods.WIMSplitFile(wimHandle, partPath, ref partSizeCopy, 0))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
/// <summary>
/// Gets the minimum size needed to to create a split WIM.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a .wim file returned by <see cref="CreateFile"/>.</param>
/// <param name="partPath">The path of the first file piece of the spanned set.</param>
/// <returns>The minimum space required to split the WIM.</returns>
/// <exception cref="ArgumentNullException">wimHandle or partPath is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static long SplitFile(WimHandle wimHandle, string partPath)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if partPath is null
if (partPath == null)
{
throw new ArgumentNullException(nameof(partPath));
}
// Declare a part size as zero
long partSize = 0;
// Call the WIMSplitFile function which should return false and set partSize to the minimum size needed
if (!WimgApi.NativeMethods.WIMSplitFile(wimHandle, partPath, ref partSize, 0))
{
// See if the return code was not ERROR_MORE_DATA
if (Marshal.GetLastWin32Error() != WimgApi.ERROR_MORE_DATA)
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
return(partSize);
}
/// <summary>
/// Registers a callback for the specified <see cref="WimHandle" />.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle" /> of a windows image file.</param>
/// <param name="messageCallback">The <see cref="WimMessageCallback" /> method to register.</param>
/// <param name="userData">User-defined data to pass to the callback.</param>
/// <returns><c>true</c> if the callback was successfully registered, otherwise <c>false</c>.</returns>
/// <exception cref="ArgumentNullException">wimHandle or messageCallback is null.</exception>
public bool RegisterCallback(WimHandle wimHandle, WimMessageCallback messageCallback, object userData)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if messageCallback is null
if (messageCallback == null)
{
throw new ArgumentNullException(nameof(messageCallback));
}
// See if the callback is already registered
if (IsCallbackRegistered(wimHandle, messageCallback))
{
return(false);
}
// See if the dictionary doesn't contain the wimHandle
if (!_registeredCallbacksByHandle.ContainsKey(wimHandle))
{
// Add an item for the wimHandle to the dictionary
_registeredCallbacksByHandle.Add(wimHandle, new Dictionary <WimMessageCallback, WimMessageCallbackWrapper>());
}
// Create a callback wrapper and add the callback to the list
_registeredCallbacksByHandle[wimHandle].Add(messageCallback, new WimMessageCallbackWrapper(messageCallback, userData));
return(true);
}
/// <summary>
/// Captures an image from a directory path and stores it in an image file.
/// </summary>
/// <param name="wimHandle">The handle to a .wim file returned by <see cref="CreateFile" />.</param>
/// <param name="path">The root drive or directory path from where the image data is captured.</param>
/// <param name="options">Specifies the features to use during the capture.</param>
/// <returns>A <see cref="WimHandle"/> of the image if the method succeeded, otherwise false.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.
/// -or-
/// path is null</exception>
/// <exception cref="DirectoryNotFoundException"><paramref name="path"/> does not exist.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static WimHandle CaptureImage(WimHandle wimHandle, string path, WimCaptureImageOptions options)
{
// See if the handle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if path is null
if (path == null)
{
throw new ArgumentNullException(nameof(path));
}
// See if path doesn't exist
if (!Directory.Exists(path))
{
throw new DirectoryNotFoundException($"Could not find part of the path '{path}'");
}
// Call the native function
WimHandle imageHandle = WimgApi.NativeMethods.WIMCaptureImage(wimHandle, path, (DWORD)options);
// See if the handle returned is valid
if (imageHandle == null || imageHandle.IsInvalid)
{
// Throw a Win32Exception which will call GetLastError
throw new Win32Exception();
}
// Return the handle to the image
return(imageHandle);
}
/// <summary>
/// Applies an image to a directory path from a Windows® image (.wim) file.
/// </summary>
/// <param name="imageHandle">A handle to a volume image returned by the <see cref="LoadImage" /> or <see cref="CaptureImage" /> methods.</param>
/// <param name="path">The root drive or the directory path where the image data will be applied.</param>
/// <param name="options">Specifies how the file is to be treated and what features are to be used.</param>
/// <exception cref="ArgumentNullException">imageHandle is null.</exception>
/// <exception cref="OperationCanceledException">The operation of applying the image was aborted by a callback returning <see cref="WimMessageResult.Abort" />.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static void ApplyImage(WimHandle imageHandle, string path, WimApplyImageOptions options)
{
// See if the handle is null
if (imageHandle == null)
{
throw new ArgumentNullException(nameof(imageHandle));
}
// Call the native function
if (!WimgApi.NativeMethods.WIMApplyImage(imageHandle, path, (UInt32)options))
{
// Get the last error
Win32Exception win32Exception = new Win32Exception();
switch (win32Exception.NativeErrorCode)
{
case WimgApi.ERROR_REQUEST_ABORTED:
// If the operation was aborted, throw an OperationCanceledException exception
throw new OperationCanceledException(win32Exception.Message, win32Exception);
default:
throw win32Exception;
}
}
}
/// <summary>
/// Gets information about an image within the .wim (Windows image) file.
/// </summary>
/// <param name="wimHandle">Either a <see cref="WimHandle"/> returned from <see cref="CreateFile"/>, <see cref="LoadImage"/>, or <see cref="CaptureImage"/>.</param>
/// <returns>AN <see cref="XDocument"/> object containing XML information about the volume image.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static XmlDocument GetImageInformationAsXmlDocument(WimHandle wimHandle)
{
string xml = GetImageInformationAsString(wimHandle);
if (xml == null)
{
return(null);
}
XmlDocument xmlDocument = new XmlDocument
{
XmlResolver = null
};
using (StringReader stringReader = new StringReader(xml))
{
using (XmlReader xmlReader = new XmlTextReader(stringReader)
{
DtdProcessing = DtdProcessing.Prohibit
})
{
xmlDocument.Load(xmlReader);
}
}
return(xmlDocument);
}
/// <summary>
/// Gets the count of callback routines currently registered by the imaging library.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a .wim file returned by <see cref="CreateFile"/>.</param>
/// <returns>The number of message callback functions currently registered.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
public static int GetMessageCallbackCount(WimHandle wimHandle)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// Return the value from the native function
return((int)WimgApi.NativeMethods.WIMGetMessageCallbackCount(wimHandle));
}
/// <summary>
/// Gets a native callback for passing to the WIMGAPI for the specified registered callback associated with the
/// <see cref="WimHandle" />.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle" /> of a windows image file.</param>
/// <param name="messageCallback">The <see cref="WimMessageCallback" /> method that was registered.</param>
/// <returns>A <see cref="WimgApi.WIMMessageCallback" /> method that can be passed to the native WIMGAPI.</returns>
/// <exception cref="InvalidOperationException">
/// The specified handle has no registered callbacks or the specified callback
/// is not registered for the handle.
/// </exception>
public WimgApi.WIMMessageCallback GetNativeCallback(WimHandle wimHandle, WimMessageCallback messageCallback)
{
// Verify the callback is registered for the handle
if (!IsCallbackRegistered(wimHandle, messageCallback))
{
throw new InvalidOperationException("Specified callback is not registered.");
}
// Return the native callback
return(_registeredCallbacksByHandle[wimHandle][messageCallback].NativeCallback);
}
/// <summary>
/// Stores information about an image in the Windows® image (.wim) file.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of an image returned by the <see cref="CreateFile"/>, <see cref="LoadImage"/>, or <see cref="CaptureImage"/> methods.</param>
/// <param name="imageInfoXml">An <see cref="IXPathNavigable"/> object that contains information about the volume image.</param>
/// <exception cref="ArgumentNullException"><paramref name="wimHandle"/> or <paramref name="imageInfoXml"/> is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
/// <remarks>If the wimHandle parameter is from the <see cref="CreateFile"/> method, then the XML data must be enclosed by <WIM></WIM> tags. If the input handle is from the <see cref="LoadImage"/> or <see cref="CaptureImage"/> methods, then the XML data must be enclosed by <IMAGE></IMAGE> tags.</remarks>
public static void SetImageInformation(WimHandle wimHandle, IXPathNavigable imageInfoXml)
{
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
if (imageInfoXml == null)
{
throw new ArgumentNullException(nameof(imageInfoXml));
}
SetImageInformation(wimHandle, imageInfoXml.CreateNavigator()?.OuterXml);
}
/// <summary>
/// Gets information about a mounted image of the specified mounted image handle.
/// </summary>
/// <param name="imageHandle">A <see cref="WimHandle"/> of an image that has been mounted.</param>
/// <returns>A <see cref="WimMountInfo"/> object containing information about the mounted image.</returns>
/// <exception cref="ArgumentNullException">imageHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static WimMountInfo GetMountedImageInfoFromHandle(WimHandle imageHandle)
{
// See if imageHandle is null
if (imageHandle == null)
{
throw new ArgumentNullException(nameof(imageHandle));
}
// Calculate the size of the buffer needed
int mountInfoSize = Marshal.SizeOf(typeof(WimgApi.WIM_MOUNT_INFO_LEVEL1));
// Allocate a buffer for the native function
IntPtr mountInfoPtr = Marshal.AllocHGlobal(mountInfoSize);
try
{
// Call the native function (the buffer may be too small)
if (!WimgApi.NativeMethods.WIMGetMountedImageInfoFromHandle(imageHandle, WimMountInfo.MountInfoLevel, mountInfoPtr, (DWORD)mountInfoSize, out DWORD returnLength))
{
// See if the return value isn't ERROR_INSUFFICIENT_BUFFER
if (Marshal.GetLastWin32Error() != 122)
{
throw new Win32Exception();
}
// Re-allocate the buffer to the correct size
Marshal.ReAllocHGlobal(mountInfoPtr, (IntPtr)returnLength);
// Call the native function a second time so it can fill buffer with a struct
if (!WimgApi.NativeMethods.WIMGetMountedImageInfoFromHandle(imageHandle, WimMountInfo.MountInfoLevel, mountInfoPtr, returnLength, out returnLength))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
// Return a WimMountInfo object which will marshal the pointer to a struct
return(new WimMountInfo(mountInfoPtr));
}
finally
{
// Free the native memory
Marshal.FreeHGlobal(mountInfoPtr);
}
}
/// <summary>
/// Saves the changes from a mounted image back to the.wim file.
/// </summary>
/// <param name="imageHandle">A <see cref="WimHandle"/> opened by the <see cref="LoadImage"/> method. The .wim file must have been opened with a <see cref="WimFileAccess.Mount"/> flag in call to <see cref="CreateFile" />.</param>
/// <param name="append"><c>true</c> to append the modified image to the .wim file. <c>false</c> to commit the changes to the original image.</param>
/// <param name="options">Specifies the features to use during the capture.</param>
/// <returns>If append is <c>true</c>, a <see cref="WimHandle"/> of the new image, otherwise a null handle.</returns>
/// <exception cref="ArgumentNullException">imageHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static WimHandle CommitImageHandle(WimHandle imageHandle, bool append, WimCommitImageOptions options)
{
// See if the handle is null
if (imageHandle == null)
{
throw new ArgumentNullException(nameof(imageHandle));
}
// Call the native function, add the append flag if needed
if (!WimgApi.NativeMethods.WIMCommitImageHandle(imageHandle, append ? WimgApi.WIM_COMMIT_FLAG_APPEND : 0 | (DWORD)options, out WimHandle newImageHandle))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
// Return the new image handle which may or may not contain a handle
return(newImageHandle);
}
/// <summary>
/// Unmounts a mounted image in a Windows® image (.wim) file from the specified directory.
/// </summary>
/// <param name="imageHandle">A <see cref="WimHandle"/> of an image previously mounted with <see cref="MountImage(WimHandle, string, WimMountImageOptions)"/>.</param>
/// <exception cref="ArgumentNullException">imageHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static void UnmountImage(WimHandle imageHandle)
{
// See if imageHandle is null
if (imageHandle == null)
{
throw new ArgumentNullException(nameof(imageHandle));
}
// Call the native function
if (!WimgApi.NativeMethods.WIMUnmountImageHandle(imageHandle, 0))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
// Close the image handle
imageHandle.Close();
}
/// <summary>
/// Un-registers all callbacks for the specified <see cref="WimHandle" />.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle" /> of a windows image file.</param>
/// <returns><c>true</c> if the all of the callbacks were successfully un-registered, otherwise <c>false</c>.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
public bool UnregisterCallbacks(WimHandle wimHandle)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if the wimHandle doesn't have any registered callbacks
if (!_registeredCallbacksByHandle.ContainsKey(wimHandle))
{
return(false);
}
// Remove the wimHandle from the list
_registeredCallbacksByHandle.Remove(wimHandle);
return(true);
}
/// <summary>
/// Makes a new image file or opens an existing image file.
/// </summary>
/// <param name="path">The name of the file to create or to open.</param>
/// <param name="desiredAccess">The type of <see cref="WimFileAccess"/> to the object. An application can obtain read access, write access, read/write access, or device query access.</param>
/// <param name="creationDisposition">The <see cref="WimCreationDisposition"/> to take on files that exist, and which action to take when files do not exist.</param>
/// <param name="options"><see cref="WimCreateFileOptions"/> to be used for the specified file.</param>
/// <param name="compressionType">The <see cref="WimCompressionType"/> to be used for a newly created image file. If the file already exists, then this value is ignored.</param>
/// <returns>A <see cref="WimHandle"/> object representing the file.</returns>
/// <exception cref="ArgumentNullException">path is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static WimHandle CreateFile(string path, WimFileAccess desiredAccess, WimCreationDisposition creationDisposition, WimCreateFileOptions options, WimCompressionType compressionType)
{
// See if destinationFile is null
if (path == null)
{
throw new ArgumentNullException(nameof(path));
}
// Call the native function
WimHandle wimHandle = WimgApi.NativeMethods.WIMCreateFile(path, (DWORD)desiredAccess, (DWORD)creationDisposition, (DWORD)options, (DWORD)compressionType, out _);
// See if the handle returned is valid
if (wimHandle == null || wimHandle.IsInvalid)
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
// Return the handle to the wim
return(wimHandle);
}
/// <summary>
/// Marks the image with the given image index as bootable.
/// </summary>
/// <param name="wimHandle">A <see cref="WimHandle"/> of a Windows® image (.wim) file returned by the <see cref="CreateFile"/> method.</param>
/// <param name="imageIndex">The one-based index of the image to load. An image file can store multiple images.</param>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
/// <exception cref="IndexOutOfRangeException">index is less than 1 or greater than the number of images in the Windows® image file.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
/// <remarks>If imageIndex is zero, then none of the images in the .wim file are marked for boot. At any time, only one image in a .wim file can be set to be bootable.</remarks>
public static void SetBootImage(WimHandle wimHandle, int imageIndex)
{
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// See if the specified index is valid
if (imageIndex < 1 || imageIndex > WimgApi.GetImageCount(wimHandle))
{
throw new IndexOutOfRangeException($"There is no image at index {imageIndex}.");
}
// Call the native function
if (!WimgApi.NativeMethods.WIMSetBootImage(wimHandle, (DWORD)imageIndex))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
/// <summary>
/// Transfers the data of an image from one Windows® image (.wim) file to another.
/// </summary>
/// <param name="imageHandle">A <see cref="WimHandle"/> opened by the <see cref="LoadImage"/> method.</param>
/// <param name="wimHandle">A <see cref="WimHandle"/> returned by the <see cref="CreateFile"/> method. This handle must have <see cref="WimFileAccess.Write"/> access to accept the exported image. Split .wim files are not supported.</param>
/// <param name="options">Specifies how the image will be exported to the destination .wim file.</param>
/// <exception cref="ArgumentNullException">imageHandle or wimHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
/// <remarks>You must call the <see cref="SetTemporaryPath"/> method for both the source and the destination .wim files before calling the ExportImage method.</remarks>
public static void ExportImage(WimHandle imageHandle, WimHandle wimHandle, WimExportImageOptions options)
{
// See if imageHandle is null
if (imageHandle == null)
{
throw new ArgumentNullException(nameof(imageHandle));
}
// See if wimHandle is null
if (wimHandle == null)
{
throw new ArgumentNullException(nameof(wimHandle));
}
// Call the native function
if (!WimgApi.NativeMethods.WIMExportImage(imageHandle, wimHandle, (UInt32)options))
{
// Throw a Win32Exception based on the last error code
throw new Win32Exception();
}
}
/// <summary>
/// Gets information about an image within the .wim (Windows image) file.
/// </summary>
/// <param name="wimHandle">Either a <see cref="WimHandle"/> returned from <see cref="CreateFile"/>, <see cref="LoadImage"/>, or <see cref="CaptureImage"/>.</param>
/// <returns>An <see cref="IXPathNavigable"/> object containing XML information about the volume image.</returns>
/// <exception cref="ArgumentNullException">wimHandle is null.</exception>
/// <exception cref="Win32Exception">The Windows® Imaging API reported a failure.</exception>
public static IXPathNavigable GetImageInformation(WimHandle wimHandle)
{
string xml = GetImageInformationAsString(wimHandle);
if (xml == null)
{
return(null);
}
XmlReaderSettings xmlReaderSettings = new XmlReaderSettings
{
DtdProcessing = DtdProcessing.Prohibit
};
using (StringReader stringReader = new StringReader(xml))
{
using (XmlReader xmlReader = XmlReader.Create(stringReader, xmlReaderSettings))
{
return(new XPathDocument(xmlReader));
}
}
}
public static extern DWORD WIMGetMessageCallbackCount(WimHandle hWim);
public static extern bool WIMGetMountedImageInfoFromHandle(WimHandle hImage, WimMountedImageInfoLevels fInfoLevelId, IntPtr pMountInfo, DWORD cbMountInfoLength, out DWORD pcbReturnLength);
public static extern bool WIMUnmountImageHandle(WimHandle hImage, DWORD dwUnmountFlags);
