SetupQuerySpaceRequiredOnDrive

[New for Windows NT 4.0 Service Pack 3.]

The SetupQuerySpaceRequiredOnDrive function examines a disk-space list to determine the space required to perform all the file operations listed for a particular drive.

BOOL SetupQuerySpaceRequiredOnDrive(
  HDSKSPC DiskSpace,        // handle to the disk-space list
  PCTSTR DriveSpec,         // specifies the drive
  LONGLONG *SpaceRequired,  // receives the space required
  PVOID Reserved1,          // must be zero
  UINT Reserved2            // must be zero
);
 

Parameters

DiskSpace

Supplies a handle to a disk-space list.

DriveSpec

Specifies the drive for which to return space information. This should be in the form "x:" or "\\server\share".

SpaceRequired

If the function succeeds, this parameter receives the amount of additional space required to process all of the file operations listed in the disk-space list for the drive specified by DriveSpec.

The SetupQuerySpaceRequiredOnDrive function calculates the additional space required on the target drive by checking for preexisting versions of the files on the target drive.

For example, if a file operation copied a 2000-byte file, FIRST.EXE, to the directory, C:\MYPROG\, the SetupQuerySpaceRequiredOnDrive function automatically checks for a preexisting version of that file in that directory. If a preexisting version of C:\MYPROG\FIRST.EXE had a file size of 500 bytes, the additional space required on the drive C for that operation would be 1500 bytes.

This value received can be zero or a negative number, if no additional space is required, or if space will be freed on the target drive.

If, in our preceding example, FIRST.EXE was being deleted from drive C, the amount of space required would be -2000 bytes, or the space freed on drive C.

If the preexisting version had a file size of 5000 bytes, then the disk space required to replace it with the 2000-byte FIRST.EXE would be –3000 bytes.

File sizes are rounded to disk cluster boundaries.

Reserved1

Reserved; must be 0.

Reserved2

Reserved; must be 0.

Return Values

If the function succeeds, the return value is a non-zero value and SpaceRequired receives the amount of space required by the file operations listed in the current disk-space list.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

QuickInfo

  Windows NT: Use version 4.0 SP3 and later.
  Windows: Use Windows 95 and later.
  Windows CE: Unsupported.
  Header: Declared in setupapi.h.
  Import Library: Link with setupapi.lib.

See Also

Overview, Functions, SetupQueryDrivesInDiskSpaceList