Skip to content

Commit f1cbd80

Browse files
techartdevtechartdev
authored
Update README.md
1 parent f9dc604 commit f1cbd80

File tree

1 file changed

+369
-1
lines changed

1 file changed

+369
-1
lines changed

‎README.md‎

Lines changed: 369 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,369 @@
1-
# VHDTools
1+
# VHDTools
2+
3+
Provides functionality for managing disk operations, including virtual disks and attached physical drives.
4+
5+
## Introduction
6+
7+
The library is designed to handle disk management tasks such as creating virtual disks, attaching and detaching disks, initializing partitions, formatting volumes, and changing drive letters. It provides a convenient interface for working with both virtual and physical disks.
8+
9+
### DiskManager
10+
11+
To create an instance of the DiskManager class, you can use one of the available constructors.
12+
13+
```csharp
14+
// Example 1: Create a DiskManager for a virtual disk
15+
string virtualDiskPath = "path/to/virtual/disk.vhd";
16+
DiskManager diskManager = new DiskManager(virtualDiskPath);
17+
18+
// Example 2: Create a DiskManager for an attached physical drive
19+
char driveLetter = 'C';
20+
DiskManager diskManager = new DiskManager(driveLetter);
21+
```
22+
23+
### Perform Disk Operations
24+
25+
Once you have an instance of the DiskManager class, you can perform various disk operations.
26+
27+
```csharp
28+
// Example: Attach a virtual disk
29+
diskManager.AttachVirtualDisk();
30+
31+
// Example: Detach the attached virtual disk
32+
diskManager.DetachVirtualDisk();
33+
34+
// Example: Initialize the virtual disk partition
35+
diskManager.InitializeVirtualDiskPartition();
36+
37+
// Example: Format all volumes of the drive
38+
diskManager.FortmatAllVolumesOfDrive(FileSystemType.NTFS);
39+
40+
// Example: Format a specific volume
41+
Volume volume = diskManager.DiskVolumes.First();
42+
diskManager.FormatSpecificVolume(volume, FileSystemType.NTFS);
43+
44+
// Example: Set a drive letter for a volume
45+
Volume volume = diskManager.DiskVolumes.First();
46+
char newDriveLetter = 'D';
47+
diskManager.SetDriveLetter(volume, newDriveLetter);
48+
49+
// Example: Change the drive letter of a volume
50+
char oldDriveLetter = 'C';
51+
char newDriveLetter = 'D';
52+
diskManager.ChangeDriveLetter(oldDriveLetter, newDriveLetter);
53+
54+
// Example: Expand the size of a virtual disk
55+
ulong newSizeInBytes = 1024 * 1024 * 1024; // 1GB
56+
diskManager.ExpandVirtualDisk(newSizeInBytes);
57+
```
58+
59+
## DiskIO Class
60+
61+
### InitializeDisk
62+
The DiskIO class provides methods for disk initialization and updating disk partitions in a Windows environment.
63+
64+
```csharp
65+
public static void InitializeDisk(string path)
66+
```
67+
68+
This method initializes a disk at the specified path. It performs the following operations:
69+
70+
1. Opens the disk using the CreateFile function.
71+
2. Checks if the handle is invalid and throws a Win32Exception if it is.
72+
3. Generates a random signature for the disk.
73+
4. Creates a disk using the DeviceIoControl function with the IOCTL_DISK_CREATE_DISK control code.
74+
5. Updates the disk properties cache using the DeviceIoControl function with the IOCTL_DISK_UPDATE_PROPERTIES control code.
75+
6. Retrieves the partition information using the DeviceIoControl function with the IOCTL_DISK_GET_PARTITION_INFO control code.
76+
7. Constructs a new drive layout with one partition.
77+
8. Sets the drive layout using the DeviceIoControl function with the IOCTL_DISK_SET_DRIVE_LAYOUT_EX control code.
78+
9. Updates the disk properties cache again.
79+
80+
### UpdateDiskPartition
81+
82+
```csharp
83+
public static void UpdateDiskPartition(string path, long growSize)
84+
```
85+
86+
This method updates the size of a disk partition at the specified path by increasing its size. It performs the following operations:
87+
88+
1. Opens the disk using the CreateFile function.
89+
2. Checks if the handle is invalid and throws a Win32Exception if it is.
90+
3. Retrieves the partition information using the DeviceIoControl function with the IOCTL_DISK_GET_PARTITION_INFO control code.
91+
4. Creates a DISK_GROW_PARTITION structure with the new size to grow the partition.
92+
5. Calls the DeviceIoControl function with the IOCTL_DISK_GROW_PARTITION control code to grow the partition.
93+
6. Updates the disk properties cache using the DeviceIoControl function with the IOCTL_DISK_UPDATE_PROPERTIES control code.
94+
7. Retrieves the disk geometry using the DeviceIoControl function with the DiskUpdateDriveSize control code.
95+
8. Retrieves the extended partition information using the DeviceIoControl function with the DiskGetPartitionInfoEx control code.
96+
9. Calculates the new length of the partition in sectors.
97+
10. Calls the DeviceIoControl function with the FsctlExtendVolume control code to extend the volume.
98+
99+
### Usage
100+
101+
```csharp
102+
// Example usage of the DiskIO class
103+
string diskPath = "C:\\MyDisk";
104+
long growSize = 1024 * 1024 * 1024; // 1 GB
105+
106+
try
107+
{
108+
DiskIO.InitializeDisk(diskPath);
109+
DiskIO.UpdateDiskPartition(diskPath, growSize);
110+
}
111+
catch (Win32Exception ex)
112+
{
113+
Console.WriteLine("An error occurred: " + ex.Message);
114+
}
115+
```
116+
117+
## FormatDisk Class
118+
119+
### FormatDrive_Shell32
120+
121+
```csharp
122+
[Obsolete("Unsupported by Microsoft nowadays. Prefer the FormatDrive() method")]
123+
public static bool FormatDrive_Shell32(char driveLetter, string label = "", bool quickFormat = true)
124+
```
125+
126+
This method formats a drive using Shell32.dll. It accepts the following parameters:
127+
- driveLetter: The drive letter to format (e.g., 'A', 'B', 'C', ...).
128+
- label (optional): The label to assign to the drive.
129+
- quickFormat (optional): A boolean indicating whether to perform a quick format. Default is true.
130+
Returns: true if the format is successful, false otherwise.
131+
132+
### SetLabel
133+
134+
```csharp
135+
public static bool SetLabel(char driveLetter, string label = "")
136+
```
137+
138+
This method sets the label for a drive. It accepts the following parameters:
139+
140+
- driveLetter: The drive letter to set the label for (e.g., 'A', 'B', 'C', ...).
141+
- label (optional): The label to assign to the drive. If not specified, the label will be empty.
142+
143+
Returns: true if the label is set successfully, false otherwise.
144+
145+
### FormatDrive_Win32Api
146+
147+
```csharp
148+
public static bool FormatDrive_Win32Api(char driveLetter, string label = "", string fileSystem = "NTFS", bool quickFormat = true, bool enableCompression = false, int clusterSize = 8192)
149+
```
150+
151+
This method formats a drive using the Win32 API. It accepts the following parameters:
152+
153+
- driveLetter: The drive letter to format (e.g., 'A', 'B', 'C', ...).
154+
- label (optional): The label to assign to the drive.
155+
- fileSystem (optional): The file system to use for the format. Possible values are "FAT", "FAT32", "EXFAT", "NTFS", "UDF". Default is "NTFS".
156+
- quickFormat (optional): A boolean indicating whether to perform a quick format. Default is true.
157+
- enableCompression (optional): A boolean indicating whether to enable drive compression. Default is false.
158+
- clusterSize (optional): The cluster size for the file system. The possible values depend on the file system. Default is 8192.
159+
160+
Returns: true if the format is successful, false otherwise.
161+
162+
### FormatDrive_Win32Api
163+
164+
```csharp
165+
public static bool FormatDrive_Win32Api(string volumeName, string label = "", string fileSystem = "NTFS", bool quickFormat = true, bool enableCompression = false, int clusterSize = 8192)
166+
```
167+
168+
This overload of the FormatDrive_Win32Api method formats a drive using the Win32 API. It accepts the following parameters:
169+
170+
- volumeName: The name of the volume to format.
171+
- label (optional): The label to assign to the drive.
172+
- fileSystem (optional): The file system to use for the format. Possible values are "FAT", "FAT32", "EXFAT", "NTFS", "UDF". Default is "NTFS".
173+
- quickFormat (optional): A boolean indicating whether to perform a quick format. Default is true.
174+
- enableCompression (optional): A boolean indicating whether to enable drive compression. Default is false.
175+
176+
### IsFileSystemValid
177+
178+
```csharp
179+
public static bool IsFileSystemValid(string fileSystem)
180+
```
181+
182+
This method checks if a provided file system value is valid. It accepts the following parameter:
183+
184+
- fileSystem: The file system value to check.
185+
186+
Returns: true if the file system is valid, false otherwise.
187+
188+
### ResolveFileSystemType
189+
190+
```csharp
191+
public static string ResolveFileSystemType(FileSystemType type)
192+
```
193+
194+
This method resolves a FileSystemType enumeration value to its corresponding string representation. It accepts the following parameter:
195+
196+
- type: The FileSystemType enumeration value to resolve.
197+
198+
Returns: The string representation of the file system type.
199+
200+
## HardDiskFooter
201+
202+
The HardDiskFooter class represents a footer structure for a hard disk image. It contains various properties and methods to manipulate and retrieve information from the footer.
203+
204+
### Constructors
205+
- HardDiskFooter(): Creates a new instance of the HardDiskFooter class with default values.
206+
- HardDiskFooter(byte[] bytes): Creates a new instance of the HardDiskFooter class from existing footer bytes.
207+
208+
### Properties
209+
- Cookie: Gets or sets the cookie that identifies the original creator of the hard disk image.
210+
- Features: Gets or sets the features enabled for the hard disk image.
211+
- FileFormatVersion: Gets or sets the version of the file format specification used in creating the file.
212+
- DataOffset: Gets or sets the byte offset to the next structure in the file.
213+
- TimeStamp: Gets or sets the creation time of the hard disk image.
214+
- CreatorApplication: Gets or sets the application that created the hard disk image.
215+
- CreatorVersion: Gets or sets the version of the application that created the hard disk image.
216+
- CreatorHostOs: Gets or sets the type of host operating system the disk image is created on.
217+
- OriginalSize: Gets or sets the size of the hard disk in bytes at creation time.
218+
- CurrentSize: Gets or sets the current size of the hard disk in bytes.
219+
- DiskGeometryCylinders: Gets or sets the cylinder value for the hard disk.
220+
- DiskGeometryHeads: Gets or sets the heads value for the hard disk.
221+
- DiskGeometrySectors: Gets or sets the sectors per track value for the hard disk.
222+
- DiskType: Gets or sets the type of virtual disk.
223+
- Checksum: Gets or sets the checksum of the hard disk footer.
224+
- IsChecksumCorrect: Gets whether the checksum is correct.
225+
- Bytes: Gets the byte representation of the footer structure.
226+
227+
### Methods
228+
229+
- BeginUpdate(): Stops processing checksum updates until EndUpdate() is called.
230+
- EndUpdate(): Recalculates fields not updated since BeginUpdate().
231+
- UpdateChecksum(): Updates the checksum of the footer.
232+
- SetSize(UInt64 size): Sets the size of the hard disk image and updates related fields.
233+
234+
## ReFS
235+
236+
The ReFS class provides static methods for working with ReFS (Resilient File System) features.
237+
238+
### Methods
239+
240+
- RemoveIntegrityStream(FileInfo file): Removes the integrity stream from the specified file.
241+
- RemoveIntegrityStream(SafeFileHandle handle): Removes the integrity stream from the file associated with the specified file handle.
242+
- HasIntegrityStream(FileInfo file): Checks if the specified file has an integrity stream.
243+
- HasIntegrityStream(SafeFileHandle handle): Checks if the file associated with the specified file handle has an integrity stream.
244+
245+
Please note that these methods rely on native methods and Win32 API calls to interact with ReFS features.
246+
247+
```csharp
248+
FileInfo fileInfo = new FileInfo("path/to/file.txt");
249+
250+
if (ReFS.HasIntegrityStream(fileInfo))
251+
{
252+
ReFS.RemoveIntegrityStream(fileInfo);
253+
}
254+
```
255+
256+
Make sure to handle any exceptions that may be thrown during the ReFS operations.
257+
258+
*Note: This class assumes familiarity with ReFS concepts and features.*
259+
260+
# VirtualDisk Class
261+
262+
The `VirtualDisk` class allows manipulation with Virtual Disk files.
263+
264+
## Constructor
265+
266+
Creates new instance.
267+
268+
### Parameters
269+
270+
| Name | Type | Description |
271+
| ---- | ---- | ----------- |
272+
| `fileName` | `string` | Full path of VHD file. |
273+
274+
## Properties
275+
276+
| Name | Type | Description |
277+
| ---- | ---- | ----------- |
278+
| `FileName` | `string` | Gets file name of VHD. |
279+
| `DiskType` | `VirtualDiskType` | Gets type of open virtual device. If device is not open, type will be AutoDetect. Once device is opened, type will change to either Iso or Vhd. |
280+
| `IsOpen` | `bool` | Gets whether connection to file is currently open. |
281+
282+
## Methods
283+
284+
### `public void Open()`
285+
286+
Opens connection to file.
287+
288+
### `public void Open(VirtualDiskAccessMask fileAccess)`
289+
290+
Opens connection to file.
291+
292+
### Parameters
293+
294+
| Name | Type | Description |
295+
| ---- | ---- | ----------- |
296+
| `fileAccess` | `VirtualDiskAccessMask` | Defines required access. |
297+
298+
### `private void Open(VirtualDiskAccessMask fileAccess, VirtualDiskType type)`
299+
300+
Opens connection to file.
301+
302+
### Parameters
303+
304+
| Name | Type | Description |
305+
| ---- | ---- | ----------- |
306+
| `fileAccess` | `VirtualDiskAccessMask` | Defines required access. |
307+
| `type` | `VirtualDiskType` | Disk type. |
308+
309+
### `public void Dispose()`
310+
311+
Disposes current `VirtualDisk` instance.
312+
313+
### `public void Create(long size)`
314+
315+
Creates new virtual disk.
316+
317+
### Parameters
318+
319+
| Name | Type | Description |
320+
| ---- | ---- | ----------- |
321+
| `size` | `long` | Size in bytes. |
322+
323+
### Exceptions
324+
325+
| Exception | Description |
326+
| --------- | ----------- |
327+
| `ArgumentException` | Invalid parameter. |
328+
| `Win32Exception` | Native error. |
329+
| `FileNotFoundException` | File not found. |
330+
| `InvalidDataException` | File type not recognized. |
331+
| `IOException` | File already exists. -or- Virtual disk creation could not be completed due to a file system limitation. |
332+
333+
## DiskTools.Volume Class
334+
335+
The `DiskTools.Volume` class represents a disk volume on a Windows system. This class provides methods to perform various operations on a volume, such as getting drive letter information, changing volume drive letter and removing volume drive letter.
336+
337+
### Constructor
338+
339+
- `Volume(string volumeName)` : Initializes a new instance of the `Volume` class with the specified volume name.
340+
341+
### Properties
342+
343+
- `VolumeName`: Gets the name of the volume.
344+
- `DriveLetter3`: Returns drive letter with colon (:) and trailing backslash (\).
345+
- `DriveLetter2`: Returns drive letter with colon (:) but without trailing backslash (\).
346+
- `PhysicalDriveNumber`: Gets the physical drive number of the volume.
347+
- `PhysicalDriveExtentOffset`: Gets the starting offset on the disk of the volume.
348+
- `PhysicalDriveExtentLength`: Gets the length of the volume in bytes.
349+
350+
### Methods
351+
352+
- `ChangeLetter(string newLetter)`: Changes the drive letter of the volume to the specified value.
353+
- `RemoveLetter()`: Removes the drive letter of the volume.
354+
- `GetFromLetter(string driveLetter)`: Returns a `Volume` instance for a given drive letter.
355+
- `GetVolumesOnPhysicalDrive(string physicalDrive)`: Returns a list of `Volume` instances for a given physical drive.
356+
357+
### Usage
358+
359+
```csharp
360+
using DiskTools;
361+
// Get Volume instance by drive letter
362+
Volume volume = Volume.GetFromLetter("F:\");
363+
// Change drive letter for the volume
364+
volume.ChangeLetter("G:\");
365+
// Remove drive letter for the volume
366+
volume.RemoveLetter();
367+
// Get all volumes for physical drive number 0
368+
var volumes = Volume.GetVolumesOnPhysicalDrive(0);
369+
```

0 commit comments

Comments
 (0)