Device Input and Output

Applications use a device input and output control to communicate with a device driver. This overview discusses device handles, which identify the device being accessed, and device control codes, which specify the action the driver is to perform.

  • About Device Input and Output
  • Using Device Input and Output Control
  • Device Input and Output Reference
Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


About Device Input and Output

The DeviceIoControl function provides a device input and output control (IOCTL) interface through which an application can communicate directly with a device driver. The DeviceIoControl function is a general-purpose interface that can send control codes to a variety of devices. Each control codes represents an operation for the driver to perform.

This overview discusses the following topics:

  • Device handles
  • Device control codes


Device Handles

When you call the DeviceIoControl function, you must specify a handle that identifies the device to access. You can use the CreateFile function to get a device handle.

The CreateFile call must specify either the name of a device or the name of the driver associated with a device. To specify a device name, the lpszname parameter of CreateFile specifies a string with the format

\\.\DeviceName

The types of devices that you can open and the method that you must use to specify them in the CreateFile function depend on the platform on which your application is running.

  • Windows NT/2000 or later: The DeviceIoControl function can open a handle to a specific device. For example, to open a handle to the logical drive A:, specify "\\\\.\\a:". Alternatively, you can use the names "\\\\.\\PhysicalDrive0", "\\\\.\\PhysicalDrive1", and so on, to open handles to the physical drives on a system.
  • Windows 95/98/Me: For Win32-based applications, DeviceIoControl must specify a handle to a virtual device driver. For example, to open a handle to the system VxD, specify "\\\\.\\vwin32".

You should specify the FILE_SHARE_READ and FILE_SHARE_WRITE access flags when calling CreateFile to open a handle to a device driver. However, when you open a communications resource, such as a serial port, you must specify exclusive access. Use the other CreateFile parameters as follows when opening a device handle:

  • The fdwCreate parameter must specify the OPEN_EXISTING flag.
  • The hTemplateFile parameter must be NULL.
  • The fdwAttrsAndFlags parameter can specify FILE_FLAG_OVERLAPPED to indicate that the returned handle can be used in overlapped (asynchronous) I/O operations.


Device Control Codes

An application can use the DeviceIoControl function to send a control code to a device driver. The control code specifies the action that the driver is to perform. For example, a control code can ask a device driver to return information about the corresponding device, or direct the driver to carry out an action on the device, such as formatting a disk.

A number of standard control codes are defined in the SDK header files. For a list of standard control codes, see DeviceIoControl. In addition, device drivers can define their own device-specific control codes. The types of control codes you can specify depend on the device being accessed and the platform on which your application is running.

  • Windows NT/2000 or later: Applications can use the standard control codes or device-specific control codes to perform direct input and output operations on a floppy disk drive, hard disk drive, tape drive, or CD-ROM drive.
  • Windows 95/98/Me: Win32-based applications cannot use the standard control codes in the SDK header files. These applications are restricted to using the control codes supported by the virtual device driver being accessed. For example, the system VxD, VWIN32.VXD, supports the input and output control (IOCTL) functions originally provided by MS-DOS Interrupt 21h.

The control code specified in a DeviceIoControl call determines the values that must be specified for the other DeviceIoControl parameters. For example, a Win32-based application can specify the IOCTL_DISK_FORMAT_TRACKS control code. In this case, the lpvInBuffer parameter must point to a filled-in FORMAT_PARAMETERS structure, and the nInBufferSize parameter must specify the size of the structure.


Using Device Input and Output Control

  • Calling DeviceIoControl on Windows NT/2000
  • Calling DeviceIoControl on Windows 95/98


Calling DeviceIoControl on Windows NT/2000

On Microsoft® Windows NT®/Windows® 2000, an application can use the DeviceIoControl function to perform direct input and output operations on, or retrieve information about, a floppy disk drive, hard disk drive, tape drive, or CD-ROM drive. The following example demonstrates how to retrieve information about the first physical drive in the system. It uses the CreateFile function to retrieve the device handle to the first physical drive, and then uses DeviceIoControl with the IOCTL_DISK_GET_DRIVE_GEOMETRY control code to fill a DISK_GEOMETRY structure with information about the drive.

/* A program to show the use of DeviceIoControl under Windows NT and
   Windows 2000. The code of interest is in the subroutine
   GetDriveGeometry. The code in main shows how to interpret the
   results of the IOCTL call. */

#include <windows.h>
#include <winioctl.h>

BOOL
GetDriveGeometry(DISK_GEOMETRY *pdg)
{
  HANDLE hDevice;               // handle to the drive to be examined
  BOOL bResult;                 // results flag
  DWORD junk;                   // discard results

  hDevice = CreateFile("\\\\.\\PhysicalDrive0", // drive to open
                       0,       // don't need any access to the drive
                       FILE_SHARE_READ | FILE_SHARE_WRITE,  // share mode
                       NULL,    // default security attributes
                       OPEN_EXISTING,  // disposition
                       0,       // file attributes
                       NULL);   // don't copy any file's attributes

  if (hDevice == INVALID_HANDLE_VALUE) // we can't open the drive
  {
    return (FALSE);
  }

  bResult = DeviceIoControl(hDevice,  // device we are querying
      IOCTL_DISK_GET_DRIVE_GEOMETRY,  // operation to perform
                             NULL, 0, // no input buffer, so pass zero
                            pdg, sizeof(*pdg),  // output buffer
                            &junk, // discard count of bytes returned
                            (LPOVERLAPPED) NULL);  // synchronous I/O

  if (!bResult) // IOCTL failed
  {
    return (FALSE);
  }

  CloseHandle(hDevice);         // we're done with the handle

  return (bResult);
}

int
main(int argc, char *argv[])
{
  DISK_GEOMETRY pdg;            // disk drive geometry structure
  BOOL bResult;                 // generic results flag
  ULONGLONG DiskSize;           // holder for the size of the drive in bytes

  bResult = GetDriveGeometry (&pdg);

  if (bResult)
  {
    printf("Cylinders = %I64d\n", pdg.Cylinders);
    printf("Tracks per cylinder = %ld\n", (ULONG) pdg.TracksPerCylinder);
    printf("Sectors per track = %ld\n", (ULONG) pdg.SectorsPerTrack);
    printf("Bytes per sector = %ld\n", (ULONG) pdg.BytesPerSector);

    DiskSize = pdg.Cylinders.QuadPart * (ULONG)pdg.TracksPerCylinder *
      (ULONG)pdg.SectorsPerTrack * (ULONG)pdg.BytesPerSector;
    printf("Disk size = %I64d (Bytes) = %I64d (Mb)\n", DiskSize,
           DiskSize / (1024 * 1024));
  } else {
    printf ("Attempt to get drive geometry failed. Error %ld.\n",
            GetLastError ());
  }

  return ((int)bResult);
}

This example succeeds only when it runs on Windows NT/Windows 2000, for two reasons:

  • The standard device input/output control codes are available only on Windows NT/Windows 2000.
  • On Microsoft® Windows® 95/98, an application must specify a virtual device driver in the CreateFile function—not a specific device.


Calling DeviceIoControl on Windows 95/98

An application running on Windows 95/98 can use the DeviceIoControl function to send control codes directly to a virtual device driver (VxD). Any VxD can support any number of control codes, or none at all.

The system VxD, VWIN32.VXD, supports the input and output control (IOCTL) functions originally provided by MS-DOS Interrupt 21h. The following example shows how to call Get Media ID (Interrupt 21h Function 440Dh Minor Code 66h) from a Win32-based application:

#define VWIN32_DIOC_DOS_IOCTL 1

typedef struct _DEVIOCTL_REGISTERS
{
    DWORD reg_EBX;
    DWORD reg_EDX;
    DWORD reg_ECX;
    DWORD reg_EAX;
    DWORD reg_EDI;
    DWORD reg_ESI;
    DWORD reg_Flags;
} DEVIOCTL_REGISTERS, *PDEVIOCTL_REGISTERS;

typedef struct _MID
{
    WORD  midInfoLevel;
    DWORD midSerialNum;
    BYTE  midVolLabel[11];
    BYTE  midFileSysType[8];
} MID, *PMID;

BOOL GetMediaID(PMID pmid, UINT nDrive)
{
    DEVIOCTL_REGISTERS reg;

    reg.reg_EAX = 0x440D;       // IOCTL for block devices
    reg.reg_EBX = nDrive;       // zero-based drive ID
    reg.reg_ECX = 0x0866;       // Get Media ID command
    reg.reg_EDX = (DWORD) pmid; // receives media ID info

    if (!DoIOCTL(&reg))
        return FALSE;

    if (reg.reg_Flags & 0x8000) // error if carry flag set
        return FALSE;

    return TRUE;
}

BOOL DoIOCTL(PDEVIOCTL_REGISTERS preg)
{
    HANDLE hDevice;

    BOOL fResult;
    DWORD cb;

    preg->reg_Flags = 0x8000; // assume error (carry flag set)

    hDevice = CreateFile("\\\\.\\vwin32",
        GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_WRITE,
        (LPSECURITY_ATTRIBUTES) NULL, OPEN_EXISTING,
        FILE_ATTRIBUTE_NORMAL, (HANDLE) NULL);

    if (hDevice == (HANDLE) INVALID_HANDLE_VALUE)
        return FALSE;
    else
    {
        fResult = DeviceIoControl(hDevice, VWIN32_DIOC_DOS_IOCTL,
            preg, sizeof(*preg), preg, sizeof(*preg), &cb, 0);

        if (!fResult)
            return FALSE;
    }

    CloseHandle(hDevice);

    return TRUE;
}


Device Input and Output Reference

The following elements are used with device input and output.

  • Device Input and Output Functions
  • Device Input and Output Control Codes
  • Device Input and Output Structures
  • Device Input and Output Enumeration Types


Device Input and Output Functions

The following function is used with device input and output.

Function | Description
DeviceIoControl | Sends a control code directly to a specified device driver.


DeviceIoControl

The DeviceIoControl function sends a control code directly to a specified device driver, causing the corresponding device to perform the corresponding operation.

BOOL DeviceIoControl(
  HANDLE hDevice,              // handle to device
  DWORD dwIoControlCode,       // operation
  LPVOID lpInBuffer,           // input data buffer
  DWORD nInBufferSize,         // size of input data buffer
  LPVOID lpOutBuffer,          // output data buffer
  DWORD nOutBufferSize,        // size of output data buffer
  LPDWORD lpBytesReturned,     // byte count
  LPOVERLAPPED lpOverlapped    // overlapped information
);

Parameters

hDevice
[in] Handle to the device on which to perform the operation, typically a volume, directory, file, or alternate stream. To retrieve a device handle, use the CreateFile function.
dwIoControlCode
[in] Specifies the control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it.

For a list of the control codes and a short description of each control code, see Device Input and Output Control Codes .

For more detailed information on each control code, see its documentation. In particular, the documentation provides details on the usage of the lpInBuffer, nInBufferSize, lpOutBuffer, nOutBufferSize, and lpBytesReturned parameters.

lpInBuffer
[in] Pointer to a buffer that contains the data required to perform the operation.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not require input data.

nInBufferSize
[in] Specifies the size, in bytes, of the buffer pointed to by lpInBuffer.
lpOutBuffer
[out] Pointer to a buffer that receives the operation's output data.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not produce output data.

nOutBufferSize
[in] Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored into the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation produces no output data, and lpOutBuffer can be NULL, DeviceIoControl makes use of the variable pointed to by lpBytesReturned. After such an operation, the value of the variable is without meaning.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling GetOverlappedResult. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or an error occurs.

Return Values

If the function succeeds, the return value is nonzero.

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

Remarks

If hDevice was opened with FILE_FLAG_OVERLAPPED and the lpOverlapped parameter points to an OVERLAPPED structure, the operation is performed as an overlapped (asynchronous) operation. In this case, the OVERLAPPED structure must contain a handle to a manual-reset event object created by a call to the CreateEvent function. For more information on manual-reset event objects, see Synchronization.

Examples

For examples that use DeviceIoControl, see the following topics:

  • Calling DeviceIoControl on Windows NT/2000
  • Calling DeviceIoControl on Windows 95/98

For an example, see Calling DeviceIoControl on Windows NT/2000.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Device Input and Output Overview, Device Input and Output Functions, CreateEvent, CreateFile, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED


Device Input and Output Control Codes

The following control codes are used with batteries.

Value | Meaning
IOCTL_BATTERY_QUERY_INFORMATION | Retrieves a variety of information for the battery
IOCTL_BATTERY_QUERY_STATUS | Retrieves the current status for the battery.
IOCTL_BATTERY_QUERY_TAG | Retrieves the battery's current tag.
IOCTL_BATTERY_SET_INFORMATION | Sets various battery information.

The following control codes are used with changer devices.

Value | Meaning
IOCTL_CHANGER_EXCHANGE_MEDIUM | Moves a piece of media from a source element to one destination, and the piece of media originally in the first destination to a second destination.
IOCTL_CHANGER_GET_ELEMENT_STATUS | Retrieves the status of all elements or a specified number of elements of a particular type.
IOCTL_CHANGER_GET_PARAMETERS | Retrieves the parameters of the specified device.
IOCTL_CHANGER_GET_PRODUCT_DATA | Retrieves product data for the specified device.
IOCTL_CHANGER_GET_STATUS | Retrieves the current status of the specified device.
IOCTL_CHANGER_INITIALIZE_ELEMENT_STATUS | Initializes the status of all elements or the specified elements of a particular type.
IOCTL_CHANGER_MOVE_MEDIUM | Moves a piece of media to a destination.
IOCTL_CHANGER_QUERY_VOLUME_TAGS | Retrieves volume tag information for the specified elements.
IOCTL_CHANGER_REINITIALIZE_TRANSPORT | Physically recalibrates a transport element.
IOCTL_CHANGER_SET_ACCESS | Sets the state of the device's import/export port (IEport), door, or keypad.
IOCTL_CHANGER_SET_POSITION | Sets the changer's robotic transport mechanism to the specified element address.

The following are defragmentation control codes.

Value | Meaning
FSCTL_GET_RETRIEVAL_POINTERS | Retrieves information about a file's cluster use.
FSCTL_GET_VOLUME_BITMAP | Retrieves a bitmap of cluster allocation.
FSCTL_MOVE_FILE | Moves all or part of a file from one set of clusters to another within a volume.

The following control codes are used with file compression.

Value | Meaning
FSCTL_GET_COMPRESSION | Retrieves the compression state of a file or directory
FSCTL_SET_COMPRESSION | Sets the compression state of a file or directory.

The following control codes are used with NTFS change journals.

Value | Meaning
FSCTL_CREATE_USN_JOURNAL | Creates an NTFS change journal stream on a target volume or modifies an existing change journal stream.
FSCTL_DELETE_USN_JOURNAL | Deletes the NTFS change journal on a volume or awaits notification of deletion of an NTFS change journal.
FSCTL_ENUM_USN_DATA | Creates an enumeration that lists the NTFS change journal entries between two specified boundaries.
FSCTL_MARK_HANDLE | Marks a specified file or directory and its NTFS change journal record with information about changes to that file or directory.
FSCTL_QUERY_USN_JOURNAL | Queries for information on the current NTFS change journal, its records, and its capacity.
FSCTL_READ_USN_JOURNAL | Retrieves to the calling process the set of NTFS change journal records between two specified USN values.
FSCTL_WRITE_USN_CLOSE_RECORD | Generates a record in the change journal stream for the input file. This record will have the USN_REASON_CLOSE bit set.

The following control codes are used with opportunistic locks.

Value | Meaning
FSCTL_OPBATCH_ACK_CLOSE_PENDING | Notifies a server that a client application is about to close a file. Use this operation following notification that an opportunistic lock on the file is about to be broken.
FSCTL_OPLOCK_BREAK_ACK_NO_2 | Responds to notification that an opportunistic lock on a file is about to be broken. Use this operation to loose all opportunistic locks on the file but keep the file open.
FSCTL_OPLOCK_BREAK_ACKNOWLEDGE | Responds to notification that an exclusive opportunistic lock on a file is about to be broken. Use this operation to indicate that the file should receive a level 2 opportunistic lock.
FSCTL_OPLOCK_BREAK_NOTIFY | Allows the calling application to wait for completion of an opportunistic lock break.
FSCTL_REQUEST_BATCH_OPLOCK | Requests a batch opportunistic lock on a file.
FSCTL_REQUEST_FILTER_OPLOCK | Requests a filter opportunistic lock on a file.
FSCTL_REQUEST_OPLOCK_LEVEL_1 | Requests a level 1 opportunistic lock on a file.
FSCTL_REQUEST_OPLOCK_LEVEL_2 | Requests a level 2 opportunistic lock on a file.

The following control codes are used with reparse points.

Value | Meaning
FSCTL_DELETE_REPARSE_POINT | Deletes a reparse point for a file or directory.
FSCTL_GET_REPARSE_POINT | Retrieves reparse point data for a file or directory.
FSCTL_SET_REPARSE_POINT | Sets a reparse point on a file or directory.

The following control codes are used with sparse files.

Value | Meaning
FSCTL_QUERY_ALLOCATED_RANGES | Scans a file for ranges of the file for which disk space is allocated.
FSCTL_SET_SPARSE | Marks a file as a sparse file.
FSCTL_SET_ZERO_DATA | Sets a range of a files bytes to zeroes.

The following control codes are used with file input and output.

Control code | Operation
FSCTL_ALLOW_EXTENDED_DASD_IO | Signals the file system driver not to perform any I/O boundary checks on partition read or write calls. Instead, boundary checks are performed by the device driver.
FSCTL_CREATE_OR_GET_OBJECT_ID | Creates or retrieves a file system object identifier for an existing, open object in a Windows 2000 NTFS file system.
FSCTL_DELETE_OBJECT_ID | Removes a file system object identifier from an existing, open object in a Windows 2000 NTFS file system.
FSCTL_DISMOUNT_VOLUME | Dismounts a volume.
FSCTL_GET_HFS_INFORMATION | Retrieves Macintosh Finder information about the file associated with the input handle.
FSCTL_GET_OBJECT_ID | Retrieves the object identifier for an existing, open object in a Windows 2000 NTFS file system.
FSCTL_LOCK_VOLUME | Locks a volume.
FSCTL_READ_COMPRESSION | Reserved for future use.
FSCTL_READ_FROM_PLEX | Reads from the specified plex.
FSCTL_RECALL_FILE | Recalls a file from storage media managed by Remote Storage, the hierarchical storage management software in Windows 2000.
FSCTL_SET_OBJECT_ID | Sets a file system object identifier for an existing, open object in a Windows 2000 NTFS file system.
FSCTL_SET_OBJECT_ID_EXTENDED | Modifies user data in the object identifier of an existing, open object in a Windows 2000 NTFS file system.
FSCTL_UNLOCK_VOLUME | Unlocks a volume.
FSCTL_WRITE_COMPRESSION | Reserved for future use.

The following control codes are used with device input and output.

Control code | Operation
IOCTL_DISK_CREATE_DISK | Initializes the specified disk and disk partition table using the specified information.
IOCTL_DISK_FORMAT_TRACKS | Formats a contiguous set of disk tracks.
IOCTL_DISK_GET_DRIVE_GEOMETRY | Retrieves information about the physical disk's geometry.
IOCTL_DISK_GET_DRIVE_GEOMETRY_EX | Retrieves information about the physical disk's geometry.
IOCTL_DISK_GET_DRIVE_LAYOUT_EX | Retrieves information about the number of partitions on a disk and the features of each partition.
IOCTL_DISK_GET_LENGTH_INFO | Retrieves the length of the specified disk, volume, or partition.
IOCTL_DISK_GET_PARTITION_INFO_EX | Retrieves partition information for AT and EFI (Extensible Firmware Interface) partitions.
IOCTL_DISK_PERFORMANCE | Provides disk performance information.
IOCTL_DISK_REASSIGN_BLOCKS | Maps disk blocks to spare-block pool.
IOCTL_DISK_SET_DRIVE_LAYOUT_EX | Partitions a disk.
IOCTL_DISK_SET_PARTITION_INFO_EX | Sets the disk partition type.
IOCTL_DISK_VERIFY | Performs logical format of a disk extent.
IOCTL_SERIAL_LSRMST_INSERT | Enables or disables placement of a line and modem status data into the data stream.
IOCTL_STORAGE_CHECK_VERIFY | Checks for change in a removable-media device.
IOCTL_STORAGE_EJECT_MEDIA | Ejects media from a SCSI device.
IOCTL_STORAGE_GET_MEDIA_TYPES | Retrieves information about media support.
IOCTL_STORAGE_LOAD_MEDIA | Loads media into a device.
IOCTL_STORAGE_MEDIA_REMOVAL | Enables or disables the media eject mechanism.
IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS | Retrieves the physical location of the specified volume on one or more disks.
IOCTL_VOLUME_IS_CLUSTERED | Determines whether a volume is clustered.

Obsolete Control Codes

FSCTL_QUERY_FAT_BPB
IOCTL_DISK_CHECK_VERIFY
IOCTL_DISK_EJECT_MEDIA
IOCTL_DISK_GET_DRIVE_LAYOUT
IOCTL_DISK_GET_MEDIA_TYPES
IOCTL_DISK_GET_PARTITION_INFO
IOCTL_DISK_LOAD_MEDIA
IOCTL_DISK_MEDIA_REMOVAL
IOCTL_DISK_SET_DRIVE_LAYOUT
IOCTL_DISK_SET_PARTITION_INFO


FSCTL_ALLOW_EXTENDED_DASD_IO

The FSCTL_ALLOW_EXTENDED_DASD_IO control code signals the file system driver not to perform any I/O boundary checks on partition read or write calls. Instead, boundary checks are performed by the device driver.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to device
  FSCTL_ALLOW_EXTENDED_DASD_IO,  // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  NULL,                          // lpOutBuffer
  0,                             // nOutBufferSize
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the logical volume (partition) on which extended read or write operations are to be allowed. To retrieve a device handle, call the CreateFile function with the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter. The process must have Administrator privileges to read from or write to the partition.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_ALLOW_EXTENDED_DASD_IO for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBuffer
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

A call using the FSCTL_ALLOW_EXTENDED_DASD_IO control code should only be used with great caution by programmers familiar with the underlying structure of a hard drive and file system. Improper use or inaccurate checking in subsequent write operations to the partition can result in damage to data on the partition, or destruction of the entire partition.

The FSCTL_ALLOW_EXTENDED_DASD_IO control code is used to signal the file system driver not to perform any I/O boundary checks on read or write calls made with the specified handle. FSCTL_ALLOW_EXTENDED_DASD_IO allows access to hidden sectors, a part of the partition that might exist between the first sector of the partition (the boot parameter block) and the first useful sector of the partition. FSCTL_ALLOW_EXTENDED_DASD_IO also allows access to lost clusters, which might exist between the last useful cluster and the end of the partition.

I/O requests issued after this operation are passed directly to the device driver. If these subsequent calls request data beyond the partition boundary, the driver causes them to fail.

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

To retrieve a handle to a partition, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is the drive letter.

The application calling CreateFile must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter of CreateFile. For more information, see the Disk Devices section in CreateFile.

To determine the partition structure of the drive and to determine if the system recognizes the partition, use the IOCTL_DISK_GET_DRIVE_LAYOUT_EX control code. For similar information on a single partition, use the IOCTL_DISK_GET_PARTITION_INFO_EX control code. To determine the size of a cluster, use the GetDiskFreeSpaceEx or GetDiskFreeSpace function, as appropriate.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, GetDiskFreeSpace, GetDiskFreeSpaceEx, IOCTL_DISK_GET_DRIVE_LAYOUT_EX, IOCTL_DISK_GET_PARTITION_INFO_EX, OVERLAPPED


FSCTL_CREATE_OR_GET_OBJECT_ID

The FSCTL_CREATE_OR_GET_OBJECT_ID control code retrieves a file system object identifier for an existing, open object in a Windows 2000 NTFS file system. If no object identifier exists for the object, using FSCTL_CREATE_OR_GET_OBJECT_ID creates one.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to device
  FSCTL_CREATE_OR_GET_OBJECT_ID, // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  (LPVOID) lpOutBuffer,          // output buffer
  (DWORD) nOutBufferSize,        // size of output buffer
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object (a directory, file, or alternate stream) from which the object identifier is to be retrieved, and created if necessary. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_CREATE_OR_GET_OBJECT_ID for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the output buffer, a FILE_OBJECTID_BUFFER structure. The object identifier associated with the input hDevice is returned in this buffer.
nOutBufferSize
[in] Size, in bytes, of the output buffer, FILE_OBJECTID_BUFFER.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer. The lpBytesReturned value is meaningless until the operation is complete.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

Object identifiers are Windows 2000 internal objects used by the operating system to track other objects such as files and directories. They are invisible to most applications and should never be modified by applications. Modifying an object identifier can result in the loss of data from portions of a file, up to and including entire volumes of data. Also, there is no guarantee that code to manipulate object identifiers will be forward compatible with future versions of Windows. Therefore, use standard Win32 functions to manipulate object identifiers and other operating system objects.

This operation creates an object identifier if the object does not already have one. To test for the presence of an object identifier, and retrieve it if it exists, use the FSCTL_GET_OBJECT_ID operation. To create an object identifier without first testing for the presence of one, use the FSCTL_SET_OBJECT_ID operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FILE_OBJECTID_BUFFER, FSCTL_DELETE_OBJECT_ID, FSCTL_GET_OBJECT_ID, FSCTL_SET_OBJECT_ID, FSCTL_SET_OBJECT_ID_EXTENDED


FSCTL_CREATE_USN_JOURNAL

The FSCTL_CREATE_USN_JOURNAL control code creates a change journal stream on a target volume or modifies an existing change journal stream.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to volume
  FSCTL_CREATE_USN_JOURNAL,   // dwIoControlCode
  (LPVOID) lpInBuffer,        // input buffer
  (DWORD) nInBufferSize,      // size of input buffer
  NULL,                       // lpOutBuffer
  0,                          // nOutBufferSize
  (LPDWORD) lpBytesReturned,  // number of bytes returned
  (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the local volume for which the change journal stream is to be created or modified. To retrieve a volume handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_CREATE_USN_JOURNAL for this operation.
lpInBuffer
[in] Pointer to the input buffer, a CREATE_USN_JOURNAL_DATA structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Possible return values include the following.

Value | Meaning
ERROR_INVALID_FUNCTION | The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER | One or more parameters was invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.
ERROR_JOURNAL_DELETE_IN_PROGRESS | An attempt was made to read from, create, delete, or modify the journal while a journal deletion was under way, or an attempt was made to write a USN record while a journal deletion was under way.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

You can use FSCTL_CREATE_USN_JOURNAL to create a new change journal stream for a volume. After the creation of the stream, NTFS maintains a change journal for that volume.

You can also use FSCTL_CREATE_USN_JOURNAL to modify an existing change journal stream. If a change journal stream already exists, FSCTL_CREATE_USN_JOURNAL sets it to the characteristics provided in the CREATE_USN_JOURNAL_DATA structure. The change journal stream eventually grows or is trimmed to the new size limit imposed by CREATE_USN_JOURNAL_DATA.

To retrieve a handle to a volume, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.

For more information about creating a change journal, see Creating, Modifying, and Deleting a Change Journal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CREATE_USN_JOURNAL_DATA, CreateFile, DeviceIoControl, OVERLAPPED


FSCTL_DELETE_OBJECT_ID

The FSCTL_DELETE_OBJECT_ID control code removes a file system object identifier from an existing, open object in a Windows 2000 NTFS file system. The underlying object is not deleted.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  FSCTL_DELETE_OBJECT_ID,      // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the directory, file, or alternate stream from which the object identifier is to be deleted. The process opening the file must have restore privilege, and the file must be opened with restore intent. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_DELETE_OBJECT_ID for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

Object identifiers are Windows 2000 internal objects used by the operating system to track other objects such as files and directories. They are invisible to most applications and should never be modified by applications. Modifying an object identifier can result in the loss of data from portions of a file, up to and including entire volumes of data. Also, there is no guarantee that code to manipulate object identifiers will be forward compatible with future versions of Windows. Therefore, use standard Win32 functions to manipulate object identifiers and other operating system objects.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, CreateFile, FSCTL_CREATE_OR_GET_OBJECT_ID, FSCTL_GET_OBJECT_ID, FSCTL_SET_OBJECT_ID, FSCTL_SET_OBJECT_ID_EXTENDED


FSCTL_DELETE_REPARSE_POINT

The FSCTL_DELETE_REPARSE_POINT control code deletes a reparse point from the file or directory identified by the specified handle. Using FSCTL_DELETE_REPARSE_POINT does not delete the file or directory.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file or directory
  FSCTL_DELETE_REPARSE_POINT,  // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file, alternate stream, or directory from which the reparse point is to be deleted. The handle must have write access to the file or directory. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_DELETE_REPARSE_POINT for this operation.
lpInBuffer
[in] Pointer to a REPARSE_GUID_DATA_BUFFER structure. The ReparseTag member must specify the tag of the reparse point to be deleted and the ReparseGuid member must specify the GUID of the reparse point to be deleted. The ReparseDataLength member must be zero.
nInBufferSize
[in] Size, in bytes, of the buffer in the lpInBuffer parameter. This value must be at least the size indicated by REPARSE_GUID_DATA_BUFFER_HEADER_SIZE.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If hDevice was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. For extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_GET_REPARSE_POINT, FSCTL_SET_REPARSE_POINT


FSCTL_DELETE_USN_JOURNAL

The FSCTL_DELETE_USN_JOURNAL control code deletes the change journal on a volume or awaits notification of deletion of a change journal.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_DELETE_USN_JOURNAL,    // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the local volume from which the change journal is to be deleted. To retrieve a volume handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_DELETE_USN_JOURNAL for this operation.
lpInBuffer
[in] Pointer to the input buffer, a DELETE_USN_JOURNAL_DATA structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Possible return values include the following.

Value | Meaning
ERROR_INVALID_FUNCTION | The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER | One or more parameters was invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.
ERROR_JOURNAL_DELETE_IN_PROGRESS | An attempt was made to read from, create, delete, or modify the journal while a journal deletion was under way, or an attempt was made to write a USN record while a journal deletion was under way.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

You can use FSCTL_DELETE_USN_JOURNAL to delete a change journal. NTFS starts the deletion operation and returns immediately to the calling process, unless the USN_DELETE_FLAG_NOTIFY flag is set in the DeleteFlags member of DELETE_USN_JOURNAL_DATA.

If the USN_DELETE_FLAG_NOTIFY and USN_DELETE_FLAG_DELETE flags are both set, a call to FSCTL_DELETE_USN_JOURNAL begins the deletion process. The call then either blocks the calling thread and awaits the deletion (on a synchronous or nonoverlapped call), or sets up event notification by using an I/O completion port or other mechanism and returns (on an asynchronous or overlapped call).

You can also use FSCTL_DELETE_USN_JOURNAL to receive notification that a change journal deletion has been completed, by setting only USN_DELETE_FLAG_NOTIFY. If you do so, the FSCTL_DELETE_USN_JOURNAL operation either waits until the deletion completes before returning (on a synchronous or nonoverlapped call) or sets up event notification by using an I/O completion port or other mechanism (on an asynchronous or overlapped call).

The deletion on which your application receives notification may have been initiated by the current process, or some other process. For example, when your application is started, it can use FSCTL_DELETE_USN_JOURNAL to determine if a deletion started by some other process is in progress and, if so, exit.

Complete deletion of a change journal requires a scan of the volume on which the change journal resides, which may take a long time on a volume with many files. The operation continues to completion even across system restarts. Attempts to create, modify, delete, or query the change journal while deletion is in progress fail and return the error code ERROR_JOURNAL_DELETE_IN_PROGRESS.

The FSCTL_DELETE_USN_JOURNAL operation has a significant performance cost, so it should be used sparingly. An administrator should delete a journal when the current USN value approaches that of the maximum possible USN value.

To retrieve a handle to a volume, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CREATE_USN_JOURNAL_DATA, CreateFile, DELETE_USN_JOURNAL_DATA, DeviceIoControl, FSCTL_CREATE_USN_JOURNAL, OVERLAPPED


FSCTL_DISMOUNT_VOLUME

The FSCTL_DISMOUNT_VOLUME control code dismounts a volume.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_DISMOUNT_VOLUME,       // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume to be dismounted. To retrieve a handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_DISMOUNT_VOLUME for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. To retrieve a volume handle, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter of CreateFile.

If the specified volume is locked by another process, the operation fails. To prevent another process from locking the volume, lock it as soon as you open it.

A dismounted volume has the following properties:

  • There are no open files.
  • The operating system does not "know" about the volume.

The operating system tries to mount an unmounted volume as soon as any attempt is made to access it. For example, a call to GetLogicalDrives triggers the operating system to mount any unmounted volumes.

Dismounting a volume is useful whenever a volume needs to disappear for a while. For example, an application that changes a volume's file system from FAT to NTFS might follow these steps:

  1. Open the volume
  2. Lock the volume
  3. Format the volume
  4. Dismount the volume
  5. Unlock the volume
  6. Close the volume handle

A dismounting operation removes the volume from the FAT file system's "awareness." When the operating system mounts the volume, it appears as an NTFS volume.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, ExitThread, GetLogicalDrives


FSCTL_ENUM_USN_DATA

The FSCTL_ENUM_USN_DATA control code creates an enumeration that lists the change journal entries between two specified boundaries.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_ENUM_USN_DATA,         // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the local volume from which data is to be retrieved. To retrieve a volume handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_ENUM_USN_DATA for this operation.
lpInBuffer
[in] Pointer to the input buffer, an MFT_ENUM_DATA structure. The MFT_ENUM_DATA structure specifies the boundaries between which change journal entries are listed.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to the output buffer, cast to a void pointer.

Initially, the output buffer may be of any size larger than a ULONGLONG. On completion of the call, the buffer contains the USN of the record following the last record in the buffer. This USN can be used in a subsequent call to FSCTL_ENUM_USN_DATA to get the next set of records. The following shows an example of this in C:

DWORDLONG NextFileReferenceNumber;

where NextFileReferenceNumber is the USN of the next record. Use NextFileReferenceNumber in any subsequent call to FSCTL_ENUM_USN_DATA to enumerate records following those in the current output buffer.

Following NextFileReferenceNumber in the buffer is a series of USN_RECORD structures aligned on 64-bit boundaries. Each structure contains a change journal record. For more information on navigating the output buffer, see Walking a Buffer of Change Journal Records.

nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned. If the lpOutBuffer buffer is too small, lpBytesReturned receives the required buffer size.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling the GetOverlappedResult function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero and the contents of the output buffer pointed to by the lpOutBuffer parameter are meaningless. To get extended error information, call GetLastError.

Possible return values include the following.

Value | Meaning
ERROR_INVALID_FUNCTION | The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER | One or more parameters is invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

To enumerate a volume's change journal, use the FSCTL_ENUM_USN_DATA operation one or more times. On the first call, set the starting point, the StartFileReferenceNumber member of the MFT_ENUM_DATA structure, to (DWORDLONG)0. Each call to FSCTL_ENUM_USN_DATA retrieves the starting point for the subsequent call as the first entry in the output buffer.

To retrieve a handle to a volume, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.

There are two DeviceIoControl operations that return USN records, FSCTL_READ_USN_JOURNAL and FSCTL_ENUM_USN_DATA. Use the latter when you simply want a listing (enumeration) of the USN records between two USNs. Use the former when you want to select by USN.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_READ_USN_JOURNAL, GetOverlappedResult, MFT_ENUM_DATA, OVERLAPPED, USN_RECORD


FSCTL_GET_COMPRESSION

The FSCTL_GET_COMPRESSION control code retrieves the current compression state of a file or directory on a volume whose file system supports per-stream compression.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file
  FSCTL_GET_COMPRESSION,       // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file, alternate stream, or directory whose state of compression is to be retrieved. To retrieve a handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_GET_COMPRESSION for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives a USHORT indicating the current compression state of the file or directory.

This parameter can be one of the following values.
Value | Meaning
COMPRESSION_FORMAT_NONE | The file or directory is not compressed.
COMPRESSION_FORMAT_LZNT1 | The file or directory is compressed, using the LZNT1 compression format.
all other values | Reserved for future use.

nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer. The buffer must be large enough to contain one USHORT value.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

On this release, LZNT1 is the only compression algorithm implemented. Future releases may have additional compression methods.

COMPRESSION_FORMAT_DEFAULT is not a compression state so it is not included in the table under the lpOutBuffer parameter. This value is only used with the FSCTL_SET_COMPRESSION control code.

If the file system of the volume containing the specified file or directory does not support per-file or per-directory compression, the operation fails.

Windows NT versions 3.51 and later support file compression on volumes formatted with NTFS.

You can set the compression state of a file or directory by using the FSCTL_SET_COMPRESSION control code. You can also compress or uncompress a file using this control code.

You can retrieve the compression attribute of a file or directory by calling the GetFileAttributes function. The compression attribute indicates whether a file or directory is compressed. The compression state indicates whether a file or directory is compressed, and, if it is, the format of the compressed data.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FSCTL_SET_COMPRESSION, GetFileAttributes


FSCTL_GET_HFS_INFORMATION

The FSCTL_GET_HFS_INFORMATION control code retrieves Macintosh Finder information about the file associated with the input handle.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hFile,              // handle to file
  FSCTL_GET_HFS_INFORMATION,   // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hFile
[in] Handle to the file for which HFS information is sought. To retrieve a file handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of file on which to perform it. Use FSCTL_GET_HFS_INFORMATION for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the output buffer, an instance of the HFS_INFORMATION_BUFFER structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer, that is the size of an HFS_INFORMATION_BUFFER structure.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hFile was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the file was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hFile was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value, and the output buffer pointed to by lpvOutBuffer contains a valid HFS_INFORMATION_BUFFER structure.

If the operation fails, DeviceIoControl returns zero. In this case, the contents of the output buffer pointed to by lpvOutBuffer are meaningless. To get extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, GetOverlappedResult, GetQueuedCompletionStatus, HFS_INFORMATION_BUFFER, OVERLAPPED


FSCTL_GET_OBJECT_ID

The FSCTL_GET_OBJECT_ID control code retrieves the object identifier for an existing, open object in a Windows 2000 NTFS file system.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to device
  FSCTL_GET_OBJECT_ID,        // dwIoControlCode
  NULL,                       // lpInBuffer
  0,                          // nInBufferSize
  (LPVOID) lpOutBuffer,       // output buffer
  (DWORD) nOutBufferSize,     // size of output buffer
  (LPDWORD) lpBytesReturned,  // number of bytes returned
  (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the directory, file, or alternate stream from which the object identifier is to be retrieved. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_GET_OBJECT_ID for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the output buffer, a FILE_OBJECTID_BUFFER structure. The object identifier associated with the input hDevice is returned in this buffer.
nOutBufferSize
[in] Size, in bytes, of the output buffer, FILE_OBJECTID_BUFFER.
lpBytesReturned
[out] Pointer to a variable that receives the actual count of bytes returned by the function in the output buffer.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

Object identifiers are Windows 2000 internal objects used by the operating system to track other objects such as files and directories. They are invisible to most applications and should never be modified by applications. Modifying an object identifier can result in the loss of data from portions of a file, up to and including entire volumes of data. Also, there is no guarantee that code to manipulate object identifiers will be forward compatible with future versions of Windows. Therefore, use standard Win32 functions to manipulate object identifiers and other operating system objects.

If there is no object identifier associated with the specified handle, none is created and an error is returned. To create an object identifier where there was none previously, and return it, use the FSCTL_CREATE_OR_GET_OBJECT_ID operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, CreateFile, FILE_OBJECTID_BUFFER, FSCTL_CREATE_OR_GET_OBJECT_ID, FSCTL_DELETE_OBJECT_ID, FSCTL_SET_OBJECT_ID, FSCTL_SET_OBJECT_ID_EXTENDED


FSCTL_GET_REPARSE_POINT

The FSCTL_GET_REPARSE_POINT control code retrieves the reparse point data associated with the file or directory identified by the specified handle.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file or directory
  FSCTL_GET_REPARSE_POINT,     // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file, alternate stream, or directory from which to retrieve the reparse point data. To retrieve a handle, use the CreateFile function.
dwIoControlCode
[in] Specifies the FSCTL_GET_REPARSE_POINT control code.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a REPARSE_GUID_DATA_BUFFER structure that receives the reparse point data.
nOutBufferSize
[in] Size, in bytes, of the output buffer. This value must be at least the size indicated by REPARSE_GUID_DATA_BUFFER_HEADER_SIZE, plus the size of the expected user-defined data.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation and a larger buffer. Specify the maximum size, or determine the minimum length needed from the ReparseDataLength member of the REPARSE_GUID_DATA_BUFFER structure.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value, and the output buffer pointed to by lpOutBuffer contains a valid REPARSE_GUID_DATA_BUFFER structure, or a portion thereof, depending on the value of nOutBufferSize.

If the operation fails, DeviceIoControl returns zero. The contents of the output buffer pointed to by lpOutBuffer are meaningless. For extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_SET_REPARSE_POINT, FSCTL_DELETE_REPARSE_POINT, REPARSE_GUID_DATA_BUFFER


FSCTL_GET_RETRIEVAL_POINTERS

The FSCTL_GET_RETRIEVAL_POINTERS control code retrieves a data structure that describes the allocation and location on disk of a specific file.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to volume
  FSCTL_GET_RETRIEVAL_POINTERS, // dwIoControlCode
  (LPVOID) lpInBuffer,          // input buffer
  (DWORD) nInBufferSize,        // size of input buffer
  (LPVOID) lpOutBuffer,         // output buffer
  (DWORD) nOutBufferSize,       // size of output buffer
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the alternate stream, file or directory for which file mapping is to be retrieved. To retrieve a device handle, call the CreateFile function.

Encrypted files must be opened with FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE access. Other files need only be opened with FILE_READ_ATTRIBUTES access. For more information, see File and Directory Security.

dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_GET_RETRIEVAL_POINTERS for this operation.
lpInBuffer
[in] Pointer to the input buffer, a STARTING_VCN_INPUT_BUFFER structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to the output buffer, a RETRIEVAL_POINTERS_BUFFER variably sized structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a DWORD variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed or an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Possible return values include:

Last error | Possible interpretation
ERROR_INVALID_PARAMETER | One or more of the following: The handle used is neither a file, a directory nor a view index (such as $Quota). The size of the input buffer is smaller than sizeof(STARTING_VCN_INPUT_BUFFER) starting VCN is less than 0. Other invalid parameter.
ERROR_INSUFFICIENT_BUFFER | The size of the output buffer is smaller than sizeof( RETRIEVAL_POINTERS_BUFFER )
ERROR_NOT_READY | The volume is NTFS and is unmounted.
ERROR_INVALID_USER_BUFFER | One or both of the buffers passed in were not within a valid address range.
ERROR_HANDLE_EOF | The volume is NTFS and the requested starting VCN is past the end of the file.
NO_ERROR | The output buffer contains the full list of VCN-to-LCN mappings from the starting VCN through to the end of the file/stream.
ERROR_MORE_DATA | The output buffer contains a partial list of VCN-to-LCN mappings for the file. More entries exist beyond this list, but the buffer was too small to include them. The caller should call again with either a larger buffer, a higher starting VCN, or both. The first member of the return structure contains a count of extents actually returned.

Remarks

The FSCTL_GET_RETRIEVAL_POINTERS operation retrieves a variably sized data structure that describes the allocation and location on disk of a specific file. The structure describes the mapping between virtual cluster numbers (VCN, offsets within the file/stream space) and logical cluster numbers (LCN, offsets within the volume space).

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, Defragmentation, DeviceIoControl, CreateFile, GetLastError, GetOverlappedResult, GetQueuedCompletionStatus, STARTING_VCN_INPUT_BUFFER, RETRIEVAL_POINTERS_BUFFER, OVERLAPPED


FSCTL_GET_VOLUME_BITMAP

The FSCTL_GET_VOLUME_BITMAP control code retrieves a bitmap of occupied and available clusters on a volume.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to volume
  FSCTL_GET_VOLUME_BITMAP,    // dwIoControlCode
  (LPVOID) lpInBuffer,        // input buffer
  (DWORD) nInBufferSize,      // size of input buffer
  (LPVOID) lpOutBuffer,       // output buffer
  (DWORD) nOutBufferSize,     // size of output buffer
  (LPDWORD) lpBytesReturned,  // number of bytes returned
  (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume from which the bitmap is to be retrieved. To retrieve a device handle, call the CreateFile function. Only administrators can open volume handles.

Encrypted files must be opened with FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE access. Other files need only be opened with FILE_READ_ATTRIBUTES access. For more information, see File and Directory Security.

dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_GET_VOLUME_BITMAP for this operation.
lpInBuffer
[in] Pointer to the input buffer, a STARTING_LCN_INPUT_BUFFER structure. The starting LCN in the input buffer may be rounded down by the operation.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to the output buffer, a VOLUME_BITMAP_BUFFER variably sized structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a DWORD variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

A return value from GetLastError of ERROR_MORE_DATA indicates to the caller that the buffer was not large enough to accommodate a complete bitmap from the requested starting LCN to the last cluster on the volume. In this event, you can make subsequent FSCTL_GET_VOLUME_BITMAP calls to retrieve the remaining bitmap.

A return value from GetLastError of ERROR_INVALID_PARAMETER indicates either that there is no input buffer, that the starting LCN requested in the input buffer was less than zero, or that the starting LCN was greater than or equal to the total clusters on the volume.

A return value from GetLastError of ERROR_NOT_READY indicates that the volume is an NTFS volume, and it is not mounted.

Remarks

The FSCTL_GET_VOLUME_BITMAP control code retrieves a data structure that describes the allocation state of each cluster in the file system from the requested starting LCN to the last cluster on the volume. The bitmap uses one bit to represent each cluster:

  • The value 1 indicates that the cluster is allocated (in use).
  • The value 0 indicates that the cluster is not allocated (free).

Note that the bitmap represents a point in time, and can be incorrect as soon as it has been read if the volume has write activity. Thus, it is possible to attempt to move a cluster onto an allocated cluster in spite of a recent bitmap indicating that the cluster is unallocated. Programs using the DeviceIoControl FSCTL_MOVE_FILE control code must be prepared for this possibility.

The handle used here must be a Volume handle and have been opened with any access. Note that only Administrators can open Volume handles.

The starting LCN in the input buffer may be rounded down before the bitmap is calculated. The rounding limit is file system dependent.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, Defragmentation, DeviceIoControl, CreateFile, GetLastError, GetOverlappedResult, GetQueuedCompletionStatus, STARTING_LCN_INPUT_BUFFER, VOLUME_BITMAP_BUFFER, FSCTL_MOVE_FILE, OVERLAPPED


FSCTL_LOCK_VOLUME

The FSCTL_LOCK_VOLUME control code locks a volume. A locked volume can be accessed only through handles to the file object (*hDevice) that locks the volume.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to a volume
  FSCTL_LOCK_VOLUME,           // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume to be locked. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_LOCK_VOLUME for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. To retrieve this handle, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter of CreateFile.

This operation fails if there are any open files on the volume. Conversely, success of this operation indicates there are no open files.

This operation is useful for applications that need exclusive access to a volume for a period of time—for example, disk utility programs.

A locked volume remains locked until one of the following occurs:

  • The application uses the FSCTL_UNLOCK_VOLUME control code to unlock the volume.
  • The handle closes, either directly through CloseHandle, or indirectly when a process terminates.

The system flushes all cached data to the volume before locking it. For example, any data held in a lazy-write cache is written to the volume.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CloseHandle, CreateFile, DeviceIoControl, FSCTL_UNLOCK_VOLUME


FSCTL_MARK_HANDLE

The FSCTL_MARK_HANDLE control code marks a specified file or directory and its change journal record with information about changes to that file or directory.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file or directory
  FSCTL_MARK_HANDLE,           // dwIoControlCode
  (LPVOID)lpInBuffer,          // input buffer
  (DWORD)nInBufferSize,        // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or directory whose handle is to be marked. To retrieve a file or directory handle, call the CreateFile function. FSCTL_MARK_HANDLE only operates on files or directories.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_MARK_HANDLE for this operation.
lpInBuffer
[in] Pointer to the input buffer, a MARK_HANDLE_INFO structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Possible return values include the following.

Value | Meaning
ERROR_INVALID_FUNCTION | The volume containing the specified file or directory does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER | One or more parameters was invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a file or directory handle.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

FSCTL_MARK_HANDLE is the only change journal operation that operates on an individual file or directory. It does not affect anything the user can do with the item. Instead, it adds information to the file or directory, either providing information on how the operating system changed the item or adding a private data stream to the item.

If there are any changes to the file or directory, then the information added with FSCTL_MARK_HANDLE is also copied into the USN record created for the file or directory. For details on the information with which FSCTL_MARK_HANDLE can mark an item, see MARK_HANDLE_INFO.

It is not an error to use FSCTL_MARK_HANDLE while the volume's change journal is being deleted or is inactive. The appropriate information is applied to the file or directory regardless of the state of the change journal, as long as the change journal exists.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, MARK_HANDLE_INFO, OVERLAPPED


FSCTL_MOVE_FILE

The FSCTL_MOVE_FILE control code relocates one or more virtual clusters of a file from one logical cluster to another within the same volume.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_MOVE_FILE,             // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume that contains the file or directory whose clusters are to be moved. To retrieve a device handle, call the CreateFile function. Only administrators can open volume handles.

Encrypted files must be opened with FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE access. Other files need only be opened with FILE_READ_ATTRIBUTES access. For more information, see File and Directory Security.

dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_MOVE_FILE for this operation.
lpInBuffer
[in] Pointer to the input buffer, a MOVE_FILE_DATA structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed or an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError. The possible return values for GetLastError include the following values.

Last error | Interpretation
ERROR_INVALID_PARAMETER | One or more of the following: One or more of the logical clusters to which the file's virtual clusters are to be moved is an allocated cluster. The handle used for the IOCTL is not a DASD (volume) handle. The FileHandle member passed in the MOVE_FILE_DATA structure is not on the same volume as the volume handle specified in hDevice. The FileHandle member of the MOVE_FILE_DATA structure was for a paging file, change journal, or a file type other than a file, directory, or view index. The StartingVcn, StartingLcn, or ClusterCount member contains an invalid value. The FileHandle member is to an encrypted file, but the handle does not have FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE. This means that there is no security context for moving the data between cache and disk, so the FSCTL_MOVE_FILE operation cannot complete.
ERROR_INVALID_FUNCTION | This is an NTFS volume with a cluster size greater than 4KB.
ERROR_INSUFFICIENT_BUFFER | This is an NTFS volume and the input buffer was smaller than sizeof(MOVE_FILE_DATA).
ERROR_NOT_READY | The volume is NTFS and is unmounted.
ERROR_GEN_FAILURE | Typically, this means that on NTFS, another compress or FSCTL_MOVE_FILE operation is happening at the same time on the file specified by the FileHandle member.

Note that when a move operation returns with a failure, some of the clusters may have been moved. To determine if this is the case, you have to acquire a new bitmap or retrieve new pointers.

Remarks

The FSCTL_MOVE_FILE control code relocates one or more virtual clusters of a file from one logical cluster to another within the same volume. If the file to be moved is a sparse or compressed file, the granularity of the move is 16 clusters; otherwise, the granularity is one cluster.

Note that the bitmap returned by the DeviceIoControl FSCTL_GET_VOLUME_BITMAP control code represents a point in time, and can be incorrect as soon as it has been read if the volume has write activity. Thus, it is possible to attempt to move a cluster onto an allocated cluster in spite of a recent bitmap indicating that the cluster is unallocated. Programs using FSCTL_MOVE_FILE must be prepared for this possibility.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, Defragmentation, DeviceIoControl, CreateFile, GetLastError, GetOverlappedResult, GetQueuedCompletionStatus, MOVE_FILE_DATA, FSCTL_GET_VOLUME_BITMAP, OVERLAPPED


FSCTL_OPBATCH_ACK_CLOSE_PENDING

The FSCTL_OPBATCH_ACK_CLOSE_PENDING control code notifies a server that a client application is about to close a file. Use this operation following notification that an opportunistic lock on the file is about to be broken.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to file
  FSCTL_OPBATCH_ACK_CLOSE_PENDING, // dwIoControlCode
  NULL,                            // lpInBuffer
  0,                               // nInBufferSize
  NULL,                            // lpOutBuffer
  0,                               // nOutBufferSize
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream about which the request is made. To retrieve a file handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED. This file handle must be the same one for which the original opportunistic lock was requested.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_OPBATCH_ACK_CLOSE_PENDING for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

You should not make assumptions about the number of available virtual channels before calling this function, because the system and other plug-ins may have reserved virtual channels. Therefore, you should always check for a CHANNEL_RC_TOO_MANY_CHANNELS return code after calling this function.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Use the FSCTL_OPBATCH_ACK_CLOSE_PENDING control code when you have been notified that an opportunistic lock on a file is about to be broken, and you intend to close the file shortly. This operation does not request a new opportunistic lock.

If you do not intend to close the file, you can use either the FSCTL_OPLOCK_BREAK_ACKNOWLEDGE or FSCTL_OPLOCK_BREAK_ACK_NO_2 control code to respond to this notification. The former, used if the lock being broken is an exclusive opportunistic lock, indicates the file should receive a level 2 opportunistic lock instead. The latter requests the file be kept open but looses all locking.

Applications are notified that an opportunistic lock is broken by using the hEvent member of the OVERLAPPED structure associated with the file on which the opportunistic lock is broken. Applications may also use functions such as GetOverlappedResult and HasOverlappedIoCompleted.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_OPLOCK_BREAK_ACK_NO_2, FSCTL_OPLOCK_BREAK_ACKNOWLEDGE, GetOverlappedResult, HasOverlappedIoCompleted, Opportunistic Locks, OVERLAPPED


FSCTL_OPLOCK_BREAK_ACK_NO_2

The FSCTL_OPLOCK_BREAK_ACK_NO_2 control code responds to notification that an opportunistic lock on a file is about to be broken. Use this operation to unlock all opportunistic locks on the file but keep the file open.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to file
  FSCTL_OPLOCK_BREAK_ACK_NO_2,  // dwIoControlCode
  NULL,                         // lpInBuffer
  0,                            // nInBufferSize
  NULL,                         // lpOutBuffer
  0,                            // nOutBufferSize
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream on which the opportunistic lock is about to be broken. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED. This handle must be the same one for which the opportunistic lock was originally requested.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_OPLOCK_BREAK_ACK_NO_2 for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications that have requested an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

When you receive notification that an opportunistic lock on a file is about to be broken, use the FSCTL_OPLOCK_BREAK_ACK_NO_2 control code to indicate to the server that you want to relinquish any opportunistic locks but plan to keep the file open. If the operation returns the error code ERROR_IO_PENDING, the server has granted a level 2 lock on the file.

One alternative to using FSCTL_OPLOCK_BREAK_ACK_NO_2 is to indicate that the application is about to close the file anyway. Use the FSCTL_OPBATCH_ACK_CLOSE_PENDING control code for this response.

Another alternative, used if the lock being broken is an exclusive opportunistic lock, is to indicate the file should receive a level 2 opportunistic lock instead. Use the FSCTL_OPLOCK_BREAK_ACKNOWLEDGE control code for this response.

Applications are notified that an opportunistic lock is broken by using the hEvent member of the OVERLAPPED structure associated with the file on which the opportunistic lock is broken. Applications may also use functions such as GetOverlappedResult and HasOverlappedIoCompleted.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_OPBATCH_ACK_CLOSE_PENDING, FSCTL_OPLOCK_BREAK_ACKNOWLEDGE, GetOverlappedResult, HasOverlappedIoCompleted, Opportunistic Locks, OVERLAPPED


FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

The FSCTL_OPLOCK_BREAK_ACKNOWLEDGE control code responds to notification that an exclusive opportunistic lock on a file is about to be broken. Use this operation to indicate that the file should receive a level 2 opportunistic lock.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to file
  FSCTL_OPLOCK_BREAK_ACKNOWLEDGE,  // dwIoControlCode
  NULL,                            // lpInBuffer
  0,                               // nInBufferSize
  NULL,                            // lpOutBuffer
  0,                               // nOutBufferSize
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream on which the opportunistic lock is about to be broken. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED. This handle must be the same one for which the opportunistic lock was originally requested.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_OPLOCK_BREAK_ACKNOWLEDGE for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications that have requested an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE is a response to notification that a level 1, batch, or filter opportunistic lock on an application's file has been broken. It indicates to the server that the application should receive a level 2 opportunistic lock. If the operation returns the error code ERROR_IO_PENDING, the server has granted the application a level 2 lock on the file.

One alternative to using FSCTL_OPLOCK_BREAK_ACKNOWLEDGE is to indicate that the application is about to close the file anyway. Use the FSCTL_OPBATCH_ACK_CLOSE_PENDING control code for this response.

Another alternative is to request to keep the file open but loose all locking, by means of the FSCTL_OPLOCK_BREAK_ACK_NO_2 control code.

Applications are notified that an opportunistic lock is broken by using the hEvent member of the OVERLAPPED structure associated with the file on which the opportunistic lock is broken. Applications may also use functions such as GetOverlappedResult and HasOverlappedIoCompleted.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_OPBATCH_ACK_CLOSE_PENDING, FSCTL_OPLOCK_BREAK_ACK_NO_2, GetOverlappedResult, HasOverlappedIoCompleted, Opportunistic Locks, OVERLAPPED


FSCTL_OPLOCK_BREAK_NOTIFY

The FSCTL_OPLOCK_BREAK_NOTIFY control code allows the calling application to wait for completion of an opportunistic lock break. This operation is not useful to the Win32 programmer and is documented here only for completeness.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to file
  FSCTL_OPLOCK_BREAK_NOTIFY,  // dwIoControlCode
  NULL,                       // lpInBuffer
  0,                          // nInBufferSize
  NULL,                       // lpOutBuffer
  0,                          // nOutBufferSize
  (LPDWORD) lpBytesReturned,  // number of bytes returned
  (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream on which the operation is to be performed. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED. This handle must be the same one for which the opportunistic lock was originally requested.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_OPLOCK_BREAK_NOTIFY for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications that have requested an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

This operation is not useful at the Win32 level and is documented here only for completeness. CreateFile handles internally the problem that this operation was designed to handle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, Opportunistic Locks, OVERLAPPED


FSCTL_QUERY_ALLOCATED_RANGES

The FSCTL_QUERY_ALLOCATED_RANGES control code scans a file or alternate stream looking for ranges that may contain nonzero data. Only compressed or sparse files can have zeroed ranges known to the operating system. For other files, the output buffer will contain only a single entry that contains the starting point and the length requested.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to file
  FSCTL_QUERY_ALLOCATED_RANGES,    // dwIoControlCode
  (LPVOID) lpInBuffer,             // input buffer
  (DWORD) nInBufferSize,           // size of input buffer
  (LPVOID) lpOutBuffer,            // output buffer
  (DWORD) nOutBufferSize,          // size of output buffer
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream to be queried for allocated ranges. To retrieve a handle, use the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_QUERY_ALLOCATED_RANGES for this operation.
lpInBuffer
[in] Pointer to a FILE_ALLOCATED_RANGE_BUFFER structure that indicates the portion of the file to search for allocated ranges. The FileOffset member indicates the offset, in bytes, to the first byte of the range to search, and the Length member indicates its size, in bytes.
nInBufferSize
[in] Size, in bytes, of the lpInBuffer buffer.
lpOutBuffer
[out] Pointer to a buffer that receives an array of FILE_ALLOCATED_RANGE_BUFFER structures. Each structure in the array provides information about an allocated range within the file. The FileOffset member of each structure indicates the beginning of a range, and the Length member indicates its size, in bytes.

Ranges returned are always at least partially within the range specified in the lpInBuffer buffer.

nOutBufferSize
[in] Size, in bytes, of the lpOutBuffer buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value, and the output buffer pointed to by lpOutBuffer contains an array of valid FILE_ALLOCATED_RANGE_BUFFER structures.

If the operation fails, DeviceIoControl returns zero. The contents of the output buffer pointed to by lpOutBuffer are meaningless. For extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

NTFS rounds the input file offset down to a convenient boundary and the length up to a convenient boundary and then begins to walk through the file.

The operating system does not track every piece of zero or nonzero data. Because zero is often a perfectly legal datum, it would be misleading. Instead, the system tracks ranges where disk space is allocated. Where no disk space is allocated, all data are assumed to be zero. Allocated storage can contain zero or nonzero data. So all this operation does is return information about parts of the file where nonzero data may be located. It is up to the application to scan these parts of the file in accordance with the application's data conventions.

Each entry in the output array contains an offset and a length that indicates a range in the file that may contain nonzero data. The actual nonzero data, if any, is somewhere within this range, and the calling program must scan further within the range to locate it and determine if it really is valid data. Multiple instances of valid data may exist within the range.

Allocated ranges are subject to the rule that a memory mapped remote (network) file and an open handle to the file are not necessarily coherent. If you memory mapped a sparse network file and wrote nonzero data to previously unallocated regions of the file, disk space would be allocated for the new data. However, a call to FSCTL_QUERY_ALLOCATED_RANGES thereafter would not necessarily return a correct list of allocated regions. To ensure coherency between the view memory and the file handle, flush the data to the file with the FlushViewOfFile function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FILE_ALLOCATED_RANGE_BUFFER, FSCTL_SET_SPARSE, FSCTL_SET_ZERO_DATA


FSCTL_QUERY_FAT_BPB

The FSCTL_QUERY_FAT_BPB control code retrieves the first 36 bytes of a FAT16 or FAT12 volume.

Note This control code is obsolete. To retrieve some of the same information in a more structured manner, use functions like GetVolumeInformation and GetDriveType. If you cannot get the information any other way, use the CreateFile function to open the volume and the ReadFile function to access the raw hard drive.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to a volume
  FSCTL_QUERY_FAT_BPB,         // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume to be queried. To retrieve a device handle, use the CreateFile function. The handle can only be to a FAT12 or FAT16 volume. The call will fail on a FAT32 volume.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_QUERY_FAT_BPB for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the output buffer. This will be an FSCTL_QUERY_FAT_BPB_BUFFER structure.
nOutBufferSize
[in] Size of the output buffer, in bytes, which is sizeof(FSCTL_QUERY_FAT_BPB_BUFFER).
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value, and the output buffer pointed to by lpvOutBuffer contains a valid FSCTL_QUERY_FAT_BPB_BUFFER structure.

If the operation fails, DeviceIoControl returns zero. The contents of the output buffer pointed to by lpvOutBuffer are meaningless.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, FAT32 File System, CreateFile, DeviceIoControl, FSCTL_QUERY_FAT_BPB_BUFFER, GetDriveType, GetOverlappedResult, GetQueuedCompletionStatus, GetVolumeInformation, ReadFile


FSCTL_QUERY_USN_JOURNAL

The FSCTL_QUERY_USN_JOURNAL control code queries for information on the current change journal, its records, and its capacity.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_QUERY_USN_JOURNAL,     // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  lpOutBuffer,                 // output buffer
  nOutBufferSize,              // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the local volume from which data is to be retrieved. To retrieve a volume handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_QUERY_USN_JOURNAL for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the output buffer, which on successful return contains a USN_JOURNAL_DATA structure, containing information on the current change journal, its records, and its capacity.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned. If the lpOutBuffer buffer is too small, lpBytesReturned receives the required buffer size.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, this parameter must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, this parameter is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value, and the output buffer pointed to by lpOutBuffer contains a valid USN_JOURNAL_DATA structure.

If the operation fails, DeviceIoControl returns zero, and the contents of the output buffer pointed to by lpOutBuffer are meaningless. To get extended error information, call GetLastError.

Possible return values include the following.

Value | Meaning
ERROR_INVALID_FUNCTION | The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER | One or more parameters was invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.
ERROR_JOURNAL_DELETE_IN_PROGRESS | An attempt was made to read from, create, delete, or modify the journal while a journal deletion was under way, or an attempt was made to write a USN record while a journal deletion was under way.
ERROR_JOURNAL_NOT_ACTIVE | An attempt was made to write a USN record or to read the change journal while the journal was inactive.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

To retrieve a handle to a volume, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED, USN_JOURNAL_DATA


FSCTL_READ_FROM_PLEX

[This is preliminary documentation and subject to change.]

The FSCTL_READ_FROM_PLEX control code reads from the specified plex. It coordinates the read operation with the underlying dynamic volume manager.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_READ_FROM_PLEX,        // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which the geometry is to be returned. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_READ_FROM_PLEX for this operation.
lpInBuffer
Pointer to the input buffer, a PLEX_READ_DATA_REQUEST structure.
nInBufferSize
Size of the input buffer, in bytes.
lpOutBuffer
[out] Pointer to a buffer that receives the requested data from the plex. This buffer must be as large as the size specified by the ByteLength member of the PLEX_READ_DATA_REQUEST structure.
nOutBufferSize
[in] Size of the buffer pointed to by lpOutBuffer, in bytes.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, PLEX_READ_DATA_REQUEST


FSCTL_READ_USN_JOURNAL

The FSCTL_READ_USN_JOURNAL control code retrieves to the calling process the set of change journal records between two specified USN values.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_READ_USN_JOURNAL,      // dwIoControlCode
  (LPVOID)lpInBuffer,          // input buffer
  (DWORD)nInBufferSize,        // size of input buffer
  (LPVOID)lpOutBuffer,         // output buffer
  (DWORD)nOutBufferSize,       // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the local volume from which change journal data is to be returned. To retrieve a volume handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_READ_USN_JOURNAL for this operation.
lpInBuffer
[in] Pointer to the input buffer, a READ_USN_JOURNAL_DATA structure.

The structure member BytesToWaitFor, which indicates the size in bytes of unfiltered data to retrieve from the change journal, should not exceed the size of the output buffer pointed to by the lpOutBuffer parameter.

The structure member Timeout is ignored for asynchronously opened handles.

nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to the output buffer, which on completion of the call contains the USN of the record following the last record in the buffer. This USN can be used in a subsequent call to FSCTL_READ_USN_JOURNAL to get the next set of records. The following shows an example of this in C:
DWORDLONG NextUsn;

where NextUsn is the next USN value.

Following the next USN in the buffer are zero or more USN_RECORD structures aligned on packed 64-bit boundaries. Each structure contains a change journal record. For more information on navigating the output buffer, see Walking a Buffer of Change Journal Records.

nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned. If the lpOutBuffer buffer is too small, lpBytesReturned receives the required buffer size.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero, and the contents of the output buffer pointed to by lpOutBuffer are meaningless. To get extended error information, call GetLastError.

Possible return values include the following.

Value | Meaning
ERROR_INVALID_FUNCTION | The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER | One or more parameters is invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.
ERROR_JOURNAL_DELETE_IN_PROGRESS | An attempt was made to read from, create, delete, or modify the journal while a journal deletion was under way, or an attempt was made to write a USN record while a journal deletion was under way.
ERROR_JOURNAL_NOT_ACTIVE | An attempt was made to write a USN record or to read the change journal while the journal was inactive.
ERROR_JOURNAL_ENTRY_DELETED | A nonzero USN was specified that is less than the first USN in the change journal. The specified USN may have been valid at one time, but it has since been deleted.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

To retrieve a handle to a volume, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.

There are two DeviceIoControl control codes that return USN records, FSCTL_READ_USN_JOURNAL and FSCTL_ENUM_USN_DATA. Use the latter when you simply want a listing (enumeration) of the USN records between two USNs. Use the former when you want to select by USN.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_ENUM_USN_DATA, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED, READ_USN_JOURNAL_DATA, USN_RECORD


FSCTL_RECALL_FILE

The FSCTL_RECALL_FILE control code recalls a file from storage media managed by Remote Storage, the hierarchical storage management software in Windows 2000.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file or directory
  FSCTL_RECALL_FILE,           // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file whose data is to be recalled from remote storage media. The handle must be opened with read access, write access, or both. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_RECALL_FILE for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

FSCTL_RECALL_FILE recovers a file from storage, such as tape, that is managed by Remote Storage. If the file is already cached locally, this operation has no effect. Similarly, if the file has not been moved to remote storage, this operation has no effect.

FSCTL_RECALL_FILE operates only on systems on which Remote Storage is installed. Where Remote Storage is not installed, the operation fails, and GetLastError returns the error code ERROR_INVALID_FUNCTION.

Directories cannot be moved to remote storage. Calling FSCTL_RECALL_FILE for a directory fails, and GetLastError returns the error code ERROR_INVALID_HANDLE.

Files stored on media managed by Remote Storage are usually recalled when an application attempts to make the first access to data. An application that opens a file without immediately accessing the data can speed up the first access by using FSCTL_RECALL_FILE immediately after opening the file. However, you should avoid indiscriminate recall of files that your application will not touch.

You need not test a file's attributes for the flag FILE_ATTRIBUTE_OFFLINE with the function GetFileAttributes before calling FSCTL_RECALL_FILE. A test is unnecessary because an online file is not affected by this operation. However, any operating system call takes processor time. To conserve processor time, call GetFileAttributes to check file attributes to determine if FSCTL_RECALL_FILE is necessary.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

The following short program, Recall.c, shows a command-line utility that recalls one or more files indicated on the command line from remote storage.

/*++
Copyright (c) 1999  Microsoft Corporation

Module Name:
    Recall.c
    Simple utility to recall files managed by Remote Storage
*/

#include <windows.h>
#include <malloc.h>
#include <stdio.h>
#include <winioctl.h>

DWORD
RecallFile(PUCHAR FileName);

int _cdecl
main(int argc, char *argv[])
{
  HANDLE file;
  LONG   i;
  DWORD  nbytes;

  if (argc < 2) {
    printf("Usage: recall <file-name1> <file-name2> ...\n");
    return 1;
  }

  for (i = 1; i < argc; i++) {
    (void) RecallFile(argv[i]);
  }
  return 0;
}

DWORD
RecallFile(IN PUCHAR FileName)
  /*++
Routine Description
    Recalls the file with the supplied path.
Arguments
    FileName - Path of the file to be recalled
Return Value
    0                   - Recall is successful.
    Any other value     - Error code for the operation.

--*/

{
  HANDLE fileHandle;
  DWORD  nbytes;
  DWORD  errorCode = 0;

  fileHandle = CreateFile(FileName,
                          GENERIC_READ,
                          FILE_SHARE_READ,
                          NULL,
                          OPEN_EXISTING,
                          FILE_ATTRIBUTE_NORMAL,
                          NULL);
  if (fileHandle == INVALID_HANDLE_VALUE) {
    errorCode = GetLastError();
    printf("Couldn't open file %s: error %x\n", FileName, errorCode);
    return errorCode;
  }

  if (!DeviceIoControl(fileHandle,
                       FSCTL_RECALL_FILE,
                       NULL,
                       0,
                       NULL,
                       0,
                       &nbytes,
                       NULL)) {

    errorCode = GetLastError();
    printf("Couldn't recall file %s: error %x\n", FileName, errorCode);
  }
  CloseHandle(fileHandle);
  return errorCode;
}

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, GetFileAttributes, OVERLAPPED


FSCTL_REQUEST_BATCH_OPLOCK

The FSCTL_REQUEST_BATCH_OPLOCK control code requests a batch opportunistic lock on a file.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file
  FSCTL_REQUEST_BATCH_OPLOCK,  // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream for which the opportunistic lock is requested. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_REQUEST_BATCH_OPLOCK for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value. To determine if the opportunistic lock is granted, call GetLastError. The code ERROR_IO_PENDING indicates that the opportunistic lock was granted. Any other code indicates that the request was denied.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications requesting an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application. An attempt to use this operation to request opportunistic locks from remote servers will result in the request being denied.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

An FSCTL_REQUEST_BATCH_OPLOCK control code fails if the file is opened in nonoverlapped (synchronous) mode.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, Opportunistic Locks, OVERLAPPED


FSCTL_REQUEST_FILTER_OPLOCK

The FSCTL_REQUEST_FILTER_OPLOCK control code requests a filter opportunistic lock on a file.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to file
  FSCTL_REQUEST_FILTER_OPLOCK,  // dwIoControlCode
  NULL,                         // lpInBuffer
  0,                            // nInBufferSize
  NULL,                         // lpOutBuffer
  0,                            // nOutBufferSize
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream for which the opportunistic lock is requested. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED. The file or alternate stream cannot be opened for write or delete access and must be shared with all other applications.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_REQUEST_FILTER_OPLOCK for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value. To determine if the opportunistic lock is granted, call GetLastError. The code ERROR_IO_PENDING indicates that the opportunistic lock was granted. Any other code indicates that the request was denied.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications requesting an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application. An attempt to use this operation to request opportunistic locks from remote servers will result in the request being denied.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

An FSCTL_REQUEST_FILTER_OPLOCK control code fails if the file is opened in nonoverlapped (synchronous) mode.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, Opportunistic Locks, OVERLAPPED


FSCTL_REQUEST_OPLOCK_LEVEL_1

The FSCTL_REQUEST_OPLOCK_LEVEL_1 control code requests a level 1 opportunistic lock on a file.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to file
  FSCTL_REQUEST_OPLOCK_LEVEL_1,  // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  NULL,                          // lpOutBuffer
  0,                             // nOutBufferSize
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream on which the opportunistic lock is requested. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_REQUEST_OPLOCK_LEVEL_1 for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value. To determine if the opportunistic lock is granted, call GetLastError. The code ERROR_IO_PENDING indicates that the opportunistic lock was granted. Any other code indicates that the request was denied.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications requesting an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application. An attempt to use this operation to request opportunistic locks from remote servers will result in the request being denied.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

An FSCTL_REQUEST_OPLOCK_LEVEL_1 control code fails if the file is opened in nonoverlapped (synchronous) mode.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, Opportunistic Locks, OVERLAPPED


FSCTL_REQUEST_OPLOCK_LEVEL_2

The FSCTL_REQUEST_OPLOCK_LEVEL_2 control code requests a level 2 opportunistic lock on a file.

To perform this operation, call the DeviceIoControl function using the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to file
  FSCTL_REQUEST_OPLOCK_LEVEL_2,  // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  NULL,                          // lpOutBuffer
  0,                             // nOutBufferSize
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream on which the opportunistic lock is requested. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_REQUEST_OPLOCK_LEVEL_2 for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value. To determine if the opportunistic lock is granted, call GetLastError. The code ERROR_IO_PENDING indicates that the opportunistic lock was granted. Any other code indicates that the request was denied.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications requesting an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application. An attempt to use this operation to request opportunistic locks from remote servers will result in the request being denied.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Use FSCTL_REQUEST_OPLOCK_LEVEL_2 to request a level 2 opportunistic lock on a file. A client file system can cache read data (but not write data) locally as long as the level 2 lock is held.

The file system provides no acknowledgment to the application that requested the level 2 opportunistic lock when the lock is broken. After the lock is broken, the network redirector is notified not to regard as valid any cached data from the file.

An FSCTL_REQUEST_OPLOCK_LEVEL_2 control code fails if the file is opened in nonoverlapped (synchronous) mode.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, Opportunistic Locks, OVERLAPPED


FSCTL_SET_COMPRESSION

The FSCTL_SET_COMPRESSION control code sets the compression state of a file or directory on a volume whose file system supports per-file and per-directory compression. You can use FSCTL_SET_COMPRESSION to compress or uncompress a file or directory on such a volume.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file or directory
  FSCTL_SET_COMPRESSION,       // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file, alternate stream, or directory to be compressed or decompressed.. To retrieve a device handle, call the CreateFile function.

Windows 2000 or later: The handle must have read-write access.

dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_SET_COMPRESSION for this operation.
lpInBuffer
[in] Pointer to a buffer containing a USHORT that specifies a new compression state for the file or directory.

This parameter can be one of the following values.
Value | Meaning
COMPRESSION_FORMAT_NONE | Uncompress the file or directory.
COMPRESSION_FORMAT_DEFAULT | Compress the file or directory, using the default compression format.
COMPRESSION_FORMAT_LZNT1 | Compress the file or directory, using the LZNT1 compression format.
all other values | Reserved for future use.

nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer. The buffer must be large enough to contain one USHORT value.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

LZNT1 is the only compression algorithm implemented. As a result, LZNT1 is used as the DEFAULT compression method. Future releases may have additional compression methods which may be used as the DEFAULT.

If the file system of the volume containing the specified file or directory does not support per-file or per-directory compression, the operation fails.

Windows NT versions 3.51 and later support file compression on volumes formatted with NTFS.

The compression state change of the file or directory occurs synchronously with the call to DeviceIoControl.

To retrieve the compression state of a file or directory, use the FSCTL_GET_COMPRESSION control code.

To retrieve the compression attribute of a file or directory, use the GetFileAttributes function. The compression attribute indicates whether a file or directory is compressed. The compression state indicates whether a file or directory is compressed and, if it is, the format of the compressed data.

Directories are not actually compressed by this operation. Rather, the operation sets the default state for files created in the directory to be compressed.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FSCTL_GET_COMPRESSION, GetFileAttributes


FSCTL_SET_OBJECT_ID

The FSCTL_SET_OBJECT_ID control code sets a file system object identifier for an existing, open object in a Windows 2000 NTFS file system.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to device
  FSCTL_SET_OBJECT_ID,        // dwIoControlCode
  (LPVOID) lpInBuffer,        // input buffer
  (DWORD) nInBufferSize,      // size of input buffer
  NULL,                       // lpOutBuffer
  0,                          // nOutBufferSize
  (LPDWORD) lpBytesReturned,  // number of bytes returned
  (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the directory, file, or alternate stream on which the object identifier is to be set. The HANDLE object must describe a file or directory that is open with restore privilege. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_SET_OBJECT_ID for this operation.
lpInBuffer
[in] Pointer to the input buffer, a FILE_OBJECTID_BUFFER structure.
nInBufferSize
[in] Size, in bytes, of the input buffer, FILE_OBJECTID_BUFFER.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

Object identifiers are Windows 2000 internal objects used by the operating system to track other objects such as files and directories. They are invisible to most applications and should never be modified by applications. Modifying an object identifier can result in the loss of data from portions of a file, up to and including entire volumes of data. Also, there is no guarantee that code to manipulate object identifiers will be forward compatible with future versions of Windows. Therefore, use standard Win32 functions to manipulate object identifiers and other operating system objects.

Use this operation to explicitly set an object identifier to a value you provide. The value must be a value unique to the volume. Use the FSCTL_CREATE_OR_GET_OBJECT_ID operation to have NTFS generate an object identifier if the object does not already have one.

An attempt to set an object identifier on an object that already has an object identifier will fail. An attempt to use an object identifier that already exists in the volume will also fail.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, CreateFile, FILE_OBJECTID_BUFFER, FSCTL_CREATE_OR_GET_OBJECT_ID, FSCTL_GET_OBJECT_ID, FSCTL_SET_OBJECT_ID, FSCTL_SET_OBJECT_ID_EXTENDED


FSCTL_SET_OBJECT_ID_EXTENDED

The FSCTL_SET_OBJECT_ID_EXTENDED control code modifies user data in the object identifier of an existing, open object in a Windows 2000 NTFS file system.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to device
  FSCTL_SET_OBJECT_ID_EXTENDED,  // dwIoControlCode
  (LPVOID) lpInBuffer,           // input buffer
  (DWORD) nInBufferSize,         // size of input buffer
  NULL,                          // lpOutBuffer
  0,                             // nOutBufferSize
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the directory, file, or alternate stream on which object identifier user data is to be set. The process must have write access to or restore privilege for the object. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_SET_OBJECT_ID_EXTENDED for this operation.
lpInBuffer
[in] Pointer to the input buffer, the ExtendedInfo member of a FILE_OBJECTID_BUFFER structure. The ObjectId member of the structure is ignored. Only the user data, in the ExtendedInfo member of the structure, is applied to the object identifier.
nInBufferSize
[in] Size, in bytes, of the input buffer, which is the size of the ExtendedInfo member of the FILE_OBJECTID_BUFFER structure.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

Object identifiers are Windows 2000 internal objects used by the operating system to track other objects such as files and directories. They are invisible to most applications and should never be modified by applications. Modifying an object identifier can result in the loss of data from portions of a file, up to and including entire volumes of data. Also, there is no guarantee that code to manipulate object identifiers will be forward compatible with future versions of Windows. Therefore, use standard Win32 functions to manipulate object identifiers and other operating system objects.

This operation sets the user data only in the object identifier. The ObjectId member of the FILE_OBJECTID_BUFFER structure is ignored. There is no mechanism for modifying the ObjectId member. The user should not attempt to modify user data, as it is created and used internally by Windows 2000 system services.

To set the object identifier on an object that does not already have one, use the FSCTL_SET_OBJECT_ID control code. To have NTFS generate an object identifier if one does not exist, use the FSCTL_CREATE_OR_GET_OBJECT_ID control code.

The typical use of the FSCTL_SET_OBJECT_ID_EXTENDED control code is where the application program does not use the user data generated by NTFS when the FSCTL_CREATE_OR_GET_OBJECT_ID control code is used. The FSCTL_SET_OBJECT_ID_EXTENDED control code would be used to install user-provided data in place of the data generated by NTFS.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, CreateFile, FILE_OBJECTID_BUFFER, FSCTL_CREATE_OR_GET_OBJECT_ID, FSCTL_GET_OBJECT_ID, FSCTL_SET_OBJECT_ID, FSCTL_SET_OBJECT_ID_EXTENDED


FSCTL_SET_REPARSE_POINT

The FSCTL_SET_REPARSE_POINT control code sets a reparse point on a file or directory.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to file or directory
  FSCTL_SET_REPARSE_POINT,     // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file, alternate stream, or directory on which to set a reparse point. The handle must have write access to the file or directory. To retrieve a handle, use the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_SET_REPARSE_POINT for this operation.
lpInBuffer
[in] Pointer to a REPARSE_GUID_DATA_BUFFER structure that contains the reparse point data.
nInBufferSize
[in] Size, in bytes, of the lpInBuffer buffer. This value must be at least the size indicated by REPARSE_GUID_DATA_BUFFER_HEADER_SIZE plus the size of the user-defined data.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. For extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FSCTL_GET_REPARSE_POINT, FSCTL_DELETE_REPARSE_POINT, REPARSE_GUID_DATA_BUFFER


FSCTL_SET_SPARSE

The FSCTL_SET_SPARSE control code marks the indicated file as sparse. In a sparse file, large ranges of zeroes may not require disk allocation. Space for nonzero data will be allocated as needed as the file is written.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to a file
  FSCTL_SET_SPARSE,            // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream to be made sparse. To retrieve a file handle, use the CreateFile function . The file must be opened with either write permission or with the FILE_FLAG_BACKUP_SEMANTICS flag. The file must be on a Windows 2000 file system or later. This operation cannot be called with a directory or volume handle.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_SET_SPARSE for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

The FSCTL_SET_SPARSE control code sets the FILE_ATTRIBUTE_SPARSE_FILE attribute of the specified file. The only way to clear this attribute is to overwrite the file, for example, by calling the CreateFile function with the CREATE_ALWAYS flag..

You cannot create a sparse file by calling CreateFile with FILE_ATTRIBUTE_SPARSE_FILE in the dwFlagsAndAttributes parameter. You must use the FSCTL_SET_SPARSE control code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FSCTL_QUERY_ALLOCATED_RANGES, FSCTL_SET_ZERO_DATA


FSCTL_SET_ZERO_DATA

The FSCTL_SET_ZERO_DATA control code fills a specified range of a file with zeroes. If the file is sparse or compressed, NTFS may deallocate disk space within the file. This sets the range of bytes to zeroes without extending the file size.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to a file
  FSCTL_SET_ZERO_DATA,         // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or alternate stream on which zero data is to be written. The file must be on a Windows 2000 file system or later. To retrieve a file handle, use the CreateFile function . The file need not be a sparse file.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_SET_ZERO_DATA for this operation.
lpInBuffer
[in] Pointer to a FILE_ZERO_DATA_INFORMATION structure that specifies the range of the file to set to zeroes. The FileOffset member is the byte offset of the first byte to set to zeroes, and the BeyondFinalZero member is the byte offset of the first byte beyond the last zeroed byte.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. For extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

If you use the WriteFile function to write zeroes to a sparse file, the file system allocates disk space for the data that you are writing. If you use the FSCTL_SET_ZERO_DATA control code to write zeroes to a sparse file and the zeroed region is large enough, the file system may not allocate disk space.

If you use the FSCTL_SET_ZERO_DATA control code to write zeros to a nonsparse file, zeros will be written to the file. The system will allocate disk storage for all of the range zeroed out. It is equivalent to using the WriteFile function to write zeros to a file.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FILE_ZERO_DATA_INFORMATION, FSCTL_QUERY_ALLOCATED_RANGES, FSCTL_SET_SPARSE


FSCTL_UNLOCK_VOLUME

The FSCTL_UNLOCK_VOLUME control code unlocks a volume.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to a volume
  FSCTL_UNLOCK_VOLUME,         // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume to be unlocked. To retrieve a handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_UNLOCK_VOLUME for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

To lock a volume, use the FSCTL_LOCK_VOLUME control code.

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. To retrieve this handle, call CreateFile with the lpFileName parameter set to a string of the following form:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the dwShareMode parameter of CreateFile.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_LOCK_VOLUME


FSCTL_WRITE_USN_CLOSE_RECORD

The FSCTL_WRITE_USN_CLOSE_RECORD control code generates a record in the change journal stream for the input file. This record will have the USN_REASON_CLOSE flag.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to volume
  FSCTL_WRITE_USN_CLOSE_RECORD,  // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  (LPVOID) lpOutBuffer,          // output buffer
  (DWORD) nOutBufferSize,        // size of output buffer
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the file or directory for which the close record is to be generated. To retrieve a handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_WRITE_USN_CLOSE_RECORD for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the output buffer that receives the USN for the close record.
nOutBufferSize
[in] Size, in bytes, of the output buffer. Must be large enough to store a USN.
lpBytesReturned
[out] Pointer to a variable that receives the actual count of bytes returned by the function in the output buffer. The lpBytesReturned value is meaningless until the operation is complete or if there is no output buffer. With an asynchronous call, the programmer must provide a non-NULL pointer to a valid value.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned is used internally and cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Possible return values include the following.

Value | Meaning
ERROR_INVALID_FUNCTION | The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER | One or more parameters was invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.
ERROR_JOURNAL_DELETE_IN_PROGRESS | An attempt was made to read from, create, delete, or modify the journal while a journal deletion was under way, or an attempt was made to write a USN record while a journal deletion was under way.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section for DeviceIoControl.

You can use FSCTL_WRITE_USN_CLOSE_RECORD to force a close record into the change journal for the input handle. The close record will contain any current USN reasons for this file as well. The output buffer will return the USN value associated with this operation.

For more information about creating a change journal, see Creating, Modifying, and Deleting a Change Journal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, OVERLAPPED


IOCTL_BATTERY_QUERY_INFORMATION

The IOCTL_BATTERY_QUERY_INFORMATION control code retrieves a variety of information for the battery.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to battery
  IOCTL_BATTERY_QUERY_INFORMATION, // dwIoControlCode
  (LPVOID) lpInBuffer,             // input buffer
  (DWORD) nInBufferSize,           // size of input buffer
  (LPVOID) lpOutBuffer,            // output buffer
  (DWORD) nOutBufferSize,          // size of output buffer
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the battery on which information is to be returned. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_BATTERY_QUERY_INFORMATION for this operation.
lpInBuffer
[in] Pointer to a BATTERY_QUERY_INFORMATION structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to the return buffer. The data type (and, therefore, size) of the return buffer depends on the information requested in the BATTERY_QUERY_INFORMATION_LEVEL member of the input BATTERY_QUERY_INFORMATION structure.

The following table shows the data returned by a given information level.
Information level | Return
BatteryDeviceName | Zero ('\0') terminated Unicode (wide) string that contains the battery's name.
BatteryEstimatedTime | ULONG estimated battery run time, in seconds. If the rate of drain provided in the AtRate element of the BATTERY_QUERY_INFORMATION structure is 0, this calculation is based on the present rate of drain. If AtRate is nonzero, the time returned is the expected run time for the given rate. If the estimated time is unknown (for example, the battery is not discharging and the AtRate specified is 0), BATTERY_UNKNOWN_TIME is returned. Note that this value is not very accurate on some battery systems. The value may vary widely depending on present power usage, which could be affected by disk activity and other factors. There is no notification mechanism for changes in this value.
BatteryGranularityInformation | An array of BATTERY_REPORTING_SCALE structures, never more than four entries.
BatteryInformation | BATTERY_INFORMATION structure.
BatteryManufactureDate | Retrieves the date the cell pack was manufactured. The BATTERY_MANUFACTURE_DATE structure is returned.
BatteryManufactureName | Zero ('\0') terminated Unicode (wide) string that contains the name of the manufacturer of the battery.
BatterySerialNumber | Zero ('\0') terminated Unicode (wide) string that contains the battery's serial number.
BatteryTemperature | ULONG that contains the battery's current temperature in 10ths of a degree Kelvin.
BatteryUniqueID Zero ('\0') terminated Unicode (wide) string that uniquely identifies the battery. This value can be used to track a specific battery.
In the case of smart batteries, this ID will be the concatenation of the manufacturer's name, device name, date of manufacture, and a printable representation of the serial number.
This value is not intended to be displayed to the end user.

nOutBufferSize
[in] Size, in bytes, of the output buffer. Depending on the information level of data requested, this may be a variably sized buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Some information about batteries is optional or may be meaningless for some batteries. If the particular type of data requested is not available for the current battery, then ERROR_INVALID_FUNCTION is returned.

All requests for battery information will complete with the status of ERROR_FILE_NOT_FOUND whenever the BatteryTag element of the request does not match that of the current battery tag. This ensures that the returned battery information matches that of the requested battery. (See Battery Tags for more information.)

Remarks

This battery IOCTL retrieves a variety of information for the battery. The input parameter structure, BATTERY_QUERY_INFORMATION, indicates the type of information to be returned and when the battery information should be returned. The data type and contents of the output buffer vary based on the data requested.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, BATTERY_QUERY_INFORMATION, IOCTL_BATTERY_QUERY_STATUS, IOCTL_BATTERY_QUERY_TAG, IOCTL_BATTERY_SET_INFORMATION


IOCTL_BATTERY_QUERY_STATUS

The IOCTL_BATTERY_QUERY_STATUS control code retrieves the current status of the battery.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to battery
  IOCTL_BATTERY_QUERY_STATUS, // dwIoControlCode
  (LPVOID) lpInBuffer,        // input buffer
  (DWORD) nInBufferSize,      // size of input buffer
  (LPVOID) lpOutBuffer,       // output buffer
  (DWORD) nOutBufferSize,     // size of output buffer
  (LPDWORD) lpBytesReturned,  // number of bytes returned
  (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the battery from which information is to be returned. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_BATTERY_QUERY_STATUS for this operation.
lpInBuffer
[in] Pointer to a BATTERY_WAIT_STATUS structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to a BATTERY_STATUS structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This battery IOCTL retrieves the status of the battery at the time the operation returns. The input parameter structure, BATTERY_WAIT_STATUS, indicates when the battery status is to be processed and returned.

Requests for battery status can be for immediate return or can be set to wait for a particular condition before completing. For example, a request for battery information can be made that waits until the battery capacity reaches a specified point or the battery state changes.

All requests for battery information will complete with the status of ERROR_FILE_NOT_FOUND whenever the BatteryTag element of the request does not match that of the current battery tag. (See Battery Tags for more information.) This is used to ensure that the returned battery information matches that of the requested battery.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, BATTERY_STATUS, BATTERY_WAIT_STATUS, IOCTL_BATTERY_QUERY_INFORMATION, IOCTL_BATTERY_QUERY_TAG, IOCTL_BATTERY_SET_INFORMATION


IOCTL_BATTERY_QUERY_TAG

The IOCTL_BATTERY_QUERY_TAG control code retrieves the battery's current tag.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to battery
  IOCTL_BATTERY_QUERY_TAG,     // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the battery from which the tag is to be retrieveed. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_BATTERY_QUERY_TAG for this operation.
lpInBuffer
[in] Pointer to a ULONG input buffer. The value indicates the number of milliseconds to wait if there is no battery. A value of -1 indicates the request will wait indefinitely (or until canceled by some other event).
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to a ULONG output buffer, which, on success, contains the current battery tag.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This battery IOCTL retrieves the battery's current tag. The battery tag is a unique nonzero value for any specified handle to the battery devices per battery, and changes whenever the physical battery changes. When a battery is not present, this request will wait the indicated time, and then return ERROR_FILE_NOT_FOUND. (See Battery Tags for more information.)

All requests for other battery information require the caller to supply the matching battery tag. This ensures that the caller is receiving information for the same battery for every request and ensures that the caller is aware of battery changes without constant polling.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_BATTERY_QUERY_INFORMATION, IOCTL_BATTERY_QUERY_STATUS, IOCTL_BATTERY_SET_INFORMATION


IOCTL_BATTERY_SET_INFORMATION

The IOCTL_BATTERY_SET_INFORMATION control code sets various battery information. The input parameter structure, BATTERY_SET_INFORMATION , indicates which battery status information is to be set.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to battery
  IOCTL_BATTERY_SET_INFORMATION, // dwIoControlCode
  (LPVOID) lpInBuffer,           // input buffer
  (DWORD) nInBufferSize,         // size of input buffer
  NULL,                          // lpOutBuffer
  0,                             // nOutBufferSize
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the battery on which the information is to be set. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_BATTERY_SET_INFORMATION for this operation.
lpInBuffer
[in] Pointer to a BATTERY_SET_INFORMATION structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

All requests to set battery information will complete with the status of ERROR_FILE_NOT_FOUND if the battery tag of the request does not match that of the current battery tag.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, BATTERY_SET_INFORMATION, IOCTL_BATTERY_QUERY_INFORMATION, IOCTL_BATTERY_QUERY_STATUS, IOCTL_BATTERY_QUERY_TAG


IOCTL_CHANGER_EXCHANGE_MEDIUM

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_EXCHANGE_MEDIUM control code moves a piece of media from a source element to one destination, and the piece of media originally in the first destination to a second destination.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to device
  IOCTL_CHANGER_EXCHANGE_MEDIUM, // dwIoControlCode
  (LPVOID) lpInBuffer,           // input buffer
  (DWORD) nInBufferSize,         // size of input buffer
  NULL,                          // lpOutBuffer
  0,                             // nOutBufferSize
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_EXCHANGE_MEDIUM for this operation.
lpInBuffer
[in] Pointer to a CHANGER_EXCHANGE_MEDIUM structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

To swap two pieces of media, specify the source as the value for the second destination.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_EXCHANGE_MEDIUM, DeviceIoControl


IOCTL_CHANGER_GET_ELEMENT_STATUS

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_GET_ELEMENT_STATUS control code retrieves the status of all elements or a specified number of elements of a particular type.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                 // handle to device
  IOCTL_CHANGER_GET_ELEMENT_STATUS, // dwIoControlCode
  (LPVOID) lpInBuffer,              // input buffer
  (DWORD) nInBufferSize,            // size of input buffer
  (LPVOID) lpOutBuffer,             // output buffer
  (DWORD) nOutBufferSize,           // size of output buffer
  (LPDWORD) lpBytesReturned,        // number of bytes returned
  (LPOVERLAPPED) lpOverlapped       // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_GET_ELEMENT_STATUS for this operation.
lpInBuffer
[in] Pointer to a CHANGER_READ_ELEMENT_STATUS structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to a CHANGER_ELEMENT_STATUS or CHANGER_ELEMENT_STATUS_EX structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_ELEMENT_STATUS, CHANGER_ELEMENT_STATUS_EX, CHANGER_READ_ELEMENT_STATUS, DeviceIoControl


IOCTL_CHANGER_GET_PARAMETERS

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_GET_PARAMETERS control code retrieves the parameters of the specified device.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to device
  IOCTL_CHANGER_GET_PARAMETERS, // dwIoControlCode
  NULL,                         // lpInBuffer
  0,                            // nInBufferSize
  (LPVOID) lpOutBuffer,         // output buffer
  (DWORD) nOutBufferSize,       // size of output buffer
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_GET_PARAMETERS for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a GET_CHANGER_PARAMETERS structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, GET_CHANGER_PARAMETERS


IOCTL_CHANGER_GET_PRODUCT_DATA

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_GET_PRODUCT_DATA control code retrieves product data for the specified device.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,               // handle to device
  IOCTL_CHANGER_GET_PRODUCT_DATA, // dwIoControlCode
  NULL,                           // lpInBuffer
  0,                              // nInBufferSize
  (LPVOID) lpOutBuffer,           // output buffer
  (DWORD) nOutBufferSize,         // size of output buffer
  (LPDWORD) lpBytesReturned,      // number of bytes returned
  (LPOVERLAPPED) lpOverlapped     // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_GET_PRODUCT_DATA for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a CHANGER_PRODUCT_DATA structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_PRODUCT_DATA, DeviceIoControl


IOCTL_CHANGER_GET_STATUS

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_GET_STATUS control code retrieves the current status of the specified device.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_CHANGER_GET_STATUS,    // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_GET_STATUS for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl


IOCTL_CHANGER_INITIALIZE_ELEMENT_STATUS

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_INITIALIZE_ELEMENT_STATUS control code initializes the status of all elements or the specified elements of a particular type.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                        // handle to device
  IOCTL_CHANGER_INITIALIZE_ELEMENT_STATUS, // dwIoControlCode
  (LPVOID) lpInBuffer,                     // input buffer
  (DWORD) nInBufferSize,                   // size of input buffer
  NULL,                                    // lpOutBuffer
  0,                                       // nOutBufferSize
  (LPDWORD) lpBytesReturned,               // number of bytes returned
  (LPOVERLAPPED) lpOverlapped              // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_INITIALIZE_ELEMENT_STATUS for this operation.
lpInBuffer
[in] Pointer to a CHANGER_INITIALIZE_ELEMENT_STATUS structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_INITIALIZE_ELEMENT_STATUS, DeviceIoControl


IOCTL_CHANGER_MOVE_MEDIUM

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_MOVE_MEDIUM control code moves a piece of media to a destination.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to device
  IOCTL_CHANGER_MOVE_MEDIUM,    // dwIoControlCode
  (LPVOID) lpInBuffer,          // input buffer
  (DWORD) nInBufferSize,        // size of input buffer
  NULL,                         // lpOutBuffer
  0,                            // nOutBufferSize
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_MOVE_MEDIUM for this operation.
lpInBuffer
[in] Pointer to a CHANGER_MOVE_MEDIUM structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_MOVE_MEDIUM, DeviceIoControl


IOCTL_CHANGER_QUERY_VOLUME_TAGS

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_QUERY_VOLUME_TAGS control code retrieves volume tag information for the specified elements.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to device
  IOCTL_CHANGER_QUERY_VOLUME_TAGS, // dwIoControlCode
  (LPVOID) lpInBuffer,             // input buffer
  (DWORD) nInBufferSize,           // size of input buffer
  (LPVOID) lpOutBuffer,            // output buffer
  (DWORD) nOutBufferSize,          // size of output buffer
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_QUERY_VOLUME_TAGS for this operation.
lpInBuffer
[in] Pointer to a CHANGER_SEND_VOLUME_TAG_INFORMATION structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
[out] Pointer to a READ_ELEMENT_ADDRESS_INFO structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_SEND_VOLUME_TAG_INFORMATION, DeviceIoControl, READ_ELEMENT_ADDRESS_INFO


IOCTL_CHANGER_REINITIALIZE_TRANSPORT

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_REINITIALIZE_TRANSPORT control code physically recalibrates a transport element. Recalibration may involve returning the transport to its home position.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                     // handle to device
  IOCTL_CHANGER_REINITIALIZE_TRANSPORT, // dwIoControlCode
  (LPVOID) lpInBuffer,                  // input buffer
  (DWORD) nInBufferSize,                // size of input buffer
  NULL,                                 // lpOutBuffer
  0,                                    // nOutBufferSize
  (LPDWORD) lpBytesReturned,            // number of bytes returned
  (LPOVERLAPPED) lpOverlapped           // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_REINITIALIZE_TRANSPORT for this operation.
lpInBuffer
[in] Pointer to a CHANGER_ELEMENT structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_ELEMENT, DeviceIoControl


IOCTL_CHANGER_SET_ACCESS

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_SET_ACCESS control code sets the state of the device's import/export port (IEport), door, or keypad.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to device
  IOCTL_CHANGER_SET_ACCESS,     // dwIoControlCode
  (LPVOID) lpInBuffer,          // input buffer
  (DWORD) nInBufferSize,        // size of input buffer
  NULL,                         // lpOutBuffer
  0,                            // nOutBufferSize
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_SET_ACCESS for this operation.
lpInBuffer
[in] Pointer to a CHANGER_SET_ACCESS structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_SET_ACCESS, DeviceIoControl


IOCTL_CHANGER_SET_POSITION

[This is preliminary documentation and subject to change.]

The IOCTL_CHANGER_SET_POSITION control code sets the changer's robotic transport mechanism to the specified element address. This optimizes moving or exchanging media by positioning the transport beforehand.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to device
  IOCTL_CHANGER_SET_POSITION,   // dwIoControlCode
  (LPVOID) lpInBuffer,          // input buffer
  (DWORD) nInBufferSize,        // size of input buffer
  NULL,                         // lpOutBuffer
  0,                            // nOutBufferSize
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the device. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_CHANGER_SET_POSITION for this operation.
lpInBuffer
[in] Pointer to a CHANGER_SET_POSITION structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CHANGER_SET_POSITION, DeviceIoControl


IOCTL_DISK_CHECK_VERIFY

The IOCTL_DISK_CHECK_VERIFY control code has been superseded by the IOCTL_STORAGE_CHECK_VERIFY control code.

See Also

Device Input and Output Overview, Device Input and Output Control Codes


IOCTL_DISK_CREATE_DISK

[This is preliminary documentation and subject to change.]

The IOCTL_DISK_CREATE_DISK control code initializes the specified disk and disk partition table using the information in the CREATE_DISK structure.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to device
  IOCTL_DISK_CREATE_DISK,        // dwIoControlCode
  (LPVOID) lpInBuffer,           // input buffer
  (DWORD) nInBufferSize,         // size of input buffer
  NULL,                          // lpOutBuffer
  0,                             // nOutBufferSize
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the disk device on which the information is to be set. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_CREATE_DISK for this operation.
lpInBuffer
[in] Pointer to a CREATE_DISK structure.
nInBufferSize
[in] Size, in bytes, of the input buffer.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CREATE_DISK, DeviceIoControl


IOCTL_DISK_EJECT_MEDIA

The IOCTL_DISK_EJECT_MEDIA control code has been superseded by the IOCTL_STORAGE_EJECT_MEDIA control code.

See Also

Device Input and Output Overview, Device Input and Output Control Codes


IOCTL_DISK_FORMAT_TRACKS

The IOCTL_DISK_FORMAT_TRACKS control code formats a specified, contiguous set of tracks on a disk.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_DISK_FORMAT_TRACKS,    // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object to be formatted. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_FORMAT_TRACKS for this operation.
lpInBuffer
[in] Pointer to a buffer that contains a FORMAT_PARAMETERS data structure.
nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a FORMAT_PARAMETERS data structure.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for floppy disk devices only.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, FORMAT_PARAMETERS


IOCTL_DISK_GET_DRIVE_GEOMETRY

The IOCTL_DISK_GET_DRIVE_GEOMETRY control code retrieves information about the physical disk's geometry: type, number of cylinders, tracks per cylinder, sectors per track, and bytes per sector.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to device
  IOCTL_DISK_GET_DRIVE_GEOMETRY, // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  (LPVOID) lpOutBuffer,          // output buffer
  (DWORD) nOutBufferSize,        // size of output buffer
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which the geometry is to be returned. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_GET_DRIVE_GEOMETRY for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives a DISK_GEOMETRY data structure.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer, which must be greater than or equal to the size of a DISK_GEOMETRY data structure.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DISK_GEOMETRY, IOCTL_STORAGE_GET_MEDIA_TYPES


IOCTL_DISK_GET_DRIVE_GEOMETRY_EX

[This is preliminary documentation and subject to change.]

The IOCTL_DISK_GET_DRIVE_GEOMETRY_EX control code retrieves information about the physical disk's geometry: type, number of cylinders, tracks per cylinder, sectors per track, and bytes per sector.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                 // handle to volume
  IOCTL_DISK_GET_DRIVE_GEOMETRY_EX, // dwIoControlCode
  NULL,                             // lpInBuffer
  0,                                // nInBufferSize
  (LPVOID) lpOutBuffer,             // output buffer
  (DWORD) nOutBufferSize,           // size of output buffer
  (LPDWORD) lpBytesReturned,        // number of bytes returned
  (LPOVERLAPPED) lpOverlapped       // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which the geometry is to be returned. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_GET_DRIVE_GEOMETRY_EX for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives a DISK_GEOMETRY_EX data structure.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer, which must be greater than or equal to the size of a DISK_GEOMETRY_EX data structure.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DISK_GEOMETRY_EX


IOCTL_DISK_GET_DRIVE_LAYOUT

The IOCTL_DISK_GET_DRIVE_LAYOUT control code retrieves information about the number of partitions on a disk and the features of each partition.

Note IOCTL_DISK_GET_DRIVE_LAYOUT has been superseded by IOCTL_DISK_GET_DRIVE_LAYOUT_EX, which retrieves layout information for AT and EFI (Extensible Firmware Interface) partitions.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_DISK_GET_DRIVE_LAYOUT, // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which the drive layout is to be retrieved. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_GET_DRIVE_LAYOUT for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives a DRIVE_LAYOUT_INFORMATION structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data received.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DRIVE_LAYOUT_INFORMATION, IOCTL_DISK_GET_DRIVE_LAYOUT_EX, IOCTL_DISK_SET_DRIVE_LAYOUT


IOCTL_DISK_GET_DRIVE_LAYOUT_EX

[This is preliminary documentation and subject to change.]

The IOCTL_DISK_GET_DRIVE_LAYOUT_EX control code retrieves information about the number of partitions on a disk and the features of each partition.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,               // handle to device
  IOCTL_DISK_GET_DRIVE_LAYOUT_EX, // dwIoControlCode
  NULL,                           // lpInBuffer
  0,                              // nInBufferSize
  (LPVOID) lpOutBuffer,           // output buffer
  (DWORD) nOutBufferSize,         // size of output buffer
  (LPDWORD) lpBytesReturned,      // number of bytes returned
  (LPOVERLAPPED) lpOverlapped     // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which the drive layout is to be retrieved. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_GET_DRIVE_LAYOUT_EX for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives the drive layout data. For more information, see DRIVE_LAYOUT_INFORMATION_EX.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data received.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DRIVE_LAYOUT_INFORMATION_EX, IOCTL_DISK_SET_DRIVE_LAYOUT_EX


IOCTL_DISK_GET_LENGTH_INFO

[This is preliminary documentation and subject to change.]

The IOCTL_DISK_GET_LENGTH_INFO control code retrieves the length, in bytes, of the specified disk, volume, or partition.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to device
  IOCTL_DISK_GET_LENGTH_INFO,    // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  (LPVOID) lpOutBuffer,          // output buffer
  (DWORD) nOutBufferSize,        // size of output buffer
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the disk, volume, or partition. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_GET_LENGTH_INFO for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the output buffer that receives a GET_LENGTH_INFORMATION structure.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the actual count of bytes returned by the function in the output buffer. The lpBytesReturned value is meaningless because there is no output buffer. With an asynchronous call, the programmer must provide a non-NULL pointer to a valid value.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned is used internally and cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation should be used instead of IOCTL_DISK_GET_PARTITION_INFO_EX for volumes that do not have partition info—such as partition type or number of hidden sectors.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, GET_LENGTH_INFORMATION


IOCTL_DISK_GET_MEDIA_TYPES

The IOCTL_DISK_GET_MEDIA_TYPES control code has been superseded by the IOCTL_STORAGE_GET_MEDIA_TYPES control code.

See Also

Device Input and Output Overview, Device Input and Output Control Codes


IOCTL_DISK_GET_PARTITION_INFO

The IOCTL_DISK_GET_PARTITION_INFO control code retrieves information about the type, size, and nature of a disk partition.

Note IOCTL_DISK_GET_PARTITION_INFO has been superseded by IOCTL_DISK_GET_PARTITION_INFO_EX, which retrieves partition information for AT and EFI (Extensible Firmware Interface) partitions.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to a partition
  IOCTL_DISK_GET_PARTITION_INFO,   // dwIoControlCode
  NULL,                            // lpInBuffer
  0,                               // nInBufferSize
  (LPVOID) lpOutBuffer,            // output buffer
  (DWORD) nOutBufferSize,          // size of output buffer
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which partition information is to be retrieved. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_GET_PARTITION_INFO for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that will receive a PARTITION_INFORMATION data structure.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain a PARTITION_INFORMATION data structure.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO_EX, IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION


IOCTL_DISK_GET_PARTITION_INFO_EX

[This is preliminary documentation and subject to change.]

The IOCTL_DISK_GET_PARTITION_INFO_EX control code retrieves information about the type, size, and nature of a disk partition.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                 // handle to a partition
  IOCTL_DISK_GET_PARTITION_INFO_EX, // dwIoControlCode
  NULL,                             // lpInBuffer
  0,                                // nInBufferSize
  (LPVOID) lpOutBuffer,             // output buffer
  (DWORD) nOutBufferSize,           // size of output buffer
  (LPDWORD) lpBytesReturned,        // number of bytes returned
  (LPOVERLAPPED) lpOverlapped       // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which partition information is to be retrieved. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_GET_PARTITION_INFO_EX for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives the partition information. For more information, see PARTITION_INFORMATION_EX.
nOutBufferSize
[in] Size, in bytes, of the output buffer.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_DISK_SET_PARTITION_INFO_EX, PARTITION_INFORMATION_EX


IOCTL_DISK_LOAD_MEDIA

The IOCTL_DISK_LOAD_MEDIA control code has been superseded by the IOCTL_STORAGE_LOAD_MEDIA control code.

See Also

Device Input and Output Overview, Device Input and Output Control Codes


IOCTL_DISK_MEDIA_REMOVAL

The IOCTL_DISK_MEDIA_REMOVAL control code has been superseded by the IOCTL_STORAGE_MEDIA_REMOVAL control code.

See Also

Device Input and Output Overview, Device Input and Output Control Codes


IOCTL_DISK_PERFORMANCE

The IOCTL_DISK_PERFORMANCE control code provides disk performance information.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_DISK_PERFORMANCE,      // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which performance information is to be retrieved.. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_PERFORMANCE to request this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives a DISK_PERFORMANCE data structure.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain a DISK_PERFORMANCE data structure.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DISK_PERFORMANCE


IOCTL_DISK_REASSIGN_BLOCKS

The IOCTL_DISK_REASSIGN_BLOCKS control code directs the disk device to map one or more blocks to its spare-block pool.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_DISK_REASSIGN_BLOCKS,  // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object on which blocks are to be reassigned. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_REASSIGN_BLOCKS for this operation.
lpInBuffer
[in] Pointer to a buffer that contains a REASSIGN_BLOCKS data structure specifying the blocks to reassign to its spare block pool.
nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain the REASSIGN_BLOCKS data structure. Note that this structure is really a header followed by an array of block specifiers; thus, it varies in size according to the number of blocks to be reassigned; each block after the first adds the size of a DWORD to the overall size.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, REASSIGN_BLOCKS


IOCTL_DISK_SET_DRIVE_LAYOUT

The IOCTL_DISK_SET_DRIVE_LAYOUT control code partitions a disk as specified by drive layout and partition information data.

Note IOCTL_DISK_SET_DRIVE_LAYOUT has been superseded by IOCTL_DISK_SET_DRIVE_LAYOUT_EX, which retrieves layout information for AT and EFI (Extensible Firmware Interface) partitions.

To perform this operation, call the DeviceIoControl function with the parameters specified below.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_DISK_SET_DRIVE_LAYOUT, // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the disk drive to be partitioned. To obtain a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_SET_DRIVE_LAYOUT for this operation.
lpInBuffer
[in] Pointer to a buffer that contains drive layout and partition information data. The data exists as a DRIVE_LAYOUT_INFORMATION data structure and a series of PARTITION_INFORMATION data structures, one of the latter for each proposed partition on the drive.
nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain one DRIVE_LAYOUT_INFORMATION data structure and as many PARTITION_INFORMATION data structures as there are proposed partitions on the drive.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DRIVE_LAYOUT_INFORMATION, IOCTL_DISK_GET_DRIVE_LAYOUT_EX, IOCTL_DISK_SET_DRIVE_LAYOUT_EX


IOCTL_DISK_SET_DRIVE_LAYOUT_EX

[This is preliminary documentation and subject to change.]

The IOCTL_DISK_SET_DRIVE_LAYOUT_EX control code partitions a disk according to the specified drive layout and partition information data.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_DISK_SET_DRIVE_LAYOUT_EX, // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  (LPVOID) lpOutBuffer,        // output buffer
  (DWORD) nOutBufferSize,      // size of the output buffer
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the disk drive to be partitioned. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_SET_DRIVE_LAYOUT_EX for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the drive layout information to be set, contained in a DRIVE_LAYOUT_INFORMATION_EX structure.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer.
lpBytesReturned
[out] Pointer to a variable that receives the actual count of bytes returned by the function in the output buffer.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned is used internally and cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DRIVE_LAYOUT_INFORMATION_EX, IOCTL_DISK_GET_DRIVE_LAYOUT_EX


IOCTL_DISK_SET_PARTITION_INFO

The IOCTL_DISK_SET_PARTITION_INFO control code sets the partition type of the specified disk partition.

Note IOCTL_DISK_SET_PARTITION_INFO has been superseded by IOCTL_DISK_SET_PARTITION_INFO_EX, which retrieves layout information for AT and EFI (Extensible Firmware Interface) partitions.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to device
  IOCTL_DISK_SET_PARTITION_INFO,   // dwIoControlCode
  (LPVOID) lpInBuffer,             // input buffer
  (DWORD) nInBufferSize,           // size of input buffer
  NULL,                            // lpOutBuffer
  0,                               // nOutBufferSize
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object on which partition information is to be set. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_SET_PARTITION_INFO for this operation.
lpInBuffer
[in] Pointer to a buffer that contains the partition data to be set. The data exists as a SET_PARTITION_INFORMATION data structure.
nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a SET_PARTITION_INFORMATION data structure.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_PARTITION_INFO_EX, SET_PARTITION_INFORMATION


IOCTL_DISK_SET_PARTITION_INFO_EX

[This is preliminary documentation and subject to change.]

The IOCTL_DISK_SET_PARTITION_INFO_EX control code sets the partition type of the specified disk partition.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                 // handle to device
  IOCTL_DISK_SET_PARTITION_INFO_EX, // dwIoControlCode
  NULL,                             // lpInBuffer
  0,                                // nInBufferSize
  (LPWORD) lpOutBuffer,             // output buffer
  (DWORD) nOutBufferSize,           // size of output buffer
  (LPDWORD) lpBytesReturned,        // number of bytes returned
  (LPOVERLAPPED) lpOverlapped       // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object on which partition information is to be set. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_SET_PARTITION_INFO_EX for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to the partition information to be set, contained in a PARTITION_INFORMATION_EX structure.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer.
lpBytesReturned
[out] Pointer to a variable that receives the actual count of bytes returned by the function in the output buffer.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned is used internally and cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO_EX, PARTITION_INFORMATION_EX


IOCTL_DISK_VERIFY

The IOCTL_DISK_VERIFY control code performs a logical format of a specified extent on a disk.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_DISK_VERIFY,           // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object to be verified. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_DISK_VERIFY for this operation.
lpInBuffer
[in] Pointer to a buffer that contains a VERIFY_INFORMATION data structure.
nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a VERIFY_INFORMATION data structure.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, VERIFY_INFORMATION


IOCTL_SERIAL_LSRMST_INSERT

The IOCTL_SERIAL_LSRMST_INSERT control code enables or disables the placement of line status and modem status values into the regular data stream that an application acquires through the ReadFile function.

When this line-status and modem-status data placement mode is enabled, status values are preceded in the data stream by an escape character. The user-definable escape character is set by the IOCTL_SERIAL_LSRMST_INSERT control code. Status values consist of 1 to 3 BYTEs. See the Remarks section following for status value details.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_SERIAL_LSRMST_INSERT,  // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object on which the operation is to be performed. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_SERIAL_LSRMST_INSERT for this operation.
lpInBuffer
[in] Pointer to a buffer that contains a single BYTE.

If the BYTE is a nonzero value, it is the desired line-status and modem-status value escape character. The operation will turn the LSRMST_INSERT line-status and modem-status data placement mode on.

If the BYTE is zero, the operation will turn the LSRMST_INSERT line-status and modem-status data placement mode off.

The escape character cannot be the XON or XOFF character.

nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer. For this operation, this value should be 1.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

Note An application that uses this scheme must examine each character in the data stream to determine the presence of modem-status or line-status data.

The following values follow the designated escape character in the data stream if the LSRMST_INSERT mode has been turned on.

Value | Meaning
SERIAL_LSRMST_ESCAPE | Indicates the reception of the escape character itself into the data stream.
SERIAL_LSRMST_LSR_DATA | Indicates that a line status change occurred, and data was available in the receive hardware buffer. Following this BYTE is a BYTE value of the line status register is the BYTE present in the receive hardware buffer when the line status change was processed.
SERIAL_LSRMST_LSR_NODATA | Indicates that a line status change occurred, but no data was available in the receive hardware buffer.
SERIAL_LSRMST_MST | Indicates that a modem status change occurred. Following this BYTE is a BYTE that is the value of the modem status register when the modem status change was processed.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, ReadFile


IOCTL_STORAGE_CHECK_VERIFY

The IOCTL_STORAGE_CHECK_VERIFY control code determines whether media are accessible for a device.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_STORAGE_CHECK_VERIFY,  // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object on which the operation is to be performed. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_STORAGE_CHECK_VERIFY for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds and the device media are accessible, DeviceIoControl returns a nonzero value.

If media are not accessible, or the operation otherwise fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl


IOCTL_STORAGE_EJECT_MEDIA

The IOCTL_STORAGE_EJECT_MEDIA control code causes media to be ejected from a SCSI device.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_STORAGE_EJECT_MEDIA,   // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which media is to be ejected. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_STORAGE_EJECT_MEDIA for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

IOCTL_STORAGE_EJECT_MEDIA may or may not be supported on SCSI devices that support removable media.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_STORAGE_LOAD_MEDIA, IOCTL_STORAGE_MEDIA_REMOVAL


IOCTL_STORAGE_GET_MEDIA_TYPES

The IOCTL_STORAGE_GET_MEDIA_TYPES control code retrieves information about the types of media a device driver supports.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to device
  IOCTL_STORAGE_GET_MEDIA_TYPES,   // dwIoControlCode
  NULL,                            // lpInBuffer
  0,                               // nInBufferSize
  (LPVOID) lpOutBuffer,            // output buffer
  (DWORD) nOutBufferSize,          // size of output buffer
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which the media type is to be retrieveed. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_STORAGE_GET_MEDIA_TYPES for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that will receive an array of DISK_GEOMETRY data structures specifying the media types the device driver supports.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain as many DISK_GEOMETRY structures as there are media that the driver supports.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for all class drivers, as well as non-small computer system interface (SCSI) hard drives and floppy disk devices.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_DRIVE_GEOMETRY


IOCTL_STORAGE_LOAD_MEDIA

The IOCTL_STORAGE_LOAD_MEDIA control code causes media to be loaded into a device.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_STORAGE_LOAD_MEDIA,    // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object to which media is to be loaded. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_STORAGE_LOAD_MEDIA for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns zero.

If the operation fails, DeviceIoControl returns a nonzero value. To get extended error information, call GetLastError.

Remarks

The IOCTL_STORAGE_LOAD_MEDIA control code is valid only for devices that support loadable media.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_STORAGE_EJECT_MEDIA, IOCTL_STORAGE_MEDIA_REMOVAL


IOCTL_STORAGE_MEDIA_REMOVAL

The IOCTL_STORAGE_MEDIA_REMOVAL control code enables or disables the mechanism that ejects media, for those devices possessing that locking capability.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_STORAGE_MEDIA_REMOVAL, // dwIoControlCode
  (LPVOID) lpInBuffer,         // input buffer
  (DWORD) nInBufferSize,       // size of input buffer
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the object from which media is to be removed. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_STORAGE_MEDIA_REMOVAL for this operation.
lpInBuffer
[in] Pointer to a buffer that contains a PREVENT_MEDIA_REMOVAL data structure.

A TRUE value for that structure's PreventMediaRemoval member specifies that media removal is prevented (the device is locked). A FALSE value specifies that media removal is allowed.

nInBufferSize
[in] Size, in bytes, of the buffer pointed to by lpInBuffer, which must be large enough to contain a PREVENT_MEDIA_REMOVAL data structure.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns a nonzero value. To get extended error information, call GetLastError.

Remarks

The IOCTL_STORAGE_MEDIA_REMOVAL control code is valid only for devices that support removable media.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, IOCTL_STORAGE_EJECT_MEDIA, IOCTL_STORAGE_LOAD_MEDIA, PREVENT_MEDIA_REMOVAL


IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS

[This is preliminary documentation and subject to change.]

The IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS control code retrieves the physical location of the specified volume on one or more disks.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                        // handle to device
  IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS,  // dwIoControlCode
  NULL,                                    // lpInBuffer
  0,                                       // nInBufferSize
  (LPVOID) lpOutBuffer,                    // output buffer
  (DWORD) nOutBufferSize,                  // size of output buffer
  (LPDWORD) lpBytesReturned,               // number of bytes returned
  (LPOVERLAPPED) lpOverlapped              // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
[out] Pointer to a buffer that receives a VOLUME_DISK_EXTENTS structure specifying the physical location of the disk.
nOutBufferSize
[in] Size, in bytes, of the buffer pointed to by lpOutBuffer, which must be large enough to contain a VOLUME_DISK_EXTENTS structure.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns zero.

If the operation fails, DeviceIoControl returns a nonzero value. To get extended error information, call GetLastError.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl, VOLUME_DISK_EXTENTS


IOCTL_VOLUME_IS_CLUSTERED

[This is preliminary documentation and subject to change.]

The IOCTL_VOLUME_IS_CLUSTERED control code determines whether the specified volume is clustered.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to device
  IOCTL_VOLUME_IS_CLUSTERED,  // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // number of bytes returned
  (LPOVERLAPPED) lpOverlapped  // OVERLAPPED structure
);

Parameters

hDevice
[in] Handle to the volume. To retrieve a device handle, call the CreateFile function.
dwIoControlCode
[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_VOLUME_IS_CLUSTERED for this operation.
lpInBuffer
Not used with this operation; set to NULL.
nInBufferSize
Not used with this operation; set to zero.
lpOutBuffer
Not used with this operation; set to NULL.
nOutBufferSize
Not used with this operation; set to zero.
lpBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of output data returned.

If the output buffer is too small to return any data, then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL, even if lpOutBuffer is NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped
[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, the operation is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and DeviceIoControl does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns zero.

If the operation fails, DeviceIoControl returns a nonzero value. To get extended error information, call GetLastError. The following are possible error return values.

Value | Meaning
NO_ERROR | The volume resides on an online Physical Disk resource in a server cluster.
ERROR_GEN_FAILURE | Either the volume is offline or the volume is not a clustered disk.
ERROR_INVALID_FUNCTION | Either the Cluster service is not installed or the volume is not a clustered disk.

Remarks

The IOCTL_VOLUME_IS_CLUSTERED control code is valid only if the Cluster service is running.

The ERROR_GEN_FAILURE error indicates that the computer that currently owns the disk on which the volume resides is a server cluster node, but either the disk is a Physical Disk resource currently in an offline state or the disk is not a Physical Disk resource. To determine which of these situations exists, use the following steps:

  1. Call the ClusterEnum function to enumerate all Physical Disk resources in the cluster.
  2. Search each enumerated Physical Disk resource for the volume by calling the ClusterResourceControl function with CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO. If you cannot find the volume among the Physical Disk resources in the cluster, the volume does not reside on a Physical Disk resource.

The ERROR_INVALID_FUNCTION error indicates that the computer that currently owns the disk on which the volume resides is not a server cluster node or the disk is not a Physical Disk resource. To determine whether a computer is a server cluster node, call the GetNodeClusterState function.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, DeviceIoControl


Device Input and Output Structures

The following structures are used with device input and output.

BATTERY_INFORMATION
BATTERY_MANUFACTURE_DATE
BATTERY_QUERY_INFORMATION
BATTERY_REPORTING_SCALE
BATTERY_SET_INFORMATION
BATTERY_STATUS
BATTERY_WAIT_STATUS
CHANGER_ELEMENT
CHANGER_ELEMENT_LIST
CHANGER_ELEMENT_STATUS
CHANGER_ELEMENT_STATUS_EX
CHANGER_EXCHANGE_MEDIUM
CHANGER_INITIALIZE_ELEMENT_STATUS
CHANGER_MOVE_MEDIUM
CHANGER_PRODUCT_DATA
CHANGER_READ_ELEMENT_STATUS
CHANGER_SEND_VOLUME_TAG_INFORMATION
CHANGER_SET_ACCESS
CHANGER_SET_POSITION
CREATE_USN_JOURNAL_DATA
DELETE_USN_JOURNAL_DATA
DISK_DETECTION_INFO
DISK_EX_INT13_INFO
DISK_EXTENT
DISK_GEOMETRY
DISK_GEOMETRY_EX
DISK_INT13_INFO
DISK_PARTITION_INFO
DISK_PERFORMANCE
DRIVE_LAYOUT_INFORMATION_EX
FILE_ALLOCATED_RANGE_BUFFER
FILE_OBJECTID_BUFFER
FILE_ZERO_DATA_INFORMATION
FORMAT_PARAMETERS
FSCTL_QUERY_FAT_BPB_BUFFER
GET_CHANGER_PARAMETERS
HFS_INFORMATION_BUFFER
MARK_HANDLE_INFO
MFT_ENUM_DATA
MOVE_FILE_DATA
PARTITION_INFORMATION_EX
PARTITION_INFORMATION_GPT
PARTITION_INFORMATION_MBR
PLEX_READ_DATA_REQUEST
PREVENT_MEDIA_REMOVAL
READ_ELEMENT_ADDRESS_INFO
READ_USN_JOURNAL_DATA
REASSIGN_BLOCKS
REPARSE_GUID_DATA_BUFFER
RETRIEVAL_POINTERS_BUFFER
STARTING_LCN_INPUT_BUFFER
STARTING_VCN_INPUT_BUFFER
USN_JOURNAL_DATA
USN_RECORD
VERIFY_INFORMATION
VOLUME_BITMAP_BUFFER
VOLUME_DISK_EXTENTS

The following device input and output structures are obsolete:

DRIVE_LAYOUT_INFORMATION
PARTITION_INFORMATION
SET_PARTITION_INFORMATION


BATTERY_INFORMATION

The BATTERY_INFORMATION structure is returned by the IOCTL_BATTERY_QUERY_INFORMATION control code when the BatteryInformation information level is requested.

typedef struct _BATTERY_INFORMATION {
  ULONG       Capabilities;
  UCHAR       Technology;
  UCHAR       Reserved[3];
  UCHAR       Chemistry[4];
  ULONG       DesignedCapacity;
  ULONG       FullChargedCapacity;
  ULONG       DefaultAlert1;
  ULONG       DefaultAlert2;
  ULONG       CriticalBias;
  ULONG       CycleCount;
} BATTERY_INFORMATION, *PBATTERY_INFORMATION;

Members

Capabilities
A bitmask with one or more of the following bits:
Bits | Meaning
BATTERY_CAPACITY_RELATIVE | Indicates that the battery capacity and rate information are relative and not in any specific units. If this bit is not set the reporting units are milliwatt hours (mWh) or milliwatts (mW), as appropriate.
BATTERY_FORCE_CHARGE_SUPPORTED | Indicates that Battery Set Information requests of the type BatteryCharge are supported by this battery device.
BATTERY_FORCE_DISCHARGE_SUPPORTED | Indicates that Battery Set Information requests of the type BatteryDischarge are supported by this battery device.
BATTERY_IS_SHORT_TERM | Indicates that the normal operation is for a fail-safe function. If this bit is not set the battery is expected to be used during normal system usage.
BATTERY_SYSTEM_BATTERY | Indicates that the battery can provide general power to run the system.

Technology
0 is a nonrechargeable battery, for example, alkaline.

1 is a rechargeable battery, for example, lead acid.

Chemistry
An abbreviated character string that indicates the battery's chemistry. This Unicode string is not necessarily zero-terminated. The following is a partial list of abbreviations that can be returned and the associated chemistries.
Unicode string | Meaning
PbAc | Lead Acid
LION | Lithium Ion
NiCd | Nickel Cadmium
NiMH | Nickel Metal Hydride
NiZn | Nickel Zinc
RAM | Rechargeable Alkaline-Manganese

Other chemistries may appear in the future and your code should be able to handle them.

DesignedCapacity
The theoretical capacity of the battery when new, in mWh unless BATTERY_CAPACITY_RELATIVE is set. In that case the units are undefined.
FullChargedCapacity
The battery's current fully charged capacity in mWh (or relative). Compare this value to DesignedCapacity to estimate the battery's wear.
DefaultAlert1
The manufacturer's suggestion of when a "low battery" battery alert should occur. Definitions of "low" vary from manufacturer to manufacturer. In general, a "warning" state will occur before a "low" state, but you should not assume that it always will.
DefaultAlert2
The manufacturer's suggestion of when a "warning" battery alert should occur. Definitions of "warning" vary from manufacturer to manufacturer. In general, a "warning" state will occur before a "low" state, but you should not assume that it always will.
CriticalBias
A bias from 0 applied to battery reporting. Some batteries reserve a small charge that is biased out of the battery's FullChargedCapacity and CurrentCapacity values to show "0" as the critical battery level. Critical bias is analogous to setting a fuel gauge to show "empty" when there are several liters of fuel left.
CycleCount
The count of the number of charge/discharge cycles the battery has experienced. This provides a means to determine the battery's wear. If the battery does not support a cycle counter, this member is zero.

Remarks

In general, a "warning" state will occur before a "low" state, but you should not assume that it always will. It is possible to poll a battery and find that neither alert level has occurred, and poll the battery again and find it discharged to the extent that both levels have been achieved. This may indicate that you are not polling often enough. It may also indicate that the battery is unable to hold a charge for very long and is discharging more rapidly than you expected. Such a battery may be nearing the end of its useful life, or it may be damaged.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_BATTERY_QUERY_INFORMATION


BATTERY_MANUFACTURE_DATE

The BATTERY_MANUFACTURE_DATE structure indicates the date of manufacture of a battery. It is used by the BATTERY_QUERY_INFORMATION structure when the BatteryManufactureDate information level is requested.

typedef struct _BATTERY_MANUFACTURE_DATE {
  UCHAR   Day;
  UCHAR   Month;
  USHORT  Year;
} BATTERY_MANUFACTURE_DATE, *PBATTERY_MANUFACTURE_DATE;

Members

Day
The day of the month of manufacture, in the range of 1 to 31. In spite of the data type, this is not an ASCII encoded value. It is an unsigned byte.
Month
The month of manufacture, in the range of 1 (January) to 12 (December). In spite of the data type, this is not an ASCII encoded value. It is an unsigned byte.
Year
The year of manufacture. This will typically be in the range of 1900-2100.

Remarks

The date is encoded in the Gregorian or western calendar format.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, BATTERY_QUERY_INFORMATION, DeviceIoControl, IOCTL_BATTERY_QUERY_INFORMATION


BATTERY_QUERY_INFORMATION

The BATTERY_QUERY_INFORMATION structure is used by the IOCTL_BATTERY_QUERY_INFORMATION control code to determine the type of information to return.

typedef struct _BATTERY_QUERY_INFORMATION {
  ULONG                           BatteryTag;
  BATTERY_QUERY_INFORMATION_LEVEL InformationLevel;
  LONG                            AtRate;
} BATTERY_QUERY_INFORMATION, *PBATTERY_QUERY_INFORMATION;

Members

BatteryTag
Specifies the current battery tag for the battery. Only information for a battery matching the tag can be returned. Whenever this value does not match the battery's current tag, the IOCTL request will be completed with ERROR_FILE_NOT_FOUND. This indicates to the caller that the battery associated with the tag longer exists. The caller may opt to use the IOCTL_BATTERY_QUERY_TAG operation to determine the tag of the newly installed battery, if one exists. (See Battery Tags for more information.)

When a query information request is made, this value is verified. In addition, if the request is in progress while this value changes, the request is aborted with the status of ERROR_FILE_NOT_FOUND.

InformationLevel
Value that represents the battery information being queried. The data returned by the IOCTL depends on the value of InformationLevel. This will be one of the following values:
Information level | Return
BatteryDeviceName | Zero ('\0') terminated Unicode (wide) string that contains the battery's name.
BatteryEstimatedTime | ULONG estimated battery run time, in seconds. If the rate of drain provided in the AtRate element of the BATTERY_QUERY_INFORMATION structure is 0, this calculation is based on the present rate of drain. If AtRate is nonzero, the time returned is the expected run time for the given rate. If the estimated time is unknown (for example, the battery is not discharging and the AtRate specified was 0) this will return BATTERY_UNKNOWN_TIME. Note that this value is not very accurate on some battery systems, and may vary widely depending on present power usage, which could be affected by disk activity and other factors. There is no notification mechanism for changes in this value.
BatteryGranularityInformation | An array of BATTERY_REPORTING_SCALE structures, never more than four entries.
BatteryInformation | BATTERY_INFORMATION structure.
BatteryManufactureDate | Retrieves in the BATTERY_MANUFACTURE_DATE structure the date the cell pack was manufactured.
BatteryManufactureName | Zero ('\0') terminated Unicode (wide) string that contains the name of the manufacturer of the battery.
BatterySerialNumber | Zero ('\0') terminated Unicode (wide) string that contains the battery's serial number.
BatteryTemperature | ULONG that contains the battery's current temperature in 10ths of a degree Kelvin.
BatteryUniqueID Zero ('\0') terminated Unicode (wide) string that uniquely identifies the battery. This value can be used to track a specific battery.
In the case of smart batteries, this ID would be the concatenation of the manufacturer's name, device name, date of manufacture, and a printable representation of the serial number.
This value is not intended to be displayed to the end user.

AtRate
This value has meaning only when asking for the BatteryEstimatedTime.

If this value is nonzero, it is a rate of drain that will be used to calculate the time until the battery is discharged for the BatteryEstimatedTime of an individual battery. It must be specified in mW, and must be a negative value to represent a battery discharge rate.

Remarks

Some information about batteries is optional or may be meaningless for some batteries. If the particular type of data requested is not available for the current battery, then ERROR_INVALID_FUNCTION is returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_BATTERY_QUERY_INFORMATION, IOCTL_BATTERY_QUERY_TAG, BATTERY_REPORTING_SCALE, BATTERY_INFORMATION, BATTERY_MANUFACTURE_DATE


BATTERY_REPORTING_SCALE

The BATTERY_REPORTING_SCALE structure reports the remaining capacity and the capacity-reporting granularity that the hardware supports. The data returned from the IOCTL_BATTERY_QUERY_INFORMATION control code with the BatteryInformation information level is a variable-length array of BATTERY_REPORTING_SCALE structures. The lower ordinal entries hold older samples.

typedef struct {
  ULONG       Granularity;
  ULONG       Capacity;
} BATTERY_REPORTING_SCALE, *PBATTERY_REPORTING_SCALE;

Members

Granularity
The granularity of the capacity reading represented by this sample, in milliwatt hours (mWh). Granularity may change over time as battery discharge and recharge lowers the range of readings.
Capacity
The difference in capacity between this sample and the previous sample, indicated in mWh. It may be a positive nonzero value, indicating that the battery is charging, or a negative value, indicating that the battery is discharging. It may also be zero, indicating that the granularity is not sufficient to report discharge from normal internal charge leakage.

Remarks

The total number of entries is indicated by the value returned in the DeviceIoControl lpBytesReturned parameter. Divide the value in lpBytesReturned by the size of the BATTERY_REPORTING_SCALE structure to determine the number of elements in the array.

The maximum number of array entries from any DeviceIoControl call is four.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_BATTERY_QUERY_INFORMATION, BATTERY_REPORTING_SCALE


BATTERY_SET_INFORMATION

The BATTERY_SET_INFORMATION structure indicates to the IOCTL_BATTERY_SET_INFORMATION control code which information about the battery is to be set, and the data to which to set it.

typedef struct _BATTERY_SET_INFORMATION {
  ULONG                         BatteryTag;
  BATTERY_SET_INFORMATION_LEVEL InformationLevel;
  UCHAR                         Buffer[1];
} BATTERY_SET_INFORMATION, *PBATTERY_SET_INFORMATION;

Members

BatteryTag
Specifies the current battery tag for the battery. Information for a battery matching the tag can only be returned. Whenever this value does not match the battery's current tag, the IOCTL request will be completed with ERROR_FILE_NOT_FOUND, which indicates to the caller that the battery for which it has a tag for no longer exists. The caller may opt to use the IOCTL_BATTERY_QUERY_TAG operation to determine the tag of the newly installed battery, if one exists. (See Battery Tags for more information.)

When a query information request is made, this value is verified. In addition, if the request is in progress while this value changes, the request is aborted with the status of ERROR_FILE_NOT_FOUND.

InformationLevel
Value that represents the battery information to be set. The type of data in the buffer element of the BATTERY_SET_INFORMATION structure depends on the value of InformationLevel. This will be one of the following values:
Information level | Return
BatteryCriticalBias | Sets the battery's critical bias adjustment. Note it is not envisioned that this value would normally be changed by software, and is present in the interfaces only as a maintenance feature. Not all batteries can maintain such a setting, and the battery information should be read to confirm that the battery accepted the setting.
BatteryCharge | Setting this value informs the battery device that the user has requested that the battery should be charging at this time. For example, with a smart battery/charger/selector, the application could charge one battery at a time. The Buffer element of this structure is ignored.
BatteryDischarge | Setting this value informs the battery device that the user has requested that the battery be discharging at this time. For example, this could be used to indicate which battery the user currently wants to power the system. The Buffer element of this structure is ignored.

Buffer
The battery information to be set. The type of data depends on the value of InformationLevel.

Remarks

The BATTERY_SET_INFORMATION structure is a variable-length structure, and you must allocate a buffer of suitable size for the information you want to include in the structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_BATTERY_SET_INFORMATION


BATTERY_STATUS

The BATTERY_STATUS structure indicates the state of the battery at the time the control code returns. It is used by the IOCTL_BATTERY_QUERY_STATUS control code.

typedef struct _BATTERY_STATUS {
  ULONG       PowerState;
  ULONG       Capacity;
  ULONG       Voltage;
  LONG        Rate;
} BATTERY_STATUS, *PBATTERY_STATUS;

Members

PowerState
Indicate the battery state. This member can be zero, one, or more of the following values.
Value | Description
BATTERY_POWER_ON_LINE | Indicates that the system has access to AC power, so no batteries are being discharged.
BATTERY_DISCHARGING | Indicates that the battery is currently discharging.
BATTERY_CHARGING | Indicates that the battery is currently charging.
BATTERY_CRITICAL | Indicates that battery failure is imminent. See the Remarks later in this topic for more information.

Capacity
The current battery capacity in mWh (or relative). This value can be used to generate a "gas gauge" display by dividing it by FullChargedCapacity member of the BATTERY_INFORMATION structure. If the capacity is unavailable, Capacity will contain the value BATTERY_UNKNOWN_CAPACITY.
Voltage
The current battery voltage in millivolts (mv) across the battery terminals. If the voltage is unavailable, this will contain BATTERY_UNKNOWN_VOLTAGE.
Rate
The current rate of battery charge or discharge. This value will be in mW unless the battery is relative, in which case it will be in arbitrary units per hour. To determine if a battery is relative, examine the BATTERY_CAPACITY_ RELATIVE flag in the Capabilities element of the BATTERY_INFORMATION structure. A nonzero positive rate indicates charging; a negative rate indicates discharging. If the rate is unavailable, this will return BATTERY_UNKNOWN_RATE.

Remarks

The BATTERY_CRITICAL flag in the PowerState member of this structure indicates a hardware "battery critical" condition. This critical level is set by the battery manufacturer, not by the user in the "critical battery alarm." It generally means that the battery system has calculated that the battery is totally drained, and any power being drawn is beyond what is expected. If all of the batteries in a system are critical, and no other source of power is available, the system will be shut down automatically.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_BATTERY_QUERY_STATUS


BATTERY_WAIT_STATUS

The BATTERY_WAIT_STATUS structure indicates when the battery status is to be collected and returned by the control code. It is used by the IOCTL_BATTERY_QUERY_STATUS control code.

typedef struct _BATTERY_WAIT_STATUS {
  ULONG       BatteryTag;
  ULONG       Timeout;
  ULONG       PowerState;
  ULONG       LowCapacity;
  ULONG       HighCapacity;
} BATTERY_WAIT_STATUS, *PBATTERY_WAIT_STATUS;

Members

BatteryTag
Specifies the current battery tag for the battery. Only information for a battery matching the tag can be returned. Whenever this value does not match the battery's current tag, the DeviceIoControl operation will fail with an error code of ERROR_FILE_NOT_FOUND, which indicates to the caller that the battery for which it has a tag is no longer installed The caller may opt to use the IOCTL_BATTERY_QUERY_TAG operation to determine the tag of the newly installed battery, if any. In addition, if the request is in progress when the battery is removed, or the tag changes, the operation is aborted with the status of ERROR_FILE_NOT_FOUND. (See Battery Tags for more information.)
Timeout
Specifies the number of milliseconds the request will wait for the condition specified by the PowerState, LowCapacity, and HighCapacity elements before completing. A value of -1 indicates that the request will wait indefinitely for the conditions to be satisfied. A value of 0 indicates that the requested battery information is to be returned immediately, regardless of the other conditions. Any other value indicates that the request should wait that length of time, or until any one of the other conditions is satisfied.

If the computer has entered sleep mode, the clock will continue to run, but exhausting the count will not wake the computer up. If the count is exhausted when the computer is awoken, and other conditions are satisfied, the call will return immediately on awakening.

PowerState
This has zero, one, or more of the following status bits on to indicate the state of the battery. It is identical to the PowerState member of the BATTERY_STATUS structure.
Value | Meaning
BATTERY_POWER_ON_LINE | Indicates that the battery has access to AC power.
BATTERY_DISCHARGING | Indicates that the battery is currently discharging.
BATTERY_CHARGING | Indicates that the battery is currently charging.
BATTERY_CRITICAL | Indicates that battery failure is imminent. See the Remarks later in this topic for more information.

LowCapacity
The current battery capacity in mWh (or relative). This value is identical to the Capacity member of the BATTERY_STATUS structure.
HighCapacity
The current battery capacity in mWh (or relative). This value is identical to the Capacity member of the BATTERY_STATUS structure.

Remarks

Requests for battery information are postponed until one of the following occurs:

  • The timeout expires (assuming it is not -1).
  • The battery's current status does not match PowerState.
  • The battery's capacity is below LowCapacity.
  • The battery's capacity is above HighCapacity.
  • The battery tag changes.

When any one of these conditions is satisfied, the data is collected and the operation returns. This allows applications to monitor typical dynamic battery information without polling the device.

Before using either of the two Capacity conditions, make sure the battery supports them by using the IOCTL_BATTERY_QUERY_STATUS control code with a time-out of zero. Examine the results to determine if the Capacity element is supported (that is, not BATTERY_UNKNOWN_CAPACITY).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_BATTERY_QUERY_STATUS, IOCTL_BATTERY_QUERY_TAG, Battery Tags


CHANGER_ELEMENT

[This is preliminary documentation and subject to change.]

The CHANGER_ELEMENT structure represents a changer element.

typedef  struct _CHANGER_ELEMENT {
  ELEMENT_TYPE  ElementType;
  DWORD         ElementAddress;
} CHANGER_ELEMENT, *PCHANGER_ELEMENT;

Members

ElementType
Specifies the element type. This parameter can be one of the values from the ELEMENT_TYPE enumeration type.
ElementAddress
Specifies the element's zero-based address.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT_LIST, DeviceIoControl, ELEMENT_TYPE, IOCTL_CHANGER_REINITIALIZE_TRANSPORT


CHANGER_ELEMENT_LIST

[This is preliminary documentation and subject to change.]

The CHANGER_ELEMENT_LIST structure represents a range of elements of a single type, typically for an operation such as getting or initializing the status of multiple elements.

typedef  struct _CHANGER_ELEMENT_LIST {
  CHANGER_ELEMENT Element;
  DWORD           NumberOfElements;
} CHANGER_ELEMENT_LIST , *PCHANGER_ELEMENT_LIST;

Members

Element
Describes the first element in the range. For more information, see CHANGER_ELEMENT.
NumberOfElements
Specifies the number of elements in the range.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT, DeviceIoControl, IOCTL_CHANGER_REINITIALIZE_TRANSPORT


CHANGER_ELEMENT_STATUS

[This is preliminary documentation and subject to change.]

The CHANGER_ELEMENT_STATUS structure represents the status of the specified element.

Note Applications should use the CHANGER_ELEMENT_STATUS_EX structure.

typedef  struct _CHANGER_ELEMENT_STATUS {
  CHANGER_ELEMENT Element;
  CHANGER_ELEMENT SrcElementAddress;
  DWORD Flags;
  DWORD ExceptionCode;
  BYTE  TargetId;
  BYTE  Lun;
  WORD  Reserved;
  BYTE  PrimaryVolumeID[MAX_VOLUME_ID_SIZE];
  BYTE  AlternateVolumeID[MAX_VOLUME_ID_SIZE];
} CHANGER_ELEMENT_STATUS, *PCHANGER_ELEMENT_STATUS;

Members

Element
Specifies the element to which this structure refers. For more information, see CHANGER_ELEMENT.
SrcElementAddress
Specifies the element from which the media currently in this element was most recently moved. For more information, see CHANGER_ELEMENT.

This member is valid only if the Flags member includes ELEMENT_STATUS_SVALID.

Flags
Indicates the status of the element. This member can be one or more of the following values.
Value | Meaning
ELEMENT_STATUS_ACCESS | The changer's transport element can access the piece of media in this element. The media is not accessible in the following circumstances: (1) If the element type is ChangerSlot, the slot is not present in the changer (for example, the magazine containing the slot has been physically removed). (2) If the element type is ChangerDrive, the drive is broken or has been removed. (3) If the element type is ChangerIEPort, the IEport is extended.
ELEMENT_STATUS_AVOLTAG | Alternate volume information in the AlternateVolumeID member is valid.
ELEMENT_STATUS_EXCEPT | The element is in an abnormal state. Check the ExceptionCode member for more information.
ELEMENT_STATUS_EXENAB | The element supports export of media through the changer's IEport.
ELEMENT_STATUS_FULL The element contains a piece of media.

Note that this value is valid only if the element type is ChangerDrive, ChangerSlot, or ChangerTransport. If ElementType is ChangerIEPort, this value is valid only if the Features0 member of GET_CHANGER_PARAMETERS includes CHANGER_REPORT_IEPORT_STATE.
ELEMENT_STATUS_ID_VALID The SCSI target ID in the TargetID member is valid.

This value is valid only if the element type is ChangerDrive.

ELEMENT_STATUS_IMPEXP The media in this element was placed there by an operator.

This value is valid only if the element type is ChangerIEPort.

ELEMENT_STATUS_INENAB | The element supports import of media through the changer's IEport.
ELEMENT_STATUS_INVERT The media in the element was flipped.

This value is valid only if ELEMENT_STATUS_SVALID is also included.
ELEMENT_STATUS_LUN_VALID | The logical unit number in the Lun member is valid. This value is valid only if the element type is ChangerDrive.
ELEMENT_STATUS_NOT_BUS | The drive at the address indicated by Lun and TargetID is on a different SCSI bus than the changer itself.
ELEMENT_STATUS_PVOLTAG | Primary volume information in the PrimaryVolumeID member is valid.
ELEMENT_STATUS_SVALID | The SourceElement member and ELEMENT_STATUS_INVERT are both valid.

ExceptionCode
Indicates that the element is in an abnormal state. This member is valid only if the Flags member includes ELEMENT_STATUS_EXCEPT. This member can be one of the following values.
Value | Meaning
ERROR_LABEL_UNREADABLE | The changer's bar-code reader could not read the bar code label on the piece of media in this element, because the media is missing, damaged, improperly positioned, or upside down.
ERROR_LABEL_QUESTIONABLE | The label might be invalid due to a unit attention condition.
ERROR_SLOT_NOT_PRESENT | The slot at this element address is currently not installed in the changer. Each slot in a removable magazine is reported not present to indicate that the magazine has been removed.
ERROR_DRIVE_NOT_INSTALLED | The drive at this element address is absent.
ERROR_TRAY_MALFUNCTION | The drive at this element address has a tray that must be extended to load or remove media, and the tray is not extending as required.
ERROR_UNHANDLED_ERROR | Unknown error condition.

TargetId
For a SCSI changer, specifies the SCSI target ID of the drive at this element address. This member is valid only if the ElementType member of the Element structure is ChangerDrive and the Flags member includes ELEMENT_STATUS_ID_VALID.
Lun
Specifies the SCSI logical unit number of the drive at this element address. This member is valid only if the ElementType member of the Element structure is ChangerDrive and the Flags member includes ELEMENT_STATUS_LUN_VALID.
Reserved
Reserved for future use. The value of this member must be zero.
PrimaryVolumeID
Specifies the primary volume identifier for the media. If the changer supports a bar-code reader and the reader is installed (as indicated by CHANGER_BAR_CODE_SCANNER_INSTALLED in the Features0 member of GET_CHANGER_PARAMETERS), PrimaryVolumeID is the bar code of the media. If the changer does not support a bar-code reader, PrimaryVolumeID is the value previously assigned to the media.

This member is valid only if the Flags member includes ELEMENT_STATUS_PVOLTAG.

If the volume identifier is missing or unreadable, this member is cleared.

AlternateVolumeID
Specifies alternate volume identification for the media. This member is valid only for two-sided media, and pertains to the ID of the inverted side. It never represents a bar code.

This member is valid only if the Flags member includes ELEMENT_STATUS_AVOLTAG.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT, DeviceIoControl, CHANGER_ELEMENT_STATUS_EX, IOCTL_CHANGER_GET_ELEMENT_STATUS


CHANGER_ELEMENT_STATUS_EX

[This is preliminary documentation and subject to change.]

The CHANGER_ELEMENT_STATUS_EX structure represents the status of the specified element.

typedef  struct _CHANGER_ELEMENT_STATUS_EX {
  CHANGER_ELEMENT Element;
  CHANGER_ELEMENT SrcElementAddress;
  DWORD Flags;
  DWORD ExceptionCode;
  BYTE  TargetId;
  BYTE  Lun;
  WORD  Reserved;
  BYTE  PrimaryVolumeID[MAX_VOLUME_ID_SIZE];
  BYTE  AlternateVolumeID[MAX_VOLUME_ID_SIZE];
  BYTE  VendorIdentification[VENDOR_ID_LENGTH];
  BYTE  ProductIdentification[PRODUCT_ID_LENGTH];
  BYTE  SerialNumber[SERIAL_NUMBER_LENGTH];
} CHANGER_ELEMENT_STATUS_EX, *PCHANGER_ELEMENT_STATUS_EX;

Members

Element
Specifies the element to which this structure refers. For more information, see CHANGER_ELEMENT.
SrcElementAddress
Specifies the element from which the media currently in this element was most recently moved. For more information, see CHANGER_ELEMENT.

This member is valid only if the Flags member includes ELEMENT_STATUS_SVALID.

Flags
Indicates the status of the element. This member can be one or more of the following values.
Value | Meaning
ELEMENT_STATUS_ACCESS | The changer's transport element can access the piece of media in this element. The media is not accessible in the following circumstances: (1) If the element type is ChangerSlot, the slot is not present in the changer (for example, the magazine containing the slot has been physically removed). (2) If the element type is ChangerDrive, the drive is broken or has been removed. (3) If the element type is ChangerIEPort, the IEport is extended.
ELEMENT_STATUS_AVOLTAG | Alternate volume information in the AlternateVolumeID member is valid.
ELEMENT_STATUS_EXCEPT | The element is in an abnormal state. Check the ExceptionCode member for more information.
ELEMENT_STATUS_EXENAB | The element supports export of media through the changer's IEport.
ELEMENT_STATUS_FULL The element contains a piece of media.

Note that this value is valid only if the element type is ChangerDrive, ChangerSlot, or ChangerTransport. If the element type is ChangerIEPort, this value is valid only if the Features0 member of GET_CHANGER_PARAMETERS includes CHANGER_REPORT_IEPORT_STATE.
ELEMENT_STATUS_ID_VALID The SCSI target ID in the TargetID member is valid.

This value is valid only if the element type is ChangerDrive.

ELEMENT_STATUS_IMPEXP The media in this element was placed there by an operator.

This value is valid only if the element type is ChangerIEPort.

ELEMENT_STATUS_INENAB | The element supports import of media through the changer's IEport.
ELEMENT_STATUS_INVERT The media in the element was flipped.

This value is valid only if ELEMENT_STATUS_SVALID is also included.
ELEMENT_STATUS_LUN_VALID | The logical unit number in the Lun member is valid. This value is valid only if the element type is ChangerDrive.
ELEMENT_STATUS_NOT_BUS | The drive at the address indicated by Lun and TargetID is on a different SCSI bus than the changer itself.
ELEMENT_STATUS_PRODUCT_DATA | The serial number in the SerialNumber member is valid.
ELEMENT_STATUS_PVOLTAG | Primary volume information in the PrimaryVolumeID member is valid.
ELEMENT_STATUS_SVALID | The SourceElement member and ELEMENT_STATUS_INVERT are both valid.

ExceptionCode
Indicates that the element is in an abnormal state. This member is valid only if the Flags member includes ELEMENT_STATUS_EXCEPT. This member can be one of the following values.
Value | Meaning
ERROR_DRIVE_NOT_INSTALLED | The drive at this element address is absent.
ERROR_INIT_STATUS_NEEDED | An Initialize Element Status command is needed.
ERROR_LABEL_QUESTIONABLE | The label might be invalid due to a unit attention condition.
ERROR_LABEL_UNREADABLE | The changer's bar-code reader could not read the bar code label on the piece of media in this element, because the media is missing, damaged, improperly positioned, or upside down.
ERROR_SLOT_NOT_PRESENT | The slot at this element address is currently not installed in the changer. Each slot in a removable magazine is reported not present to indicate that the magazine has been removed.
ERROR_TRAY_MALFUNCTION | The drive at this element address has a tray that must be extended to load or remove media, and the tray is not extending as required.
ERROR_UNHANDLED_ERROR | Unknown error condition.

TargetId
For a SCSI changer, specifies the SCSI target ID of the drive at this element address. This member is valid only if the ElementType member of the Element structure is ChangerDrive and the Flags member includes ELEMENT_STATUS_ID_VALID.
Lun
Specifies the SCSI logical unit number of the drive at this element address. This member is valid only if the ElementType member of the Element structure is ChangerDrive and the Flags member includes ELEMENT_STATUS_LUN_VALID.
Reserved
Reserved for future use. The value of this member must be zero.
PrimaryVolumeID
Specifies the primary volume identifier for the media. If the changer supports a bar-code reader and the reader is installed (as indicated by CHANGER_BAR_CODE_SCANNER_INSTALLED in the Features0 member of GET_CHANGER_PARAMETERS), PrimaryVolumeID is the bar code of the media. If the changer does not support a bar-code reader, PrimaryVolumeID is the value previously assigned to the media.

This member is valid only if the Flags member includes ELEMENT_STATUS_PVOLTAG.

If the volume identifier is missing or unreadable, this member is cleared.

AlternateVolumeID
Specifies alternate volume identification for the media. This member is valid for two-sided media only, and pertains to the ID of the inverted side. It never represents a bar code.

This member is valid only if the Flags member includes ELEMENT_STATUS_AVOLTAG.

VendorIdentification
Specifies the vendor identifier.
ProductIdentification
Specifies the product identifier.
SerialNumber
Specifies the serial number for the drive.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT, DeviceIoControl, IOCTL_CHANGER_GET_ELEMENT_STATUS


CHANGER_EXCHANGE_MEDIUM

[This is preliminary documentation and subject to change.]

The CHANGER_EXCHANGE_MEDIUM structure contains information that the IOCTL_CHANGER_EXCHANGE_MEDIUM control code uses to move a piece of media from a source element to one destination, and the piece of media originally in the first destination to a second destination.

typedef struct _CHANGER_EXCHANGE_MEDIUM {
  CHANGER_ELEMENT Transport;
  CHANGER_ELEMENT Source;
  CHANGER_ELEMENT Destination1;
  CHANGER_ELEMENT Destination2;
  BOOLEAN         Flip1;
  BOOLEAN         Flip2;
} CHANGER_EXCHANGE_MEDIUM, *PCHANGER_EXCHANGE_MEDIUM;

Members

Transport
Indicates which transport to use for the exchange operation. For more information, see CHANGER_ELEMENT.
Source
Indicates the source for the media that is to be moved. For more information, see CHANGER_ELEMENT.
Destination1
Indicates the final destination of the media originally at Source. For more information, see CHANGER_ELEMENT.
Destination2
Indicates the destination of the media moved from Destination1. For more information, see CHANGER_ELEMENT.
Flip1
Indicates whether the medium should be flipped.
Flip2
Indicates whether the medium should be flipped.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT, DeviceIoControl, IOCTL_CHANGER_EXCHANGE_MEDIUM


CHANGER_INITIALIZE_ELEMENT_STATUS

[This is preliminary documentation and subject to change.]

The CHANGER_INITIALIZE_ELEMENT_STATUS structure represents the status of all media changer elements or the specified elements of a particular type.

typedef struct _CHANGER_INITIALIZE_ELEMENT_STATUS {
  CHANGER_ELEMENT_LIST ElementList;
  BOOLEAN BarCodeScan;
} CHANGER_INITIALIZE_ELEMENT_STATUS, *PCHANGER_INITIALIZE_ELEMENT_STATUS;

Members

ElementList
List describing the elements and range on which to initialize. For more information, see CHANGER_ELEMENT_LIST.
BarCodeScan
Indicates whether a bar code scan should be used.

This member is applicable only if CHANGER_BAR_CODE_SCANNER_INSTALLED is set in the Features0 member of GET_CHANGER_PARAMETERS.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT_LIST, DeviceIoControl, IOCTL_CHANGER_INITIALIZE_ELEMENT_STATUS


CHANGER_MOVE_MEDIUM

[This is preliminary documentation and subject to change.]

The CHANGER_MOVE_MEDIUM structure contains information that the IOCTL_CHANGER_MOVE_MEDIUM control code uses to move a piece of media to a destination.

typedef struct _CHANGER_MOVE_MEDIUM {
  CHANGER_ELEMENT Transport;
  CHANGER_ELEMENT Source;
  CHANGER_ELEMENT Destination;
  BOOLEAN         Flip;
} CHANGER_MOVE_MEDIUM, *PCHANGER_MOVE_MEDIUM;

Members

Transport
Indicates which transport to use for the move operation. For more information, see CHANGER_ELEMENT.
Source
Indicates the source for the media that is to be moved. For more information, see CHANGER_ELEMENT.
Destination
Indicates the destination of the media originally at Source. For more information, see CHANGER_ELEMENT.
Flip
Indicates whether the media should be flipped.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT, DeviceIoControl, IOCTL_CHANGER_MOVE_MEDIUM


CHANGER_PRODUCT_DATA

[This is preliminary documentation and subject to change.]

The CHANGER_PRODUCT_DATA structure represents product data for a changer device. It is used by the IOCTL_CHANGER_GET_PRODUCT_DATA control code.

typedef  struct _CHANGER_PRODUCT_DATA {
  BYTE  VendorId[VENDOR_ID_LENGTH];
  BYTE  ProductId[PRODUCT_ID_LENGTH];
  BYTE  Revision[REVISION_LENGTH];
  BYTE  SerialNumber[SERIAL_NUMBER_LENGTH];
  BYTE  DeviceType;
} CHANGER_PRODUCT_DATA, *PCHANGER_PRODUCT_DATA;

Members

VendorId
Device manufacturer's name—based on Inquiry data.
ProductId
Product identification as defined by the vendor—based on Inquiry data.
Revision
Product revision as defined by the vendor.
SerialNumber
Vendor unique value used to globally identify this device. This value can be from Vital Product Data, for example.
DeviceType
Indicates device type of data transports, as defined by SCSI-2.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_CHANGER_GET_PRODUCT_DATA


CHANGER_READ_ELEMENT_STATUS

[This is preliminary documentation and subject to change.]

The CHANGER_READ_ELEMENT_STATUS structure contains information that the IOCTL_CHANGER_GET_ELEMENT_STATUS control code needs to determine the elements whose status is to be retrieved.

typedef struct _CHANGER_READ_ELEMENT_STATUS {
  CHANGER_ELEMENT_LIST ElementList;
  BOOLEAN VolumeTagInfo;
} CHANGER_READ_ELEMENT_STATUS, *PCHANGER_READ_ELEMENT_STATUS;

Members

ElementList
List describing the elements and range for which information is to be retrieved. For more information, see CHANGER_ELEMENT_LIST.
VolumeTagInfo
Indicates whether volume tag information is to be retrieved. If this member is TRUE, volume information is retrieved. If this member is FALSE, no volume information is retrieved.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT_LIST, DeviceIoControl, IOCTL_CHANGER_GET_ELEMENT_STATUS


CHANGER_SEND_VOLUME_TAG_INFORMATION

[This is preliminary documentation and subject to change.]

The CHANGER_SEND_VOLUME_TAG_INFORMATION structure contains information that the IOCTL_CHANGER_QUERY_VOLUME_TAGS control code uses to determine the volume information to be retrieved.

typedef  struct _CHANGER_SEND_VOLUME_TAG_INFORMATION {
  CHANGER_ELEMENT StartingElement;
  DWORD ActionCode;
  BYTE  VolumeIDTemplate[MAX_VOLUME_TEMPLATE_SIZE];
} CHANGER_SEND_VOLUME_TAG_INFORMATION, *PCHANGER_SEND_VOLUME_TAG_INFORMATION;

Members

StartingElement
Describes the starting element for which to retrieve information. For more information, see CHANGER_ELEMENT.
ActionCode
Indicates the specific action to perform.
Value | Meaning
ASSERT_ALTERNATE | Assert - as the alternate volume tag - if tag now undefined.
ASSERT_PRIMARY | Assert - as the primary volume tag - if tag now undefined.
REPLACE_ALTERNATE | Replace - the alternate volume tag - current tag ignored.
REPLACE_PRIMARY | Replace - the primary volume tag - current tag ignored.
SEARCH_ALL | Translate - search all defined volume tags.
SEARCH_ALL_NO_SEQ | Translate - search all defined volume tags but ignore sequence numbers.
SEARCH_ALT_NO_SEQ | Translate - search only alternate volume tags but ignore sequence numbers.
SEARCH_ALTERNATE | Translate - search only alternate volume tags.
SEARCH_PRI_NO_SEQ | Translate - search only primary volume tags but ignore sequence numbers.
SEARCH_PRIMARY | Translate - search only primary volume tags.
UNDEFINE_ALTERNATE | Undefine - the alternate volume tag - current tag ignored.
UNDEFINE_PRIMARY | Undefine - the primary volume tag - current tag ignored.

VolumeIDTemplate
Template that the device uses to search for volume IDs.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_CHANGER_QUERY_VOLUME_TAGS


CHANGER_SET_ACCESS

[This is preliminary documentation and subject to change.]

The CHANGER_SET_ACCESS structure contains information that the IOCTL_CHANGER_SET_ACCESS control code needs to set the state of the device's import/export port (IEport), door, or keypad.

typedef struct _CHANGER_SET_ACCESS {
  CHANGER_ELEMENT Element;
  DWORD           Control;
} CHANGER_SET_ACCESS, *PCHANGER_SET_ACCESS;

Members

Element
Specifies the changer element. This member can be one of the following values.
Value | Meaning
ChangerDoor | A mechanism that provides access to all media in a changer at one time (as compared to an IEport that provides access to one or more, but not all, media). For example, a large front door or a magazine that contains all media in the changer is an element of this type.
ChangerIEPort | An IEport element, which is a single or multiple-cartridge access port in some changers. An element is an IEport only if it is possible to move a piece of media from a slot to the IEport.
ChangerKeypad | The keypad or other input control on the front panel of a changer.

Control
Specifies the operation.
Value | Meaning
LOCK_ELEMENT | The element is to be locked.
UNLOCK_ELEMENT | The element is to be unlocked.
EXTEND_IEPORT | The element is to be extended.
RETRACT_IEPORT | The element is to be retracted.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_CHANGER_SET_ACCESS


CHANGER_SET_POSITION

[This is preliminary documentation and subject to change.]

The CHANGER_SET_POSITION structure contains information needed by the IOCTL_CHANGER_SET_POSITION control code to set the changer's robotic transport mechanism to the specified element address.

typedef struct _CHANGER_SET_POSITION {
  CHANGER_ELEMENT Transport;
  CHANGER_ELEMENT Destination;
  BOOLEAN         Flip;
} CHANGER_SET_POSITION, *PCHANGER_SET_POSITION;

Members

Transport
Indicates which transport to move. For more information, see CHANGER_ELEMENT.
Destination
Indicates the final destination of the transport. For more information, see CHANGER_ELEMENT.
Flip
Indicates whether the media currently carried by Transport should be flipped.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_CHANGER_SET_POSITION


CREATE_DISK

[This is preliminary documentation and subject to change.]

The CREATE_DISK structure contains information used by the IOCTL_DISK_CREATE_DISK control code to initialize GPT, MBR, or raw disks.

typedef struct {
  PARTITION_STYLE PartitionStyle;
  union {
    CREATE_DISK_MBR Mbr;
    CREATE_DISK_GPT Gpt;
  };
} CREATE_DISK, *PCREATE_DISK;

Members

PartitionStyle
The format of the partition. For a list of values, see PARTITION_STYLE.
Mbr
A CREATE_DISK_MBR structure containing disk information when an MBR disk is to be initialized.
Gpt
A CREATE_DISK_GPT structure containing disk information when a GPT disk is to be initialized.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CREATE_DISK_MBR, CREATE_DISK_GPT, IOCTL_DISK_CREATE_DISK, PARTITION_STYLE


CREATE_DISK_GPT

[This is preliminary documentation and subject to change.]

The CREATE_DISK_GPT structure contains information used by the IOCTL_DISK_CREATE_DISK control code to initialize GPT disks.

typedef struct {
  GUID DiskId;
  DWORD MaxPartitionCount;
} CREATE_DISK_GPT, *PCREATE_DISK_GPT;

Members

DiskId
The disk identifier (GUID) of the GPT disk to be initialized.
MaxPartitionCount
The maximum number of partitions allowed on the GPT disk to be initialized without repartitioning the disk.

Remarks

The CREATE_DISK_GPT structure is defined as part of the CREATE_DISK structure.

If a maximum partition count (MaxPartitionCount) of less than 128 is specified, it will be reset to 128. This is in compliance with the EFI specification.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, IOCTL_DISK_CREATE_DISK, CREATE_DISK, CREATE_DISK_MBR


CREATE_DISK_MBR

[This is preliminary documentation and subject to change.]

The CREATE_DISK_MBR structure contains information used by the IOCTL_DISK_CREATE_DISK control code to initialize MBR disks.

typedef struct {
  DWORD Signature;
} CREATE_DISK_MBR, *PCREATE_DISK_MBR;

Members

Signature
The disk signature of the MBR disk to be initialized.

Remarks

The CREATE_DISK_MBR structure is defined as part of the CREATE_DISK structure.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, IOCTL_DISK_CREATE_DISK, CREATE_DISK, CREATE_DISK_GPT


CREATE_USN_JOURNAL_DATA

The CREATE_USN_JOURNAL_DATA structure contains information describing an NTFS change journal.

typedef struct {
  DWORDLONG MaximumSize;
  DWORDLONG AllocationDelta;
} CREATE_USN_JOURNAL_DATA, *PCREATE_USN_JOURNAL_DATA;

Members

MaximumSize
Target maximum size, in bytes, that NTFS allocates for the change journal. The change journal can grow larger than this value, but it is then truncated at the next NTFS checkpoint to less than this value.
AllocationDelta
Size, in bytes, of memory allocation that is added to the end and removed from the beginning of the change journal. The change journal can grow to more than the sum of the values of MaximumSize and AllocationDelta before being trimmed.

Remarks

If you specify zero for MaximumSize and AllocationData, the system will choose a default value based on the volume size.

For more information on the use of CREATE_USN_JOURNAL_DATA, see Creating, Modifying, and Deleting a Change Journal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, FSCTL_CREATE_USN_JOURNAL


DELETE_USN_JOURNAL_DATA

The DELETE_USN_JOURNAL_DATA structure contains information on the deletion of an NTFS change journal using the FSCTL_DELETE_USN_JOURNAL control code.

typedef struct {
  DWORDLONG UsnJournalID;
  DWORD DeleteFlags;
} DELETE_USN_JOURNAL_DATA, *PDELETE_USN_JOURNAL_DATA;

Members

UsnJournalID
Identifier of the change journal to delete.

If the journal is active and deletion is requested by setting the USN_DELETE_FLAG_DELETE flag in the DeleteFlags member, then this identifier must specify the change journal for the current volume. Use FSCTL_QUERY_USN_JOURNAL to retrieve the identifier of this change journal. If in this case the identifier is not for the current volume's change journal, FSCTL_DELETE_USN_JOURNAL fails.

If notification instead of deletion is requested by setting only the USN_DELETE_FLAG_NOTIFY flag in DeleteFlags, UsnJournalID is ignored.

DeleteFlags
Value that indicates whether deletion or notification regarding deletion is performed, or both. The DeleteFlags member must contain one or both of the following values.
Value Meaning
USN_DELETE_FLAG_DELETE If this flag is set and the USN_DELETE_FLAG_NOTIFY flag is not set, the FSCTL_DELETE_USN_JOURNAL operation starts the journal deletion process and returns immediately. The journal deletion process continues, if necessary, across system restarts.
If this flag is set and the USN_DELETE_FLAG_NOTIFY flag is also set, both deletion and notification occur.
If this flag is set and the journal is active, you must provide the identifier for the change journal for the current volume in UsnJournalID or the operation fails. If the journal is not active, then UsnJournalID is ignored and the journal is deleted.
USN_DELETE_FLAG_NOTIFY If this flag is set, the call sets up notification about when deletion is complete. The journal deletion request is completed when the journal deletion process is complete. If this flag is set and the USN_DELETE_FLAG_DELETE flag is not set, then the call sets up notification of a deletion that may already be in progress. For example, when your application starts, it might use this flag to determine if a deletion is in progress.
If this flag is set and the USN_DELETE_FLAG_DELETE flag is also set, both deletion and notification occur.
The notification is performed using an I/O completion port or another mechanism for asynchronous event notification.

Remarks

For more information on deleting a change journal, see Creating, Modifying, and Deleting a Change Journal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, FSCTL_DELETE_USN_JOURNAL, FSCTL_QUERY_USN_JOURNAL


DISK_DETECTION_INFO

[This is preliminary documentation and subject to change.]

The DISK_DETECTION_INFO structure contains detected drive parameters.

typedef struct _DISK_DETECTION_INFO {
    DWORD SizeOfDetectInfo;
    DETECTION_TYPE DetectionType;
    union {
        struct {
            DISK_INT13_INFO Int13;
            DISK_EX_INT13_INFO ExInt13;
        };
    };
} DISK_DETECTION_INFO, *PDISK_DETECTION_INFO;

Members

SizeOfDetectInfo
Size of the structure, in bytes.
DetectionType
Specifies the detected partition type. This member can be one of the following values.
Value | Meaning
DetectExInt13 | The disk has an extended Int13 partition.
DetectInt13 | The disk has a standard Int13 partition.
DetectNone | The disk has neither an Int13 nor an extended Int13 partition.

Int13
If DetectionType is DetectInt13, the union is a DISK_INT13_INFO structure.
ExInt13
If DetectionType is DetectExInt13, the union is a DISK_EX_INT13_INFO structure.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DISK_EX_INT13_INFO, DISK_GEOMETRY_EX, DISK_INT13_INFO


DISK_EX_INT13_INFO

[This is preliminary documentation and subject to change.]

The DISK_EX_INT13_INFO structure contains extended Int13 drive parameters.

typedef struct _DISK_EX_INT13_INFO {
    WORD   ExBufferSize;
    WORD   ExFlags;
    DWORD  ExCylinders;
    DWORD  ExHeads;
    DWORD  ExSectorsPerTrack;
    DWORD64 ExSectorsPerDrive;
    WORD   ExSectorSize;
    WORD   ExReserved;
} DISK_EX_INT13_INFO, *PDISK_EX_INT13_INFO;

Members

For a description of these members, consult your BIOS documentation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DISK_DETECTION_INFO


DISK_EXTENT

[This is preliminary documentation and subject to change.]

The DISK_EXTENT structure represents a disk extent.

typedef struct _DISK_EXTENT {
    DWORD           DiskNumber;
    LARGE_INTEGER   StartingOffset;
    LARGE_INTEGER   ExtentLength;
} DISK_EXTENT, *PDISK_EXTENT;

Members

DiskNumber
The number of the disk that contains this extent. This is the same number used to construct the name of the disk (for example, the X in PhysicalDriveX or HarddiskX).
StartingOffset
The offset, in bytes, from the beginning of the disk.
ExtentLength
The number of bytes in this extent.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS, LARGE_INTEGER, VOLUME_DISK_EXTENTS


DISK_GEOMETRY

The DISK_GEOMETRY structure describes the geometry of disk devices and media.

typedef struct _DISK_GEOMETRY {
  LARGE_INTEGER  Cylinders;
  MEDIA_TYPE  MediaType;
  DWORD  TracksPerCylinder;
  DWORD  SectorsPerTrack;
  DWORD  BytesPerSector;
} DISK_GEOMETRY;

Members

Cylinders
The number of cylinders.
MediaType
The type of media. See MEDIA_TYPE.
TracksPerCylinder
The number of tracks per cylinder.
SectorsPerTrack
The number of sectors per track.
BytesPerSector
The number of bytes per sector.

Remarks

The DeviceIoControl function receives a DISK_GEOMETRY structure in response to an IOCTL_DISK_GET_DRIVE_GEOMETRY control code. The DeviceIoControl function receives an array of DISK_GEOMETRY structures in response to an IOCTL_STORAGE_GET_MEDIA_TYPES control code.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_STORAGE_GET_MEDIA_TYPES, MEDIA_TYPE


DISK_GEOMETRY_EX

[This is preliminary documentation and subject to change.]

The DISK_GEOMETRY_EX structure describes the geometry of disk devices and media.

typedef struct _DISK_GEOMETRY_EX {
    DISK_GEOMETRY Geometry;
    LARGE_INTEGER DiskSize;
    BYTE  Data[1];
} DISK_GEOMETRY_EX, *PDISK_GEOMETRY_EX;

Members

Geometry
A DISK_GEOMETRY structure.
DiskSize
Disk size, in bytes.
Data
Data buffer.

Remarks

DISK_GEOMETRY_EX is a variable-length structure composed of a DISK_GEOMETRY structure followed by a DISK_PARTITION_INFO structure and a DISK_DETECTION_INFO structure. Because the partition and detection information are not at fixed locations within the DISK_GEOMETRY_EX structure, use the following macro to access the DISK_PARTITION_INFO structure.

PDISK_PARTITION_INFO DiskGeometryGetPartition(
  DISK_GEOMETRY_EX Geometry
);

Similarly, use the following macro to access the DISK_DETECTION_INFO structure.

PDISK_DETECTION_INFO DiskGeometryGetDetect(
  DISK_GEOMETRY_EX Geometry
);

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DISK_DETECTION_INFO, DISK_GEOMETRY, DISK_PARTITION_INFO


DISK_INT13_INFO

[This is preliminary documentation and subject to change.]

The DISK_INT13_INFO structure contains standard Int13 drive parameters.

typedef struct _DISK_INT13_INFO {
        WORD   DriveSelect;
        DWORD  MaxCylinders;
        WORD   SectorsPerTrack;
        WORD   MaxHeads;
        WORD   NumberDrives;
} DISK_INT13_INFO, *PDISK_INT13_INFO;

Members

For a description of these members, consult your BIOS documentation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DISK_DETECTION_INFO


DISK_PARTITION_INFO

[This is preliminary documentation and subject to change.]

The DISK_PARTITION_INFO structure contains disk partition information.

typedef struct _DISK_PARTITION_INFO {
    DWORD SizeOfPartitionInfo;
    PARTITION_STYLE PartitionStyle;
    union {
        struct {
            DWORD Signature;
            DWORD CheckSum;
        } Mbr;
        struct {
            GUID DiskId;
        } Gpt;
    };
} DISK_PARTITION_INFO, *PDISK_PARTITION_INFO;

Members

SizeOfPartitionInfo
Size of the partition, in bytes.
PartitionStyle
The format of the partition. For a list of values, see PARTITION_STYLE.
Mbr
If PartitionStyle is PARTITION_STYLE_MBR, the union is a structure that contains information for an MBR partition. It includes a disk signature and a checksum.
Gpt
If PartitionStyle is PARTITION_STYLE_GPT, the union is a structure that contains information for a GPT partition. It includes a disk identifier (GUID).

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DISK_GEOMETRY_EX, PARTITION_STYLE


DISK_PERFORMANCE

The DISK_PERFORMANCE structure provides disk performance information. It is used by the IOCTL_DISK_PERFORMANCE control code.

typedef struct _DISK_PERFORMANCE {
  LARGE_INTEGER BytesRead;
  LARGE_INTEGER BytesWritten;
  LARGE_INTEGER ReadTime;
  LARGE_INTEGER WriteTime;
  LARGE_INTEGER IdleTime;
  DWORD ReadCount;
  DWORD WriteCount;
  DWORD QueueDepth;
  DWORD SplitCount;
  LARGE_INTEGER QueryTime;
  DWORD StorageDeviceNumber;
  WCHAR StorageManagerName[8];
} DISK_PERFORMANCE, *PDISK_PERFORMANCE;

Members

BytesRead
Specifies the number of bytes read.
BytesWritten
Specifies the number of bytes written.
ReadTime
Specifies the time it took to complete the read.
WriteTime
Specifies the time it took to complete the write.
IdleTime
Specifies the idle time.
ReadCount
Specifies the number of read operations.
WriteCount
Specifies the number of write operations.
QueueDepth
Specifies the depth of the queue.
SplitCount
Specifies the cumulative count of I/Os that are actually associated I/Os. An associated I/O is fragmented I/O, where multiple I/Os to the disk are required to fulfill the original logical I/O request. The most common example of such a situation is a file that is fragmented on the disk. Such multiple I/Os are counted as split I/O counts.
QueryTime
Specifies the system time stamp when the query for this structure was returned. Use this member to synchronize between the file system driver and the caller.
StorageDeviceNumber
Specifies a unique number for the device that identifies it to the storage manager indicated in the StorageManagerName member.
StorageManagerName
Specifies the name of the storage manager that controls this device. Examples of storage managers are "PhysDisk," "FTDISK," and "DMIO."

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_PERFORMANCE


DRIVE_LAYOUT_INFORMATION

The DRIVE_LAYOUT_INFORMATION structure provides information about a drive's partitions.

Note DRIVE_LAYOUT_INFORMATION has been supseded by the DRIVE_LAYOUT_INFORMATION_EX structure.

typedef struct _DRIVE_LAYOUT_INFORMATION {
  DWORD  PartitionCount;
  DWORD  Signature;
  PARTITION_INFORMATION  PartitionEntry[1];
} DRIVE_LAYOUT_INFORMATION, *PDRIVE_LAYOUT_INFORMATION;

Members

PartitionCount
The number of partitions on the drive.
Signature
A drive signature value.
PartitionEntry
A variable-sized array of PARTITION_INFORMATION structures, one structure for each partition on the drive.

Remarks

The DeviceIoControl function receives a DRIVE_LAYOUT_INFORMATION structure in response to an IOCTL_DISK_GET_DRIVE_LAYOUT control code. The DeviceIoControl function uses a DRIVE_LAYOUT_INFORMATION structure as input to an IOCTL_DISK_SET_DRIVE_LAYOUT control code.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, DRIVE_LAYOUT_INFORMATION_EX, IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_SET_DRIVE_LAYOUT


DRIVE_LAYOUT_INFORMATION_EX

[This is preliminary documentation and subject to change.]

The DRIVE_LAYOUT_INFORMATION_EX structure provides information about a drive's partitions.

typedef struct _DRIVE_LAYOUT_INFORMATION_EX {
  DWORD PartitionStyle;
  DWORD PartitionCount;
  union {
      DRIVE_LAYOUT_INFORMATION_MBR Mbr;
      DRIVE_LAYOUT_INFORMATION_GPT Gpt;
  };
  PARTITION_INFORMATION_EX PartitionEntry[1];
} DRIVE_LAYOUT_INFORMATION_EX, *PDRIVE_LAYOUT_INFORMATION_EX;

Members

PartitionStyle
The style of partitions on the drive. For a list of values, see PARTITION_STYLE.
PartitionCount
The number of partitions on the drive.
PartitionEntry
A variable size array of PARTITION_INFORMATION_EX structures, one structure for each partition on the drive.

Remarks

The DeviceIoControl function receives a DRIVE_LAYOUT_INFORMATION_EX structure in response to an IOCTL_DISK_GET_DRIVE_LAYOUT_EX control code. The DeviceIoControl function uses a DRIVE_LAYOUT_INFORMATION_EX structure as input to an IOCTL_DISK_SET_DRIVE_LAYOUT_EX control code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_GET_DRIVE_LAYOUT_EX, IOCTL_DISK_SET_DRIVE_LAYOUT_EX, PARTITION_INFORMATION_EX, PARTITION_STYLE


FILE_ALLOCATED_RANGE_BUFFER

The FILE_ALLOCATED_RANGE_BUFFER structure is used with the FSCTL_QUERY_ALLOCATED_RANGES control code to indicate a range of bytes in a file. On input to the FSCTL_QUERY_ALLOCATED_RANGES control code, the structure indicates the range of the file to search. On output, the operation retrieves an array of FILE_ALLOCATED_RANGE_BUFFER structures to indicate the allocated ranges within the search range.

typedef struct _FILE_ALLOCATED_RANGE_BUFFER {
  LARGE_INTEGER FileOffset;
  LARGE_INTEGER Length;
} FILE_ALLOCATED_RANGE_BUFFER, *PFILE_ALLOCATED_RANGE_BUFFER;

Members

FileOffset
Indicates the file offset, in bytes, of the start of a range of bytes in a file.
Length
Indicates the size, in bytes, of the range.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, FSCTL_QUERY_ALLOCATED_RANGES, Sparse Files


FILE_OBJECTID_BUFFER

The FILE_OBJECTID_BUFFER structure describes an object identifier in the Windows 2000 NTFS file system.

typedef struct _FILE_OBJECTID_BUFFER {
  BYTE ObjectId[16];
  union {
      struct {
          BYTE  BirthVolumeId[16];
          BYTE  BirthObjectId[16];
          BYTE  DomainId[16];
      } ;
      BYTE  ExtendedInfo[48];
  };
} FILE_OBJECTID_BUFFER, *PFILE_OBJECTID_BUFFER;

Members

ObjectId
Data that uniquely identifies the object within the volume on which it resides. This is the only data in the object identifier that is used in indexing.
ExtendedInfo
User-provided data. You can use it to contain the BirthVolumeID, BirthObjectID, and DomainID members as described later in this topic, or you can define a different data structure.
BirthVolumeId
The object identifier of the volume on which the object resided when the object identifier was created, or zero if the volume had no object identifier at that time. After copy operations, move operations, or other file operations, this may not be the same as the object identifier of the volume on which the object presently resides.
BirthObjectId
The object identifier of the object at the time it was created. After copy operations, move operations, or other file operations, this may not be the same as the ObjectId member at present.
DomainId
Reserved; must be zero.

Remarks

Object identifiers are Windows 2000 internal objects used by the operating system to track other objects such as files and directories. They are invisible to most applications and should never be modified by applications. Modifying an object identifier can result in the loss of data from portions of a file, up to and including entire volumes of data. Also, there is no guarantee that code to manipulate object identifiers will be forward compatible with future versions of Windows. Therefore, use standard Win32 functions to manipulate object identifiers and other operating system objects.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, FSCTL_CREATE_OR_GET_OBJECT_ID, FSCTL_DELETE_OBJECT_ID, FSCTL_GET_OBJECT_ID, FSCTL_SET_OBJECT_ID, FSCTL_SET_OBJECT_ID_EXTENDED


FILE_ZERO_DATA_INFORMATION

The FILE_ZERO_DATA_INFORMATION structure is used by the FSCTL_SET_ZERO_DATA control code to indicate a range of a file to set to zeroes.

typedef struct _FILE_ZERO_DATA_INFORMATION {
  LARGE_INTEGER FileOffset;
  LARGE_INTEGER BeyondFinalZero;
} FILE_ZERO_DATA_INFORMATION, *PFILE_ZERO_DATA_INFORMATION;

Members

FileOffset
Indicates the file offset, in bytes, of the start of the range to set to zeroes.
BeyondFinalZero
Indicates the byte offset of the first byte beyond the last zeroed byte.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, FSCTL_SET_ZERO_DATA, Sparse Files


FORMAT_PARAMETERS

The FORMAT_PARAMETERS structure provides information used in formatting a contiguous set of disk tracks. It it used by the IOCTL_DISK_FORMAT_TRACKS control code.

typedef struct _FORMAT_PARAMETERS{
  MEDIA_TYPE MediaType;
  DWORD StartCylinderNumber;
  DWORD EndCylinderNumber;
  DWORD StartHeadNumber;
  DWORD EndHeadNumber;
} FORMAT_PARAMETERS, *PFORMAT_PARAMETERS;

Members

MediaType
Specifies the media type. See MEDIA_TYPE.
StartCylinderNumber
Specifies the cylinder number at which to begin the format.
EndCylinderNumber
Specifies the cylinder number at which to end the format.
StartHeadNumber
Specifies the beginning head location.
EndHeadNumber
Specifies the ending head location.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_FORMAT_TRACKS, MEDIA_TYPE


FSCTL_QUERY_FAT_BPB_BUFFER

The FSCTL_QUERY_FAT_BPB_BUFFER structure describes the first 36 bytes of data on a FAT16 or FAT12 volume. It is used by the FSCTL_QUERY_FAT_BPB control code.

typedef struct _FSCTL_QUERY_FAT_BPB_BUFFER {
  BYTE  First0x24BytesOfBootSector[0x24];
} FSCTL_QUERY_FAT_BPB_BUFFER, *PFSCTL_QUERY_FAT_BPB_BUFFER;

Members

First0x24BytesOfBootSector[0x24]
The first 36 bytes of data from a FAT16 or FAT12 volume.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, FSCTL_QUERY_FAT_BPB


GET_LENGTH_INFORMATION

[This is preliminary documentation and subject to change.]

The GET_LENGTH_INFORMATION structure contains disk, volume, or partition length information used by the IOCTL_DISK_GET_LENGTH_INFO control code.

typedef struct {
  LARGE_INTEGER Length;
} GET_LENGTH_INFORMATION;

Members

Length
The length of the disk, volume, or partition.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Alsoo

Device Input and Output Overview, Device Input and Output Structures, IOCTL_DISK_GET_LENGTH_INFO


GET_CHANGER_PARAMETERS

[This is preliminary documentation and subject to change.]

The GET_CHANGER_PARAMETERS structure represents the parameters of a changer.

typedef struct _GET_CHANGER_PARAMETERS {
  DWORD Size;
  WORD  NumberTransportElements;
  WORD  NumberStorageElements;
  WORD  NumberCleanerSlots;
  WORD  NumberIEElements;
  WORD  NumberDataTransferElements;
  WORD  NumberOfDoors;
  WORD  FirstSlotNumber;
  WORD  FirstDriveNumber;
  WORD  FirstTransportNumber;
  WORD  FirstIEPortNumber;
  WORD  FirstCleanerSlotAddress;
  WORD  MagazineSize;
  WORD  DriveCleanTimeout;
  DWORD Features0;
  DWORD Features1;
  BYTE  MoveFromTransport;
  BYTE  MoveFromSlot;
  BYTE  MoveFromIePort;
  BYTE  MoveFromDrive;
  BYTE  ExchangeFromTransport;
  BYTE  ExchangeFromSlot;
  BYTE  ExchangeFromIePort;
  BYTE  ExchangeFromDrive;
  BYTE  LockUnlockCapabilities;
  BYTE  PositionCapabilities;
  BYTE  Reserved1[2];
  DWORD Reserved2[2];
} GET_CHANGER_PARAMETERS, *PGET_CHANGER_PARAMETERS;

Members

Size
Specifies the size of this structure, in bytes, as returned by sizeof.
NumberTransportElements
Indicates the number of transport elements in the changer. For a SCSI changer, this is defined in the element address page. This value is almost always 1, because most changers have a single transport element with one or two picker mechanisms. A changer that has two picker mechanisms on its transport must not be represented as having two transports, because pickers are not individually addressable. High-end media libraries can have dual and multiple transport elements for fault tolerance.
NumberStorageElements
Indicates the number of storage elements (slots) in the changer. For a SCSI changer, this is defined in the element address page. This value represents the maximum number of slots available for this changer including those in removable magazines, whether or not the magazines are installed. If NumberCleanerSlots is 1, then NumberStorageElements is 1 less than the maximum number of slots in the changer.
NumberCleanerSlots
Indicates the number of storage elements (slots) for cleaner cartridges in the changer. If NumberCleanerSlots is 1, then FirstCleanerSlotAddress indicates the zero-based address of the slot in which a drive cleaner should be inserted. If the changer does not support drive cleaning by programmatically moving the cleaner cartridge from its slot to a drive, NumberCleanerSlots is 0. NumberCleanerSlots cannot be greater than 1.
NumberIEElements
Indicates the number of IEport elements the changer has for inserting and ejecting media. For a SCSI changer, this is defined in the element address page. An IEport element must not be part of the storage element (slot) space, and it must be possible to transport media between the IEport and a slot using a MOVE MEDIUM command. If the changer has a door and not a true IEport, NumberIEElements is 0.
NumberDataTransferElements
Indicates the number of data transfer elements (drives) in the changer. For a SCSI changer, this is defined in the element address page. Unlike NumberStorageElements, which indicates the total number of possible slots whether or not the slots are actually present, NumberDataTransferElements indicates the number of drives that are actually present in the changer.
NumberOfDoors
Indicates the number of doors the changer has. A door provides access to all media in the changer at once, unlike an IEport, which provides access to one or more, but not all, media. A changer's door can be a physical front door or a single magazine that contains all media. If a changer supports only an IEport for inserting and ejecting media, NumberOfDoors is 0.
FirstSlotNumber
Indicates the number used by the changer vendor to identify the first storage element (slot) in the changer to the end user, either by marking a magazine or by defining a slot numbering scheme in the changer's operators guide. FirstSlotNumber is typically 0 or 1, but it can be the first address in a consecutive range of slot addresses defined by the vendor.
FirstDriveNumber
Indicates the number used by the changer vendor to identify the first data transfer element (drive) in the changer to the end user. FirstDriveNumber is typically 0 or 1, but it can be the first address in a consecutive range of drive addresses defined by the vendor.
FirstTransportNumber
Indicates the number used by the changer vendor to identify the first (and usually only) transport element in the changer to the end user. FirstTransportNumber is typically 0 or 1, but it can be the first address in a consecutive range of transport addresses defined by the vendor.
FirstIEPortNumber
Indicates the number used by the changer vendor to identify the first (and usually only) IEport in the changer to the end user. FirstIEPortNumber is typically 0 or 1, but it can be the first address in a consecutive range of IEport addresses defined by the vendor. If NumberIEElements is 0, FirstIEPortNumber must also be 0.
FirstCleanerSlotAddress
Indicates the number used by the changer vendor to identify the first (and only) slot address assigned to a drive cleaner cartridge to the end user. This must be the value defined by the vendor in the changer's operators guide. For example, if a changer has 8 slots numbered 1 through 8 and its operator's guide designates slot 8 as the drive cleaner slot, FirstSlotNumber would be 1 and FirstCleanerSlotAddress would be 8. If the same 8 slots were numbered 0 through 7, FirstSlotNumber would be 0 and FirstCleanerSlotAddress would be 7. If NumberCleanerSlots is 0, FirstCleanerSlotAddress must be 0.
MagazineSize
Indicates the number of slots in the removable magazines in the changer. This member is valid only if CHANGER_CARTRIDGE_MAGAZINE is set in Features0.
DriveCleanTimeout
Indicates twice the maximum number of seconds a cleaning is expected to take. The changer's drives should be cleaned by its cleaner cartridge in half the time specified by DriveCleanTimeout. For example, if a drive is typically cleaned in 300 seconds (5 minutes), DriveCleanTimeout should be set to 600.
Features0
Indicates the features supported by the changer. This member can have one or more of the following values.
Value | Meaning
CHANGER_BAR_CODE_SCANNER_INSTALLED | The changer supports a bar-code reader and the reader is installed.
CHANGER_CARTRIDGE_MAGAZINE | The changer uses removable cartridge magazines for some or all storage slots.
CHANGER_CLEANER_ACCESS_NOT_VALID | The ELEMENT_STATUS_ACCESS flag in a CHANGER_ELEMENT_STATUS structure for a data transport element is invalid when the transport element contains a cleaning cartridge.
CHANGER_CLEANER_SLOT | The changer has a slot designated for a cleaner cartridge. If this flag is set, NumberCleanerSlots must be 1 and FirstCleanerSlotAddress must specify the address of the cleaner slot.
CHANGER_CLOSE_IEPORT | The changer has an IEport and can retract the IEport programmatically
CHANGER_DEVICE_REINITIALIZE_CAPABLE | The changer can recalibrate its transport element in response to an explicit command.
CHANGER_DRIVE_CLEANING_REQUIRED | The changer's drives require periodic cleaning, which must be initiated by either the user or an application, and the changer can use its transport element to mount a cleaner cartridge in a drive.
CHANGER_DRIVE_EMPTY_ON_DOOR_ACCESS | The changer requires all drives to be empty (dismounted) before they can be accessed through its door.
CHANGER_EXCHANGE_MEDIA | The changer can exchange media between elements. For a SCSI changer, this flag indicates whether the changer supports the EXCHANGE MEDIUM command.
CHANGER_INIT_ELEM_STAT_WITH_RANGE | The changer can initialize elements within a specified range. For a SCSI changer, this flag indicates whether the changer supports the INITIALIZE ELEMENT STATUS WITH RANGE command.
CHANGER_KEYPAD_ENABLE_DISABLE | The changer keypad can be enabled and disabled programmatically.
CHANGER_LOCK_UNLOCK | The changer's door, IEport, or keypad can be locked or unlocked programmatically. If this flag is set, LockUnlockCapabilities indicates which elements can be locked or unlocked.
CHANGER_MEDIUM_FLIP | The changer's transport element supports flipping (rotating) media. For a SCSI changer, this flag reflects the rotate bit in the transport geometry parameters page.
CHANGER_OPEN_IEPORT | The changer has an IEport and can extend the IEport programmatically.
CHANGER_POSITION_TO_ELEMENT | The changer can position the transport to a particular destination. For a SCSI changer, this flag indicates whether the changer supports the POSITION TO ELEMENT command. If this flag is set, PositionCapabilities indicates the elements to which the transport can be positioned.
CHANGER_PREDISMOUNT_EJECT_REQUIRED | The changer requires an explicit command issued through a mass-storage driver (tape, disk, or CDROM, for example) to eject media from a drive before the changer can move the media from a drive to a slot.
CHANGER_PREMOUNT_EJECT_REQUIRED | The changer requires an explicit command issued through a mass storage driver to eject a drive mechanism before the changer can move media from a slot to the drive. For example, a changer with CD-ROM drives might require the tray to be presented to the robotic transport so that a piece of media could be loaded onto the tray during a mount operation.
CHANGER_REPORT_IEPORT_STATE | The changer can report whether media is present in the IEport. Such a changer must have a sensor in the IEport to detect the presence or absence of media.
CHANGER_SERIAL_NUMBER_VALID | The serial number is valid and unique for all changers of this type. Serial numbers are not guaranteed to be unique across vendor and product lines.
CHANGER_STATUS_NON_VOLATILE | The changer uses nonvolatile memory for element status information.
CHANGER_STORAGE_DRIVE | The changer can use a drive as an independent storage element; that is, it can store media in the drive without reading it. For a SCSI changer, this flag reflects the state of the DT bit in the device capabilities page.
CHANGER_STORAGE_IEPORT | The changer can use an IEport as an independent storage element. For a SCSI changer, this flag reflects the state of the I/E bit in the device capabilities page.
CHANGER_STORAGE_SLOT | The changer can use a slot as an independent storage element for media. For a SCSI changer, this flag reflects the state of the ST bit in the device capabilities page. Slots are the normal storage location for media, so the changer must support this functionality.
CHANGER_STORAGE_TRANSPORT | The changer can use a transport as an independent storage element. For a SCSI changer, this flag reflects the state of the MT bit in the device capabilities page.
CHANGER_VOLUME_ASSERT | The changer can verify volume information. For a SCSI changer, this flag indicates whether the changer supports the SEND VOLUME TAG command with a send action code of ASSERT.
CHANGER_VOLUME_IDENTIFICATION | The changer supports volume identification. For a SCSI changer, this flag indicates whether the changer supports the SEND VOLUME TAG and REQUEST VOLUME ELEMENT ADDRESS commands.
CHANGER_VOLUME_REPLACE | The changer can replace volume information. For a SCSI changer, this flag indicates whether the changer supports the SEND VOLUME TAG command with a send action code of REPLACE.
CHANGER_VOLUME_SEARCH | The changer can search for volume information. For a SCSI changer, this flag indicates whether the changer supports the supports the SEND VOLUME TAG command with a send action code of TRANSLATE.
CHANGER_VOLUME_UNDEFINE | The changer can clear existing volume information. For a SCSI changer, this flag indicates whether the changer supports the SEND VOLUME TAG command with a send action code of UNDEFINE.

Features1
Indicates additional features supported by the changer. This member can be one or more of the following values.
Value | Meaning
CHANGER_CLEANER_AUTODISMOUNT | The changer will move the cleaning cartridge back to its original slot automatically after cleaning is finished.
CHANGER_CLEANER_OPS_NOT_SUPPORTED | The changer does not support automatic cleaning of its elements.
CHANGER_IEPORT_USER_CONTROL_CLOSE | The changer requires the user to manually close an open IEport.
CHANGER_IEPORT_USER_CONTROL_OPEN | The changer requires the user to manually open a closed IEport.
CHANGER_MOVE_EXTENDS_IEPORT | The changer will extend the tray automatically whenever a command is issued to move media to an IEport.
CHANGER_MOVE_RETRACTS_IEPORT | The changer will retract the tray automatically whenever a command is issued to move media from an IEport.
CHANGER_PREDISMOUNT_ALIGN_TO_DRIVE | The changer requires an explicit command to position the transport element to a drive before it can eject media from the drive.
CHANGER_PREDISMOUNT_ALIGN_TO_SLOT | The changer requires an explicit command to position the transport element to a slot before it can eject media from the slot.
CHANGER_RTN_MEDIA_TO_ORIGINAL_ADDR | The changer requires media to be returned to its original slot after it has been moved.
CHANGER_SLOTS_USE_TRAYS | The changer uses removable trays in its slots, which require the media to be placed in a tray and the tray moved to the desired position.
CHANGER_TRUE_EXCHANGE_CAPABLE | The changer can exchange media between a source and a destination in a single operation. This flag is valid only if CHANGER_EXCHANGE_MEDIA is also set in Features0.

MoveFromTransport
Indicates whether the changer supports moving a piece of media from a transport element to another transport element, a storage slot, an IEport, or a drive. For a SCSI changer, this is defined in the device capabilities page. The transport is not typically the source or destination for moving or exchanging media.

To determine whether the changer can move media to a given element, use the following values.
Value | Meaning
CHANGER_TO_DRIVE | The changer can carry out the operation from the specified element to a drive.
CHANGER_TO_IEPORT | The changer can carry out the operation from the specified element to an IEport.
CHANGER_TO_SLOT | The changer can carry out the operation from the specified element to a storage slot.
CHANGER_TO_TRANSPORT | The changer can carry out the operation from the specified element to a transport.

MoveFromSlot
Indicates whether the changer supports moving medium from a storage slot to a transport element, another storage slot, an IEport, or a drive. Use the flags described under MoveFromTransport to determine whether the changer supports the move.
MoveFromIePort
Indicates whether the changer supports moving medium from an IEport to a transport element, a storage slot, another IEport, or a drive. For a SCSI changer, this is defined in the device capabilities page. Use the flags described under MoveFromTransport to determine whether the changer supports the move
MoveFromDrive
Indicates whether the changer supports moving medium from a drive to a transport element, a storage slot, an IEport, or another drive. Use the flags described under MoveFromTransport to determine whether the changer supports the move.
ExchangeFromTransport
Indicates whether the changer supports exchanging medium between a transport element and another transport element, a storage slot, an IEport, or a drive. Use the flags described under MoveFromTransport to determine whether the changer supports the exchange.
ExchangeFromSlot
Indicates whether the changer supports exchanging medium between a storage slot and a transport element, another storage slot, an IEport, or a drive. Use the flags described under MoveFromTransport to determine whether the changer supports the exchange.
ExchangeFromIePort
Indicates whether the changer supports exchanging medium between an IEport and a transport element, a storage slot, another IEport, or a drive. Use the flags described under MoveFromTransport to determine whether the changer supports the exchange.
ExchangeFromDrive
Indicates whether the changer supports exchanging medium between a drive and a transport element, a storage slot, an IEport, or another drive. Use the flags described under MoveFromTransport to determine whether the changer supports the exchange.
LockUnlockCapabilities
Indicates which elements of a changer can be locked or unlocked programmatically. This member is valid only if CHANGER_LOCK_UNLOCK is set in Features0.

To determine whether the changer can lock or unlock a particular element, use one or more of the following values.
Value | Meaning
LOCK_UNLOCK_DOOR | The changer can lock or unlock its door.
LOCK_UNLOCK_IEPORT | The changer can lock or unlock its IEport.
LOCK_UNLOCK_KEYPAD | The changer can lock or unlock its keypad.

PositionCapabilities
Indicates the elements to which a changer can position its transport. Use the flags described under MoveFromTransport to determine whether the changer supports positioning the transport to a particular element. This member is valid only if CHANGER_POSITION_TO_ELEMENT is set in Features0.
Reserved1
Reserved for future use.
Reserved2
Reserved for future use.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_CHANGER_GET_PARAMETERS


HFS_INFORMATION_BUFFER

The HFS_INFORMATION_BUFFER structure contains Macintosh Finder information. It is used by the FSCTL_GET_HFS_INFORMATION control code.

typedef struct {
  BYTE FinderInfo[32];
} HFS_INFORMATION_BUFFER, *PHFS_INFORMATION_BUFFER;

Members

FinderInfo[32]
Macintosh Finder data.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, FSCTL_GET_HFS_INFORMATION


MARK_HANDLE_INFO

The MARK_HANDLE_INFO structure contains information used to mark a specified file or directory and its change journal record with data about changes. It is used by the FSCTL_MARK_HANDLE control code.

typedef struct {
  DWORD UsnSourceInfo;
  HANDLE VolumeHandle;
  DWORD HandleInfo;
} MARK_HANDLE_INFO, *PMARK_HANDLE_INFO;

Members

UsnSourceInfo
Information regarding the type of changes being made. The operation does not modify the file or directory externally from the point of view of the application that created it. The following values are defined.
Value Meaning
USN_SOURCE_DATA_MANAGEMENT The operation provides information about a change to the file or directory made by the operating system.

A typical use is when Remote Storage moves data from external to local storage. Remote Storage is the hierarchical storage management software in Windows 2000. Such a move usually at a minimum adds the USN_REASON_DATA_OVERWRITE flag to a USN record. However, the data has not changed from the users' point of view. By noting USN_SOURCE_DATA_MANAGEMENT in the SourceInfo member of the USN_RECORD structure holding the record, you can determine that although a write operation was performed on the item, data has not changed.
USN_SOURCE_AUXILIARY_DATA The operation adds a private data stream to a file or directory.

An example might be a virus detector adding checksum information. As the virus detector modifies the item, the system generates USN records. USN_SOURCE_AUXILIARY_DATA indicates that the modifications did not change the application data.

VolumeHandle
Direct Access to Storage Device (DASD) handle to the volume on which the file or directory resides. This handle is required to check the privileges for this operation. To retrieve a DASD handle to a volume, call CreateFile with the lpFileName parameter set to a string of the following form:
\\.\X:

where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.

HandleInfo
Reserved; must be set to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CreateFile, DeviceIoControl, FSCTL_MARK_HANDLE, USN_RECORD


MFT_ENUM_DATA

The MFT_ENUM_DATA structure contains information defining the boundaries for and starting place of an enumeration of change journal records. It is used by the FSCTL_ENUM_USN_DATA control code.

typedef struct {
  DWORDLONG StartFileReferenceNumber;
  USN LowUsn;
  USN HighUsn;
} MFT_ENUM_DATA, *PMFT_ENUM_DATA;

Members

StartFileReferenceNumber
Ordinal position within the files on the current volume at which the enumeration is to begin.

The first call to FSCTL_ENUM_USN_DATA during an enumeration must have the StartFileReferenceNumber member set to (DWORDLONG)0. Each call to FSCTL_ENUM_USN_DATA retrieves the starting point for the subsequent call as the first entry in the output buffer. Subsequent calls must be made with StartFileReferenceNumber set to this value. For more information, see FSCTL_ENUM_USN_DATA.

LowUsn
Lower boundary of the range of USN values used to filter which records are returned. Only records whose last change journal USN is between or equal to the LowUsn and HighUsn member values are returned.
HighUsn
Upper boundary of the range of USN values used to filter which files are returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, FSCTL_ENUM_USN_DATA


MOVE_FILE_DATA

The MOVE_FILE_DATA structure provides input data to the FSCTL_MOVE_FILE control code.

typedef struct {
  HANDLE FileHandle;
  LARGE_INTEGER StartingVcn;
  LARGE_INTEGER StartingLcn;
  DWORD ClusterCount;
} MOVE_FILE_DATA, *PMOVE_FILE_DATA;

Members

FileHandle
Handle to the file to be moved. To retrieve a handle to a file, use CreateFile.

If the file is encrypted, the handle must have FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE access. For more information, see File and Directory Security.

StartingVcn
The VCN (cluster number relative to the beginning of the file) of the first cluster to be moved.
StartingLcn
The LCN (cluster number on the volume) to which the VCN is to be moved.
ClusterCount
The count of clusters to be moved.

Remarks

To retrieve data to fill in this structure, use the DeviceIoControl FSCTL_GET_RETRIEVAL_POINTERS control code.

The first cluster of a directory on a FAT volume cannot be moved.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, Defragmentation, DeviceIoControl, CreateFile, GetFileAttributesEx, GetFileAttributes, GetFileInformationByHandle, FSCTL_GET_RETRIEVAL_POINTERS, FSCTL_MOVE_FILE


PARTITION_INFORMATION

The PARTITION_INFORMATION structure provides information about a disk partition.

Note PARTITION_INFORMATION has been superseded by the PARTITION_INFORMATION_EX structure.

typedef struct _PARTITION_INFORMATION {
  LARGE_INTEGER StartingOffset;
  LARGE_INTEGER PartitionLength;
  DWORD HiddenSectors;
  DWORD PartitionNumber;
  BYTE  PartitionType;
  BOOLEAN BootIndicator;
  BOOLEAN RecognizedPartition;
  BOOLEAN RewritePartition;
} PARTITION_INFORMATION, *PPARTITION_INFORMATION;

Members

StartingOffset
Specifies the starting offset of the partition.
PartitionLength
Specifies the length of the partition.
HiddenSectors
Specifies the number of hidden sectors in the partition.
PartitionNumber
Specifies the number of the partition (1-based).
PartitionType
Specifies the type of partition. For a list of values, see Partition Types.
BootIndicator
Specifies whether the partition is bootable.
RecognizedPartition
Specifies whether the partition is recognized.
RewritePartition
Specifies whether the partition information has changed. When you change a partition (with IOCTL_DISK_SET_DRIVE_LAYOUT), the system uses this member to determine which partitions have changed and need their information rewritten.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_DRIVE_LAYOUT, IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION_EX


PARTITION_INFORMATION_EX

[This is preliminary documentation and subject to change.]

The PARTITION_INFORMATION_EX structure contains partition information for standard AT- and EFI-formatted disks.

typedef struct {
  PARTITION_STYLE PartitionStyle;
  LARGE_INTEGER StartingOffset;
  LARGE_INTEGER PartitionLength;
  DWORD PartitionNumber;
  BOOLEAN RewritePartition;
  union {
     PARTITION_INFORMATION_MBR Mbr;
     PARTITION_INFORMATION_GPT Gpt;
  };
} PARTITION_INFORMATION_EX;

Members

PartitionStyle
Specifies the format of the partition. For a list of values, see PARTITION_STYLE.
StartingOffset
Specifies the starting offset of the partition.
PartitionLength
Specifies the length of the partition in bytes.
PartitionNumber
Specifies the 1-based number of the partition.
RewritePartition
Specifies whether the partition is rewritable. The value of this parameter should be set to TRUE.
Mbr
Specifies partition information specific to MBR-formatted disks. The MBR (master boot record) partition format is the standard AT-style format. For more information, see PARTITION_INFORMATION_MBR.
Gpt
Specifies partition information specific to GPT-formatted disks. The GPT (GUID partition table) format corresponds to the EFI partition format. For more information, see PARTITION_INFORMATION_GPT.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, IOCTL_DISK_GET_PARTITION_INFO_EX, IOCTL_DISK_SET_PARTITION_INFO_EX, PARTITION_INFORMATION_GPT, PARTITION_INFORMATION_MBR, PARTITION_STYLE


PARTITION_INFORMATION_GPT

[This is preliminary documentation and subject to change.]

The PARTITION_INFORMATION_GPT structure contains partition information specific to EFI-formatted disks.

typedef struct _PARTITION_INFORMATION_GPT {
  GUID PartitionType;
  GUID PartitionId;
  DWORD64 Attributes;
  WCHAR Name[36];
} PARTITION_INFORMATION_GPT;

Members

PartitionType
Specifies the Unique Partition GUID of the partition. Each partition type supported by the EFI specification is identified by its own GUID, which is published by the developer of the partition type.
PartitionId
Specifies the GUID of this partition.
Attributes
Specifies the EFI attributes of the partition. Currently there are no EFI attributes defined for this operation, so the value of this parameter should always be zero.
Name
Specifies the name of this partition, in Unicode characters.

Remarks

The GPT (GUID partition table) partition format is synonymous with the EFI partition format.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, PARTITION_INFORMATION_EX, IOCTL_DISK_GET_PARTITION_INFO_EX, IOCTL_DISK_SET_PARTITION_INFO_EX


PARTITION_INFORMATION_MBR

[This is preliminary documentation and subject to change.]

The PARTITION_INFORMATION_MBR structure contains partition information specific to MBR disks.

typedef struct _PARTITION_INFORMATION_MBR {
  BYTE PartitionType;
  BOOLEAN BootIndicator;
  BOOLEAN RecognizedPartition;
  DWORD HiddenSectors;
} PARTITION_INFORMATION_MBR;

Members

PartitionType
Specifies the type of partition. For a list of values, see Partition Types.
BootIndicator
Specifies whether the partition is a boot partition. When this structure is used with the IOCTL_DISK_SET_PARTITION_INFO_EX control code, the value of this parameter is ignored.
RecognizedPartition
Specifies whether the partition is of a recognized type. When this structure is used with the IOCTL_DISK_SET_PARTITION_INFO_EX control code, the value of this parameter is ignored.
HiddenSectors
Specifies the number of hidden sectors to be allocated when the partition table is created.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, IOCTL_DISK_GET_PARTITION_INFO_EX, IOCTL_DISK_SET_PARTITION_INFO_EX, PARTITION_INFORMATION_EX


PLEX_READ_DATA_REQUEST

[This is preliminary documentation and subject to change.]

The PLEX_READ_DATA_REQUEST structure indicates the range of the read operation to perform and which plex to read from.

typedef struct _PLEX_READ_DATA_REQUEST {
    LARGE_INTEGER ByteOffset;
    DWORD ByteLength;
    DWORD PlexNumber;
} PLEX_READ_DATA_REQUEST, *PPLEX_READ_DATA_REQUEST;

Members

ByteOffset
Offset of the range to read. The offset can be the virtual offset to a file or volume. File offsets should be cluster aligned and volume offsets should be sector aligned.
ByteLength
Length of the range to read. The maximum value is 64K.
PlexNumber
Plex to read from. A value of zero indicates the primary copy, a value of one indicates the secondary copy, and so on.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, FSCTL_READ_FROM_PLEX


PREVENT_MEDIA_REMOVAL

The PREVENT_MEDIA_REMOVAL structure provides removable media locking data. It is used by the IOCTL_STORAGE_MEDIA_REMOVAL control code.

typedef struct _PREVENT_MEDIA_REMOVAL{
  BOOLEAN PreventMediaRemoval;
} PREVENT_MEDIA_REMOVAL;

Members

PreventMediaRemoval
Specifies whether the media is to be locked (if TRUE) or not (if FALSE).

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_STORAGE_MEDIA_REMOVAL


READ_ELEMENT_ADDRESS_INFO

[This is preliminary documentation and subject to change.]

The READ_ELEMENT_ADDRESS_INFO structure represents volume tag information. It is used by the IOCTL_CHANGER_QUERY_VOLUME_TAGS control code.

typedef struct _READ_ELEMENT_ADDRESS_INFO {
  DWORD NumberOfElements;
  CHANGER_ELEMENT_STATUS ElementStatus[1];
} READ_ELEMENT_ADDRESS_INFO, *PREAD_ELEMENT_ADDRESS_INFO;

Members

NumberOfElements
Number of elements matching criteria set forth by the ActionCode member of CHANGER_SEND_VOLUME_TAG_INFORMATION.

For information on compatibility with the current device, see the Features0 member of GET_CHANGER_PARAMETERS.

ElementStatus
Array of CHANGER_ELEMENT_STATUS structures, one for each element that corresponded with the information passed in with the CHANGER_SEND_VOLUME_TAG_INFORMATION structure.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CHANGER_ELEMENT_STATUS, CHANGER_SEND_VOLUME_TAG_INFORMATION, DeviceIoControl, IOCTL_CHANGER_QUERY_VOLUME_TAGS


READ_USN_JOURNAL_DATA

The READ_USN_JOURNAL_DATA structure contains information defining a set of change journal records to return to the calling process. It is used by the FSCTL_QUERY_USN_JOURNAL and FSCTL_READ_USN_JOURNAL control codes.

typedef struct {
  USN StartUsn;
  DWORD ReasonMask;
  DWORD ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA, *PREAD_USN_JOURNAL_DATA;

Members

StartUsn
USN at which to begin reading the change journal.

To start the read operation at the first record in the journal, set the StartUsn member to zero. Because a USN is contained in every journal record, the output buffer tells at which record the read operation actually started.

To start the read operation at a specific record, set StartUsn to that record's USN.

If a nonzero USN is specified that is less than the first USN in the change journal, then an error occurs and the ERROR_JOURNAL_ENTRY_DELETED error code is returned. This code may indicate a case in which the specified USN was valid at one time but has since been deleted.

For more information on navigating the change journal buffer returned in READ_USN_JOURNAL_DATA, see Walking a Buffer of Change Journal Records.

ReasonMask
Mask of flags, each flag noting a change for which the file or directory has a record in the change journal. To be returned in a FSCTL_READ_USN_JOURNAL operation, a change journal record must have at least one of these flags set.

The list of valid flags is as follows. Unused bits are reserved.
Value | Meaning
USN_REASON_
BASIC_INFO_CHANGE 		A user has either changed one or more file or directory attributes (such as the read-only, hidden, system, archive, or sparse attribute), or one or more time stamps.
USN_REASON_CLOSE | The file or directory was closed.
USN_REASON_COMPRESSION_CHANGE | The compression state of the file or directory was changed from or to compressed.
USN_REASON_DATA_EXTEND | The file or directory was added to.
USN_REASON_DATA_OVERWRITE | Data in the file or directory was overwritten.
USN_REASON_DATA_TRUNCATION | The file or directory was truncated.
USN_REASON_EA_CHANGE | The user made a change to the file's or directory's extended attributes. These NTFS attributes are not accessible to Win32-based applications.
USN_REASON_ENCRYPTION_CHANGE | The file or directory was encrypted or decrypted.
USN_REASON_FILE_CREATE | The file or directory was created for the first time.
USN_REASON_FILE_DELETE | The file or directory was deleted.
USN_REASON_HARD_LINK_CHANGE | An NTFS hard link was added to or removed from the file or directory. An NTFS hard link, similar to a POSIX hard link, is one of several directory entries that refer to the same file or directory.
USN_REASON_INDEXABLE_CHANGE | A user changed the FILE_ATTRIBUTE_NOT_CONTENT_INDEXED attribute. That is, the user changed the file or directory from one that can be content indexed to one that cannot, or vice versa. (Content indexing permits rapid searching of data by building a database of selected content.)
USN_REASON_NAMED_DATA_EXTEND | One or more named data streams for the file were added to.
USN_REASON_NAMED_DATA_OVERWRITE | Data in one or more named data streams for the file was overwritten.
USN_REASON_NAMED_DATA_TRUNCATION | One or more named data streams for the file were truncated.
USN_REASON_OBJECT_ID_CHANGE | The object identifier of the file or directory was changed.
USN_REASON_RENAME_NEW_NAME | The file or directory was renamed, and the file name in the USN_RECORD structure holding this journal record is the new name.
USN_REASON_RENAME_OLD_NAME | The file or directory was renamed, and the file name in the USN_RECORD structure holding this journal record is the previous name.
USN_REASON_REPARSE_POINT_CHANGE | The reparse point contained in the file or directory was changed, or a reparse point was added to or deleted from the file or directory.
USN_REASON_SECURITY_CHANGE | A change was made in the access permissions to the file or directory.
USN_REASON_STREAM_CHANGE | A named stream has been added to or removed from the file or directory, or a named stream has been renamed.

ReturnOnlyOnClose
Value that specifies when to return change journal records.

To receive notification when the final handle for the changed file or directory is closed, rather than at the time a change occurs, set ReturnOnlyOnClose to any nonzero value and specify the USN_REASON_CLOSE flag in the ReasonMask member.

All changes indicated by ReasonMask flags eventually generate a call to the change journal software when the file is closed. If your DeviceIoControl call is waiting for the file to be closed, that call in turn will allow your DeviceIoControl call to return. In the event that a file or directory is not closed prior to a volume failure, operating system failure, or shutdown, a cleanup call to the change journal software occurs the next time the volume is mounted. The call occurs even if there is an intervening system restart.

To receive notification the first time each change is logged, as well as at cleanup, set ReturnOnlyOnClose to zero.

Whether ReturnOnlyOnClose is zero or nonzero, the records generated at cleanup log within the change journal all reasons for USN changes that occurred to the file or directory. Each time a final close operation occurs for an item, a USN close record is written to the change journal, and the ReasonMask flags for the item are all reset.

For a file or directory for which no user data exists (for example, a volume mount point), the final close operation occurs when the CloseHandle function is called on the last user handle to the item.

Timeout
Time-out value, in seconds, used with the BytesToWaitFor member to tell the operating system what to do if the FSCTL_READ_USN_JOURNAL operation requests more data than exists in the change journal.

If Timeout is zero, BytesToWaitFor is nonzero, and the FSCTL_READ_USN_JOURNAL operation call reaches the end of the change journal without finding data to return, FSCTL_READ_USN_JOURNAL waits until BytesToWaitFor bytes of unfiltered data have been added to the change journal and then retrieves the specified records.

If Timeout is nonzero, BytesToWaitFor is nonzero, and the FSCTL_READ_USN_JOURNAL operation call reaches the end of the change journal without finding data to return, FSCTL_READ_USN_JOURNAL waits Timeout seconds and then attempts to return the specified records. After Timeout seconds, FSCTL_READ_USN_JOURNAL retrieves any records available within the specified range.

In either case, after the time-out period any new data appended to the change journal is processed. If there are still no records to return from the specified set, the time-out period is repeated. In this mode, FSCTL_READ_USN_JOURNAL remains outstanding until at least one record is returned or I/O is canceled.

If BytesToWaitFor is zero, then Timeout is ignored. Timeout is also ignored for asynchronously opened handles.

BytesToWaitFor
Number of bytes of unfiltered data added to the change journal. Use this value with Timeout to tell the operating system what to do if the FSCTL_READ_USN_JOURNAL operation requests more data than exists in the change journal.

If BytesToWaitFor is zero, then Timeout is ignored. In this case, the FSCTL_READ_USN_JOURNAL operation always returns successfully when the end of the change journal file is encountered. It also retrieves the USN that should be used for the next FSCTL_READ_USN_JOURNAL operation. When the returned next USN is the same as the StartUsn supplied, there are no records available. The calling process should not use FSCTL_READ_USN_JOURNAL again immediately.

Because the amount of data returned cannot be predicted when BytesToWaitFor is zero, you run a risk of overflowing the output buffer. To reduce this risk, specify a nonzero BytesToWaitFor value in repeated FSCTL_READ_USN_JOURNAL operations until all records in the change journal are exhausted. Then specify zero to await new records.

Alternatively, use the lpBytesReturned parameter of DeviceIoControl in the FSCTL_READ_USN_JOURNAL operation call to determine the amount of data available, reallocate the output buffer (with room to spare for new records), and call DeviceIoControl again.

UsnJournalID
Identifier that indicates the instance of the journal current for the volume.

NTFS can miss putting events in the change journal if the change journal is stopped and restarted or deleted and recreated. If either of these events occurs, NTFS gives the journal a new identifier. If the journal identifier you supply in the UsnJournalID member does not agree with the current journal identifier, the call to DeviceIoControl fails and returns an appropriate error code. To retrieve the new journal identifier, call DeviceIoControl with the FSCTL_QUERY_USN_JOURNAL operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, CloseHandle, DeviceIoControl, FSCTL_QUERY_USN_JOURNAL, FSCTL_READ_USN_JOURNAL, USN_RECORD


REASSIGN_BLOCKS

The REASSIGN_BLOCKS structure provides disk-block reassignment data. It is a variable-length structure whose last member is an array of block numbers to be reassigned. It is used by the IOCTL_DISK_REASSIGN_BLOCKS control code.

typedef struct _REASSIGN_BLOCKS {
  WORD   Reserved;
  WORD   Count;
  DWORD BlockNumber[1];
} REASSIGN_BLOCKS ;

Members

Reserved
This member is reserved. Do not use it. Set it to zero.
Count
Specifies the number of blocks to be reassigned. This is the number of elements that are in the BlockNumber member array.
BlockNumber
An array of Count block numbers, one for each block to be reassigned.

Remarks

The DeviceIoControl function uses a REASSIGN_BLOCKS structure as input to an IOCTL_DISK_REASSIGN_BLOCKS control code.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_REASSIGN_BLOCKS


REPARSE_GUID_DATA_BUFFER

The REPARSE_GUID_DATA_BUFFER structure contains information about a reparse point. It is used by the FSCTL_GET_REPARSE_POINT control code.

typedef struct _REPARSE_GUID_DATA_BUFFER {
  DWORD  ReparseTag;
  WORD   ReparseDataLength;
  WORD   Reserved;
  GUID   ReparseGuid;
  struct {
      BYTE   DataBuffer[1];
  } GenericReparseBuffer;
} REPARSE_GUID_DATA_BUFFER, *PREPARSE_GUID_DATA_BUFFER;

Members

ReparseTag
Reparse point tag. The ReparseTag member indicates the structure of the user-defined reparse data. For more information, see Reparse Point Tags.
ReparseDataLength
Size, in bytes, of the reparse data in the DataBuffer member. This value may vary with different tags and may vary between two uses of the same tag.
Reserved
Reserved; do not use.
ReparseGuid
GUID that uniquely identifies the kind of reparse point, as the ReparseTag member also does. When setting a reparse point, the software setting the point must provide a non-NULL GUID in the ReparseGuid member. When retrieveing a reparse point from the file system, ReparseGuid is the GUID assigned when the reparse point was set.
DataBuffer
User-defined data for the reparse point. The nature of this data is up to the reparse point implementer. The tag in the ReparseTag member and the GUID in the ReparseGuid member indicate the nature of the data.

Remarks

The REPARSE_GUID_DATA_BUFFER structure is used by all third-party layered drivers to store data for a reparse point. Each reparse point contains one instance of a REPARSE_GUID_DATA_BUFFER structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winnt.h; include Windows.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, FSCTL_GET_REPARSE_POINT


RETRIEVAL_POINTERS_BUFFER

The RETRIEVAL_POINTERS_BUFFER structure is the output buffer for the FSCTL_GET_RETRIEVAL_POINTERS control code.

typedef struct RETRIEVAL_POINTERS_BUFFER {
  DWORD ExtentCount;
  LARGE_INTEGER StartingVcn;
  struct {
      LARGE_INTEGER NextVcn;
      LARGE_INTEGER Lcn;
  } Extents[1];
} RETRIEVAL_POINTERS_BUFFER, *PRETRIEVAL_POINTERS_BUFFER;

Members

ExtentCount
The count of Extents structure elements in the present RETRIEVAL_POINTERS_BUFFER structure.
StartingVcn
The starting VCN returned by the function call. This is not necessarily the VCN requested by the function call, as the file system driver may round down to the first VCN of the extent in which the requested starting VCN is found.
Extents
An array of Extents structures. For the number of members in the array, see ExtentCount. Each member of the array has the following members:
Member | Meaning
NextVcn | The VCN at which the next extent begins. This value minus either StartingVcn (for the first Extents array member) or the NextVcn of the previous member of the array (for all other Extents array members) is the length, in clusters, of the current extent. The length is an input to the DeviceIoControl FSCTL_MOVE_FILE operation.
Lcn | The LCN at which the current extent begins on the volume. This value is an input to the DeviceIoControl FSCTL_MOVE_FILE operation. On NTFS, the value (LONGLONG) –1 indicates either a compression unit which is partially allocated, or an unallocated region of a sparse file.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, Defragmentation, DeviceIoControl, FSCTL_GET_RETRIEVAL_POINTERS, FSCTL_MOVE_FILE


SET_PARTITION_INFORMATION

The SET_PARTITION_INFORMATION structure provides information used to set a disk partition's type.

Note SET_PARTITION_INFORMATION has been superseded by the PARTITION_INFORMATION_EX structure.

typedef struct _SET_PARTITION_INFORMATION {
  BYTE PartitionType;
} SET_PARTITION_INFORMATION, *PSET_PARTITION_INFORMATION;

Members

PartitionType
Specifies the type of partition. For a list of values, see Partition Types.

Remarks

The DeviceIoControl function uses a SET_PARTITION_INFORMATION structure as input to an IOCTL_DISK_SET_PARTITION_INFO control code.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION_EX


STARTING_LCN_INPUT_BUFFER

The STARTING_LCN_INPUT_BUFFER structure provides the starting LCN to the FSCTL_GET_VOLUME_BITMAP control code.

typedef struct {
  LARGE_INTEGER StartingLcn;
} STARTING_LCN_INPUT_BUFFER, *PSTARTING_LCN_INPUT_BUFFER;

Members

StartingLcn
The LCN from which the DeviceIoControl FSCTL_GET_VOLUME_BITMAP operation should start when describing a bitmap. The StartingLcn member will be rounded down to a file-system-dependent rounding boundary, and that value will be returned. This value should be an integral multiple of eight.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, Defragmentation, DeviceIoControl, FSCTL_GET_VOLUME_BITMAP


STARTING_VCN_INPUT_BUFFER

The STARTING_VCN_INPUT_BUFFER structure provides the starting VCN to the FSCTL_GET_RETRIEVAL_POINTERS control code.

typedef struct {
  LARGE_INTEGER StartingVcn;
} STARTING_VCN_INPUT_BUFFER, *PSTARTING_VCN_INPUT_BUFFER;

Members

StartingVcn
The VCN at which FSCTL_GET_RETRIEVAL_POINTERS will begin enumerating extents in the file. This value may be rounded down to the first VCN of the extent in which the given extent is found.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, Defragmentation, DeviceIoControl, FSCTL_GET_RETRIEVAL_POINTERS


USN_JOURNAL_DATA

The USN_JOURNAL_DATA structure represents a change journal, its records, and its capacity. It is the output buffer for the FSCTL_QUERY_USN_JOURNAL control code.

typedef struct {
  DWORDLONG UsnJournalID;
  USN FirstUsn;
  USN NextUsn;
  USN LowestValidUsn;
  USN MaxUsn;
  DWORDLONG MaximumSize;
  DWORDLONG AllocationDelta;
} USN_JOURNAL_DATA, *PUSN_JOURNAL_DATA;

Members

UsnJournalID
Current journal identifier. A journal is assigned a new identifier on creation and can be stamped with a new identifier in the course of its existence. NTFS uses this identifier for an integrity check.
FirstUsn
Number of first record that can be read from the journal.
NextUsn
Number of next record to be written to the journal.
LowestValidUsn
First record that was written into the journal for this journal instance. Enumerating the files or directories on a volume can return a USN lower than this value (in other words, a FirstUsn member value less than the LowestValidUsn member value). If it does, the journal has been stamped with a new identifier since the last USN was written. In this case, LowestValidUsn may indicate a discontinuity in the journal, in which changes to some or all files or directories on the volume may have occurred that are not recorded in the change journal.
MaxUsn
Largest USN that the change journal supports. An administrator must delete the change journal as the value of NextUsn approaches this value.
MaximumSize
Target maximum size for the change journal, in bytes. The change journal can grow larger than this value, but it is then truncated at the next NTFS checkpoint to less than this value.
AllocationDelta
Number of bytes of disk memory added to the end and removed from the beginning of the change journal each time memory is allocated or deallocated. In other words, allocation and deallocation take place in units of this size. An integer multiple of a cluster size is a reasonable value for this member.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, FSCTL_QUERY_USN_JOURNAL


USN_RECORD

The USN_RECORD structure contains the information for a change journal version 2.0 record. Win32-based applications should not attempt to work with change journal versions earlier than 2.0.

typedef struct {
  DWORD RecordLength;
  WORD MajorVersion;
  WORD MinorVersion;
  DWORDLONG FileReferenceNumber;
  DWORDLONG ParentFileReferenceNumber;
  USN Usn;
  LARGE_INTEGER TimeStamp;
  DWORD Reason;
  DWORD SourceInfo;
  DWORD SecurityId;
  DWORD FileAttributes;
  WORD FileNameLength;
  WORD FileNameOffset;
  WCHAR FileName[1];
} USN_RECORD, *PUSN_RECORD;

Members

RecordLength
Total length of the record in bytes. Because USN_RECORD is of variable size, the RecordLength member should be used when calculating the address of the next record in an output buffer, such as a buffer returned from operations for the DeviceIoControl function that work with USN_RECORD.

The size in bytes of any change journal record is at most the size of the USN_RECORD structure, plus MaximumComponentLength characters minus 1 (for the character declared in the structure) times the size of a wide character. The value of MaximumComponentLength may be determined by calling the function GetVolumeInformation . In C, you can determine a record's size as follows:

(MaximumComponentLength * sizeof(WCHAR) + sizeof(USN_RECORD) - sizeof(WCHAR))

To maintain compatibility across version changes of the change journal software, use a run-time calculation to determine the size of the USN_RECORD structure. For more information about compatibility across version changes, see the Remarks section later in this topic.

MajorVersion
Major version number of the change journal software for this record. For example, if the change journal software is version 2.0, the major version number is 2.
MinorVersion
Minor version number of the change journal software for this record. For example, if the change journal software is version 2.0, the minor version number is 0.
FileReferenceNumber
Ordinal number of the file or directory for which this record notes changes. This is an arbitrarily assigned value that associates a journal record with a file.
ParentFileReferenceNumber
Ordinal number of the directory in which the file or directory associated with this record is located. This is an arbitrarily assigned value that associates a journal record with a parent directory.
Usn
USN of this record.
TimeStamp
Standard UTC time stamp of this record, in 64-bit format.
Reason
Flags describing reasons for changes that have accumulated in this file or directory journal record since the file or directory opened. When a file or directory closes, then a final USN record is generated with the USN_REASON_CLOSE flag set. The next change (for example, after the next open operation or deletion) starts a new record with a new set of reason flags.

Note that a rename or move operation generates two USN records, one recording the old parent directory for the item and one recording a new parent.

The list of valid flags is as follows. Unused bits are reserved.
Value | Meaning
USN_REASON_BASIC_INFO_CHANGE | A user has either changed one or more file or directory attributes (such as the read-only, hidden, system, archive, or sparse attribute), or one or more time stamps.
USN_REASON_CLOSE | The file or directory was closed.
USN_REASON_COMPRESSION_CHANGE | The compression state of the file or directory was changed from or to compressed.
USN_REASON_DATA_EXTEND | The file or directory was added to.
USN_REASON_DATA_OVERWRITE | Data in the file or directory was overwritten.
USN_REASON_DATA_TRUNCATION | The file or directory was truncated.
USN_REASON_EA_CHANGE | The user made a change to the file's or directory's extended attributes. These NTFS attributes are not accessible to Win32-based applications.
USN_REASON_ENCRYPTION_CHANGE | The file or directory was encrypted or decrypted.
USN_REASON_FILE_CREATE | The file or directory was created for the first time.
USN_REASON_FILE_DELETE | The file or directory was deleted.
USN_REASON_HARD_LINK_CHANGE | An NTFS hard link was added to or removed from the file or directory. An NTFS hard link, similar to a POSIX hard link, is one of several directory entries that refer to the same file or directory.
USN_REASON_INDEXABLE_CHANGE | A user changed the FILE_ATTRIBUTE_NOT_CONTENT_INDEXED attribute. That is, the user changed the file or directory from one that can be content indexed to one that cannot, or vice versa. (Content indexing permits rapid searching of data by building a database of selected content.)
USN_REASON_NAMED_DATA_EXTEND | One or more named data streams for the file were added to.
USN_REASON_NAMED_DATA_OVERWRITE | Data in one or more named data streams for the file was overwritten.
USN_REASON_NAMED_DATA_TRUNCATION | One or more named data streams for the file was truncated.
USN_REASON_OBJECT_ID_CHANGE | The object identifier of the file or directory was changed.
USN_REASON_RENAME_NEW_NAME | The file or directory was renamed, and the file name in this USN_RECORD structure is the new name.
USN_REASON_RENAME_OLD_NAME | The file or directory was renamed, and the file name in this USN_RECORD structure is the previous name.
USN_REASON_REPARSE_POINT_CHANGE | The reparse point contained in the file or directory was changed, or a reparse point was added to or deleted from the file or directory.
USN_REASON_SECURITY_CHANGE | A change was made in the access rights to the file or directory.
USN_REASON_STREAM_CHANGE | A named stream has been added to or removed from the file, or a named stream has been renamed.

SourceInfo
Additional information about the source of the change, set by the FSCTL_MARK_HANDLE DeviceIoControl operation. One of the two following values can be set.
Value Meaning
USN_SOURCE_DATA_MANAGEMENT The operation provides information about a change to the file or directory made by the operating system.

A typical use is when the Remote Storage system moves data from external to local storage. Remote Storage is the hierarchical storage management software in Windows 2000. Such a move usually at a minimum adds the USN_REASON_DATA_OVERWRITE flag to a USN record. However, the data has not changed from the users' point of view. By noting USN_SOURCE_DATA_MANAGEMENT in the SourceInfo member, you can determine that although a write operation was performed on the item, data has not changed.
USN_SOURCE_AUXILIARY_DATA The operation adds a private data stream to a file or directory.

An example might be a virus detector adding checksum information. As the virus detector modifies the item, the system generates USN records. USN_SOURCE_AUXILIARY_DATA indicates that the modifications did not change the application data.

SecurityId
Unique security identifier assigned to the file or directory associated with this record.
FileAttributes
Attributes for the file or directory associated with this record, as returned by the GetFileAttributes function. Attributes of streams associated with the file or directory are excluded.
FileNameLength
Length, in bytes, of the name of the file or directory associated with this record. The FileName member contains the name for which the FileNameLength member indicates the length. Use FileNameLength to determine file name length, rather than depending on a trailing '\0' to delimit the file name in FileName.
FileNameOffset
Offset of the FileName member from the beginning of the structure.
FileName
Name of the file or directory associated with this record in Unicode format. This file or directory name is of variable length.

When working with FileName, do not count on the file name containing a trailing '\0' delimiter, but instead determine the length of the file name with FileNameLength.

Do not perform any compile-time pointer arithmetic using FileName. Instead, make any necessary calculations at run time using the value of the FileNameOffset member. Doing so helps make your code compatible with any future versions of USN_RECORD.

Remarks

In output buffers returned from DeviceIoControl operations that work with USN_RECORD, all records are aligned on 64-bit boundaries from the start of the buffer.

To provide a path for upward compatibility in change journal clients, Microsoft provides a major and minor version number of the change journal software in the USN_RECORD structure. Your code should examine these values, detect its own compatibility with the change journal software, and if necessary gracefully handle any incompatibility.

A change in the minor version number indicates that the existing USN_RECORD structure members are still valid, but that new members may have been added between the penultimate member and the last, which is a variable-length string. In order to handle such a change gracefully, your code should not do any compile-time pointer arithmetic that relies on the location of the last member. For example, this makes the C code sizeof(USN_RECORD) unreliable. Instead, rely on run-time calculations using the RecordLength member.

An increase in the major version number of the change journal software indicates that the USN_RECORD structure may have undergone major changes and that the current definition may not be reliable. If your code detects a change in the major version number of the change journal software, it should not work with the change journal.

For more information on working with change journal records, see Creating, Modifying, and Deleting a Change Journal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, GetVolumeInformation, FSCTL_MARK_HANDLE, FSCTL_READ_USN_JOURNAL, GetFileAttributes, READ_USN_JOURNAL_DATA


VERIFY_INFORMATION

The VERIFY_INFORMATION structure provides information used to logically format a disk extent. It is the output buffer for the IOCTL_DISK_VERIFY control code.

typedef struct _VERIFY_INFORMATION {
  LARGE_INTEGER  StartingOffset;
  DWORD  Length;
} VERIFY_INFORMATION, *PVERIFY_INFORMATION;

Members

StartingOffset
Specifies the starting offset of the disk extent.
Length
Length, in bytes, of the disk extent.

Remarks

The DeviceIoControl function uses a VERIFY_INFORMATION structure as input to an IOCTL_DISK_VERIFY control code.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_DISK_VERIFY


VOLUME_BITMAP_BUFFER

The VOLUME_BITMAP_BUFFER structure represents the occupied and available clusters on a disk. It is the output buffer for the FSCTL_GET_VOLUME_BITMAP control code.

typedef struct {
  LARGE_INTEGER StartingLcn;
  LARGE_INTEGER BitmapSize;
  BYTE  Buffer[1];
} VOLUME_BITMAP_BUFFER, *PVOLUME_BITMAP_BUFFER;

Members

StartingLcn
The starting LCN requested as an input to the DeviceIoControl FSCTL_GET_VOLUME_BITMAP operation.
BitmapSize
The number of clusters on the volume, starting from the starting LCN returned in the StartingLcn member of this structure. See the following Remarks section for details.
Buffer
An array of bytes containing the bitmap that the operation returns. The bitmap is bitwise from bit zero of the bitmap to the end. Thus, starting at the requested cluster, the bitmap goes from bit 0 of byte 0, bit 1 of byte 0 ... bit 7 of byte 0, bit 0 of byte 1, and so on. The value 1 indicates that the cluster is allocated (in use). The value 0 indicates that the cluster is not allocated (free).

Remarks

The BitmapSize member is the number of clusters on the volume starting from the starting LCN returned in the StartingLcn member of this structure. For example, suppose there are 0xD3F7 clusters on the volume. If you start the bitmap query at LCN 0xA007, then both the FAT and NTFS file systems will round down the returned starting LCN to LCN 0xA000. The value returned in the BitmapSize member will be (0xD3F7 – 0xA000), or 0x33F7.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, Defragmentation, DeviceIoControl, FSCTL_GET_VOLUME_BITMAP


VOLUME_DISK_EXTENTS

[This is preliminary documentation and subject to change.]

The VOLUME_DISK_EXTENTS structure represents a physical location on a disk. It is the output buffer for the IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS control code.

typedef struct _VOLUME_DISK_EXTENTS {
    DWORD       NumberOfDiskExtents;
    DISK_EXTENT Extents[1];
} VOLUME_DISK_EXTENTS, *PVOLUME_DISK_EXTENTS;

Members

NumberOfDiskExtents
The number of disks in the volume (a volume can span multiple disks). An extent is a contiguous run of sectors on one disk.
Extents
An array of DISK_EXTENT structures.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, DISK_EXTENT, IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS


Device Input and Output Enumeration Types

The following enumeration types are used with device input and output.

ELEMENT TYPE
MEDIA_TYPE
PARTITION_STYLE


ELEMENT_TYPE

[This is preliminary documentation and subject to change.]

The ELEMENT_TYPE enumeration type defines values that are used to specify the element type of a changer device.

typedef  enum _ELEMENT_TYPE {
  AllElements,
  ChangerTransport,
  ChangerSlot,
  ChangerIEPort,
  ChangerDrive,
  ChangerDoor,
  ChangerKeypad
} ELEMENT_TYPE, *PELEMENT_TYPE;

Enumeration Values

AllElements
All elements of a changer, including its robotic transport, drives, slots, and import/export ports (IEport). AllElements is valid only with IOCTL_CHANGER_GET_ELEMENT_STATUS or IOCTL_CHANGER_INITIALIZE_ELEMENT_STATUS.
ChangerTransport
The changer's robotic transport element, which is used to move media between IEports, slots, and drives.
ChangerSlot
A storage element, which is a slot in the changer in which media is stored when not mounted in a drive.
ChangerIEPort
An IEport element, which is a single- or multiple-cartridge access port in some changers. An element is an IEport only if it is possible to move a piece of media from a slot to the IEport.
ChangerDrive
A data transfer element where data can be read from and written to media.
ChangerDoor
A mechanism that provides access to all media in a changer at one time (as compared to an IEport that provides access to one or more, but not all, media). For example, a large front door or a magazine that contains all media in the changer is an element of this type. ChangerDoor is valid only with IOCTL_CHANGER_SET_ACCESS.
ChangerKeypad
The keypad or other input control on the front panel of a changer. ChangerKeypad is valid only with IOCTL_CHANGER_SET_ACCESS.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Enumeration Types, CHANGER_ELEMENT, DeviceIoControl


MEDIA_TYPE

The MEDIA_TYPE enumeration type contains values that specify various forms of device media. The comments explain the enumerators.

typedef enum _MEDIA_TYPE {
  Unknown,
  F5_1Pt2_512,
  F3_1Pt44_512,
  F3_2Pt88_512,
  F3_20Pt8_512,
  F3_720_512,
  F5_360_512,
  F5_320_512,
  F5_320_1024,
  F5_180_512,
  F5_160_512,
  RemovableMedia,
  FixedMedia,
  F3_120M_512,
  F3_640_512,
  F5_640_512,
  F5_720_512,
  F3_1Pt2_512,
  F3_1Pt23_1024,
  F5_1Pt23_1024,
  F3_128Mb_512,
  F3_230Mb_512,
  F8_256_128,
  F3_200Mb_512
} MEDIA_TYPE;

Enumeration Values

Unknown
Format is unknown
F5_1Pt2_512
A 5.25" floppy, with 1.2MB and 512 bytes/sector.
F3_1Pt44_512
A 3.5" floppy, with 1.44MB and 512 bytes/sector.
F3_2Pt88_512
A 3.5" floppy, with 2.88MB and 512 bytes/sector.
F3_20Pt8_512
A 3.5" floppy, with 20.8MB and 512 bytes/sector.
F3_720_512
A 3.5" floppy, with 720KB and 512 bytes/sector.
F5_360_512
A 5.25" floppy, with 360KB and 512 bytes/sector.
F5_320_512
A 5.25" floppy, with 320KB and 512 bytes/sector.
F5_320_1024
A 5.25" floppy, with 320KB and 1024 bytes/sector.
F5_180_512
A 5.25" floppy, with 180KB and 512 bytes/sector.
F5_160_512
A 5.25" floppy, with 160KB and 512 bytes/sector.
RemovableMedia
Removable media other than floppy.
FixedMedia
Fixed hard disk media.
F3_120M_512
A 3.5" floppy, with 120MB and 512 bytes/sector.
F3_640_512
A 3.5" floppy, with 640MB and 512 bytes/sector.
F5_640_512
A 5.25" floppy, with 640KB and 512 bytes/sector.
F5_720_512
A 5.25" floppy, with 720KB and 512 bytes/sector.
F3_1Pt2_512
A 3.5" floppy, with 1.2MB and 512 bytes/sector.
F3_1Pt23_1024
A 3.5" floppy, with 1.23MB and 1024 bytes/sector.
F5_1Pt23_1024
A 5.25" floppy, with 1.23KB and 1024 bytes/sector.
F3_128Mb_512
A 3.5" floppy, with 128MB and 512 bytes/sector.
F3_230Mb_512
A 3.5" floppy, with 230MB and 512 bytes/sector.
F8_256_128
An 8" floppy, with 256KB and 128 bytes/sector.
F3_200Mb_512
A 3.5" floppy, with 200MB (HiFD).

Remarks

The MediaType member of the DISK_GEOMETRY data structure is of type MEDIA_TYPE. The DeviceIoControl function receives a DISK_GEOMETRY structure in response to an IOCTL_DISK_GET_DRIVE_GEOMETRY control code. The DeviceIoControl function receives an array of DISK_GEOMETRY structures in response to an IOCTL_STORAGE_GET_MEDIA_TYPES control code.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Enumeration Types, DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_STORAGE_GET_MEDIA_TYPES


PARTITION_STYLE

[This is preliminary documentation and subject to change.]

This enumeration contains values that identify the format of a partition.

typedef enum _PARTITION_STYLE {
  PARTITION_STYLE_MBR,
  PARTITION_STYLE_GPT,
  PARTITION_STYLE_RAW
} PARTITION_STYLE;

Enumeration Values

PARTITION_STYLE_MBR
The partition is initialized in the MBR format. This corresponds to standard AT-style master boot records.
PARTITION_STYLE_GPT
The partition is initialized in the GPT format.
PARTITION_STYLE_RAW
The partition is not formatted in either of the recognized formats—MBR or GPT. It is considered a raw partition.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Enumeration Types, PARTITION_INFORMATION_EX, IOCTL_DISK_GET_PARTITION_INFO_EX, IOCTL_DISK_SET_PARTITION_INFO_EX


Partition Types

The following are valid partition types used by disk drivers.

Value | Meaning
PARTITION_EXTENDED | Specifies an extended partition entry.
PARTITION_FAT_12 | Specifies a partition with 12-bit FAT entries.
PARTITION_FAT_16 | Specifies a partition with 16-bit FAT entries.
PARTITION_FAT32 | Specifies a FAT32 partition.
PARTITION_FAT32_XINT13 | Windows 95/98/Me: Same as PARTITION_FAT32, but uses extended int13 services.
PARTITION_HUGE | Specifies an MS-DOS V4 huge partition.
PARTITION_IFS | Specifies an IFS partition.
PARTITION_LDM | Specifies a logical disk manager partition.
PARTITION_NTFT | Specifies an NTFT partition.
PARTITION_OS2BOOTMGR | Specifies an OS/2 boot manager partition.
PARTITION_PREP | Specifies a PowerPC Reference Platform (PReP) partition.
PARTITION_UNIX | Specifies a UNIX partition.
PARTITION_XENIX_1 | Specifies a Xenix type 1 partition.
PARTITION_XENIX_2 | Specifies a Xenix type 2 partition.
PARTITION_XINT13 | Windows 95/98/Me: Specifies a partition that uses extended int13 services.
PARTITION_XINT13_EXTENDED | Windows 95/98/Me: Same as PARTITION_EXTENDED, but uses extended int13 services.
VALID_NTFT | The high bit of the partition type code indicates that a partition is part of an NTFT mirror or striped array.

See Also

PARTITION_INFORMATION_EX, PARTITION_INFORMATION_MBR, SET_PARTITION_INFORMATION


Device Management

Device management provides a way to uniformly notify all applications and system components of changes that may affect their operation or access to resources. Applications and the system use and process device events to take advantage of new resources when they become available and to prevent loss of data when existing resources become unavailable.

  • About Device Management
  • Using Device Management
  • Device Management Reference


About Device Management

The system uses messages to notify applications of device changes and power changes. Device messages notify applications of device change events; power messages notify applications of power management events. Applications and drivers can also define and use custom messages to enable notification of other types of events. This overview provides information on the following topics:

  • Plug and Play Device Management
  • Device Messages
  • Device Event Types
  • Device Notifications
  • Device Events
  • Device Interfaces

For more information about power messages, see Power Management.


Plug and Play Device Management

Plug and Play (PnP) is a combination of hardware and software support that enables applications and the system to recognize and adapt to changes in hardware configuration. As another benefit, users can add or remove devices while the system is in use, without performing manual configuration.

Windows 2000 and Windows 98 use the Advanced Configuration and Power Interface (ACPI) to support Plug and Play and power management. This includes support for the following:

  • Automatic and dynamic recognition of installed hardware
  • Hardware resource allocation and reallocation
  • Loading of appropriate drivers
  • An interface for driver interaction with the Plug and Play system
  • Dynamic handling of device management and power management events
  • Registration for device notification events


Device Messages

Device messages are system messages that notify applications and other components of device change events. These events occur whenever the system detects a change to the system hardware, such as when the user docks and undocks a laptop computer, or inserts or removes a device such as a PCMCIA card. Device events can occur while the system is running or when the system resumes operation after temporarily being suspended.

To help ensure that applications do not lose data when devices become unavailable, the system monitors the hardware configuration and sends device messages to the applications to notify them of the changes and to give them the opportunity to prepare for the changes before they occur.

For each device event, the system broadcasts a WM_DEVICECHANGE message to all applications. In this message, the wParam parameter identifies the device event type and the lParam parameter is a pointer to event-specific data.


Device Event Types

To determine the device event type when processing a WM_DEVICECHANGE message, examine the wParam parameter. The value of wParam determines the meaning of the event-specific data in the lParam parameter. In general, the event-specific data identifies the device and provides additional detail about the event. The format of this data depends on the device type, but the first few bytes always have the same format as the DEV_BROADCAST_HDR structure. To determine the format of the data, check the dbch_devicetype member.

The system broadcasts a device event of type DBT_DEVICEARRIVAL (that is, a WM_DEVICECHANGE message with wParam set to DBT_DEVICEARRIVAL) whenever a device has been inserted and is available for use. Applications typically check the device type and begin using the device immediately if it is appropriate.

The system broadcasts a DBT_DEVICEQUERYREMOVE device event to request permission to remove a device. To determine whether it needs the device, an application can display a dialog box to prompt the user for instructions. If an application determines that it needs the device, it can deny this request and cancel the removal by returning BROADCAST_QUERY_DENY. If the application does not need the device, it must return TRUE. The system immediately sends a DBT_DEVICEQUERYREMOVEFAILED message if any application or driver canceled a previous request to remove a device.

The system broadcasts a DBT_DEVICEREMOVEPENDING device event as a last warning before a device is removed. At this point, the application cannot cancel the removal, so if it is using the device it must prepare for its removal to prevent loss of data. This is especially important when a network connection is being removed. The application must determine whether any of its open files or pipes are on that connection. It can do this by comparing the network resource identifier in the event-specific data of the message with the resource identifiers previously obtained for the files and pipes. The system broadcasts a DBT_DEVICEREMOVECOMPLETE device event when a device has been removed and is no longer available.

The system broadcasts a DBT_QUERYCHANGECONFIG device event to request permission to change the current configuration (dock or undock). Any application can return BROADCAST_QUERY_DENY to deny the request and cancel the change. If an application denies the request, the system sends a DBT_CONFIGCHANGECANCELED message. If the current configuration has changed, due to a dock or undock, the system sends a DBT_CONFIGCHANGED message.

The system broadcasts a DBT_DEVICETYPESPECIFIC device event whenever a device-specific event occurs.

Drivers can create their own custom event types. Custom events are sent only to application that have registered for device-event notification on a particular device, and can only be initiated by kernel-mode drivers. For more information, see DBT_CUSTOMEVENT.


Device Notifications

The system broadcasts device change events to all applications and services. To specify which events your application or service should receive, use the RegisterDeviceNotification function.

When an application or service calls RegisterDeviceNotification, it also specifies the window that will receive the notification events. Services can specify a service status handle instead of a window handle. If a service specifies its service status handle, its service control handler will receive the notification events. For more information, see HandlerEx.

Device notification handles returned by RegisterDeviceNotification must be closed by calling the UnregisterDeviceNotification function when they are no longer needed.


Device Events

Applications, including services, can register to receive notification of device events. For example, a catalog service can receive notice of volumes being mounted or dismounted so it can adjust the paths to files on the volume. The system notifies an application that a device event has occurred by sending the application a WM_DEVICECHANGE message. The system notifies a service that a device event has occurred by invoking the service's event handler function, HandlerEx.

To receive device event notices, call the RegisterDeviceNotification function with a DEV_BROADCAST_HANDLE structure. Be sure to set the dbch_handle member to the device handle obtained from the CreateFile function. Also, set the dbch_devicetype member to DBT_DEVTYP_HANDLE. The function returns a device notification handle. Note that this is not the same as the volume handle.

When your application receives notification, if the event type is DBT_CUSTOMEVENT, you may have received one of the device events defined in IoEvent.h. To determine if one of these events has occurred, use the following steps.

  1. Treat the event data as a DEV_BROADCAST_HDR structure. Verify that the dbch_devicetype member is set to DBT_DEVTYPE_HANDLE.
  2. If dbch_devicetype is DBT_DEVTYPE_HANDLE, the event data is really a pointer to a DEV_BROADCAST_HANDLE structure.
  3. Compare the dbch_eventguid member to the GUIDs listed in the following table using the IsEqualGUID function.
Device Event GUID | Meaning
GUID_IO_VOLUME_CHANGE | The volume label has changed.
GUID_IO_VOLUME_DISMOUNT | An attempt to dismount the volume is in progress. You should close all handles to files and directories on the volume. GUID_IO_VOLUME_DISMOUNT will not necessarily be preceded by a GUID_IO_VOLUME_LOCK notice.
GUID_IO_VOLUME_DISMOUNT_FAILED | An attempt to dismount a volume failed. This often happens because another process failed to respond to a GUID_IO_VOLUME_DISMOUNT notice by closing its outstanding handles. Because the dismount failed, you may reopen any handles to the affected volume.
GUID_IO_VOLUME_LOCK | Another process is attempting to lock the volume. You should close all handles to files and directories on the volume.
GUID_IO_VOLUME_LOCK_FAILED | An attempt to lock a volume failed. This often happens because another process failed to respond to a GUID_IO_VOLUME_LOCK notice by closing its outstanding handles. Because the lock failed, you may reopen any handles to the affected volume.
GUID_IO_VOLUME_MOUNT | The volume has been mounted by another process. You may open one or more handles to it.
GUID_IO_VOLUME_UNLOCK | The volume has been unlocked by another process. You may open one or more handles to it.

The GUID_IO_VOLUME_DISMOUNT and GUID_IO_VOLUME_DISMOUNT_FAILED events are related, as are the GUID_IO_VOLUME_LOCK and GUID_IO_VOLUME_LOCK_FAILED event. The GUID_IO_VOLUME_DISMOUNT and GUID_IO_VOLUME_LOCK events indicate that an operation is being attempted. You should act on the event notification, and record the action taken. The GUID_IO_VOLUME_DISMOUNT_FAILED and GUID_IO_VOLUME_LOCK_FAILED events indicate that the attempted operation failed. You may then use your record to undo the actions you made in response to the operation.

The dbch_hdevnotify member of the DEV_BROADCAST_HANDLE structure indicates the affected device. Note that this is the device notification handle returned by RegisterDeviceNotification, not a volume handle. To perform operations on the volume, map this handle to the corresponding volume handle.


Device Interfaces

Device drivers provide a uniform and extensible way for applications and the system to interact with them programmatically, known as a device interface. Drivers expose, register, and enable device interfaces. A driver can expose zero, one, or more than one interface for a particular device. A device interface is represented by a GUID.

Each device interface is a member of a device interface class. A device interface class is a group of device interfaces with the same functionality. For example, all the joysticks on a system could be members of the joystick device interface class. A device interface class is identified by a class GUID.

When an application must communicate with a device, it searches for a device that exports the required interface. To perform the search, use the following steps.

  1. Call the SetupDiGetClassDevs or SetupDiGetClassDevsEx function to obtain a list of all devices in a specified device class. This list is known as a device information set.
  2. Call the SetupDiEnumDeviceInterfaces function to enumerate all devices of the specified class that export the interface.

To communicate with the device, call the SetupDiGetDeviceInterfaceDetail function. This function returns device information in an SP_DEVICE_INTERFACE_DETAIL_DATA structure. The DevicePath member provides the symbolic link name, which can be used in the CreateFile function to access the device.


Using Device Management

  • Processing a request to remove a device
  • Registering for Device Notification
  • Enumerating Current Devices


Processing a Request to Remove a Device

An application receives a DBT_DEVICEQUERYREMOVE device event when a component in the system has decided to remove a specified device. When the application receives this event, it should determine whether it is using the specified device and either cancel or prepare for the removal.

In the following example, an application maintains an open handle, hFile, to the file or device represented by FileName. The application registers for device event notification on the underlying device by calling the RegisterDeviceNotification function, using a DBT_DEVTYP_HANDLE type notification filter and specifying hFile in the dbch_handle member of the filter.

The application processes the DBT_DEVICEQUERYREMOVE device event by closing the open file handle to the device that is to be removed. In the event that removal of this device is canceled, the application processes the DBT_DEVICEQUERYREMOVEFAILED device event to reopen the handle to the device. After the device has been removed from the system, the application processes the DBT_DEVICEREMOVECOMPLETE device event by unregistering its notification handle for the device.

LPCTSTR FileName;   // path to the file or device of interest
HANDLE  hFile;      // handle to the file or device
PDEV_BROADCAST_HDR pDevBroadcastHdr;
PDEV_BROADCAST_HANDLE pDevBroadcastHandle;
DWORD Err;

case WM_DEVICECHANGE:
    switch (wParam)
    {
        case DBT_DEVICEQUERYREMOVE:
            pDevBroadcastHdr = (PDEV_BROADCAST_HDR) lParam;
            switch (pDevBroadcastHdr->dbch_devicetype)
            {
                case DBT_DEVTYP_HANDLE:
                    // A request has been made to remove the device;
                    // close any open handles to the file or device

                    pDevBroadcastHandle = (PDEV_BROADCAST_HANDLE) pDevBroadcastHdr;
                    if (hFile != INVALID_HANDLE_VALUE)
                    {
                        CloseHandle(hFile);
                        hFile = INVALID_HANDLE_VALUE;
                    }
            }
            return TRUE;

        case DBT_DEVICEQUERYREMOVEFAILED:
            pDevBroadcastHdr = (PDEV_BROADCAST_HDR) lParam;
            switch (pDevBroadcastHdr->dbch_devicetype)
            {
                case DBT_DEVTYP_HANDLE:
                    // Removal of the device has failed;
                    // reopen a handle to the file or device

                    pDevBroadcastHandle = (PDEV_BROADCAST_HANDLE) pDevBroadcastHdr;
                    hFile = CreateFile(FileName,
                                       GENERIC_READ,
                                       FILE_SHARE_READ,
                                       NULL,
                                       OPEN_EXISTING,
                                       FILE_ATTRIBUTE_NORMAL,
                                       NULL);
                    if (hFile == INVALID_HANDLE_VALUE)
                    {
                        Err = GetLastError();
                        printf( "CreateFile failed: %lx.\n", Err);
                    }
            }
            return TRUE;

        case DBT_DEVICEREMOVEPENDING:
            pDevBroadcastHdr = (PDEV_BROADCAST_HDR) lParam;
            switch (pDevBroadcastHdr->dbch_devicetype)
            {
                case DBT_DEVTYP_HANDLE:
                    // All queries for removal of the device were
                    // successful; device removal is pending

                    ;
            }
            return TRUE;

        case DBT_DEVICEREMOVECOMPLETE:
            pDevBroadcastHdr = (PDEV_BROADCAST_HDR) lParam;
            switch (pDevBroadcastHdr->dbch_devicetype)
            {
                case DBT_DEVTYP_HANDLE:
                    pDevBroadcastHandle = (PDEV_BROADCAST_HANDLE) pDevBroadcastHdr;
                    // The device has been removed from the system;
                    // unregister its notification handle

                    UnregisterDeviceNotification(pDevBroadcastHandle->dbch_hdevnotify);
            }
            return TRUE;

        default:
            return TRUE;
    }


Registering for Device Notification

Applications can use the RegisterDeviceNotification function to register to receive notification messages from the system. The following example function demonstrates how to register for notification of events for the device interfaces which are members of the interface class whose GUID is passed to the function.

BOOL DoRegisterDeviceInterface(
    GUID InterfaceClassGuid,
    HDEVNOTIFY *hDevNotify
)
/*
Routine Description:
    Registers for notification of changes in the device interfaces for
    the specified interface class GUID.

Parameters:
    InterfaceClassGuid - The interface class GUID for the device
        interfaces.

    hDevNotify - Receives the device notification handle. On failure,
        this value is NULL.

Return Value:
    If the function succeeds, the return value is TRUE.

    If the function fails, the return value is FALSE.
*/
{
    DEV_BROADCAST_DEVICEINTERFACE NotificationFilter;
    DWORD Err;

    ZeroMemory( &NotificationFilter, sizeof(NotificationFilter) );
    NotificationFilter.dbcc_size =
        sizeof(DEV_BROADCAST_DEVICEINTERFACE);
    NotificationFilter.dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE;
    NotificationFilter.dbcc_classguid = InterfaceClassGuid;

    *hDevNotify = RegisterDeviceNotification( hWnd,
        &NotificationFilter,
        DEVICE_NOTIFY_WINDOW_HANDLE
    );

    if(!*hDevNotify)
    {
        Err = GetLastError();
        printf( "RegisterDeviceNotification failed: %lx.\n", Err);
        return FALSE;
    }

    return TRUE;
}

The application will receive the WM_DEVICECHANGE message whenever a device interface event notification is sent. Currently, the only events that will be received for device interfaces are DBT_DEVICEARRIVAL and DBT_DEVICEREMOVECOMPLETE.


Enumerating Current Devices

Applications can use the SetupDiGetClassDevsEx function to retrieve the list of current devices. The following example function demonstrates how to retrieve this list.

HDEVINFO DoDeviceEnum( GUID InterfaceClassGuid
)
/*
Routine Description:
    Retrieves the device information set that contains that contains
    the devices of the specified class.

Parameters:
    InterfaceClassGuid - The interface class GUID.

Return Value:
    If the function succeeds, the return value is a handle to the
    device information set.

    If the function fails, the return value is zero.
*/
{
    HDEVINFO DeviceInfoSet;
    HDEVINFO NewDeviceInfoSet;

    // Create a device information set that will be the container for
    // the device interfaces.

    DeviceInfoSet = SetupDiCreateDeviceInfoList(NULL, NULL);

    if(DeviceInfoSet == INVALID_HANDLE_VALUE) {
        Err = GetLastError();
        printf( "SetupDiCreateDeviceInfoList failed: %lx.\n", Err );
        return 0;
    }

    // Retrieve the device information set for the interface class.

    NewDeviceInfoSet = SetupDiGetClassDevsEx( InterfaceClassGuid,
        NULL,
        NULL,
        DIGCF_PRESENT | DIGCF_DEVICEINTERFACE,
        DeviceInfoSet,
        NULL,
        NULL
    );

    if(NewDeviceInfoSet == INVALID_HANDLE_VALUE)
    {
        Err = GetLastError();
        printf( "SetupDiGetClassDevsEx failed: %lx.\n", Err );
        return 0;
    }

    return NewDeviceInfoSet;
}

After you have registered to receive device interface notification messages, you can call this function to obtain a device information set that contains the current list of device interfaces. When you receive a DBT_DEVICEARRIVAL event, you can use the SetupDiOpenDeviceInterface function to add the device interface to the device information set. When you receive a DBT_DEVICEREMOVECOMPLETE event, you can use the SetupDiDeleteDeviceInterfaceData function to delete the device interface from the device information set.


Device Management Reference

The following elements are used in device management.

  • Device Management Functions
  • Device Management Messages
  • Device Management Events
  • Device Management Structures


Device Management Functions

The following functions are used in device management.

Function | Description
RegisterDeviceNotification | Specifies the device or type of device for which a window will receive notifications.
SetupDiCreateDeviceInfoList | Creates an empty device information set.
SetupDiCreateDeviceInfoListEx | Creates an empty device information set for a local or remote computer.
SetupDiCreateDeviceInterfaceRegKey | Creates a registry key for storing information about a device interface instance.
SetupDiDeleteDeviceInterfaceData | Deletes a device interface from a device information set.
SetupDiDeleteDeviceInterfaceRegKey | Deletes the registry subkey used by applications and drivers to store information specific to a device interface instance.
SetupDiDestroyDeviceInfoList | Destroys a device information set and frees all associated memory.
SetupDiEnumDeviceInterfaces | Retrieves a context structure for a device interface of a device information set.
SetupDiGetClassDevs | Retrieves a device information set that contains all devices of a specified class.
SetupDiGetClassDevsEx | Retrieves a device information set that contains all devices of a specified class on a local or remote computer.
SetupDiGetDeviceInterfaceAlias | Retrieves an alias for the specified device interface.
SetupDiGetDeviceInterfaceDetail | Retrieves detailed information about a specified device interface.
SetupDiOpenClassRegKeyEx | Opens the registry key for the device setup or interface class, or a subkey for a specific class.
SetupDiOpenDeviceInterface | Retrieves information about an existing device interface and adds it to the specified device information set.
SetupDiOpenDeviceInterfaceRegKey | Opens the registry subkey that applications and drivers use to store information specific to a device interface instance.
UnregisterDeviceNotification | Closes the specified device notification handle.


RegisterDeviceNotification

The RegisterDeviceNotification function specifies the device or type of device for which a window will receive notifications.

HDEVNOTIFY RegisterDeviceNotification(
  HANDLE hRecipient,
  LPVOID NotificationFilter,
  DWORD Flags
);

Parameters

hRecipient
[in] Handle to the window or service that will receive device events for the devices specified in the NotificationFilter parameter. The same window handle can be used in multiple calls to RegisterDeviceNotification.

Services can specify either a window handle or service status handle.

NotificationFilter
[in] Pointer to a block of data that specifies the type of device for which notifications should be sent. This block always begins with the DEV_BROADCAST_HDR structure. The data following this header is dependent on the value of the dbch_devicetype member.
Flags
[in] This parameter can be one of the following values.
Type | Description
DEVICE_NOTIFY_WINDOW_HANDLE | The hRecipient parameter is a window handle.
DEVICE_NOTIFY_SERVICE_HANDLE | The hRecipient parameter is a service status handle.

In addition, you can specify the following value.
Value Meaning
DEVICE_NOTIFY_ALL_INTERFACE_CLASSES Whistler: Notifies the recipient of device interface events for all device interface classes. (The dbcc_classguid member is ignored.)

This value can be used only if the dbch_devicetype member is DBT_DEVTYP_DEVICEINTERFACE.

Return Values

If the function succeeds, the return value is a device notification handle.

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

Remarks

Applications send event notifications using the BroadcastSystemMessage function. Any application with a top-level window can receive basic notifications by processing the WM_DEVICECHANGE message. Applications can use the RegisterDeviceNotification function to register to receive device notifications.

Services can use the RegisterDeviceNotification function to register to receive device notifications. If a service specifies a window handle in the hRecipient parameter, the notifications are sent to the window procedure. If hRecipient is a service status handle, SERVICE_CONTROL_DEVICEEVENT notifications are sent to the service control handler. For more information about the service control handler, see HandlerEx.

Device notification handles returned by RegisterDeviceNotification must be closed by calling the UnregisterDeviceNotification function when they are no longer needed.

For example, see Registering for Device Notification.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

Device Management Overview, Device Management Functions, BroadcastSystemMessage, DEV_BROADCAST_HDR, HandlerEx, UnregisterDeviceNotification, WM_DEVICECHANGE


SetupDiCreateDeviceInfoList

The SetupDiCreateDeviceInfoList function creates an empty device information set. This set can be associated with a class GUID.

To create a device information set for a remote computer, call the SetupDiCreateDeviceInfoListEx function.

HDEVINFO SetupDiCreateDeviceInfoList(
  CONST LPGUID ClassGuid,
  HWND hwndParent
);

Parameters

ClassGuid
[in] Optionally specifies the GUID of the setup class associated with this device information set. If this parameter is specified, only devices of this class can be included in this device information set.
hwndParent
[in] Optionally specifies a handle to the top-level window in which to display a user interface.

Return Values

If the function succeeds, the return value is a handle to an empty device information set.

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

Remarks

To destroy the device information set when you have finished, call the SetupDiDestroyDeviceInfoList function.

For an example, see Enumerating Current Devices.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiCreateDeviceInfoListEx, SetupDiDestroyDeviceInfoList


SetupDiCreateDeviceInfoListEx

The SetupDiCreateDeviceInfoListEx function creates an empty device information set for a local or remote computer. This set can be associated with a class GUID.

HDEVINFO SetupDiCreateDeviceInfoListEx(
  CONST LPGUID ClassGuid,
  HWND hwndParent,
  PCTSTR MachineName,
  PVOID Reserved
);

Parameters

ClassGuid
[in] Optionally specifies the GUID of the setup class associated with this device information set. If this parameter is specified, only devices of this class can be included in this device information set.
hwndParent
[in] Optionally specifies a handle to the top-level window to use for any user interface related to actions not specific to a particular device.
MachineName
[in] Optionally specifies the name of the computer on the network. If this parameter is specified, the devices you add to this device information set must reside on the specified computer. If MachineName is NULL, the device information set is for local devices.
Reserved
Reserved; must be NULL.

Return Values

If the function succeeds, the return value is a handle to an empty device information set.

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

Remarks

To destroy the device information set when you have finished, call the SetupDiDestroyDeviceInfoList function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiDestroyDeviceInfoList


SetupDiCreateDeviceInterfaceRegKey

The SetupDiCreateDeviceInterfaceRegKey function creates a registry key for storing information about a device interface instance.

HKEY SetupDiCreateDeviceInterfaceRegKey(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  DWORD Reserved,
  REGSAM samDesired,
  HINF InfHandle,
  PCTSTR InfSectionName
);

Parameters

DeviceInfoSet
[in] Pointer to a device information set containing the interface and its underlying device. The device information set must not contain remote devices.
DeviceInterfaceData
[in] Pointer to an SP_DEVICE_INTERFACE_DATA structure that identifies the device interface.
Reserved
Reserved; must be zero.
samDesired
[in] Specifies the registry access to the key to be created.
InfHandle
[in] Optionally specifies the handle to an open .inf file that contains an Install section to be executed for the newly created key. If this parameter is not NULL, the InfSectionName parameter must be specified as well.
InfSectionName
[in] An optional pointer to the name of an Install section in the .inf file specified by the InfHandle parameter. This section is executed for the newly created key. If this parameter is not NULL, InfHandle must be specified as well.

Return Values

If the function succeeds, it returns a handle to the newly created registry key.

If the function fails, it returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The SetupDiCreateDeviceInterfaceRegKey function creates a nonvolatile subkey of the registry key for the specified device interface. This subkey is used to store private configuration data for the device interface.

To close the handle returned from this function, call the RegCloseKey function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiDeleteDeviceInterfaceRegKey, SetupDiOpenDeviceInterfaceRegKey, SP_DEVICE_INTERFACE_DATA


SetupDiDeleteDeviceInterfaceData

The SetupDiDeleteDeviceInterfaceData function deletes a device interface from a device information set.

BOOL SetupDiDeleteDeviceInterfaceData(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parameters

DeviceInfoSet
[in] Pointer to the device information set that contains the interface and its underlying device. This handle is typically returned by the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.
DeviceInterfaceData
[in] Pointer to an SP_DEVICE_INTERFACE_DATA structure that identifies the interface to be deleted. This structure is typically returned by the SetupDiEnumDeviceInterfaces function.

Return Values

If the function succeeds, the return value is nonzero.

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

Remarks

The SetupDiDeleteDeviceInterfaceData function deletes a device interface from a device information set. This function has no effect on the device interface or the underlying device.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiEnumDeviceInterfaces, SetupDiGetClassDevs, SetupDiGetClassDevsEx


SetupDiDeleteDeviceInterfaceRegKey

The SetupDiDeleteDeviceInterfaceRegKey function deletes the registry subkey used by applications and drivers to store information specific to a device interface instance.

BOOL SetupDiDeleteDeviceInterfaceRegKey(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  DWORD Reserved
);

Parameters

DeviceInfoSet
[in] Pointer to a device information set containing the interface and its underlying device. The device information set must not contain remote devices.
DeviceInterfaceData
[in] Pointer to a structure that identifies the device interface. This structure is typically returned by the SetupDiEnumDeviceInterfaces function.
Reserved
Reserved; must be zero.

Return Values

If the function succeeds, the return value is nonzero.

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

Remarks

The SetupDiDeleteDeviceInterfaceRegKey function deletes the subkey used by drivers and applications to store information about the device interface instance. This subkey was created by the SetupDiCreateDeviceInterfaceRegKey function or by the driver. The SetupDiDeleteDeviceInterfaceRegKey function does not affect the main registry key for the device interface instance nor any other subkeys that may have been created.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiCreateDeviceInterfaceRegKey, SetupDiEnumDeviceInterfaces


SetupDiDestroyDeviceInfoList

The SetupDiDestroyDeviceInfoList function destroys a device information set and frees all associated memory.

BOOL SetupDiDestroyDeviceInfoList(
  HDEVINFO DeviceInfoSet
);

Parameters

DeviceInfoSet
[in] Specifies a handle to the device information set to destroy. This handle is created by the SetupDiCreateDeviceInfoList or SetupDiCreateDeviceInfoListEx function.

Return Values

If the function succeeds, the return value is nonzero.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiCreateDeviceInfoList, SetupDiCreateDeviceInfoListEx


SetupDiEnumDeviceInterfaces

The SetupDiEnumDeviceInterfaces function retrieves a context structure for a device interface of a device information set. Each call returns information about one device interface. The function can be called repeatedly to get information about several interfaces exposed by one or more devices.

BOOL SetupDiEnumDeviceInterfaces(
  HDEVINFO DeviceInfoSet,
  PSP_DEVINFO_DATA DeviceInfoData,
  CONST LPGUID InterfaceClassGuid,
  DWORD MemberIndex,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parameters

DeviceInfoSet
[in] Pointer to a device information set containing the devices for which to return interface information. This handle is typically returned by the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.
DeviceInfoData
[in] An optional pointer to an SP_DEVINFO_DATA structure that constrains the search for interfaces to those of just one device in the device information set.
InterfaceClassGuid
[in] Pointer to a GUID that specifies the device interface class for the requested interface.
MemberIndex
[in] Specifies a zero-based index to the list of interfaces in the device information set. You should first call this function with the MemberIndex parameter set to zero to obtain the first interface. Then, repeatedly increment MemberIndex and retrieve an interface until this function fails and GetLastError returns ERROR_NO_MORE_ITEMS.

If the DeviceInfoData parameter specifies a particular device, MemberIndex applies only to the interfaces exposed by that device.

DeviceInterfaceData
[out] Pointer to a buffer that contains, on successful return, a completed SP_DEVICE_INTERFACE_DATA structure that identifies an interface that meets the search parameters. You must set the cbSize member to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function.

Return Values

If the function succeeds, the return value is nonzero.

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

Remarks

The DeviceInterfaceData member is a pointer to a structure that identifies a requested device interface. To get detailed information about an interface, call the SetupDiGetDeviceInterfaceDetail function. The detailed information includes the name of the device interface that can be passed to a function (such as CreateFile) to get a handle to the interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiGetClassDevs, SetupDiGetClassDevsEx, SetupDiGetDeviceInterfaceDetail, SP_DEVICE_INTERFACE_DATA, SP_DEVINFO_DATA


SetupDiGetClassDevs

The SetupDiGetClassDevs function retrieves a device information set that contains all devices of a specified class.

To retrieve a device information set for devices on a remote computer, call the SetupDiGetClassDevsEx function.

HDEVINFO SetupDiGetClassDevs(
  CONST LPGUID ClassGuid,
  PCTSTR Enumerator,
  HWND hwndParent,
  DWORD Flags
);

Parameters

ClassGuid
[in] An optional pointer to a class GUID for a setup class or an interface class. If the DIGCF_DEVICEINTERFACE flag is set, ClassGuid represents an interface class; otherwise, ClassGuid represents a setup class.

If the DIGCF_ALLCLASSES flag is set, this parameter is ignored and the resulting list contains devices of all installed classes.

Enumerator
[in] An optional pointer to a string that filters the devices that are returned.

If the DIGCF_DEVICEINTERFACE flag is set, this parameter is an optional pointer to a string representing the PnP name of a particular device. This function examines this particular device only to determine whether it exposes any interfaces of the requested interface class.

If the DIGCF_DEVICEINTERFACE flag is not set, this parameter optionally specifies the name of the PnP enumerator for the devices of interest. (The names of system-supplied enumerators appear in the DDK header file Register.h.) This function examines only device instances of this enumerator. If this parameter is NULL, this function retrieves device information for all device instances on the system.

hwndParent
[in] Specifies the handle to the top-level window to be used for any user interface relating to the members of this set.
Flags
[in] Specifies control options used in building the device information set. This parameter can be one or more of the following values.
Value | Meaning
DIGCF_ALLCLASSES | Return a list of installed devices for all classes. If this flag is set, the ClassGuid parameter is ignored.
DIGCF_DEVICEINTERFACE | Return devices that expose interfaces of the interface class specified by ClassGuid. If this flag is not set, ClassGuid specifies a setup class.
DIGCF_PRESENT | Return only devices that are currently present.
DIGCF_PROFILE | Return only devices that are a part of the current hardware profile.

Return Values

If the function succeeds, the return value is a handle to a device information set containing all installed devices matching the specified parameters.

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

Remarks

To destroy the device information set when you have finished, call the SetupDiDestroyDeviceInfoList function.

If DIGCF_DEVICEINTERFACE is set, ClassGuid (if used) must point to a device interface class GUID, and Enumerator (if used) must point to a PnP device name. The device information set returned contains devices that expose interfaces of the requested interface class. Enumerate the interfaces of the devices using the SetupDiEnumDeviceInterfaces function.

If DIGCF_DEVICEINTERFACE is not set, ClassGuid (if used) must point to a setup class GUID, and Enumerator (if used) must specify the name of the PnP enumerator that enumerates the devices of interest.

To retrieve the devices for a class on a remote computer, call the SetupDiGetClassDevsEx function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiDestroyDeviceInfoList, SetupDiEnumDeviceInterfaces, SetupDiGetClassDevsEx


SetupDiGetClassDevsEx

The SetupDiGetClassDevsEx function retrieves a device information set that contains all devices of a specified class on a local or remote computer.

HDEVINFO SetupDiGetClassDevsEx(
  CONST LPGUID ClassGuid,
  PCTSTR Enumerator,
  HWND hwndParent,
  DWORD Flags,
  HDEVINFO DeviceInfoSet,
  PCTSTR MachineName,
  PVOID Reserved
);

Parameters

ClassGuid
[in] An optional pointer to a class GUID for a setup class or an interface class. If the DIGCF_DEVICEINTERFACE flag is set, ClassGuid represents an interface class; otherwise, ClassGuid represents a setup class.

If the DIGCF_ALLCLASSES flag is set, this parameter is ignored and the resulting list contains devices of all installed classes.

Enumerator
[in] An optional pointer to a string that filters the devices that are returned.

If the DIGCF_DEVICEINTERFACE flag is set, this parameter is an optional pointer to a string representing the PnP name of a particular device. This function examines this particular device only to determine whether it exposes any interfaces of the requested interface class.

If the DIGCF_DEVICEINTERFACE flag is not set, this parameter optionally specifies the name of the PnP enumerator that enumerates the devices of interest. (The names of system-supplied enumerators appear in the DDK header file Register.h.) This function examines only device instances of this enumerator. If this parameter is NULL, this function retrieves device information for all device instances on the system.

hwndParent
[in] Specifies the handle to the top-level window to be used for any user interface relating to the members of this set.
Flags
[in] Specifies control options used in building the device information set. This parameter can be one or more of the following values.
Value | Meaning
DIGCF_ALLCLASSES | Return a list of installed devices for all classes. If this flag is set, the ClassGuid parameter is ignored.
DIGCF_DEVICEINTERFACE | Return devices that expose interfaces of the interface class specified by ClassGuid. If this flag is not set, ClassGuid specifies a setup class.
DIGCF_PRESENT | Return only devices that are currently present.
DIGCF_PROFILE | Return only devices that are a part of the current hardware profile.

DeviceInfoSet
[in] Optionally specifies a handle to an existing device information set to which these new device information elements will be added. If the Flags parameter includes the value DIGCF_DEVICEINTERFACE, device interfaces will also be added.

If this parameter is specified, the same handle is returned upon success, with the new elements and interfaces added. If this parameter is zero, a new device information set is created and its handle is returned.

MachineName
[in] Optionally specifies the name of a remote computer on which the device resides. A value of NULL for MachineName specifies that the device resides on the local computer.
Reserved
Reserved; must be NULL.

Return Values

If the function succeeds, the return value is a handle to a device information set containing all devices matching the specified parameters.

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

Remarks

To destroy the device information set when you have finished, call the SetupDiDestroyDeviceInfoList function.

If DIGCF_DEVICEINTERFACE is set, ClassGuid (if used) must point to a device interface class GUID, and Enumerator (if used) must point to a PnP device name. The returned device information set contains devices that expose interfaces of the requested interface class. Enumerate the interfaces of the devices using the SetupDiEnumDeviceInterfaces function.

If DIGCF_DEVICEINTERFACE is not set, ClassGuid (if used) must point to a setup class GUID, and Enumerator (if used) must specify the name of the PnP enumerator that enumerates the devices of interest.

If the DeviceInfoSet parameter is specified, the associated class of this device information set (if any) must match the ClassGuid specified, if it is a setup class. If the DIGCF_DEVICEINTERFACE flag is set, the device interfaces retrieved are filtered based on whether their corresponding device's setup class matches that of the device information set. This feature can be used to retrieve a list of device interfaces of a particular interface class, but only if those interfaces are exposed by devices of a particular setup class. For example, suppose there is a device information set whose associated setup class is Volume. To retrieve a list of all device interfaces of interface class Mounted Device, call SetupDiGetClassDevsEx passing in the handle to the device information set. The result is a device information set containing all devices of interface class Mounted Device that are exposed by devices of setup class Volume.

For an example, see Enumerating Current Devices.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiDestroyDeviceInfoList, SetupDiEnumDeviceInterfaces


SetupDiGetDeviceInterfaceAlias

The SetupDiGetDeviceInterfaceAlias function retrieves an alias for the specified device interface. Device interfaces are considered aliases if they are exposed by the same underlying device and have identical reference strings, but are of different interface classes.

BOOL SetupDiGetDeviceInterfaceAlias(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  CONST LPGUID AliasInterfaceClassGuid,
  PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
);

Parameters

DeviceInfoSet
[in] Pointer to the device information set containing the device interface for which to retrieve an alias. This handle is typically returned by the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.
DeviceInterfaceData
[in] Pointer to an SP_DEVICE_INTERFACE_DATA structure that identifies the device interface within the device information set. This pointer is typically returned by the SetupDiEnumDeviceInterfaces function.
AliasInterfaceClassGuid
[in] A class GUID specifying the interface class of the alias to retrieve.
AliasDeviceInterfaceData
[out] Pointer to a buffer that contains, on successful return, a completed SP_DEVICE_INTERFACE_DATA structure that identifies the requested alias. You must set the cbSize member to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. Possible errors returned by GetLastError include the following.

Error | Meaning
ERROR_INVALID_PARAMETER | Invalid DeviceInfoSet or DeviceInterfaceData parameter.
ERROR_NO_SUCH_INTERFACE_DEVICE | There is no alias of class AliasInterfaceClassGuid for the specified device interface.
ERROR_INVALID_USER_BUFFER | Invalid AliasDeviceInterfaceData buffer.

Remarks

The SetupDiGetDeviceInterfaceAlias function can be used to locate a device that exposes more than one interface. For example, consider a disk that can be part of a fault-tolerant volume and can contain encrypted data. The function driver for the disk device could register a fault-tolerant-volume interface and an encrypted-volume interface. These interfaces are device interface aliases if the function driver registers them with identical reference strings and they refer to the same device.

To locate a device with multiple interfaces, perform the following steps

  1. Locate all available devices of a particular class by using the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.
  2. Determine which of these devices expose one of the interfaces by using the SetupDiEnumDeviceInterfaces function.
  3. Pass a device that exposes the first interface to SetupDiGetDeviceInterfaceAlias and request an alias for the other interface class.

If the requested alias exists but the AliasDeviceInterfaceData buffer is invalid, this function successfully adds the device interface to the device information set, but returns FALSE. In this case, GetLastError returns ERROR_INVALID_USER_BUFFER.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiEnumDeviceInterfaces, SetupDiGetClassDevs, SetupDiGetClassDevsEx, SP_DEVICE_INTERFACE_DATA


SetupDiGetDeviceInterfaceDetail

The SetupDiGetDeviceInterfaceDetail function retrieves detailed information about a specified device interface.

BOOL SetupDiGetDeviceInterfaceDetail(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  PSP_DEVICE_INTERFACE_DETAIL_DATA DeviceInterfaceDetailData,
  DWORD DeviceInterfaceDetailDataSize,
  PDWORD RequiredSize,
  PSP_DEVINFO_DATA DeviceInfoData
);

Parameters

DeviceInfoSet
[in] Pointer to the device information set that contains the interface and its underlying device. This handle is typically returned by the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.
DeviceInterfaceData
[in] Pointer to an SP_DEVICE_INTERFACE_DATA structure that identifies the interface. This structure is typically returned by the SetupDiEnumDeviceInterfaces function.
DeviceInterfaceDetailData
[out] An optional pointer to a SP_DEVICE_INTERFACE_DETAIL_DATA structure to receive information about the specified interface. You must set the cbSize member to sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) before calling this function. The cbSize member always contains the size of the fixed part of the data structure, not a size reflecting the variable-length string at the end.

This parameter must be NULL if the DeviceInterfaceDetailSize parameter is zero.

DeviceInterfaceDetailDataSize
[in] Specifies the size of the DeviceInterfaceDetailData buffer. The buffer must be at least (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) bytes, to contain the fixed part of the structure and a single NULL character to terminate an empty MULTI_SZ string.

This parameter must be zero if DeviceInterfaceDetailData is NULL.

RequiredSize
[out] An optional pointer to a variable to receive the required size of the DeviceInterfaceDetailData buffer. This size includes the size of the fixed part of the structure plus the number of bytes required for the variable-length device path string.
DeviceInfoData
[out] An optional pointer to an SP_DEVINFO_DATA structure to receive information about the device that exposes the requested interface. You must set the cbSize member to sizeof(SP_DEVINFO_DATA).

Return Values

If the function succeeds, the return value is nonzero.

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

Remarks

Using the SetupDiGetDeviceInterfaceDetail function to get details about an interface is typically a two-step process:

  1. Get the required buffer size. Call SetupDiGetDeviceInterfaceDetail with a NULL DeviceInterfaceDetailData pointer, a DeviceInterfaceDetailDataSize of zero, and a valid RequiredSize variable. In response to such a call, this function fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the RequiredSize parameter receives the required buffer size.
  2. Allocate an appropriately sized buffer and call the function again to get the interface details.

The interface details returned by this function include a device path that can be passed to Win32 functions such as CreateFile. Do not attempt to parse the device path symbolic name. Note that the device path can be reused after the system is rebooted.

The SetupDiGetDeviceInterfaceDetail function can be used to get only the DeviceInfoData parameter. If the interface exists but the DeviceInterfaceDetailData parameter is NULL, the function fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the DeviceInfoData structure is filled with information about the device that exposes the interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiEnumDeviceInterfaces, SetupDiGetClassDevs, SetupDiGetClassDevsEx, SP_DEVICE_INTERFACE_DATA, SP_DEVICE_INTERFACE_DETAIL_DATA, SP_DEVINFO_DATA


SetupDiOpenClassRegKeyEx

The SetupDiOpenClassRegKeyEx function opens the registry key for the device setup or interface class, or a subkey for a specific class. This function opens the specified key on the local computer or on a remote computer.

HKEY SetupDiOpenClassRegKeyEx(
  CONST LPGUID ClassGuid,
  REGSAM samDesired,
  DWORD Flags,
  PCTSTR MachineName,
  PVOID Reserved
 );

Parameters

ClassGuid
[in] An optional pointer to the GUID of the class for which the registry key is to be opened. If this parameter is NULL, the function opens the root of the class tree, HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class.
samDesired
[in] Specifies the required access to the key.
Flags
[in] Specifies the kind of registry key to be opened. This parameter can be one of the following values.
Value | Meaning
DIOCR_INSTALLER | Open a setup class key. If the ClassGuid parameter is NULL, open the root key of the class installer branch.
DIOCR_INTERFACE | Open an interface class key. If ClassGuid is NULL, open the root key of the interface class branch.

MachineName
[in] An optional pointer to a string containing the name of a remote computer on which to open the specified key.
Reserved
Reserved. Must be NULL.

Return Values

If the function succeeds, the return value is a handle to an opened registry key where information pertaining to this setup class can be stored or retrieved.

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

Remarks

The SetupDiOpenClassRegKeyEx function does not create a registry key if it does not already exist.

To close the handle returned from this function, call the RegCloseKey function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiCreateDeviceInterfaceRegKey, SetupDiOpenDeviceInterfaceRegKey


SetupDiOpenDeviceInterface

The SetupDiOpenDeviceInterface function retrieves information about an existing device interface and adds it to the specified device information set. This function creates a device information instance for the underlying device if an instance is not already present in the device information set.

BOOL SetupDiOpenDeviceInterface(
  HDEVINFO DeviceInfoSet,
  PCTSTR DevicePath,
  DWORD OpenFlags,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parameters

DeviceInfoSet
[in] Pointer to a device information set that contains, or will contain, the device that exposes the interface to be opened.
DevicePath
[in] Pointer to a string containing the name of the device interface to be opened. This name is a Win32 device path typically received in a PnP notification structure or through a call to the SetupDiEnumDeviceInterfaces function.
OpenFlags
Reserved; must be zero.
DeviceInterfaceData
[out] An optional pointer to a buffer that receives a completed SP_DEVICE_INTERFACE_DATA structure that identifies the interface. You must set the cbSize member to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function.

Return Values

If the function succeeds, the return value is nonzero.

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

Remarks

If a device interface instance for the interface already exists in the DeviceInfoSet parameter, SetupDiOpenDeviceInterface updates the flags. Therefore, this function can be used to refresh the flags for a device interface. For example, an interface might have been inactive when it was first opened, but has subsequently become active.

If the new device interface is successfully opened, but the DeviceInterfaceData buffer is invalid, this function returns FALSE and GetLastError returns ERROR_INVALID_USER_BUFFER. This error does not prevent the interface from being opened.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiEnumDeviceInterfaces, SP_DEVICE_INTERFACE_DATA


SetupDiOpenDeviceInterfaceRegKey

The SetupDiOpenDeviceInterfaceRegKey function opens the registry subkey that applications and drivers use to store information specific to a device interface instance. The function returns a handle to the key.

HKEY SetupDiOpenDeviceInterfaceRegKey(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  DWORD Reserved,
  REGSAM samDesired
);

Parameters

DeviceInfoSet
[in] Pointer to a device information set containing the specified interface and its underlying device.
DeviceInterfaceData
[in] Pointer to a structure that identifies the device interface. This structure is typically returned by the SetupDiEnumDeviceInterfaces function.
Reserved
Reserved; must be zero.
samDesired
[in] Specifies the required access to the registry key.

Return Values

If the function succeeds, the return value is a handle to the opened registry key.

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

Remarks

To close the handle returned by this function, call the RegCloseKey function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.
Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiCreateDeviceInterfaceRegKey, SetupDiEnumDeviceInterfaces


UnregisterDeviceNotification

The UnregisterDeviceNotification function closes the specified device notification handle.

BOOL UnregisterDeviceNotification(
  HDEVNOTIFY Handle
);

Parameters

Handle
[in] Device notification handle returned by the RegisterDeviceNotification function.

Return Values

If the function succeeds, the return value is nonzero.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.

See Also

Device Management Overview, Device Management Functions, RegisterDeviceNotification, WM_DEVICECHANGE


Device Management Messages

The following message is used in device management.

WM_DEVICECHANGE


WM_DEVICECHANGE

The WM_DEVICECHANGE device message notifies an application of a change to the hardware configuration of a device or the computer.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Specifies the event. This parameter can be one of the following values.
Value | Meaning
DBT_CONFIGCHANGECANCELED | A request to change the current configuration (dock or undock) has been canceled.
DBT_CONFIGCHANGED | The current configuration has changed, due to a dock or undock.
DBT_CUSTOMEVENT | Windows 98/Me, Windows 2000 or later: A custom event has occurred.
DBT_DEVICEARRIVAL | A device has been inserted and is now available.
DBT_DEVICEQUERYREMOVE | Permission is requested to remove a device. Any application can deny this request and cancel the removal.
DBT_DEVICEQUERYREMOVEFAILED | A request to remove a device has been canceled.
DBT_DEVICEREMOVECOMPLETE | A device has been removed.
DBT_DEVICEREMOVEPENDING | A device is about to be removed. Cannot be denied.
DBT_DEVICETYPESPECIFIC | A device-specific event has occurred.
DBT_QUERYCHANGECONFIG | Permission is requested to change the current configuration (dock or undock).
DBT_USERDEFINED | The meaning of this message is user-defined.

lParam
Pointer to a structure that contains event-specific data. Its format depends on the value of the wParam parameter. For more information, refer to the documentation for each event.

Return Values

Return TRUE to grant the request.

Return BROADCAST_QUERY_DENY to deny the request.

Remarks

For devices that offer software-controllable features, such as ejection and locking, the system typically sends a DBT_DEVICEREMOVEPENDING message to let applications and device drivers end their use of the device gracefully. If the system forcibly removes a device, it may not send a DBT_DEVICEQUERYREMOVE message before doing so.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Device Management Overview, Device Management Messages, DBT_CONFIGCHANGECANCELED, DBT_CONFIGCHANGED, DBT_CUSTOMEVENT, DBT_DEVICEARRIVAL, DBT_DEVICEQUERYREMOVE, DBT_DEVICEQUERYREMOVEFAILED, DBT_DEVICEREMOVECOMPLETE, DBT_DEVICEREMOVEPENDING, DBT_DEVICETYPESPECIFIC, DBT_QUERYCHANGECONFIG, DBT_USERDEFINED


Device Management Events

The following are the device events.

DBT_CONFIGCHANGECANCELED
DBT_CONFIGCHANGED
DBT_CUSTOMEVENT
DBT_DEVICEARRIVAL
DBT_DEVICEQUERYREMOVE
DBT_DEVICEQUERYREMOVEFAILED
DBT_DEVICEREMOVECOMPLETE
DBT_DEVICEREMOVEPENDING
DBT_DEVICETYPESPECIFIC
DBT_DEVNODES_CHANGED
DBT_QUERYCHANGECONFIG
DBT_USERDEFINED


DBT_CONFIGCHANGECANCELED

The system broadcasts the DBT_CONFIGCHANGECANCELED device event when a request to change the current configuration (dock or undock) has been canceled.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_CONFIGCHANGECANCELED and lParam set to zero.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_CONFIGCHANGECANCELED.
lParam
Set to zero.

Return Values

Return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DBT_CONFIGCHANGED, DBT_QUERYCHANGECONFIG, WM_DEVICECHANGE


DBT_CONFIGCHANGED

The system broadcasts the DBT_CONFIGCHANGED device event to indicate that the current configuration has changed, due to a dock or undock. An application or driver that stores data in the registry under the HKEY_CURRENT_CONFIG key should update the data.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_CONFIGCHANGED and lParam set to zero.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_CONFIGCHANGED.
lParam
Set to zero.

Return Values

Return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DBT_CONFIGCHANGECANCELED, DBT_QUERYCHANGECONFIG, WM_DEVICECHANGE


DBT_CUSTOMEVENT

The system sends the DBT_CUSTOMEVENT device event when a driver-defined custom event has occurred.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_CUSTOMEVENT and lParam set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_CUSTOMEVENT.
lParam
Pointer to a structure identifying the device. To determine the structure type, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

Return Values

Return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEARRIVAL

The system broadcasts the DBT_DEVICEARRIVAL device event when a device has been inserted and becomes available.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_DEVICEARRIVAL and lParam set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_DEVICEARRIVAL.
lParam
Pointer to a structure identifying the device inserted. To determine the structure type, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

Return Values

Return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEQUERYREMOVE

The system broadcasts the DBT_DEVICEQUERYREMOVE device event to request permission to remove a device. This message is the last chance for applications and drivers to prepare for the removal of the device. However, any application can deny this request and cancel the device removal.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_DEVICEQUERYREMOVE and lParam set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_DEVICEQUERYREMOVE.
lParam
Pointer to a structure identifying the device to remove. To determine the structure type, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

Return Values

Return TRUE to grant permission to remove a device.

Return BROADCAST_QUERY_DENY to deny permission to remove a device.

Remarks

On Windows NT/Windows 2000, you must close all handles to the device or the device removal will fail. This is not a requirement on Windows 95/98, but it is a good rule to follow and it should increase reliability.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEQUERYREMOVEFAILED

The system broadcasts the DBT_DEVICEQUERYREMOVEFAILED device event when a request to remove a device has been canceled.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_DEVICEQUERYREMOVEFAILED and lParam set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_DEVICEQUERYREMOVEFAILED.
lParam
Pointer to a structure identifying the device. To determine the structure type, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

Return Values

Return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEREMOVECOMPLETE

The system broadcasts the DBT_DEVICEREMOVECOMPLETE device event when a device has been physically removed.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_DEVICEREMOVECOMPLETE and lParam set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_DEVICEREMOVECOMPLETE
lParam
Pointer to a structure identifying the device removed. To determine the structure type, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

Return Values

Return TRUE.

Remarks

The system may broadcast a DBT_DEVICEREMOVECOMPLETE message without sending corresponding DBT_DEVICEQUERYREMOVE and DBT_DEVICEREMOVEPENDING messages. In such cases, the applications and drivers must recover from the loss of the device as best they can.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DBT_DEVICEQUERYREMOVE, DBT_DEVICEREMOVEPENDING, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICEREMOVEPENDING

The system broadcasts the DBT_DEVICEREMOVEPENDING device event when the device driver stack has been removed and the device is no longer available for use.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_DEVICEREMOVEPENDING and lParam set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_DEVICEREMOVEPENDING.
lParam
Pointer to a structure identifying the device. To determine the structure type, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

Return Values

Return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVICETYPESPECIFIC

The system broadcasts the DBT_DEVICETYPESPECIFIC device event when a device-specific event occurs.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_DEVICETYPESPECIFIC and lParam set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_DEVICETYPESPECIFIC.
lParam
Pointer to a structure identifying the device. To determine the structure type, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

Return Values

Return TRUE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_DEVNODES_CHANGED

The system broadcasts the DBT_DEVNODES_CHANGED device event when a device has been added to or removed from the system. Applications that maintain lists of devices in the system should refresh their lists.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_DEVNODES_CHANGED and lParam set to zero.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_DEVNODES_CHANGED.
lParam
Set to zero.

Return Values

Return TRUE.

Remarks

There is no additional information about which device has been added to or removed from the system. Applications that require more information should register for device notification.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DBT_QUERYCHANGECONFIG

The system broadcasts the DBT_QUERYCHANGECONFIG device event to request permission to change the current configuration (dock or undock). Any application can deny this request and cancel the change.

To broadcast this device event, the system uses the WM_DEVICECHANGE message with wParam set to DBT_QUERYCHANGECONFIG and lParam set to zero.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_QUERYCHANGECONFIG.
lParam
Set to zero.

Return Values

Return TRUE to grant permission to change the configuration.

Return BROADCAST_QUERY_DENY to deny permission to change the configuration.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, DBT_CONFIGCHANGECANCELED, DBT_CONFIGCHANGED, WM_DEVICECHANGE


DBT_USERDEFINED

The DBT_USERDEFINED device event identifies a user-defined event.

To broadcast this device event, call the BroadcastSystemMessage function with the WM_DEVICECHANGE message. Set wParam to DBT_USERDEFINED and set lParam as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_DEVICECHANGE
  WPARAM wParam,   // device-change event
  LPARAM lParam    // event-specific data
);

Parameters

wParam
Set to DBT_USERDEFINED.
lParam
Pointer to a _DEV_BROADCAST_USERDEFINED structure which describes the user-defined broadcast in progress. The dbud_szName member contains the name of the user-defined message, followed by any user-defined data.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Events, _DEV_BROADCAST_USERDEFINED, WM_DEVICECHANGE


Device Management Structures

The following structures are used with device events.

_DEV_BROADCAST_USERDEFINED
DEV_BROADCAST_DEVICEINTERFACE
DEV_BROADCAST_HANDLE
DEV_BROADCAST_HDR
DEV_BROADCAST_OEM
DEV_BROADCAST_PORT
DEV_BROADCAST_VOLUME
SP_DEVINFO_DATA
SP_DEVICE_INTERFACE_DATA
SP_DEVICE_INTERFACE_DETAIL_DATA


_DEV_BROADCAST_USERDEFINED

The _DEV_BROADCAST_USERDEFINED structure contains the user-defined event and optional data associated with the DBT_USERDEFINED device event.

typedef struct _DEV_BROADCAST_USERDEFINED {
  struct _DEV_BROADCAST_HDR dbud_dbh;
  char  dbud_szName[1];           // name string
//  BYTE  dbud_rgbUserDefined[];    // optional user-defined data
};

Members

dbud_dbh
Information about the device affected by a WM_DEVICECHANGE message as specified by the DEV_BROADCAST_HDR structure. Because _DEV_BROADCAST_USERDEFINED is variable length, the dbch_size member of the dbud_dbh structure must be the size in bytes of the entire structure, including the variable length portion.
dbud_szName
A case-sensitive, null-terminated string that names the message. The string must consist of the vendor name, a backslash, followed by arbitrary user-defined null-terminated text. For example:
"WidgetWare\QueryScannerShutdown"

– Or –

"WidgetWare\Video Q39S\AdapterReady"
dbud_rgbUserDefined
Optional user-defined information.

Remarks

Because this structure contains variable length fields, use it as a template for creating a pointer to a user-defined structure. Note that the structure must not contain pointers. The following example shows such a user-defined structure.

#define NAME_LENGTH 32
#define USER_LENGTH 50

typedef struct tagWIDGET_WARE_DEV_BROADCAST_USERDEFINED
{
    struct _DEV_BROADCAST_HDR DBHeader;
    char  szName[NAME_LENGTH]
    BYTE  UserDefined[USER_LENGTH];
} WIDGET_WARE_DEV_BROADCAST_USERDEFINED;

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Structures, DBT_USERDEFINED, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DEV_BROADCAST_DEVICEINTERFACE

The DEV_BROADCAST_DEVICEINTERFACE structure contains information about a class of devices.

typedef struct _DEV_BROADCAST_DEVICEINTERFACE {
  DWORD dbcc_size;
  DWORD dbcc_devicetype;
  DWORD dbcc_reserved;
  GUID dbcc_classguid;
  TCHAR dbcc_name[1];
} DEV_BROADCAST_DEVICEINTERFACE *PDEV_BROADCAST_DEVICEINTERFACE;

Members

dbcc_size
Specifies the size, in bytes, of this structure.
dbcc_devicetype
Set to the device type DBT_DEVTYP_DEVICEINTERFACE
dbcc_reserved
Reserved; do not use.
dbcc_classguid
A globally unique identifier (GUID) for the interface device class.
dbcc_name
A null-terminated string specifying the name of the device.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Structures, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DEV_BROADCAST_HANDLE

The DEV_BROADCAST_HANDLE structure contains information about a file system handle.

typedef struct _DEV_BROADCAST_HANDLE {
  DWORD dbch_size;
  DWORD dbch_devicetype;
  DWORD dbch_reserved;
  HANDLE dbch_handle;
  HDEVNOTIFY dbch_hdevnotify;

  // The following are valid only for DBT_CUSTOMEVENT
  GUID dbch_eventguid;
  LONG dbch_nameoffset;
  BYTE dbch_data[1];
} DEV_BROADCAST_HANDLE *PDEV_BROADCAST_HANDLE;

Members

dbch_size
Specifies the size, in bytes, of this structure.
dbch_devicetype
Set to the DBT_DEVTYP_HANDLE device type.
dbch_reserved
Reserved; do not use.
dbch_handle
Handle specified in the call to the RegisterDeviceNotification function.
dbch_hdevnotify
Handle to the device notification. This handle is returned by the RegisterDeviceNotification function.
dbch_eventguid
A globally unique identifier (GUID) for the custom event.
dbch_nameoffset
The offset of an optional string buffer.
dbch_data
Optional binary data.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Structures, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DEV_BROADCAST_HDR

The DEV_BROADCAST_HDR structure is a standard header for information related to a device event reported through the WM_DEVICECHANGE message.

The members of the DEV_BROADCAST_HDR structure are contained in each device management structure. To determine which structure you have received through WM_DEVICECHANGE, treat the structure as a DEV_BROADCAST_HDR structure and check its dbch_devicetype member.

typedef struct _DEV_BROADCAST_HDR {
  DWORD dbch_size;
  DWORD dbch_devicetype;
  DWORD dbch_reserved;
} DEV_BROADCAST_HDR;
typedef DEV_BROADCAST_HDR *PDEV_BROADCAST_HDR;

Members

dbch_size
Specifies the size of this structure, in bytes.

If this is a user-defined event, this member must be the size of this header, plus the size of the variable-length data in the _DEV_BROADCAST_USERDEFINED structure.

dbch_devicetype
The device type. Determines the event-specific information that follows the first three members. This member can be one of the following values.
Value | Meaning
DBT_DEVTYP_DEVICEINTERFACE | Windows 98/Me, Windows 2000 or later: Class of devices. This structure is a DEV_BROADCAST_DEVICEINTERFACE structure.
DBT_DEVTYP_HANDLE | Windows 98/Me, Windows 2000 or later: File system handle. This structure is a DEV_BROADCAST_HANDLE structure.
DBT_DEVTYP_OEM | OEM- or IHV-defined device type. This structure is a DEV_BROADCAST_OEM structure.
DBT_DEVTYP_PORT | Port device (serial or parallel). This structure is a DEV_BROADCAST_PORT structure.
DBT_DEVTYP_VOLUME | Logical volume. This structure is a DEV_BROADCAST_VOLUME structure.

dbch_reserved
Reserved; do not use.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Structures, DEV_BROADCAST_DEVICEINTERFACE, DEV_BROADCAST_HANDLE, DEV_BROADCAST_OEM, DEV_BROADCAST_PORT, DEV_BROADCAST_VOLUME, WM_DEVICECHANGE


DEV_BROADCAST_OEM

The DEV_BROADCAST_OEM structure contains information about a OEM-defined device type.

typedef struct _DEV_BROADCAST_OEM {
  DWORD dbco_size;
  DWORD dbco_devicetype;
  DWORD dbco_reserved;
  DWORD dbco_identifier;
  DWORD dbco_suppfunc;
} DEV_BROADCAST_OEM;
typedef DEV_BROADCAST_OEM *PDEV_BROADCAST_OEM;

Members

dbco_size
Specifies the size of this structure, in bytes.
dbco_devicetype
Set to the device type DBT_DEVTYPE_OEM.
dbco_reserved
Reserved; do not use.
dbco_identifier
An OEM-specific identifier for the device.
dbco_suppfunc
An OEM-specific function value. Possible values depend on the device.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Structures, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DEV_BROADCAST_PORT

The DEV_BROADCAST_PORT structure contains information about a modem, serial, or parallel port.

typedef struct _DEV_BROADCAST_PORT {
  DWORD dbcp_size;
  DWORD dbcp_devicetype;
  DWORD dbcp_reserved;
  TCHAR dbcp_name[1];
} DEV_BROADCAST_PORT *PDEV_BROADCAST_PORT;

Members

dbcp_size
Specifies the size of this structure, in bytes.
dbcp_devicetype
Set to the device type DBT_DEVTYP_PORT.
dbcp_reserved
Reserved; do not use.
dbcp_name
A null-terminated string specifying the friendly name of the port or the device connected to the port. Friendly names are intended to help the user quickly and accurately identify the device—for example, "COM1" and "Standard 28800 bps Modem" are considered friendly names.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Structures, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DEV_BROADCAST_VOLUME

The DEV_BROADCAST_VOLUME structure contains information about a logical volume.

typedef struct _DEV_BROADCAST_VOLUME {
  DWORD dbcv_size;
  DWORD dbcv_devicetype;
  DWORD dbcv_reserved;
  DWORD dbcv_unitmask;
  WORD dbcv_flags;
} DEV_BROADCAST_VOLUME;
typedef DEV_BROADCAST_VOLUME *PDEV_BROADCAST_VOLUME;

Members

dbcv_size
Specifies the size of this structure, in bytes.
dbcv_devicetype
Set to the device type DBT_DEVTYP_VOLUME.
dbcv_reserved
Reserved; do not use.
dbcv_unitmask
A logical unit mask identifying one or more logical units. Each bit in the mask corresponds to one logical drive. Bit 0 represents drive A, bit 1 represents drive B, and so on.
dbcv_flags
Specifies whether drive or media is affected. This parameter can be one of the following values.
Value | Meaning
DBTF_MEDIA | Change affects media in drive. If not set, change affects physical device or drive.
DBTF_NET | Indicated logical volume is a network volume.

Remarks

Although the dbcv_unitmask member may specify more than one volume in any message, this does not guarantee that only message is generated for a specified event. Multiple system components may independently generate messages for logical volumes at the same time.

Messages for media arrival and removal are sent only for media in devices that support a soft-eject mechanism. For example, applications will not see media-related volume messages for floppy disks.

Messages for network drive arrival and removal are not sent whenever network commands are issued, but rather when network connections will disappear as the result of a hardware event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Dbt.h.

See Also

Device Management Overview, Device Management Structures, DEV_BROADCAST_HDR, WM_DEVICECHANGE


SP_DEVINFO_DATA

The SP_DEVINFO_DATA structure defines a device instance that is a member of a device information set.

typedef struct _SP_DEVINFO_DATA {
  DWORD cbSize;
  GUID  ClassGuid;
  DWORD DevInst;
  ULONG_PTR Reserved;
} SP_DEVINFO_DATA, *PSP_DEVINFO_DATA;

Members

cbSize
Specifies the size, in bytes, of the structure.
ClassGuid
The globally unique identifier (GUID) of the device interface class.
DevInst
Handle to this device instance.
Reserved
Reserved; do not use.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.

See Also

Device Management Overview, Device Management Structures, SetupDiEnumDeviceInterfaces, SetupDiGetDeviceInterfaceDetail


SP_DEVICE_INTERFACE_DATA

The SP_DEVICE_INTERFACE_DATA structure defines a device interface.

typedef struct _SP_DEVICE_INTERFACE_DATA {
  DWORD cbSize;
  GUID  InterfaceClassGuid;
  DWORD Flags;
  ULONG_PTR Reserved;
} SP_DEVICE_INTERFACE_DATA, *PSP_DEVICE_INTERFACE_DATA;

Members

cbSize
Specifies the size, in bytes, of the structure.
InterfaceClassGuid
The globally unique identifier (GUID) of the device interface class.
Flags
Specifies information about the device interface. This parameter can be one of the following values.
Value | Meaning
SPINT_ACTIVE | The device is active.
SPINT_DEFAULT | The device is the default device.
SPINT_REMOVED | The device has been removed.

Reserved
Reserved; do not use.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.

See Also

Device Management Overview, Device Management Structures, SetupDiCreateDeviceInterfaceRegKey, SetupDiDeleteDeviceInterfaceData, SetupDiDeleteDeviceInterfaceRegKey, SetupDiEnumDeviceInterfaces, SetupDiGetDeviceInterfaceAlias, SetupDiGetDeviceInterfaceDetail, SetupDiOpenDeviceInterface, SetupDiOpenDeviceInterfaceRegKey


SP_DEVICE_INTERFACE_DETAIL_DATA

The SP_DEVICE_INTERFACE_DETAIL_DATA structure provides detailed information about a particular device interface.

typedef struct _SP_DEVICE_INTERFACE_DETAIL_DATA {
  DWORD  cbSize;
  TCHAR  DevicePath[ANYSIZE_ARRAY];
} SP_DEVICE_INTERFACE_DETAIL_DATA, *PSP_DEVICE_INTERFACE_DETAIL_DATA;

Members

cbSize
Specifies the size, in bytes, of the structure.
DevicePath
A NULL-terminated string that specifies the device path.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Setupapi.h.

See Also

Device Management Overview, Device Management Structures, SetupDiGetDeviceInterfaceDetail


Removable Storage Manager

Purpose

Removable Storage Manager (RSM) is a service included with Microsoft Windows® 2000 that facilitates communication among applications, robotic changers, and media libraries. It enables multiple applications to share local robotic media libraries and tape or disk drives, and manage removable media within a single-server system.

Where Applicable

A group of libraries, drives, and media that are managed by Removable Storage Manager is called an RSM system. Use Removable Storage Manager to write applications that make effective use of the media resources in an RSM system.

Developer Audience

A developer should use Removable Storage Manager if they are developing a media management application and require the following functionality:

  • The application is one of multiple applications that must share the same library, drive, and media resources

  • The application runs on a single computer that must track multiple types of media

  • The application runs on a single computer that must track media that are inside or outside a media library unit

Run-time Requirements

Windows® 2000

See Also

Microsoft Management Console

Overview

General information about Removable Storage Manager.

Removable Storage Manager Function Reference

Documentation of Removable Storage Manager methods and interfaces.

Feedback

Make error reports and feature requests directly to Microsoft.


Legal Information

Removable Storage Manager

Information in this document, including URL and other Internet web site references, is subject to change without notice. The example companies, organizations, products, people and events depicted herein are fictitious. No association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2001 Microsoft Corporation. All rights reserved.

ActiveX, BackOffice, DirectX, JScript, Microsoft, Microsoft Press, MS-DOS, Visual Basic, Visual C++, Windows, Win32, Win32s, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries/regions.

Portions © 1999 HighGround Systems, Inc. All rights reserved.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


Roadmap to Removable Storage Manager Documentation

The Removable Storage Manager (RSM) for Microsoft® Windows® 2000 documentation covers the following functional areas:

  • About Removable Storage Manager

    Contains high-level information about RSM and the features it provides, as well as information about designing your own RSM application.

  • Developing a Media Label Library

    information on how to write and install a media label library.

  • Removable Storage Manager Function Reference

    Contains RSM function reference pages.

  • Media Label Library Function Reference

    Contains media label library function reference pages.

  • Removable Storage Manager Structure Reference

    Contains RSM structure reference pages.

  • Glossary

    Contains RSM glossary terms and definitions.

This section contains information about RSM that is tailored for developers creating RSM client applications. There is additional information in the Windows 2000 Resource Kit about administrative aspects of RSM. To completely understand how to utilize RSM within your application and design a good user experience, please read this information.


About Removable Storage Manager

RSM is a service included with Microsoft® Windows® 2000 that facilitates communication among applications, robotic changers, and media libraries. It enables multiple applications to share local robotic media libraries and tape or disk drives, and manage removable media within a single-server system. A group of libraries, drives, and media that are managed by RSM is called an RSM system. RSM can help you create an application that makes effective use of the media resources in an RSM system.

RSM includes the following components:

  • RSM application programming interface (API)
  • RSM database
  • RSM MMC snap-in

The following figure illustrates the relationships among the components of RSM, devices, and Windows 2000. RSM components are shown in solid white.

When an application needs to mount a tape, for example, it uses the MountNtmsMedia function to issue a mount request for the specified tape. RSM reads the database for location and identification information of the tape. If the tape is offline, RSM generates an operator request to insert it. If the tape is online, RSM uses the changer driver to mount it and updates the database. When the tape is in the drive RSM uses the tape driver to read the label on the tape. RSM then compares what was read from the database to what was expected to ensure the correct tape was mounted.


RSM API

The RSM API is the interface that applications use to access the services and media in an RSM system. It is a dynamic-link library (DLL) that contains a group of functions you can use to build your data management application. These functions perform the following operations:

  • Mount and dismount media
  • Clean drives
  • Insert and eject media
  • Inventory libraries
  • Enable and disable libraries, drives, and media
  • Access information in the RSM database

When you develop your media management application using the RSM API, you gain the following benefits:

  • Multiple applications can share the same library, drive, and media resources
  • Code written to the RSM API for a specific library can execute on a wide range of libraries, both those that exist now and those that are introduced in the future
  • A single computer can track multiple types of media
  • A single computer can track media that are inside or outside a media library unit


RSM Database

The RSM database contains information about the objects in an RSM system. RSM maintains the data in the database and updates it whenever the administrator, an application, or a device makes a change in an RSM system. For example, if the administrator wants to mount a piece of media in an online library, RSM mounts the media and updates the database to reflect the change. The database includes the following information:

  • Library, drive, and media configuration and state
  • Media pool configuration and contents
  • Library work list
  • Operator requests


RSM MMC Snap-in

The RSM MMC snap-in is a administrative interface to RSM that is a snap-in for the Microsoft Management Console (MMC) for Windows 2000. Administrators can use the snap-in to insert and eject media, perform inventories, mount and dismount media, clean drives and check status information. RSM objects can be physical objects (such as libraries, drives, and media) or groups of media (called media pools).

Normal users should never be required to use the snap-in because each RSM client application takes care of routine tasks. For example, a simple backup application should not require a user to go to the snap-in to place media in a drive. In general, administrative support should only be required if a system is running more than one RSM client application, backup and a document management system, for example, or the system has a sophisticated robotic library that requires administrative management.

The MMC snap-in can help administrators perform the following tasks:

  • Complete or refuse operator requests
  • Point and click operations such as inserting media, ejecting media, drive cleaning, and dismounting media, moving media from one pool to another
  • Cancel work queue items
  • Enable and disable drives and libraries


RSM Basic Concepts

Removable Storage Manager can be described in terms of five basic concepts: media, physical locations, media pools, work queue items, and operator requests. The last four of these are the top level nodes in the Removable Storage Manager snap-in. The first, media, is the most fundamental concept and affects all the others.


Media

Units of media store information. Each unit of media, or medium, also referred to as a "cartridge", is of a certain type, such as 8mm tape, magnetic disk, optical disk, or CD-ROM.

Most types of media have a single side. For example, a tape must always be oriented in a certain way. When the tape is placed in a drive, all of its data is accessible. Some types of media, such as magneto-optic (MO) disks, have two sides. An MO disk has an "A" side and a "B" side. When an MO disk is placed in a drive with the "A" side up, then the "A" side is accessible and the "B" side is not. To access the "B" side, the disk must be inserted with the "B" side up.

Removable Storage Manager represents media physically and logically. Physical media are the tangible media that are inserted and removed from libraries and mounted in drives.

When an application needs to access data on a cartridge, Removable Storage Manager generates a logical identifier (ID) that allows the application to request the data on that cartridge. Since access to the data occurs only through that ID, Removable Storage Manager can manage the physical location of the data. For example, if the original cartridge begins to fail, Removable Storage Manager can move the data to a new cartridge without having to notify the application.

Physical media and the sides they contain are tracked in Removable Storage Manager and can take on various states as they are entered into a library and used. For more information about media and side states, see Media Identification and Naming and media pools.

Removable Storage Manager provides the infrastructure necessary to share media among various applications. Removable Storage Manager ensures that all media are used in such a way as to preserve the data they contain. Removable Storage Manager accomplishes this by identifying and verifying the identity of each cartridge. For more information about how Removable Storage Manager verifies the identity of media, see Media Identification and Naming.


Physical Locations

Removable Storage Manager manages two classes of physical locations: libraries and the offline media physical location. Libraries include both media and the means to read and write them. The offline media physical location is a special holder for media that is cataloged by Removable Storage, but does not reside in a library.

The set of all physical locations includes the libraries and the offline media physical location.

Libraries

In its simplest form, a library is composed of data storage media and a means to read and write the media. A CD-ROM drive with a disc inserted is a simple library with one drive, no slots, and no transport. A more complex example of a library is a robotic-based tape library, which holds several (up to several thousand) tapes, has one or more tape drives, and has a mechanical means to move tapes into and out of the drives.

Specifically, libraries are composed of the following:

Slots

Slots are storage locations in the library. For example, a tape library has one slot for each tape that the library can hold. A stand-alone drive library has no slots. However, most libraries have at least four slots. Sometimes slots are organized into collections of slots called magazines. Magazines are usually removable.

Drives

A drive is a device that can read or write to a cartridge. An Iomega Jaz drive, for example, can read and write to a Jaz cartridge which is inserted into it. A library has at least one drive.

Transports

A transport is the robotic device that moves a cartridge from its slot to a drive and back again. Robotic libraries usually have only one transport.

Bar Code Readers

A label with a bar code is attached to the outside of a cartridge that is both human readable and computer readable. Libraries that hold media with bar codes attached might have a bar code reader. There is only one reader, which is usually mounted on the transport.

Doors

A door is a means to gain unconstrained access to the media in a library. On larger libraries a door might resemble an actual door. When the door is open, an administrator can add and remove media from the library. Doors on smaller libraries might not always look exactly like doors, but they still provide the same functionality. For example, some small changers have all their slots in a magazine. When an administrator instructs Removable Storage Manager to open the door, the changer pushes the magazine out through the front. The administrator can add, replace, or remove media and then reinsert the magazine into the changer. When an administrator adds media to a library, the media are placed directly into a slot. Some libraries have no doors, while others have several.

Insert/Eject Ports

While doors provide unconstrained access to the media in a library, an insert/eject (IE) port provides very controlled access. When an administrator adds media to a library through an IE port, the media are not placed directly into a slot. Instead, the media are placed in the IE port and then the library uses the transport to move the media from the IE port to a slot. Some libraries have no IE ports, while others have several. Also called "mailslots," some IE ports handle only one cartridge at a time, while others may handle several.

Types of Libraries

A robotic library can have any of the components described above. At a minimum, a robotic library has some media, slots to hold the media, one or more drives, a transport, and either a door or an IE port. Robotic libraries are sometimes referred to as changers or jukeboxes. No human intervention is required to place a cartridge in a library in one of its drives.

A stand-alone drive library or stand-alone drive is a special kind of library. A cartridge must be manually placed in a drive. The CD-ROM drive found on most desktop computers is a stand-alone drive library. Removable Storage Manager treats stand-alone drives as libraries with one drive and an IE port. Removable Storage Manager models these drives as libraries to make its program interfaces simpler. For this reason, an application need not know whether a cartridge is mounted by a transport or a human.

Offline Media Physical Locations

The offline media physical location is where Removable Storage Manager lists media that are not in a library. The physical location of media in an online library is the library in which it resides. Media that are not in any of these libraries, such as archived backup tapes on a shelf, are offline media and reside in the offline media physical location. When a user or administrator moves an offline cartridge into a library, Removable Storage Manager changes its physical location to be the library into which it was placed. When a cartridge is taken out of an online library, Removable Storage Manager notes that it now resides in the offline media physical location.


Media Pools

A media pool is a logical collection of media that share some common attributes. A media pool contains media of only one type, but media in the media pool can be in more than one library. Each cartridge is in a media pool. There are two classes of media pools: system and application. System media pools are created by Removable Storage Manager for its own use and include the free, import and unrecognized pools. Application media pools are created by applications to group media. Grouping media is especially important if several applications are sharing the libraries attached to a system and the media they contain.

Each media pool has access permissions that control access to the media that belong to it. While these permissions do not control access to the data contained on the media, they do control the manipulation of the media, including an application's ability to move media from the pool or to allocate it for its own use.

Media pools can be used hierarchically. A media pool can be used to hold other media pools, or it can be used to hold media. An application that needs to group media of several types into one collection can create an application media pool for the whole collection and additional media pools within it, one for each media type. Removable Storage Manager actually uses this technique for its system pools. Within the free pool, for example, is a media pool for each media type. Both sides of a two-sided cartridge are always in the same pool.

System Pools

The system pools are used to hold media that are not currently being used by an application. The free pool holds unused media that are available to applications, and the unrecognized and import pools are temporary holding places for media that have been newly placed in a library. For more information on how Removable Storage Manager uses these pools, especially the unrecognized and import pools, see Media Identification and Naming.

Free Pools

The free pools support sharing media among applications. They contain media that are freely available to any application, and they hold no useful data. An application can draw media from the free pools when it needs additional media, and it can return media to the free pools when the media are no longer needed and should be made available to other applications.

Unrecognized Pools

When a cartridge is placed in a library, Removable Storage Manager tries to identify it. If it has not seen this particular media before nor discerned its format or the application which last wrote data on it, Removable Storage Manager places the cartridge in the unrecognized pool for its media type. Blank media are treated this way. Media in the unrecognized pools might have data on them, but they are not cataloged by Removable Storage Manager nor is Removable Storage Manager able to read any data on these media.

Import Pools

If Removable Storage Manager can identify the format or application associated with a cartridge that has just been placed in a library but has never been seen before, it places the cartridge in the import pool. For example, if an administrator placed a tape written by Backup on one system into a library attached to a second system, the instance of Removable Storage Manager on the second system recognizes that the tape was written using Microsoft Tape Format (MTF) and places it in the proper media type import pool.

Application Pools

Each application that uses media managed by Removable Storage Manager uses one or more application pools. Applications can create these pools, or they can be created using the Removable Storage Manager snap-in. Permissions on application pools can be set up to allow applications to share pools, or to assign each application its own set of pools.

As mentioned earlier, a pool can either be created to hold other pools or it can be created to hold media. A pool created to hold media has additional properties that specify the actions to be taken when an application allocates or deallocates media.

The example discussed in the section Designing an RSM Application shows one way in which media pools might be configured to support the needs of several client applications. The example system contains two libraries — one optical disk library and one tape library — and two data mover applications — a backup application and a document management application.


Work Queues

When applications make a library request , Removable Storage Manager places these requests in a queue and processes them as resources become available. For example, a request to mount a tape in a library results in a mount work queue item, which might wait until a drive is available.


Operator Requests

Sometimes, even with robotic libraries, manual assistance is needed to complete a request or perform maintenance or support. If an application requests that a cartridge in the offline media physical location be mounted, the cartridge must be manually entered into an online library, generating a request to the operator to enter the cartridge.

Operator requests can be presented to an administrator through the Windows 2000 Messenger Service or the status area of the taskbar. An administrator can refuse or complete these requests.

Note "Operator" as used here, is synonymous with "administrator."


Media Identification and Naming

As a manager of shared resources, Removable Storage Manager ensures that client applications do not corrupt each other's data. Placing permissions on media pools prevents an application from modifying the data of another application. Another way to accomplish this is to assign each medium a unique name which applications can use to refer to it, and to track the identities of all media in a system, ensuring that the mapping between the unique name and the physical media is always accurate.

A library management system could simply use a media's home slot as its identity. A request to mount a medium in a drive could be as simple as "Mount the medium in slot 6 of drive 2." There are problems with this minimalist approach, however. An administrator could exchange the medium in slot 6 for that in slot 7 during a door access. An application executing the request might get a medium it did not expect and not know it. To prevent this, Removable Storage Manager assigns each medium a unique name, which is used to refer to the medium programmatically. In keeping with Windows 2000 naming conventions, Removable Storage Manager uses globally unique identifiers (GUIDs) as the form for these names.

Removable Storage Manager identifies each medium side by reading its label. At various times, Removable Storage Manager reads the label to ensure that the name it has for a medium maps correctly. Consider a refinement of the example given earlier. If the name of a medium simply referred to the medium in slot 7, an administrator could change the contents of slot 7 during a door access and the next time an application used the name it would get a different medium. Removable Storage Manager prevents this by associating information stored in the medium's label with its name. Each time a medium is mounted, for example, Removable Storage Manager reads the label to ensure that the medium it mounted is correct. An inventory is an operation that an administrator can request or that Removable Storage Manager can initiate, which verifies the labels associated with each named medium in a library.

Since administrators also need to identify media uniquely, and since GUIDs are difficult to read in printed form, Removable Storage Manager also assigns each medium a display name. These names are changeable so if an administrator has a naming scheme for media, a display name can be assigned that is different from the one Removable Storage Manager initially assigned.


On-media Identifiers

On-media identifiers (OMIDs) are electronically recorded labels on each medium side in a Removable Storage Manager system. Each label is composed of at least two parts: a type and an ID. A label type identifies the format used to record information on the medium. A label ID is an identifier that uniquely identifies each medium.

Different media types have different types of labels. Media sides with file systems (optical disk and Jaz cartridges, for example) have file system labels. An NTFS-formatted Jaz cartridge, for example, has an NTFS label type, and the ID is the volume serial number. Tapes using MTF have a label type of MTF and the ID is derived from various fields in the MTF header.

On-media identifiers are handled somewhat differently for CD-ROM and DVD-ROM media. Serial numbers for instances of these media might not be unique — a library can hold multiple copies of the same CD-ROM title, for example, with each having the same serial number — so Removable Storage Manager allows non-unique label IDs in this case. This doesn't degrade the media identification objectives of Removable Storage; any of the CD-ROMs with identical IDs can be used interchangeably since their contents are identical and cannot be changed.


Duplicate Copies of Media

Although Removable Storage Manager tries to uniquely identify each cartridge that it manages, it also handles media duplicates. It treats identical media as separate media that are identical in every way and can be used interchangeably. For example, if a user has two copies of the Windows 2000 Server Setup CD and places both in a changer, Removable Storage Manager shows both media and each can be mounted, ejected, and so on, separately. Since each has its own record in the database, it is possible to attach different attributes to each media. You can give each a different display name, for example, although this is discouraged because there is no guarantee that these differing attributes will always be associated with the same cartridge. If both are ejected, the attributes may be reversed when both are inserted again.


Bar Codes

Bar code labels on physical media, in libraries with bar code readers, are used as a shortcut to determine the identity of physical media and its sides. Reading an on-media label can be time consuming since it requires reading data on the media, which requires that the medium be placed in a drive if it's not already there. With unique bar codes, a bar code scan is a much faster way of identifying a physical medium and the sides it contains.


Media Names

When new physical media are placed into a library, Removable Storage Manager assigns an initial display name to the media that an administrator can use to visually identify the media. This name is derived from several sources, including the on-media label and the bar code. The rules include the following:

  1. If the media has a bar code label, its alphanumeric value is used as the display name.
  2. If the media is single-sided and has a recognized label type on its single side, the name is taken from the label. If the format is MTF, the label is taken from information in the MTF header. If the format is a file system, the name is taken from the volume name.
  3. The sequence number is used.


Media Change Detection

Many removable media devices, including all those connected to the system by means of SCSI and IDE, cannot themselves report when media are entered or removed. Instead the host system must notice such changes either by querying the device specifically for this information or when performing some other operation on the drive.

Since Removable Storage Manager controls changers and knows when media enter and leave drives, this is not a problem for drives in changers. It is an issue, however, for stand-alone drives. The information that Removable Storage Manager has about the contents of a stand-alone drive might be incorrect if the state of the drive has changed. For example, the snap-in might show that a drive is empty for a period of time after a tape is inserted into a tape drive. An inventory operation on the stand-alone drive library brings the state up-to-date.

Some applications need to have current information. For these applications Removable Storage Manager provides a media change detection mechanism that can be turned on and controlled through Removable Storage Manager API calls. With media detection turned on for a stand-alone drive library, the state of the drive that Removable Storage Manager presents to applications is updated almost immediately after the physical state of the drive changes.


Designing an RSM Application

This section describes how to design an RSM application. You should read it before you make decisions about how to use RSM in your application.
  • Building a media label library
  • Creating and configuring media pools
  • Allocating and using media
  • Recovering from a disaster


Building a Media Label Library

A media label library (MLL) is a DLL that can identify tapes written using a particular tape format. If your application uses a standard tape format (MTF, QIC 113 or HP OmniBack II), then you do not need to develop your own MLL. If you use a different tape format then you will have to develop your own MLL, which you must install as part of your application installation.

MLLs are currently used only with tape media. Disk media, or file system capable media, are identified in a different manner. The system call GetVolumeInformation is used to determine the file system type, volume serial number and volume name of disk sides. This information is used as the OMID.

For more information about building a media label library, see Developing a Media Label Library.


Creating and Configuring Media Pools

Applications use media pools to hold media that share common attributes. These attributes are: media type, relationship to the free pool and security. These properties are set on a pool and all media in that pool are then governed by these properties. All media in a pool are of the same type. Accessibility to each cartridge in the pool is governed by the ACL placed on the pool. The media pool used by the application determines what happens when an application requires a new cartridge or is done with a cartridge.

Your application might use two media pools, for example, if it needs to use cartridges of two different types. Similarly, your application might need to use two media pools if it has some cartridges that must only be accessible to certain users and other cartridges that are available to every one.

The following points should be considered when you set the parameters for this function and configure the media pool:

  • Available media types

    You can enumerate the media pools in the free media pool folder to generate a list of the media types in an RSM system. You can enumerate the media type object to list all the media types supported by RSM. You can also enumerate the media type object of each library in the system.

  • Automatic media draw

    Decide whether RSM will automatically draw media from the free pool when there are no media set to the Available state in the media pool.

  • Automatic media return

    Decide whether RSM will automatically return media to the free pool when the media are no longer needed.

  • Media pool security

    Decide what level of security you want to assign to the media pool.

The first task your application should perform, usually when installed, is to create and configure media pools. You can use the CreateNtmsMediaPool function to create media pools.


Allocating and Using Media

After you create and configure media pools, you can allocate media using the AllocateNtmsMedia function. This function returns a logical media identifier (LMID). Media can only be allocated by one application at a time. While in this allocated state, a cartridge is considered "in use" by your application may contain valuable data. When your application no longer requires the cartridge it must deallocate the media by calling DeallocateNtmsMedia. Once deallocated, a cartridge is available to for use by other applications. If the deallocated cartridge remains in your media pool then only other applications that have access to your pool can utilize it for their use. If the deallocated cartridge is returned to the free pool then any other application can utilize it.

To use a cartridge you call MountNtmsMedia, which places the cartridge in a drive. After this call, you can use standard Microsoft® Win32® I/O functions to read and write the contents of the media. Use the DismountNtmsMedia function to dismount the cartridge. The following list follows the path of functions you should use to access media in a RSM system.

  • OpenNtmsSession
  • AllocateNtmsMedia (do this only when you need another cartridge)
  • MountNtmsMedia
  • Use the media (create a file, modify it, close, etc.)
  • DismountNtmsMedia
  • DeallocateNtmsMedia
  • CloseNtmsSession


Using Basic RSM Functions

This section describes the typical life cycle of RSM media. Most media in RSM follows the same path; variations from this path are provoked by unusual situations. The following figure illustrates the typical media pool cycle of RSM media.

When a new cartridge is inserted into an online library, RSM typically puts the cartridge in either the import or the unrecognized media pool. The administrator or your application can move the cartridge to the appropriate free media pool using the MoveToNtmsMediaPool function.

The following figure illustrates the typical media state cycle of RSM media.

Note When you use the MountNtmsMedia function to mount tape media, remember that your application must specifically set the drive to fixed or variable block mode. Your application cannot assume that the device is in the default mode. You can use the Microsoft® Win32® function, SetTapeParameters to set the drive mode.

When you do not want to record any more information on the cartridge, you can set the its state to Completed using the SetNtmsMediaComplete function. Typically, Completed media is not written to again. Placing a cartridge in the Completed state allows a management application to replicate or refresh the media.

Media that hold less vital information and are recorded on many times are typically decommissioned after the maximum number of allocations. Only Available media can be decommissioned, so you must use the DeallocateNtmsMedia function before you can decommission a piece of media. You can use the DecommissionNtmsMedia function to decommission Available media.

After you deallocate media, you can leave the media in the application media pool or move it to a free media pool so that it can be used by other applications. Your application can reallocate Available media that remains in the application media pool until it has reached its allocation maximum (determined by the administrator or an application).


Using Operator Requests in RSM

An RSM operator request is a request for a person (often an administrator, but can be a user) to perform a task. Operator requests can be issued by RSM or by RSM applications. RSM generates operator requests in the following situations:

  • Media must be moved online because an application has initiated a mount request for media that is offline.
  • There are no Available media online in the specified application media pool or in the appropriate free media pool when an application requests media allocation. The operator can supply new media or Available media that is offline to satisfy the request.
  • A device failed and requires service.
  • A drive needs to be cleaned and there is no usable cleaner cartridge available in the library unit.

Operator requests are displayed in the RSM MMC snap-in. The person acting on the request must ether complete or refuse it in the snap-in. When the individual performs the request successfully then the request must be completed. If the request cannot be completed then it must be refused.. When an operator cancels an operator request, RSM notifies the application that generated the request.


Cleaning Drives in RSM

Unless you are developing an application that is intended to manage device maintenance, your application does not have to address drive cleaning. RSM is designed to manage device maintenance.

In the RSM model of device maintenance, each library unit can contain one cleaner cartridge. Administrators can use the RSM MMC snap-in to place a cleaning cartridge in a library, clean a dirty drive or remove an exhausted cleaning cartridge.

RSM maintains a usage count for each cleaner cartridge. When a cleaner reaches its maximum usage count, RSM generates an operator request. If you are developing an application that manages device maintenance, you can use the following RSM functions to implement drive cleaning functionality.

  • CleanNtmsDrive
  • EjectNtmsCleaner
  • InjectNtmsCleaner
  • ReleaseNtmsCleanerSlot
  • ReserveNtmsCleanerSlot

If your application calls EjectNtmsCleaner, it must first call ReserveNtmsCleanerSlot in order to have a place in the library to put the cleaning cartridge.


Disaster Recovery

System administrators or users should routinely backup the RSM database. For instructions on how to do this, see the Windows 2000 Resource Kit.

If you are writing a backup application that is used to backup system databases such as RSMs, or if your application requires its own preparations for disaster recovery that might require special handling of the RSM database, then you need to call specific RSM functions in order to get a consistent copy of the database files. For example, Windows 2000 Remote Storage makes copies of the RSM database files at the end of each data migration job. In a disaster situation, it is possible to completely restore Remote Storage even if the administrator has not been routinely backing up RSM's database explicitly.


Backing Up the RSM Database

The default location of the RSM database is %SYSTEMROOT%\System32\NTMSData. The actual location of the database can be changed to any location. The current location of the database is found in the registry under

HKLM\System\CurrentControlSet\Control\NTMS

as the value "NtmsData". The database files are always stored in a folder named "NtmsData" under the folder given in this value. If RSM is not running, it is a sufficient backup strategy is to make copies of these files. Most backup applications, though, require RSM to be running while the backup occurs.

To back up the RSM database while RSM is running, an application must open an RSM session and use the ExportNtmsDatabase function. This function creates a consistent replica of the current database. RSM creates the replica in the Export subdirectory of the RSM database directory.


Recovering the Database

When the RSM database files have been restored from a backup two additional step are needed before RSM will begin using the restored database. First the recovery application must call the ImportNtmsDatabase function. This function makes the changes necessary for RSM to import the restored on the next restart. Once this is completed, the next time RSM starts it uses the restored database. This can either be done by restarting the service with the Service Control Manager or rebooting.


Updating the Restored Database

The database as restored may not have been current at the time of the destructive event. An application may have allocated a tape between the last database backup and a disaster that destroyed the running database.

In general, your application should scan its own pools as well as the free and import pools after a recovery, searching for the OMIDs of its media and any media that may be in the wrong place. The following table describes how your application can resolve each problem.

Problem | Solution
A specified side is deallocated by an application after the backup but before the disaster and remains in the application media pool. RSM recognizes this side as still allocated after the recovery and leaves it in the application media pool. | The application must deallocate this side again.
A specified side is allocated by an application after the backup but before the disaster. RSM leaves the cartridge in the import or free media pools. | The application can import the cartridge to the free media pool.


Restoring the RSM Database in the Absence of a Backup

This section describes a strategy for an application to recover the RSM database when the database has been lost and there is no backup copy, but the application has not lost the database that refers to the lost RSM database. For this example it is assumed that the application has kept both the RSM LMID and its own OMID information in its database. An application can take the following steps to in essence create a usable new RSM database:

  1. When RSM starts without a database it does a full inventory and all the media in the library appear in the import pool.
  2. The application must create its media pool(s).

    The application must have a mechanism that scans the Import media pool for its media. This can be accomplished by reading the OMID information of the sides of the physical media and finding all media with the szOmidLabelType parameter that is the application's type. As an additional check the application can verify that the szOmidLabelInfo parameter is correct for the media.

  3. For all sides found, the application must call the AllocateNtmsMedia function, specifying the side and media pool.
  4. The application database must be updated with the new LMID that is assigned to the media. The application should search through its database for all cases of the OMID it has found and replace the corresponding LMID with the new one.
  5. Media that were offline and not in the library at the time of the full inventory must be injected into the library so they can be identified and placed in the import pool. To do so, repeat steps 3, 4 and 5.


Developing a Media Label Library

A media label library (MLL) is a DLL that can parse a tape label and find certain information within the label that uniquely identifies the tape. RSM passes labels to each MLL, and an MLL will pass back on-media identifier (OMID) information for each media it can parse.


Label Constraints

Your media labels must:

  • Be recorded at the beginning of the specified media.
  • Include a label type that is the same across all media of this format.
  • Include a label ID that is unique for each media of this format.


Installing a Media Label Library

You must install or provide instructions for installing your media label library in the installation program for your application. Your installation program must create the appropriate registry entries and copy your media label library to the appropriate directory. Your application must create the following registry node under

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\NTMS\OMID\Tape

The name of this node can be either your company or product name, but it must be unique. For example, if you wish to name your MLL "STL", the key is:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\NTMS\OMID\Tape\STL

Under the key for your media label library, the installation program must create two registry values: Description and Path. The Description registry value is of type REG_SZ and contains a human readable description of the media label library. The Path registry value is of type REG_SZ or REG_EXPAND_SZ and contains the absolute path of the media label library.

Remember the following rules when you develop the installation program for your application:

  • Installations of new media label libraries are restricted to members of the Administrator group.
  • The registry entries that contain the list of media label libraries are accessible only by members of the Administrator group.
  • The folder that contains all the media label library DLLs is typically accessible only by members of the Administrator group. The default location for RSM media label libraries is winnt\system32.


Using MTF Media Labels

RSM provides a generic media label library for Microsoft Tape Format (MTF). If your application writes MTF labels on tapes, there are certain requirements it must follow in how the labels are written.

RSM has the following requirements for applications that use MTF:

  • The DBLK Type field in the Common Block Header of the Media Header must be 'TAPE'.
  • The Header Checksum value in the Common Block Header of the Media Header is set correctly.
  • RSM uses the TapeName value as the Label Application Description and the SoftwareName value as the Label Type.
  • If the Tape Media Label Bit is set in the Tape Attribute field, the label library verifies the media label field of the MTF label and checks the description/label field for a GUID (UUID) of the form
    12345678-1234-1234-1234-123456789012
  • If found, RSM uses the UUID as the LabelID of the side. If a GUID is not found in the field, then an MD5 algorithm is used to generate a unique ID from the MTF block and it is returned as the LabelID.


RSM Startup

RSM performs several tasks at startup time. During some of the tasks, RSM is unavailable for commands. At other times during startup, RSM may accept commands; however, the execution of the command may be delayed while RSM completes initialization. The following steps outline the process followed by RSM during startup. It is important to note that the process is the same when the service is restarted or the computer has been restarted.

  1. Build or reconfigure the RSM database based on the current device configuration.
  2. Mark all not completed work-items in the work queue as cancelled.
  3. Start a thread to process requests for each library in the system.
  4. Each thread checks its configuration and performs a default inventory for its library. The inventory may result work items to identify media being placed on the library's work queue.
  5. Start accepting requests.
  6. Complete the default inventory work.

Note Inventory will empty the drives if possible. If the drives are currently in use, RSM leaves the media in the drive and examines the media in the drive at a later time. Also, note that the inventory performed is the default inventory for the specified device which can be set to FULL, FAST, or NONE.


Removable Storage Manager Function Reference

This section includes Removable Storage Manager (RSM) functions.

Note These functions were defined before NTMS was renamed to Removable Storage Manager and as a result each function name contains the prefix "Ntms". Similarly, the "scratch" pool was renamed "free", and the "foreign" pool was renamed "unrecognized". The term "partition" was replaced with the term "side".

Cleaner Management Functions

RSM can automatically clean tape drives that become dirty through use. Use the following functions to control drive cleaning:

CleanNtmsDrive

EjectNtmsCleaner

InjectNtmsCleaner

ReleaseNtmsCleanerSlot

ReserveNtmsCleanerSlot

Database Backup and Recovery Functions

RSM uses a database to store information about the removable media devices and cartridges in a system. Like any system resource, this database should be backed up in case it becomes lost or corrupted. Use the following functions for RSM database backup and recovery:

ExportNtmsDatabase

ImportNtmsDatabase

Database Notification Functions

You can use the following functions to get notifications when RSM database objects change:

CloseNtmsNotification

OpenNtmsNotification

WaitForNtmsNotification

Session Management Functions

Before calling any other functions, an application must open an RSM session, and the session must be closed before the application exits. The following session management functions open and close RSM sessions:

CloseNtmsSession

OpenNtmsSession

Library Control Functions

Library control functions control:

  • Injecting and ejecting media
  • Moving media between libraries
  • Enabling and disabling drive and changer resources
  • Taking library inventory

You can use the following library control functions:

AccessNtmsLibraryDoor

CancelNtmsLibraryRequest

DeleteNtmsDrive

DeleteNtmsLibrary

DeleteNtmsRequests

DismountNtmsDrive

EjectNtmsMedia

GetNtmsRequestOrder

InjectNtmsMedia

InventoryNtmsLibrary

SetNtmsRequestOrder

Media Services Functions

Media services functions are used for:

  • Mounting and dismounting media
  • Allocating and deallocating media
  • Managing media pools

You can use the following media services functions:

AddNtmsMediaType

AllocateNtmsMedia

ChangeNtmsMediaType

CreateNtmsMedia

CreateNtmsMediaPool

DeallocateNtmsMedia

DecommissionNtmsMedia

DeleteNtmsMedia

DeleteNtmsMediaPool

DeleteNtmsMediaType

DismountNtmsMedia

GetNtmsMediaPoolName

MountNtmsMedia

MoveToNtmsMediaPool

SetNtmsMediaComplete

SwapNtmsMedia

Object Management Functions

You can use the following functions to enumerate, get, and set information about RSM objects:

DisableNtmsObject

EnableNtmsObject

EnumerateNtmsObject

GetNtmsObjectAttribute

GetNtmsObjectInformation

GetNtmsObjectSecurity

SetNtmsObjectAttribute

SetNtmsObjectInformation

SetNtmsObjectSecurity

On-Media-Identifier Management Functions

RSM identifies media in a system by reading an on-media identifier (OMID) The following function updates the RSM database when a new OMID is written:

UpdateNtmsOmidInfo

Operator Request Functions

You can use the following functions to manage and control requests to system operators:

CancelNtmsOperatorRequest

SatisfyNtmsOperatorRequest

SubmitNtmsOperatorRequest

WaitForNtmsOperatorRequest

Change Detection Functions

RSM does not detect inject and eject operations on standalone drives unless requested to do so by the application. Although some RSM functions automatically begin change detection of certain devices, applications that require current information on the presence or absence of media in standalone drives must use these functions to request RSM to detect the changes. With change detection enabled, an application can use database notification functions to be notified when media is injected and ejected. You can use the following functions:

BeginNtmsDeviceChangeDetection

EndNtmsDeviceChangeDetection

SetNtmsDeviceChangeDetection


AccessNtmsLibraryDoor

The AccessNtmsLibraryDoor function unlocks the door of the specified online library. If the library is busy, RSM queues the request and returns successfully.

DWORD WINAPI AccessNtmsLibraryDoor(
  HANDLE hSession,
  LPNTMS_GUID lpLibraryId,
  DWORD dwAction
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibraryId
Specifies the unique identifier of a library object. This library must support door access.
dwAction
This parameter can be one of the following values.
Value | Meaning
NTMS_INVENTORY_NONE | After the user closes the door, no inventory is performed. However, if a mount-label check fails, an inventory will be performed.
NTMS_INVENTORY_OMID | After the user closes the door, a full on-media inventory is performed. This can be time consuming because each side of each medium must be mounted.
NTMS_INVENTORY_FAST | If the library has a bar-code reader installed, this flag causes bar-code inventory to be performed. If the library does not have a bar-code reader, this flag causes a differential inventory to be performed. The OMIDs are checked on each medium placed in an empty slot while the door is open.
NTMS_INVENTORY_DEFAULT | Use the InventoryMethod specified in the library object.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DEVICE_NOT_AVAILABLE | The library is disabled.
ERROR_INVALID_HANDLE | The session ID is invalid or missing.
ERROR_INVALID_PARAMETER | The library ID is missing.
ERROR_LIBRARY_OFFLINE | The library ID references an offline library without a door.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_RESOURCE_NOT_PRESENT | The library does not have a door.
ERROR_SUCCESS | Door access is queued.

Remarks

The AccessNtmsLibraryDoor function is valid only for online libraries.

Some libraries provide no means for RSM to programmatically lock and unlock their doors. The behavior of this function with these libraries is identical to its behavior with libraries that RSM can unlock and lock.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions, EjectNtmsMedia, InjectNtmsMedia


AddNtmsMediaType

The AddNtmsMediaType function adds the specified media type to the specified library if there is not currently a relation in the library object. The function then creates the system media pools (FREE/IMPORT/UNRECOGNIZED) if they do not exist.

DWORD AddNtmsMediaType(
  HANDLE hSession,
  LPNTMS_GUID lpMediaTypeId,
  LPNTMS_GUID lpLibId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaTypeId
Specifies the unique identifier of a media type to add to the library.
lpLibId
Specifies the unique identifier of the library to which to add the media type.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to media's media pool is denied.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_LIBRARY | The library ID is invalid.
ERROR_INVALID_PARAMETER | The media type or library ID is missing.
ERROR_NOT_ENOUGH_MEMORY | There was an allocation failure during processing.
ERROR_SUCCESS | The function was successful.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, DeleteNtmsMediaType


AllocateNtmsMedia

The AllocateNtmsMedia function allocates a piece of available media.

DWORD WINAPI AllocateNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaPool,
  LPNTMS_GUID lpPartId,
  LPNTMS_GUID lpMediaId,
  DWORD dwOptions,
  DWORD dwTimeout
  LPNTMS_ALLOCATION_INFORMATION lpAllocateInformation
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaPool
Specifies the unique identifier of a media pool from which the media is to be allocated.
lpPartId
Specifies the part ID of a side to use for LMID. The side must be in the Available or Import state. This feature can be used to allocate a particular side or to import media. This parameter is optional.
lpMediaId
Used to return the media ID of the allocated medium. The returned logical media ID is NULL if the medium cannot be allocated.
dwOptions
This parameter can be one or more of the following values.
Value | Meaning
NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE | Prevents the submission of an operator request for new media if none can be allocated with the specified constraints.
NTMS_ALLOCATE_NEW | Allocates a side of the specified medium that cannot be shared with another application's logical media. For example, this value reserves the second side of two-sided optical media.
NTMS_ALLOCATE_NEXT Allocate the next side of the multi-sideed medium previously allocated with the NTMS_ALLOCATE_NEW value. This allows a single application to use both sides of a piece of two-sided media and ensure that the application owns all the data on the piece of physical media.

If all the sides of the medium are already allocated, the allocation request fails.

dwTimeout
Specifies the maximum time allowed in milliseconds to allocate the specified media. Set this parameter to INFINITE so the function will not time out. Set this parameter to zero to not wait for media. Note that this function does not queue a request for more media if the NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE value is specified.
lpAllocateInformation
Pointer to a structure that returns the source media pool from which the medium was taken. If this information is not needed, pass a NULL pointer.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to media's media pool is denied.
ERROR_CANCELLED | The operator canceled the request for new media.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DEVICE_NOT_AVAILABLE | An intermediate resource is not available; for example, the free media pool is not available.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA | The partition ID or logical media ID was invalid upon input when using the NTMS_ALLOCATE_NEXT flag.
ERROR_INVALID_MEDIA_POOL | The media pool ID is invalid.
ERROR_INVALID_PARAMETER | The media or media pool ID is missing.
ERROR_MEDIA_OFFLINE | The specified media is offline and cannot be allocated.
ERROR_MEDIA_UNAVAILABLE | No media has been allocated within the specified time-out event.
ERROR_NOT_ENOUGH_MEMORY | There was an allocation failure during processing.
ERROR_SUCCESS | The function was successful.
ERROR_TIMEOUT | The time-out event expired before media was available.

Remarks

Only application pools may be specified for allocation using the AllocateNtmsMedia function.

The AllocateNtmsMedia function returns an LMID. Depending upon the media pool's policy, if the specified media pool does not contain any online Available media, AllocateNtmsMedia might search the free media pool for the specified medium to move to the specified media pool. Media from the designated media pool is allocated first, and then the free media is moved and allocated.

If the media pool contains any online Available media, a medium from the pool is allocated.

If the media pool is configured to allocate media from the free pool automatically, and the free pool contains online Available media, a medium is moved to the specified pool and allocated.

When the NTMS_ALLOCATE_NEXT value is specified, the lpMediaId parameter must point to a valid media ID at the time of invocation. In this case, lpMediaId is used as an IN and OUT parameter. The next side of the multiple sided medium specified by lpMediaId is allocated, and the new partition ID is returned through lpMediaId (overwriting the original media ID passed in).

If NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE is specified, ERROR_MEDIA_ UNAVAILABLE is returned if no media is available.

When necessary, RSM generates an operator request to insert new or Available media. If the time specified in the dwTimeout parameter elapses before the operator request is handled, RSM returns ERROR_TIMEOUT and deletes the operator request.

If the user cancels the allocation request, RSM returns ERROR_CANCELLED.

If a user indicates that the operator request has been satisfied, the request is deleted and RSM retries the process.

When an application requires new media containing data, a user or administrator places the media in a library or drive. RSM identifies the media and places it in the import pool. The application searches the import pool, moves the media to its application pool and allocates it. This routine process can be streamlined and made atomic through a single call to AllocateNtmsMedia. After searching the import pool the application can call AllocateNtmsMedia, passing the partition ID of the side as the value of the lpPartId argument. RSM then:

  1. moves the medium to the specified media pool.
  2. changes the media's state to allocated.
  3. returns an LMID.

Note For two-sided media, the flip side remains in the Import state and is not available for use until imported.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, DeallocateNtmsMedia


CancelNtmsLibraryRequest

The CancelNtmsLibraryRequest function cancels outstanding RSM requests, such as calls to the CleanNtmsDrive function. If the library is busy, RSM queues the CancelNtmsLibraryRequest function and returns success.

DWORD WINAPI CancelNtmsLibraryRequest(
  HANDLE hSession,
  LPNTMS_GUID lpRequestId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpRequestId
Specifies the RSM request object ID. To get a list of the existing library requests (or work items) to cancel, see the EnumerateNtmsObject function.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Only an administrator of the RSM server can cancel library requests.
ERROR_OBJECT_NOT_FOUND | The library request object ID was not found. This error occurs if the request is completed prior to issuing the cancel or when an invalid request ID is specified.
ERROR_SUCCESS | The library request has been queued for cancellation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions, EnumerateNtmsObject


CancelNtmsOperatorRequest

The CancelNtmsOperatorRequest function cancels the specified RSM operator request.

DWORD WINAPI CancelNtmsOperatorRequest(
  HANDLE hSession,
  LPNTMS_GUID lpRequestId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpRequestId
Specifies the operator request object ID.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | The user that tried to execute this function does not have administrator privileges. Only an administrator of the RSM server can cancel operator requests.
ERROR_OBJECT_NOT_FOUND | The operator request object ID was not found. This error occurs if the request is completed prior to cancellation of the operation or when an invalid request ID is supplied.
ERROR_SUCCESS | The operator request has been canceled.

Remarks

For a list of the existing requests to cancel with the CancelNtmsOperatorRequest function, see the EnumerateNtmsObject function or use the ID passed back by the SubmitNtmsOperatorRequest function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Operator Request Functions, SatisfyNtmsOperatorRequest, SubmitNtmsOperatorRequest


ChangeNtmsMediaType

The ChangeNtmsMediaType function moves the specified PMID to the specified target media pool and sets the PMID's MediaType GUID to the MediaType of the target media pool.

DWORD ChangeNtmsMediaType(
  HANDLE hSession,
  LPNTMS_GUID Pmid,
  LPNTMS_GUID MPoolId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
Pmid
Specifies the unique identifier of the physical media to be moved.
MPoolId
Specifies the unique identifier of a media pool to which the media is to be allocated.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to media's media pool is denied.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA_POOL | The media pool ID is invalid.
ERROR_INVALID_PARAMETER | The media pool or media ID is missing.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

The ChangeNtmsMediaType function uses the same policy for moving media as the MoveToNtmsMediaPool function (UNRECOGNIZED media can only be moved to the FREE Pool).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, AddNtmsMediaType, DeleteNtmsMediaType


CreateNtmsMedia

The CreateNtmsMedia function creates a PMID and side (or sides) for a new piece of offline media. The media is placed in the media pool specified for lpPhysicalMedia.

DWORD WINAPI CreateNtmsMedia(
  HANDLE hSession,
  LPNTMS_OBJECTINFORMATION lpPhysicalMedia,
  LPNTMS_OBJECTINFORMATION lpPartitions,
  DWORD dwOptions
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpPhysicalMedia
A required input parameter, providing information about the medium to create. See Remarks NTMS_OBJECTINFORMATION and NTMS_PMIDINFORMATION for a description of the applicable members.
lpPartitions
A required input parameter, pointing to an array of sides associated with the medium. See NTMS_OBJECTINFORMATION and NTMS_PARTITIONINFORMATION for a description of the fields.
dwOptions
Defines processing behavior:
Value | Description
0 | Default value. Allows the creation of a duplicate medium with a duplicate OMID.
NTMS_ERROR_ON_DUPLICATION | Returns an error and does not create the medium if a medium with the specified OMID already exists on the system.

Return Values

Value | Meaning
ERROR_SUCCESS | The function executed successfully.
ERROR_INVALID_PARAMETER | Missing parameter or invalid object information size or object type.
ERROR_INVALID_HANDLE | Bad or missing session handle.
ERROR_INVALID_MEDIA_POOL | Media pool specified either does not exist, or is not a valid Import or Application pool.
ERROR_INVALID_MEDIA | An entry already exists for a medium with this barcode.
ERROR_MEDIA_INCOMPATIBLE | Number of specified sides does not match the number of sides associated with the media pool's media type.
ERROR_NOT_ENOUGH_MEMORY | Memory allocation failure during processing.
ERROR_ACCESS_DENIED | NTMS_USE_ACCESS to the media pool or the offline library is denied; other security errors are also possible but indicate a security subsystem error.
ERROR_DATABASE_FAILURE | Database inaccessible or damaged.
ERROR_DATABASE_FULL | Database is full.
ERROR_DUPLICATE_OMID | The option NTMS_ERROR_ON_DUPLICATE was provided and a medium already exists with this OMID.

Remarks

The lpPhysicalMedia parameter must point to an NTMS_OBJECTINFORMATION structure, whose dwType parameter is of the value NTMS_PHYSICAL_MEDIA, with the following information, included is a list of members and descriptions for the NTMS_OBJECTINFORMATION structure.

Member Description
dwSize [In]

CreateNtmsMedia verifies that the provided size matches the expected length of an NTMS_OBJECTINFORMATION structure containing NTMS_PMIDINFORMATION. It returns ERROR_INVALID_PARAMETER if the size is incorrect.
dwType [In]

CreateNtmsMedia verifies that the value NTMS_PHYSICAL_MEDIA was provided. It returns ERROR_INVALID_PARAMETER if the provided type is incorrect.
Created [Out]

Indicates time the physical media object was entered into the NTMS database.
Modified [Out]

Indicates time the physical media object was entered into the NTMS database.
ObjectGuid [In/Out]

This field is the unique identifier for the physical media object (PMID). If a non-NULL value is provided, the value is used as the GUID of the Physical Medium, otherwise a GUID is generated.
Enabled [In]

ndicates whether or not the physical medium should be enabled.

dwOperationalState [Out]

Always NTMS_READY.
szName [In/Out]

CreateNtmsMedia contains functionality to allow an application to specify the name of a new physical medium. This enables the application to carry the name of a medium forward when moving it from one RSM computer to another. The RSM default naming selection is: for single sided: Barcode, then Label Info value or Sequence Number;. for multi-sided media Barcode then Sequence Number.

Note that the name that appears in the RSM user interface for a partition is this name (the name assigned to the physical media object).
szDescription [In]

The description is an optional parameter that may be set using CreateNtmsMedia. Provide the empty string ("\0") to avoid passing in a value for the description.

The following is a list of members and descriptions for the NTMS_PMIDINFORMATION structure.

Member | Description
CurrentLibrary | [In] Must be either the NULL_GUID, or the GUID of the Offline library. CreateNtmsMedia function returns an error if any other GUID is provided.
MediaPool | [In] Must be the GUID of a valid Import or Application pool. CreateNtmsMedia verifies that this is the GUID of a valid Import or Application Pool. It also verifies that the number of partitions provided are correct for the media type associated with this media pool.
Location | [Out] This field will be set to the NULL_GUID.
LocationType | [Out] Always NTMS_STORAGESLOT, as are all media in the offline library.
HomeSlot | Output parameter. Always the NULL_GUID.
MediaType | [Out] CreateNtmsMedia sets the media type to the media type associated with the media pool provided.
szBarCode | [In/Out] The barcode is stripped of any ending spaces. CreateNtmsMedia does not perform any additional attempts at verifying the validity of the barcode.
BarCodeState | [Out] The BarCodeState is set to NTMS_BARCODESTATE_UNREADABLE if the value passed in for szBarCode is an empty string, otherwise it is set to NTMS_BARCODESTATE_OK.
szSequenceNumber | [Out] CreateNtmsMedia assigns the newly-created medium a sequence number, which is returned in this field.
MediaState | [Out] CreateNtmsMedia sets the MediaState to NTMS_MEDIASTATE_IDLE.
dwNumberOfPartitions | [In] dwNumberOfPartitions defines the number of NTMS_OBJECTINFORMATION structures representing sides for this medium. CreateNtmsMedia checks to ensure that the number of sides specified matches the number of sides implied by the media pool to which it is to be assigned. If they do not match, ERROR_MEDIA_INCOMPATIBLE is returned.
dwMediaTypeCode | [In] The dwMediaTypeCode member is the SCSI media type code. This field is not used by RSM, but may be used by applications written to RSM for additional information about the media. For a description of what this field should be set to, see the Hardware Manufacturer's SCSI spec for possible settings. RSM updates this field when it mounts the newly-imported medium for the first time.
dwDensityCode | [In] The dwDensityCode member is the SCSI density code. This field is not used by RSM, but may be used by applications written to RSM for additional information about the media. For a description of what this field should be set to, see the Hardware Manufacturer's SCSI spec for possible settings. RSM updates this field when it mounts the newly-imported medium for the first time

Specifying the Partition Information

The lpPartitions parameter must point to an NTMS_OBJECTINFORMATION structure whose dwType is NTMS_PARTITION with the following information.

Member | Description
dwSize | [In] CreateNtmsMedia verifies that the provided size matches the expected length of an NTMS_OBJECTINFORMATION structure containing NTMS_PARTITIONINFORMATION. It returns ERROR_INVALID_PARAMETER if the size is incorrect.
dwType | [In] CreateNtmsMedia verifies that the value NTMS_PARTITIONwas provided. It returns ERROR_INVALID_PARAMETER if the provided type is incorrect.
Created | [Out] Indicates the time that the partition object was entered into the RSM database.
Modified | [Out] Indicates the time that the partition object was entered into the RSM database.
ObjectGuid | [In/Out] This field is the unique identifier for the side. If a non-NULL value is provided, the value is used as the GUID of the side; otherwise, a GUID is generated.
Enabled | [In] Determines whether or not the side should be enabled.
dwOperationalState | [Out] Always NTMS_READY.
szName | CreateNtmsMedia allows an application to specify the name of a new side.
szDescription | [In] The description is an optional parameter that may be set using CreateNtmsMedia. Provide the empty string ("\0") to avoid passing in a value for the description.
PhysicalMedia | [Out] CreateNtmsMedia sets this field to the GUID of the newly-created side object.
LogicalMedia | [In/Out] LogicalMedia is an optional input parameter, as well as an output parameter. If the LogicalMedia GUID is provided, CreateNtmsMedia attempts to create a new logical media object with the preassigned GUID. If the GUID is not unique, CreateNtmsMedia returns an error.
State | [In] Any valid side state is acceptable.
Side | [Out] CreateNtmsMedia sets the side number to its offset in the Partitions array.
dwOmidLabelIdLength | [In] Must be a positive value. CreateNtmsMedia uses the dwOmidIdLabelIdLength to determine the number of significant bytes in the OmidLabelId member. If the value is not correct, the recorded OmidLabelId is incorrect.
OmidLabelId | [In] This must represent a valid media label that can be recognized by an installed MLL.
szOmidLabelType | [In] Must not be an empty string.
szOmidLabelInfo | [In] May be the empty string.
dwMountCount | [In] Any value is accepted.
dwAllocateCount | [In] Any value is accepted.
Capacity | [In] The Capacity field is the SCSI capacity code. This field is not used by RSM, but may be used by applications written to RSM for additional information about the media. For a description of what this field should be set to, see the Hardware Manufacturer's SCSI spec for possible settings. RSM updates this field when it mounts the newly-imported medium for the first time.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.


CleanNtmsDrive

The CleanNtmsDrive function queues a cleaning request for the specified drive for cleaning.

DWORD WINAPI CleanNtmsDrive(
  HANDLE hSession,
  LPNTMS_GUID lpDriveId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpDriveId
Specifies the unique identifier of the drive to be cleaned.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DEVICE_NOT AVAILABLE | The drive or the library is not enabled.
ERROR_INVALID_DRIVE | The drive ID is invalid.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_LIBRARY | The library for the drive is invalid.
ERROR_INVALID_PARAMETER | The drive ID is missing.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The cleaning was queued successfully.

Remarks

If the drive you selected in the CleanNtmsDrive function is a stand-alone drive, the drive is marked as cleaned and the time is noted in the RSM Database.

Queued cleaning requests are deleted when the service is restarted.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Cleaner Management Functions, EjectNtmsCleaner, InjectNtmsCleaner, ReleaseNtmsCleanerSlot, ReserveNtmsCleanerSlot


CloseNtmsNotification

The CloseNtmsNotification function closes the specified open notification channel.

DWORD WINAPI CloseNtmsNotification(
  HANDLE hNotification
);

Parameters

hNotification
Notification handle generated by the OpenNtmsNotification function.

Return Values

Value | Meaning
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid or NULL.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_SUCCESS | The function was successful.

Remarks

If the CloseNtmsNotification function is called while there is an outstanding call to the WaitForNtmsNotification function, an error returns.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Database Notification Functions, OpenNtmsNotification, WaitForNtmsNotification


CloseNtmsSession

The CloseNtmsSession function closes the specified RSM session.

DWORD WINAPI CloseNtmsSession(
  HANDLE hSession
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.

Return Values

Value | Meaning
ERROR_CONNECTION_UNAVAIL | Connection to the RSM server or domain is not available.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid or NULL.

Remarks

The CloseNtmsSession function releases all resources. Use of a closed session handle returns an error code.

If a call to the CloseNtmsSession function occurs while an application has an outstanding synchronous request (for example, a mount or dismount request), the request is unwound and canceled.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Session Management Functions, OpenNtmsSession


CreateNtmsMediaPool

The CreateNtmsMediaPool function creates a new application media pool.

DWORD WINAPI CreateNtmsMediaPool(
  HANDLE hSession,
  LPCTSTR lpPoolName,
  LPNTMS_GUID lpMediaType,
  DWORD dwAction,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  LPNTMS_GUID lpPoolId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpPoolName
Specifies the name of the new media pool. Media pool names must be unique within the scope of a single RSM database.
lpMediaType
Specifies the type of media in this media pool. Use the EnumerateNtmsObject function to get a list of available media types and their attributes. The application can pass a NULL pointer to create a media pool that only contains other media pools.
dwAction
This parameter must be one of the following values.
Value | Meaning
NTMS_OPEN_EXISTING | Opens an exisiting media pool by name. Returns ERROR_OBJECT_NOT_FOUND if the pool does not exist.
NTMS_OPEN_ALWAYS | Opens an existing media pool or creates the pool if it does not exist.
NTMS_CREATE_NEW | Creates a new media pool. Returns ERROR_ALREADY_EXISTS if the pool exists.

lpSecurityAttributes
Optional. Specifies the security descriptor used to restrict access to the pool.
lpPoolId
Pointer to the unique identifier where the media pool ID is returned after the media pool is successfully created or opened.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to the parent media pool is denied while trying to create a new media pool.
ERROR_ALREADY_EXISTS | Unable to create a new media pool because one already exists with this name.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA | The selected media type is not valid.
ERROR_INVALID_NAME | The pool name syntax is invalid. (The name is too long.)
ERROR_INVALID_PARAMETER | The media pool name or media pool ID pointer is missing.
ERROR_OBJECT_NOT_FOUND | Unable to open existing media pool.
ERROR_SUCCESS | The function was successful.

Remarks

Free, Unrecognized, and Import media pools are created by RSM and cannot be created with the CreateNtmsMediaPool function.

RSM media pools are organized as a hierarchy separated by the "\" character. Application, Free, Unrecognized, and Import media pools exist at the root of the hierarchy. RSM creates and manages the Free, Unrecognized, and Import pools. RSM creates a Free media pool for each media type available.

Application-specific media pools are created by applications. Applications create media pools for their own use under the root application pool. These media pools have file system-like names. Only the end-point of the name contains media and policy. An application can define pools such as \MyApp\Pool1 and \MyApp\Pool2. This conveys the hierarchy to the user interface and avoids duplicate names. Each pool level must be created individually; first MyApp and then Pool1 and Pool2, much like folders and files.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, AllocateNtmsMedia , DeleteNtmsMediaPool, GetNtmsObjectSecurity, SetNtmsObjectSecurity


DeallocateNtmsMedia

The DeallocateNtmsMedia function deallocates the side associated with the specified logical media.

DWORD WINAPI DeallocateNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId,
  DWORD dwOptions
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies the unique identifier of logical media.
dwOptions
Reserved; must be zero.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to media's media pool is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA | The LMID is invalid.
ERROR_INVALID_PARAMETER | The media or media pool ID is missing.
ERROR_INVALID_PARTITION | The LMID side is invalid.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

When a logical medium is deallocated with the DeallocateNtmsMedia function, RSM puts the side associated with the logical media in the Available or Decommissioned media state. The logical media is deleted from the system when the logical media is deallocated.

Sides are decommissioned upon deallocation if the side has been allocated the maximum number of times specified in the media pool. After media is in the Decommissioned state, it cannot be allocated again.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, AllocateNtmsMedia


DecommissionNtmsMedia

The DecommissionNtmsMedia function moves a side from the Available state to the Decommissioned state.

DWORD WINAPI DecommissionNtmsMedia(
   HANDLE hSession,
  LPNTMS_GUID lpMedia
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMedia
Specifies the unique identifier of a side of a piece of physical media.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to either media's media pool is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA | The media identifier is invalid.
ERROR_INVALID_MEDIA_POOL | The media pool for media is invalid.
ERROR_INVALID_PARAMETER | The media identifier is missing.
ERROR_INVALID_STATE | The media is not in the Available state.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

Media decommissioned by the DecommissionNtmsMedia function is recognized by RSM but the decommissioned media does not contain any data and is never again used.

Only media that is in the Available state can be decommissioned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, AllocateNtmsMedia


DeleteNtmsDrive

The DeleteNtmsDrive function deletes a drive from the RSM database. The drive must have a dwOperationalState of NTMS_NOT_PRESENT.

DWORD WINAPI DeleteNtmsDrive(
  HANDLE hSession,
  LPNTMS_GUID lpDriveId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpDriveId
Specifies the unique identifier of a drive.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_DRIVE | The drive identifier is invalid.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_LIBRARY | The drive library identifier is invalid.
ERROR_INVALID_PARAMETER | The media identifier is missing.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

You can use this function to remove drives that are no longer connected to the RSM server.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions


DeleteNtmsLibrary

The DeleteNtmsLibrary function deletes a library, and all the devices contained in the library, from the RSM database. All media in the library is moved to the offline library.

DWORD WINAPI DeleteNtmsLibrary(
  HANDLE hSession,
  LPNTMS_GUID lpLibraryId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibraryId
Specifies the unique identifier of a library.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | There is an invalid or missing session handle.
ERROR_INVALID_LIBRARY | There is an invalid library identifier.
ERROR_INVALID_PARAMETER | There is a missing media identifier.
ERROR_NOT_ENOUGH_MEMORY | There was an allocation failure during processing.
ERROR_SUCCESS | The function was successful.

Remarks

If the library referenced by the DeleteNtmsLibrary function contains media, the media is moved to the offline library.

You can use DeleteNtmsLibrary to remove libraries that are no longer connected to the RSM server.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions


DeleteNtmsRequests

The DeleteNtmsRequests function deletes a request or a list of requests from the RSM database. Library or operator requests that are in a completed, failed, refused, or canceled state are removed. Submitted requests, queued requests, waiting requests, and in progress requests cannot be deleted.

DWORD WINAPI DeleteNtmsRequests(
  HANDLE hSession,
  LPNTMS_GUID lpRequestId,
  DWORD dwType,
  DWORD dwCount
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpRequestId
List of NTMS_LIBREQUEST or NTMS_OPREQUEST identifiers to delete.
dwType
Either NTMS_LIBREQUESTINFORMATION or NTMS_OPREQUESTINFORMATION.
dwCount
Number of requests in the list.

Return Values

Value | Meaning
ERROR_SUCCESS | The function executed successfully.
ERROR_INVALID_PARAMETER | Invalid type identifier.
ERROR_INVALID_HANDLE | Bad or missing session handle.
ERROR_NOT_ENOUGH_MEMORY | Memory allocation failure during processing.
ERROR_DATABASE_FAILURE | Database is inaccessible or damaged.
ERROR_DATABASE_FULL | Database is full.
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to the library is denied. Other security errors may have occurred, but these other security errors indicate a security subsystem error.

Remarks

An error is not returned if a request or list of requests is not found.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.


DeleteNtmsMedia

The DeleteNtmsMedia function deletes a physical piece of offline media from RSM by removing all references to the specified media from the database.

DWORD WINAPI DeleteNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies the unique identifier of a piece of physical media.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to either media's media pool is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA | The media identifier is invalid.
ERROR_INVALID_MEDIA_POOL | The media pool for the media is invalid.
ERROR_INVALID_PARAMETER | The media identifier is missing.
ERROR_INVALID_STATE | The media is not offline.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

Media specified by the DeleteNtmsMedia function must be located in an offline library and not have a side in the Allocated, Completed, or Reserved states.

You can use DeleteNtmsMedia to remove lost or destroyed media.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions


DeleteNtmsMediaPool

The DeleteNtmsMediaPool function deletes the specified application media pool.

DWORD WINAPI DeleteNtmsMediaPool(
  HANDLE hSession,
  LPNTMS_GUID lpPoolId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpPoolId
Specifies the unique identifier of the media pool.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the media pool is denied. Other security errors are also possible, but they indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA_POOL | Unable to open existing media pool, or attempting to delete free, import, or unrecognized media pools.
ERROR_INVALID_PARAMETER | The media pool ID is missing.
ERROR_NOT_EMPTY | The media pool must be empty to be deleted.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

Only empty media pools can be deleted with the DeleteNtmsMediaPool function.

Free, unrecognized, and import media pools are managed by RSM and cannot be deleted with DeleteNtmsMediaPool.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, CreateNtmsMediaPool, MoveToNtmsMediaPool


DeleteNtmsMediaType

The DeleteNtmsMediaType function deletes the specified media type relation from the specified library provided that the library does not contain any physical media objects of the specified media type.

DWORD DeleteNtmsMediaType(
  HANDLE hSession,
  LPNTMS_GUID lpMediaTypeId,
  LPNTMS_GUID lpLibId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaTypeId
Specifies the unique identifier of a media type to delete from a library.
lpLibId
Specifies the unique identifier of the library from which to delete the media type.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to media's media pool is denied.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is bad or missing.
ERROR_INVALID_LIBRARY | The library ID is invalid.
ERROR_INVALID_PARAMETER | The media type or library ID is missing.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

If there are no physical media objects of the specified media type in the RSM system and there are no library objects that contain the specified media type relation in the RSM system, the system media pools for that media type will be deleted. Inability to delete the system media pools does not cause the DeleteNtmsMediaType function to fail.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, AddNtmsMediaType


DisableNtmsObject

The DisableNtmsObject function disables the specified RSM object.

DWORD WINAPI DisableNtmsObject(
  HANDLE hSession,
  DWORD dwType,
  LPNTMS_GUID lpObjectId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
dwType
Specifies the RSM object type. This parameter can be one of the following values.
Value | Meaning
NTMS_DRIVE | An RSM drive.
NTMS_LIBRARY | An RSM library unit.
NTMS_PHYSICAL_MEDIA | A physical media object (a tape, optical disk, CD, or magnetic cartridge).

lpObjectId
Specifies the unique identifier of the RSM object.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library containing the object is denied.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_PARAMETER | An object ID is missing or the object type is invalid. (The object type is invalid if it is not NTMS_LIBRARY, NTMS_DRIVE, or NTMS_PHYSICAL_MEDIA.)
ERROR_INVALID_STATE | The object is already disabled.
ERROR_LIBRARY_OFFLINE | The library ID refers to an off-line library that cannot be enabled or disabled.
ERROR_OBJECT_NOT_FOUND | The object is not valid.
ERROR_SUCCESS | The disable is queued.

Remarks

The DisableNtmsObject function queues a disable command for the specified object. The function returns successfully when the command is queued. If RSM is busy, the command can take some time to complete. When the medium is disabled, RSM renders all of the media's sides and associated logical media unavailable. All requests to disabled media return errors.

To remove a drive or media changer from service the drive or media changer must first be disabled.

All objects contained by a disabled object are also disabled. For example, disabling a piece of physical media disables all sides. Whenever possible, when a drive is disabled, the medium in the drive is removed and placed in its slot.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, EnableNtmsObject


DismountNtmsDrive

The DismountNtmsDrive function queues a command to move the media in the specified drive to its storage slot. This function should be paired with the MountNtmsMedia function.

DWORD WINAPI DismountNtmsDrive(
  HANDLE hSession,
  LPNTMS_GUID lpDriveId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpDriveId
Specifies the unique identifier of a drive object.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DEVICE_NOT_AVAILABLE | The drive or library is not enabled.
ERROR_INVALID_DRIVE | There is an invalid drive ID.
ERROR_INVALID_HANDLE | There is an invalid or missing session handle.
ERROR_INVALID_LIBRARY | There is an invalid library for the drive.
ERROR_INVALID_PARAMETER | There is a missing drive ID.
ERROR_INVALID_STATE | The drive does not contain media.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

If the drive specified by the DismountNtmsDrive function is empty or if the media is opened, an error is returned. Otherwise, the media is returned to its slot.

Dismount requests to stand alone drives place the drive in the dismountable state and return success.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions


DismountNtmsMedia

The DismountNtmsMedia function queues a command to move the specified media in a drive to its storage. This function should be paired with the MountNtmsMedia function.

DWORD WINAPI DismountNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId,
  DWORD dwCount,
  DWORD dwOptions
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies an array of at least one logical medium or side.
dwCount
Specifies the number of media identifiers in the lpMediaId parameter.
dwOptions
This parameter can be the following value.
Value | Meaning
NTMS_DISMOUNT_DEFERRED | Marks media state as Dismountable, and keeps the medium in the drive. Subsequent mount requests are satisfied using dismounted or dismountable drives. The default is to dismount immediately.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_USE_ACCESS to the media pool or library that contains the media is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DEVICE_NOT_AVAILABLE | One or more resources required to perform the dismount are not currently available (probably disabled).
ERROR_INVALID_LIBRARY | The library that contains the media is not valid.
ERROR_INVALID_MEDIA | At least one of the specified media is not valid.
ERROR_INVALID_STATE | An unexpected media or device state occurred during dismount.
ERROR_MEDIA_OFFLINE | The specified media is offline.
ERROR_MEDIA_NOT_AVAILABLE | One or more media resources required to perform the mount are not currently available (probably disabled).
ERROR_NOT_ENOUGH_MEMORY | A memory allocation failure occurred during processing.
ERROR_SUCCESS | The media dismount has been queued.
ERROR_TIMEOUT | The time-out event expired while the application attempted to acquire one or more resources.

Remarks

An application must use the DismountNtmsMedia function to release the drive resource after the application has used the specified medium. Unreleased media cannot be used by other RSM sessions.

The DismountNtmsMedia function returns as soon as the operation is queued with RSM. The application can wait for the side state to become idle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, MountNtmsMedia


EjectNtmsCleaner

The EjectNtmsCleaner function ejects the cleaning cartridge from the currently reserved cleaner slot.

DWORD WINAPI EjectNtmsCleaner(
  HANDLE hSession,
  LPNTMS_GUID lpLibrary,
  LPNTMS_GUID lpEjectOperation,
  DWORD dwAction
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibrary
Specifies the unique identifier of a library object.
lpEjectOperation
Specifies the GUID of the eject process. This value is returned for use with a Stop action code.
dwAction
Specifies the action to take. This parameter can be either one of the following values.
Value | Meaning
NTMS_EJECT_START | Starts the eject operation with a port. The specified medium is ejected until the time-out event occurs or the EjectNtmsCleaner function is called again with the NTMS_EJECT_STOP flag set for this parameter. The time-out value is specified in the library object and is applied to all ejections in the library.
NTMS_EJECT_STOP | For libraries with NTMS_IEPORTobjects only. Terminates the ejection process prior to the time-out event lapsing.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to one or more RSM objects is denied.
ERROR_INVALID_HANDLE | The value supplied in the hSession parameter is invalid.
ERROR_INVALID_LIBRARY | Unable to retrieve the library definition from the database.
ERROR_NO_SLOT_SET | This library does not have a cleaner slot reserved.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_SLOT_EMPTY | A cleaner slot is reserved but is already empty.
ERROR_SLOT_NOT_PRESENT | A cleaner slot is reserved but the slot is currently not installed in the library. This error occurs when at least one magazine is missing from the library.
ERROR_SUCCESS | The function was successful.

Remarks

If the library specified in the EjectNtmsCleaner function has an NTMS_IEPORT object, RSM uses the NTMS_IEPORT object to eject the cleaner. If there is no NTMS_IEPORT object, the NTMS_IEDOOR object is used to allow the operator to gain access to the cleaner slot.

Ejected cleaner cartridges are not tracked in the offline library.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Cleaner Management Functions, CleanNtmsDrive, InjectNtmsCleaner, ReleaseNtmsCleanerSlot, ReserveNtmsCleanerSlot


EjectNtmsMedia

The EjectNtmsMedia function ejects the specified medium from the port of the current library. If the library is busy, RSM queues EjectNtmsMedia and returns success.

DWORD WINAPI EjectNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId,
  LPNTMS_GUID lpEjectOperation,
  DWORD dwAction
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies the unique identifier of a piece of physical media (PMID).
lpEjectOperation
Specifies the GUID of the eject process. This must be used with the dwAction parameter set to the NTMS_EJECT_STOP flag.
dwAction
This parameter can be one of the following values.
Value | Meaning
NTMS_EJECT_START | Start the eject operation with a port. The specified medium is ejected until the time-out event occurs or until NTMS_EJECT_STOP is issued. The time-out value is specified in the library object and is applied to all ejects in the library.
NTMS_EJECT_STOP | Terminate the ejection process before the time-out event lapses.
NTMS_EJECT_QUEUE | Queue the specified media for ejection. Used to group media for multi-slot NTMS_IEPORT objects.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_BUSY | More media was queued than slots available in the NTMS_IEPORT object.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DEVICE_NOT_AVAILABLE | The library is disabled.
ERROR_INVALID_HANDLE | The session ID is invalid or missing.
ERROR_INVALID_OPERATION | A stop was performed on an invalid operation ID.
ERROR_INVALID_PARAMETER | A library ID or operation ID pointer is missing.
ERROR_LIBRARY_OFFLINE | The library ID refers to an offline library that cannot eject media.
ERROR_MEDIA_NOT_AVAILABLE | The media is disabled.
ERROR_NOT_ENOUGH_MEMORY | There was an allocation failure during processing.
ERROR_SUCCESS | The eject is queued.

Remarks

Media ejected using the EjectNtmsMedia function is moved to the offline library or deleted from the database. Cleaner cartridges, import media, unrecognized media, and incompatible media are deleted when ejected.

If the NTMS_EJECT_STOP flag is specified for dwAction, the EjectNtmsMedia function stops the eject operation specified by the lpEjectOperation parameter. The lpEjectOperation GUID is returned when the NTMS_EJECT_START flag is used.

The NTMS_EJECT_QUEUE flag is used to bundle or batch media marked for ejection into a multi-slot library. You can queue media for ejection using the queue action when the application has queued all the necessary media. The application uses the start command to begin the physical eject operation. If more media is queued than slots in the NTMS_IEPORT object, EjectNtmsMedia returns ERROR_BUSY. To begin the physical eject operation, the application can use the START action on the last media or use a NULL media ID with the Start Operation

The QUEUE action does not return a GUID that can be used for the STOP action. However, when the queued requests are started with the START action, a GUID returns that can be used to cancel the entire operation with the STOP action.

If the media is currently in use (mounted or opened), this function returns an error.

If the library does not have a port, use the AccessNtmsLibraryDoor function to insert and eject media.

Eject works only with online libraries.

The EjectNtmsMedia function returns to the application as soon as the eject request is queued.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions, InjectNtmsMedia


EnableNtmsObject

The EnableNtmsObject function enables the specified object.

DWORD WINAPI EnableNtmsObject(
  HANDLE hSession,
  DWORD dwType,
  LPNTMS_GUID lpObjectId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
dwType
Specifies the RSM object type. This parameter can be one of the following values.
Value | Meaning
NTMS_DRIVE | An RSM drive.
NTMS_LIBRARY | An RSM library unit.
NTMS_PHYSICAL_MEDIA | A physical media object (a tape, optical disk, CD, or magnetic disk cartridge).

lpObjectId
The unique identifier of the RSM object.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library containing the object is denied.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_PARAMETER | The object ID is missing or the object type is invalid. (The object type is invalid if it is not NTMS_LIBRARY, NTMS_DRIVE, or NTMS_PHYSICAL_MEDIA.)
ERROR_INVALID_STATE | The object is already enabled.
ERROR_LIBRARY_OFFLINE | The library ID refers to an off-line library that cannot be enabled or disabled.
ERROR_OBJECT_NOT_FOUND | The object is not valid.
ERROR_SUCCESS | The enable is queued.

Remarks

The EnableNtmsObject function queues a disable command with RSM. If RSM is busy, the command can take some time to complete.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, DisableNtmsObject


EnumerateNtmsObject

The EnumerateNtmsObject function enumerates the RSM objects contained in the lpContainerId parameter.

DWORD WINAPI EnumerateNtmsObject(
  HANDLE hSession,
  LPNTMS_GUID lpContainerId,
  LPNTMS_GUID lpList,
  LPDWORD lpdwListSize,
  DWORD dwType,
  DWORD dwOptions
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpContainerId
Specifies the unique identifier of the RSM object container. The type of object identified depends on the type of object being requested. Can be set to Library, Media Pool, Partition ID, Physical Media, Logical Media, or NULL. Set this parameter to NULL to enumerate all objects of the type specified by the dwType parameter.
lpList
Buffer for the array of libraries, drives, media or other RSM object iDs.
lpdwListSize
Pointer to a DWORD that specifies the maximum number of iDs the function can return through the lpList parameter. At return time, the number of iDs in lpList is returned in lpdwListSize.
dwType
Specifies the type of objects that you are enumerating in the container. This parameter can be one of the following values.
Value | Meaning
NTMS_CHANGER | Lists changers contained in the library specified by the lpContainerId parameter or all the changers supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_DRIVE | Lists drives contained in a specific library specified by the lpContainerId parameter or all the drives supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_CHANGER_TYPE | Lists changer types supported by RSM. The lpContainerId parameter must be NULL.
NTMS_COMPUTER | Specifies the current computer object. The lpContainerId parameter must be NULL.
NTMS_DRIVE_TYPE | Lists drive types supported by RSM. The lpContainerId parameter must be NULL.
NTMS_IEDOOR | Lists access doors contained in a library specified by the lpContainerId parameter or all the doors supported by RSM if a NULL container ID is specified. Available when lpContainerID is set to NULL or Library.
NTMS_IEPORT | Lists insert/eject ports contained in a library specified by the lpContainerId parameter or all the insert/eject ports supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_LIBRARY | Lists the library objects. These include the physical library units and the offline library. The lpContainerId parameter must be NULL.
NTMS_LIBREQUEST | Lists library active requests (or work items) queued to the library specified by the lpContainerId parameter or all the library work items queued within RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.
NTMS_LOGICAL_MEDIA | Specifies a logical media object. This is a medium allocated to an application that might contain more than one side or piece of physical media. Available when lpContainerID is set to NULL, Media Pool, or Partition ID.
NTMS_MEDIA_POOL | Specifies a media pool object that contains logical and/or physical media, and configuration parameters to manage them. If NULL is specified as a container ID, only the top-level names are returned. Available when lpContainerID is set to NULL or Media Pool.
NTMS_MEDIA_TYPE | Specifies a media type object that contains the attributes of a type of medium that is supported by RSM. Enumerating with a NULL will give all possible media types, not just those available on the current server. Available when lpContainerID is set to NULL or Library.
NTMS_OPREQUEST | Lists operator requests that are on this RSM server. The lpContainerId parameter must be NULL.
NTMS_PARTITION | Specifies a side on a piece of physical media. The piece of physical media can contain multiple physical sides (for example, an optical disk contains two sides). Available when lpContainerID is set to NULL, Physical Media, Logical Media, or Media Pool.
NTMS_PHYSICAL_MEDIA Specifies a piece of physical media (a tape, optical disk, CD-ROM, or magnetic cartridge). A piece of physical media can contain multiple physical sides (for example, sides of an optical disk).

The container ID contains NULL to get all the physical media, a media pool, logical media, or a library. Available when lpContainerID is set to NULL, Media Pool, or Library
NTMS_STORAGESLOT | Lists media slots contained in a library specified by the lpContainerId parameter or all the storage slots supported by RSM if a NULL container ID is supplied. Available when lpContainerID is set to NULL or Library.

dwOptions
Option flags. Reserved and must be set to 0.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | The lpdwListSize pointer is missing, or lpContainerId is an invalid container for the object type specified by dwType.
ERROR_INSUFFICIENT_BUFFER | The buffer size specified by lpdwListSize is too small for all the objects found. The function truncates the list and returns the actual size in lpdwListSize.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_OBJECT_NOT_FOUND | The GUID specified by lpContainerId is not the GUID of any container object in the database.
ERROR_SUCCESS | The function was successful. If lpContainerId contains no objects of the type specified by dwType, the function returns ERROR_SUCCESS and a lpdwListSize of 0.

Remarks

Security functions are also available to get and set specific access rights on RSM objects.

If the available number of iDs specified in the lpdwListSize parameter is greater than the current buffer size, lpdwListSize returns the number of iDs required. The application should then allocate a larger buffer and try again.

Since it is possible for iDs to be added by another process, it is possible for a subsequent function with a resized list to get an error indicating that the list is too small.

If the lpContainerId parameter is set to NULL, RSM enumerates top-level objects (such as libraries).

If more than one object is listed, the object may be enumerated from more than one container. The NULL container is the highest-level container and enumerates all objects in a system. For example, you can enumerate media in a particular library or all media in the system.

The following table lists the database relationships among RSM objects. The NULL container represents the RSM system and enumerates top-level objects.

Container object (lpContainerId) | Object
Library | Changer
 | Door
 | Drive
 | Library request
 | Media type
 | Physical media
 | Port
 | Slot
Logical media | Side
Media pool | Logical media
 | Media pool
 | Physical media
NULL | Changer
 | Changer type
 | Door
 | Drive
 | Drive type
 | Library
 | Library request
 | Logical media
 | Media pools (free, unrecognized, import and application root)
 | Media type
 | Operator request
 | Port
 | Physical media
 | Side
Physical Media | Side

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, CreateNtmsMediaPool, GetNtmsObjectInformation, SetNtmsObjectInformation


ExportNtmsDatabase

The ExportNtmsDatabase function creates a consistent set of database files in the RSM database directory. The default location of the database is%SystemRoot%\System32\NtmsData, but this can be set by defining a registry value:

HKLM\System\CurrentControlSet\Control\NTMS\NtmsData

This function creates a subdirectory called Export and places the consistent files there.

DWORD WINAPI ExportNtmsDatabase(
  HANDLE hSession
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to one or more RSM objects is denied.
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_SUCCESS | The function was successful.

Remarks

The ExportNtmsDatabase function is used by backup applications to create a copy of the RSM database. Any existing files in the Export directory are overwritten by this function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Database Backup and Recovery Functions, ImportNtmsDatabase


GetNtmsMediaPoolName

The GetNtmsMediaPoolName function returns the specified media pool's full name hierarchy into the output buffer.

DWORD WINAPI GetNtmsMediaPoolName(
  HANDLE hSession,
  LPNTMS_GUID lpPoolId,
  LPTSTR lpBufName,
  LPDWORD lpdwBufSize
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpPoolId
Specifies the GUID of the media pool to retrieve the name.
lpBufName
Specifies the name of the output buffer.
lpdwBufSize
Specifies the size of the name data buffer on input. Returns the number of characters (string length) of the full name.

Return Values

Value | Meaning
ERROR_INSUFFICIENT_BUFFER | The buffer size is not large enough. The correct size is returned in lpdwBufSize.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is NULL or invalid.
ERROR_INVALID_MEDIA_POOL | The media pool ID is missing or invalid.
ERROR_INVALID_PARAMETER | The parameter is missing or invalid.
ERROR_NOT_ENOUGH_MEMORY | The memory allocation failed.
ERROR_SUCCESS | The function was successful.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, CreateNtmsMediaPool


GetNtmsObjectAttribute

The GetNtmsObjectAttribute function gets private data from the specified RSM object.

DWORD WINAPI GetNtmsObjectAttribute(
  HANDLE hSession,
  LPNTMS_GUID lpObjectId,
  DWORD dwType,
  LPCTSTR lpAttributeName,
  LPVOID lpAttributeData,
  LPDWORD lpAttributeSize
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpObjectId
Specifies the GUID of the object from which to retrieve the attribute.
dwType
Specifies the RSM object type. See EnumerateNtmsObject for object types.
lpAttributeName
Specifies the name for the extended attribute to get from the RSM objects.
lpAttributeData
Pointer to the buffer in which the attribute is returned.
lpAttributeSize
Specifies the size of the attribute data buffer on input and returns the actual size of the attribute data on return.

Return Values

Value | Meaning
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INSUFFICIENT_BUFFER | The buffer size is not correctly specified. The correct size is returned in the lpAttributeSize parameter.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is NULL or invalid.
ERROR_INVALID_PARAMETER | The pointer is NULL or invalid.
ERROR_NO_DATA | The attribute specified is greater than or equal to NTMS_MAXATTR_LENGTH.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_OBJECT_NOT_FOUND | The specified attribute was not found.
ERROR_SUCCESS | The function was successful.

Remarks

The GetNtmsObjectAttribute function must be executed on the RSM server. Because the buffer of bytes is unmarshaled between systems of different architectures, remote execution of this function may result in unpredictable results.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, EnumerateNtmsObject, SetNtmsObjectAttribute


GetNtmsObjectInformation

The GetNtmsObjectInformation function returns an object's information structure for the specified object.

DWORD WINAPI GetNtmsObjectInformation(
  HANDLE hSession,
  LPNTMS_GUID lpObjectId,
  LPNTMS_OBJECTINFORMATION lpInfo
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpObjectId
Specifies a unique identifier of the RSM object.
lpInfo
Pointer to the NTMS_OBJECTINFORMATION structure.

Return values

Value | Meaning
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_PARAMETER | The object ID or information structure is missing, or the object information size or object type is invalid.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_OBJECT_NOT_FOUND | The object ID is invalid.
ERROR_SUCCESS | The function was successful.

Remarks

The information size and type of the information structure must be set correctly in the lpInfo parameter before you use the GetNtmsObjectInformation function.

To avoid unpredictable results, applications must call the GetNtmsObjectInformation function before calling the SetNtmsObjectInformation function. The SetNtmsObjectInformation function updates all writable members of the NTMS_OBJECTINFORMATION structure, therefore the application is responsible for providing a value for all writable members.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, GetNtmsObjectSecurity, NTMS_OBJECTINFORMATION, SetNtmsObjectInformation


GetNtmsObjectSecurity

The GetNtmsObjectSecurity function reads the security descriptor for the specified RSM object.

DWORD WINAPI GetNtmsObjectSecurity(
  HANDLE hSession,
  LPNTMS_GUID lpObjectId,
  DWORD dwType,
  SECURITY_INFORMATION RequestedInformation,
  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  DWORD nLength,
  LPDWORD lpnLengthNeeded
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpObjectId
Specifies the unique identifier of the RSM object.
dwType
Specifies the object type. (See the EnumerateNtmsObject function for object types.)
RequestedInformation
Specifies the Windows 2000 security data.
pSecurityDescriptor
Specifies the Windows 2000 security descriptor.
nLength
Specifies the length of the descriptor.
lpnLengthNeeded
Specifies the required length if the supplied buffer is not large enough for the security descriptor.

Return Values

Value | Meaning
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_PARAMETER | The object ID is missing.
ERROR_NO_SECURITY_ON_OBJECT | There is no security information for this object.
ERROR_OBJECT_NOT_FOUND | The object ID is invalid.
ERROR_SUCCESS | The function was successful.

Remarks

RSM security uses the same security descriptors and information members that Windows 2000 security uses. This allows the standard security dialog boxes to be used to select RSM security.

For more information on Windows 2000 security, see the SetPrivateObjectSecurity function and the security section in the Platform SDK. For more information on RSM security, see RSM Security.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, EnumerateNtmsObject, SetNtmsObjectSecurity


GetNtmsRequestOrder

The GetNtmsRequestOrder function gets the order that the specified request will be processed in the library queue.

DWORD WINAPI GetNtmsRequestOrder(
  HANDLE hSession,
  LPNTMS_GUID lpRequestId,
  LPDWORD lpdwOrderNumber
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpRequestId
Specifies the unique identifier of a library request.
lpdwOrderNumber
Specifies the order in which this request will be processed in the queue.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_INVALID_HANDLE | The request ID is invalid or missing.
ERROR_INVALID_PARAMETER | The library ID or operation ID pointer is missing.
ERROR_SUCCESS | The insert is queued.

Remarks

If the GetNtmsRequestOrder function returns zero, ordering is not available for this request. The order number is specific to the type of request because the types are processed in a predetermined order.

For example, the NTMS_LM_DISMOUNT request is processed prior to an NTMS_LM_MOUNT request. Within a specific class of requests the queue can be ordered, however. The lower-ordered requests are processed first, for example, 1 is the first request processed, 2 is the next request processed, and so forth.

You can use this order number, the request type, the submission time, and the submission date to help view the queue in sorted order. Request type, order number, and submission time should perform sorting.

Currently on NTMS_LM_MOUNT, requests are sorted using the order number.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions, SetNtmsRequestOrder


ImportNtmsDatabase

The ImportNtmsDatabase function causes RSM to import the database files from the database Export directory at the next restart of the RSM.

DWORD WINAPI ImportNtmsDatabase(
  HANDLE hSession
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to at least one RSM object is denied.
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid.
ERROR_NOT_CONNECTED | Unable to connect to the RSM.
ERROR_SUCCESS | The function was successful.

Remarks

The ImportNtmsDatabase function is used by backup applications during disaster recovery.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Database Backup and Recovery Functions, ExportNtmsDatabase


InjectNtmsCleaner

The InjectNtmsCleaner function allows a cleaner cartridge to be inserted into the specified online library unit.

DWORD WINAPI InjectNtmsCleaner(
  HANDLE hSession,
  LPNTMS_GUID lpLibrary,
  LPNTMS_GUID lpInjectOperation,
  WORD dwNumberOfCleansLeft,
  DWORD dwAction
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibrary
Specifies the unique identifier of a library object.
lpInjectOperation
Specifies the GUID of the insert process. This is returned for use of with Stop action code.
dwNumberOfCleansLeft
Represents the number of cleaning cycles left on the inserted cleaning cartridge
dwAction
This parameter can be one of the following values.
Value | Meaning
NTMS_INJECT_START | Start the insertion with either the NTMS_IEPORT or the NTMS_IEDOOR object. A single cleaner cartridge should be inserted. If the NTMS_IEDOOR object is used, no inventory will be performed on the library.
NTMS_INJECT_STOP | For libraries with PORTs only: Terminates the insertion prior to the time-out event lapsing.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to at least one RSM object is denied.
ERROR_DEVICE_NOT_AVAILABLE | The library is not currently connected.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid.
ERROR_INVALID_LIBRARY | Unable to retrieve the library definition from the database.
ERROR_LIBRARY_OFFLINE | The library must be online for a cleaner cartridge to be inserted.
ERROR_NO_SLOT_SET | This library has no slot reserved as a cleaner slot.
ERROR_SLOT_FULL | A cleaner slot is reserved but already has a cleaner cartridge. The cleaner cartridge must be ejected first, using the EjectNtmsCleaner function.
ERROR_SLOT_NOT_PRESENT | A cleaner slot is reserved but the slot specified is currently not installed in the library. This error occurs if at least one magazine is missing from the library.
ERROR_SUCCESS | The function was successful.

Remarks

To use the InjectNtmsCleaner function, the number of cleaning cycles that remain on the cleaner cartridge must be specified so that RSM can keep track of it.

If an NTMS_IEPORT object is available, the NTMS_IEPORT object directs the cartridge to the currently reserved cleaner slot.

If there is no NTMS_IEPORT object, a door access is performed. In this case, the operator is directed to place the media into the reserved slot.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Cleaner Management Functions, CleanNtmsDrive, EjectNtmsCleaner, ReleaseNtmsCleanerSlot, ReserveNtmsCleanerSlot


InjectNtmsMedia

The InjectNtmsMedia function allows media to be inserted into the port of the specified online library. If the library is busy, RSM queues InjectNtmsMedia and returns success.

DWORD WINAPI InjectNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpLibraryId,
  LPNTMS_GUID lpInjectOperation,
  DWORD dwAction
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibraryId
Specifies the unique identifier of a library object.
lpInjectOperation
Specifies the GUID of the insert Libraryworkitem. This is returned for use with the Stop action code.
dwAction
This parameter can be one of the following values.
Value | Meaning
NTMS_INJECT_START | Start the insert operation with a port. Media is repeatedly inserted until the time-out event occurs or the NTMS_INJECT_STOP flag is issued.
NTMS_INJECT_STOP | Terminate the insertion process prior to the time-out event lapsing.
NTMS_INJECT_RETRACT | Direct the library to retract the IE-Port and check for media placed there by the operator.
NTMS_INJECT_START_MANY | Direct the IE-Port to open continually and check for media placed there by the operator. If a medium is found, the IE-Port is reopened to receive more media.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DEVICE_NOT_AVAILABLE | The library is disabled.
ERROR_INVALID_HANDLE | The session ID is invalid or missing.
ERROR_INVALID_OPERATION | There was a Stop action performed on an invalid operation ID.
ERROR_INVALID_PARAMETER | The library ID or operation ID pointer is missing.
ERROR_LIBRARY_OFFLINE | The library ID refers to an offline library that cannot eject media.
ERROR_NOT_ENOUGH_MEMORY | There was an allocation failure during processing.
ERROR_SUCCESS | The insert is queued.

Remarks

If the library specified by the InjectNtmsMedia function does not have a port, use the AccessNtmsLibraryDoor function to insert and eject media.

This function is valid only for online libraries.

This function returns to the application as soon as the insert request is queued.

Insert begins the process of inserting media into an online library. Because libraries vary on the functionality of the NTMS_IEPORT object, each device may operate slightly differently. The following steps describe how RSM generally handles an inject:

To insert media into a library

  1. Allow/unlock/extend the NTMS_IEPORT.
  2. Poll for a full NTMS_IEPORT, a retracted NTMS_IEPORT, a Stop Inject command, or a time-out value. If none of these have occurred, continue to wait. (Multi-cartridge IEports are not scanned for full status.)
  3. When one of the preceding events occurs, the NTMS_IEPORT is locked, each medium in the NTMS_IEPORT is moved to a slot, and an identify medium command is queued for each medium.

If there are not enough slots for the media in the NTMS_IEPORT object, the media remains in the NTMS_IEPORT object and an Operator Request is posted to have media removed from the library.

If there are no free slots, the InjectNtmsMedia function receives an error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions, EjectNtmsMedia


InventoryNtmsLibrary

The InventoryNtmsLibrary function queues an inventory of the specified online library. If the library is busy, RSM queues InventoryNtmsLibrary and returns success.

DWORD WINAPI InventoryNtmsLibrary(
  HANDLE hSession,
  LPNTMS_GUID lpLibraryId,
  DWORD dwAction
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibraryId
Specifies the unique identifier of an online library object.
dwAction
This parameter can be one of the following values.
Value | Meaning
NTMS_INVENTORY_OMID | A full on-media inventory is performed. Each side of each medium must be mounted into a drive. This is a time consuming process.
NTMS_INVENTORY_FAST | If the library has a bar-code reader installed, this flag causes a bar-code inventory to be performed. If the library does not have a bar-code reader, this flag causes a differential inventory to be performed (slots are classified).
NTMS_INVENTORY_DEFAULT | Use the InventoryMethod specified in the library object.
NTMS_INVENTORY_STOP | Stop the current inventory in the specified library.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to one or more RSM objects is denied.
ERROR_DEVICE_NOT_AVAILABLE | The library is not currently connected.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid.
ERROR_INVALID_LIBRARY | The library specified is not an online library.
ERROR_INVALID_PARAMETER | The library ID or session ID is invalid.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_SUCCESS | The function was successful.

Remarks

Not present libraries cannot be inventoried.

The InventoryNtmsLibrary function marks all the slots that currently contain a medium in the library for classification/identification. The InventoryNtmsLibrary function returns when all the media is marked.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions, AccessNtmsLibraryDoor


MountNtmsMedia

The MountNtmsMedia function synchronously mounts one or more pieces of media.

DWORD WINAPI MountNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId,
  LPNTMS_GUID lpDriveId,
  DWORD dwCount,
  DWORD dwOptions,
  DWORD dwPriority,
  DWORD dwTimeout,
  LPNTMS_MOUNT_INFORMATION lpMountInformation
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies an array of unique identifiers of logical media or sides.
lpDriveId
Specifies an array of drive identifiers that corresponds to the list of media in the IpMediaId parameter. This array either supplies a list of drives to mount media into or returns the list of drives that media is mounted into on operation completion. See the NTMS_MOUNT_SPECIFIC_DRIVE value below. If the MountNtmsMedia function times out prior to the completion of the mount, RSM does not return the list of drives.
dwCount
Specifies the number of media identifiers and drive identifiers passed in the lpMediaId and lpDriveId parameters. Note that lpMediaId and lpDriveId must point to the first element of equal-length arrays.
dwOptions
This parameter can be one or more of the following values.
Value | Meaning
NTMS_MOUNT_SPECIFIC_DRIVE | Mount the media into the specific drives provided in the lpDriveId parameter.
NTMS_MOUNT_READ | Mount the media for read access. Use this value to mount read-only media.
NTMS_MOUNT_WRITE Mount the media for write access. Use this flag to prevent RSM from mounting Completed media. This value can be combined with NTMS_MOUNT_READ for read/write access.

RSM cannot mount Completed media if this flag is selected.
NTMS_MOUNT_ERROR_NOT_AVAILABLE | This value returns an error if the media or a drive is not available.
NTMS_MOUNT_ERROR_OFFLINE | Do not issue an operator request to mount offline media. Return an error if the media specified is not currently in an online library.

dwPriority
Specifies the priority of the mount used by RSM to allow access to drives. Priorities range from -15 to 15, with 15 the highest priority and 0 is the default. This parameter can also take one of the following constants. An application should pass NTMS_PRIORITY_NORMAL unless a special mount priority is required.
Value | Meaning
NTMS_PRIORITY_NORMAL | Mounts that are not time critical.
NTMS_PRIORITY_LOW | Mounts performed as a background activity.
NTMS_PRIORITY_HIGH | Mounts that are time critical.
NTMS_PRIORITY_LOWEST | Lowest priority mount.
NTMS_PRIORITY_HIGHEST | Highest priority mount.

dwTimeout
Specifies the maximum time, in milliseconds, allowed to mount the specified media. Set this parameter to INFINITE to wait as long as the mount takes.
lpMountInformation
This is a reserved argument and should be passed as a NULL pointer.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_USE_ACCESS to the media pool or library that contains the media is denied; other security errors are also possible but they would indicate a security subsystem error.
ERROR_BUSY | The media or drives are busy.
ERROR_CANCELED | The request was canceled by the CloseNtmsSession function.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_DRIVE_MEDIA_MISMATCH | The media and drive specified are not in the same library.
ERROR_INVALID_DRIVE | At least one of the specified drives is not valid.
ERROR_INVALID_LIBRARY | The library that contains the drives or media is not valid.
ERROR_INVALID_MEDIA | One or more of the media specified is not valid, or there are duplicate media IDs in list of media.
ERROR_INVALID_STATE | An unexpected media or device state occurred during mount.
ERROR_MEDIA_OFFLINE | The media is offline and cannot be mounted.
ERROR_NOT_ENOUGH_MEMORY | A memory allocation failure occurred during processing.
ERROR_REQUEST_REFUSED | The user canceled the request through the user interface.
ERROR_RESOURCE_DISABLED | One or more resources required to perform the mount are disabled.
ERROR_SUCCESS | The media has been mounted and is ready for use.
ERROR_TIMEOUT | The time-out event expired while attempting to acquire one or more required resources. The mount request has been canceled.
ERROR_WRITE_PROTECT | The media state is set to Completed and the NTMS_MOUNT_WRITE value was specified.

Remarks

The MountNtmsMedia function queues a request to mount the specified media, then waits for the number of milliseconds specified in the dwTimeout parameter for the mount to complete or for an error to be detected. If RSM cannot complete the mount operation before dwTimeout expires, NTMS cancels the request and returns an error. If the specified media is in an offline library, the application might be blocked for an extended period of time. You can use the GetNtmsObjectInformation function to determine the current location of the specified medium. You can also use the NTMS_MOUNT_ERROR_OFFLINE value to generate an immediate error instead of an operator request when the media is offline.

If the specified medium is in use or a drive is not available, the process blocks up to the time-out value and returns ERROR_BUSY. If the NTMS_MOUNT_ERROR_NOT_AVAILABLE value is specified, the function returns an immediate error when a resource (media or drive) is not available.

The time-out value of INFINITE can be used to make the function wait without timing out. When a non-zero time-out value is specified in the dwTimeout parameter, RSM waits for all the media specified in lpMediaId to become mounted. If the specified time elapses before all the media is mounted, the MountNtmsMedia function returns an error and cancels the request. The application can examine the status returned and resubmit the request if desired.

When multiple media to be mounted are specified with a single call, all the specified media must be in a single library. If any of the specified media are offline, none of the media will be mounted until all the media are online.

At the completion of the mount the drive state (for example, fix or variable mode) is not defined. The application must set up the drive.

The CloseNtmsSession function can be used to cancel a mount that is pending. The default behavior is:

If the specified medium is offline, RSM posts an operator request to mount the media and the MountNtmsMedia function waits for the period of time specified in the dwTimeout parameter.

If the specified medium is online, RSM requests the mount.

If a drive or media is not available, RSM sends the request and the MountNtmsMedia function waits for the period of time specified in the dwTimeout parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions


MoveToNtmsMediaPool

The MoveToNtmsMediaPool function moves the specified medium from its current media pool to the specified media pool.

DWORD WINAPI MoveToNtmsMediaPool(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId,
  LPNTMS_GUID lpPoolId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies the unique identifier of a piece of physical media.
lpPoolId
Specifies the unique identifier of the destination media pool.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to source media's media pool or the destination media pool is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_BUSY | At least one side of the media is in use or currently unavailable.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA_POOL | The destination media pool is invalid. The media pool is nonexistent. The media in the unrecognized or import pool may only be moved to the free pool.
ERROR_INVALID_MEDIA | The source media or implied source media pool is invalid.
ERROR_INVALID_PARAMETER | The media ID or media pool ID is missing.
ERROR_MEDIA_INCOMPATIBLE | The source media type differs from the destination media pool's media type.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

The destination pool specified in the MoveToNtmsMediaPool function must be of the same media type and have compatible security.

RSM writes an on-media identifier to media before moving the media into the free media pool.

A medium having a partition in the Completed, Allocated, or Reserved state may not be moved to the "Free" media pool. A medium may be moved to an Import pool only if all the partitions of the medium are in the "Import" state.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, AllocateNtmsMedia, CreateNtmsMediaPool


OpenNtmsNotification

The OpenNtmsNotification function opens a channel to receive RSM object change notifications for objects of the specified type.

HANDLE WINAPI OpenNtmsNotification(
  HANDLE hSession,
  DWORD dwType
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
dwType
Specifies the RSM object type for notification.

Return Values

Value | Meaning
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid or NULL.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_SUCCESS | The function was successful.
INVALID_HANDLE_VALUE | The function failed.

Remarks

The OpenNtmsNotification function returns a notification handle that you pass to the WaitForNtmsNotification or CloseNtmsNotification functions.

For extended error information, call the Win32 GetLastError function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Database Notification Functions, CloseNtmsNotification, WaitForNtmsNotification


OpenNtmsSession

The OpenNtmsSession function sets up a session with a RSM server.

HANDLE WINAPI OpenNtmsSession(
  LPCTSTR lpServer,
  LPCTSTR lpApplication,
  DWORD dwOptions
);

Parameters

lpServer
Specifies a character string that points to the RSM server name. If this parameter is NULL, the current computer is used.
lpApplication
Specifies a unique character string that identifies the application. This name identifies resources and operator requests. This parameter is optional and may be Null.
dwOptions
Reserved. The application should pass 0.

Return Values

Value | Meaning
ERROR_INVALID_COMPUTERNAME | An invalid computer name format was supplied.
ERROR_INVALID_PARAMETER | Invalid parameters were supplied.
ERROR_NO_NETWORK | The network is not started or not available.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_NOT_READY | RSM service has not started. The application should wait and retry.
ERROR_SUCCESS | The function was successful.
INVALID_HANDLE_VALUE | RSM cannot open a session.
RPC_S_NO_INTERFACES | The service is using an older version of RSM than your application.

Remarks

The OpenNtmsSession function returns a session handle used with other RSM functions, establishes a connection with the RSM database, and initializes the RSM subsystem for the application.

The OpenNtmsSession function returns a handle that uniquely identifies this session, or it returns INVALID_HANDLE_VALUE if RSM cannot open a session. Other RSM functions use this session handle to perform operations.

If INVALID_HANDLE_VALUE returns, you can call the Win32 GetLastError function to retrieve the error code.

When OpenNtmsSession returns, the application can perform RSM operations.

Sessions are thread-safe but cannot be passed among processes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Session Management Functions, CloseNtmsSession


ReleaseNtmsCleanerSlot

The ReleaseNtmsCleanerSlot function removes an existing slot reservation for a cleaning cartridge. The slot can then be used for data cartridges.

DWORD WINAPI ReleaseNtmsCleanerSlot(
  HANDLE hSession,
  LPNTMS_GUID lpLibrary
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibrary
Specifies the unique identifier of the library to set the cleaner slot.

Return Values

Value | Meaning
ERROR_ DEVICE_NOT_AVAILABLE | The library is not currently connected.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_NO_SLOT_RESERVED | This library has no slot reserved for a cleaner cartridge.
ERROR_SLOT_FULL | The library has a reserved cleaner cartridge slot but the slot contains a cleaner cartridge (the slot must be empty). Use the EjectNtmsCleaner function to eject a cleaner cartridge.
ERROR_SLOT_NOT_PRESENT | The library has a reserved cleaner cartridge slot, but the specified slot is currently not installed in the library. This error can occur if at least one magazine is missing from the library.
ERROR_SUCCESS | The function was queued successfully.

Remarks

For the ReleaseNtmsCleanerSlot function to succeed, the slot must be present and empty. The library must also have a slot reserved for cleaning.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Cleaner Management Functions, CleanNtmsDrive, EjectNtmsCleaner, InjectNtmsCleaner, ReserveNtmsCleanerSlot


ReserveNtmsCleanerSlot

The ReserveNtmsCleanerSlot function reserves a single slot in an online library unit for a drive cleaner cartridge.

DWORD WINAPI ReserveNtmsCleanerSlot(
  HANDLE hSession,
  LPNTMS_GUID lpLibrary,
  LPNTMS_GUID lpSlot
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpLibrary
Specifies the unique identifier of the library to set the cleaner slot.
lpSlot
Specifies the unique identifier of the slot that is to be reserved for a cleaner cartridge.

Return Values

Value | Meaning
ERROR_ALREADY_RESERVED | Either this slot or another slot in the library has already been reserved for cleaning. To change the cleaner cartridge slot, the currently reserved cleaner slot must be released first, using the ReleaseNtmsCleanerSlot function.
ERROR_ DEVICE_NOT_AVAILABLE | The library is not currently connected.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid.
ERROR_INVALID_SLOT | Unable to retrieve the slot definition from the database.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_SLOT_FULL | A cleaner slot is not reserved. The slot specified has media in it. Reservation can only be performed on an empty slot.
ERROR_SLOT_NOT_PRESENT | A cleaner slot is not reserved. The slot specified is currently not installed in the library. This error occurs if at least one cartridge magazine is missing from the library.
ERROR_SUCCESS | The function was queued successfully.

Remarks

The slot reserved with the ReserveNtmsCleanerSlot function must be present and empty. The library must not already have a slot reserved for a cleaner cartridge.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Cleaner Management Functions, CleanNtmsDrive, EjectNtmsCleaner, InjectNtmsCleaner, ReleaseNtmsCleanerSlot


SatisfyNtmsOperatorRequest

The SatisfyNtmsOperatorRequest function completes the specified RSM operator request.

DWORD WINAPI SatisfyNtmsOperatorRequest(
  HANDLE hSession,
  LPNTMS_GUID lpRequestId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpRequestId
The operator request object ID.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | The user that tried to execute this function does not have administrator privileges. Only an administrator of the RSM server can satisfy operator requests.
ERROR_OBJECT_NOT_FOUND | The operator request object ID was not found. This error occurs if the request is completed before the operation has been satisfied or when an invalid request ID is supplied.
ERROR_SUCCESS | The operator request has been satisfied.

Remarks

If an application detects that the operator did not acknowledge a satisfied operator request, the application can use the SatisfyNtmsOperatorRequest function to remove the request.

For a list of the existing operator requests to cancel with the SatisfyNtmsOperatorRequest function, see the EnumerateNtmsObject function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Operator Request Functions, CancelNtmsOperatorRequest, SubmitNtmsOperatorRequest, WaitforNtmsOperatorRequest


SetNtmsMediaComplete

The SetNtmsMediaComplete function marks a piece of logical media as complete.

DWORD WINAPI SetNtmsMediaComplete(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies the unique identifier of a piece of logical media.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to either media's media pool is denied Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA | The media identifier is invalid.
ERROR_INVALID_MEDIA_POOL | The media pool for the media is invalid.
ERROR_INVALID_PARAMETER | The media identifier is missing.
ERROR_INVALID_STATE | The media is not in the allocated state or is currently mounted.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

The SetNtmsMediaComplete function marks the specified medium as Complete. An application marks the medium as Complete when the application is no longer going to write to the medium. Complete media cannot be mounted with the NTMS_MOUNT_WRITE flag.

The SetNtmsMediaComplete function is typically used when an application reaches the end of media. Media that is mounted or in use cannot be marked as complete.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, MountNtmsMedia


SetNtmsObjectAttribute

The SetNtmsObjectAttribute function creates private data in the specified RSM object.

DWORD WINAPI SetNtmsObjectAttribute(
  HANDLE hSession,
  LPNTMS_GUID lpObjectId,
  DWORD dwType,
  LPCTSTR lpAttributeName,
  LPVOID lpAttributeData,
  DWORD dwAttributeSize
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpObjectId
Specifies the GUID of the object for which to set the attribute.
dwType
Specifies the RSM object type. See EnumerateNtmsObject for object types.
lpAttributeName
Specifies the name that the extended attribute writes to one of the RSM objects.
lpAttributeData
Specifies the data to save as the RSM object attribute.
dwAttributeSize
Specifies the size of the attribute data.

Return Values

Value | Meaning
ERROR_DATABASE_FAILURE | The database update failed.
ERROR_INSUFFICIENT_BUFFER | The buffer size is not correctly specified. The correct size is returned in the lpAttributeSize parameter.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is NULL or invalid.
ERROR_INVALID_NAME | The name or attribute is invalid. The NTMS_MAXATTR_NAMELEN value defines the maximum attribute name length. The length includes a NULL.
ERROR_INVALID_PARAMETER | The pointer is NULL or invalid.
ERROR_NO_DATA | The attribute specified is greater than or equal to NTMS_MAXATTR_LENGTH.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_OBJECT_NOT_FOUND | The GUID is invalid.
ERROR_SUCCESS | The function was successful.

Remarks

The SetNtmsObjectAttribute function must be executed on the specified RSM server. Because the buffer of bytes is unmarshaled between systems of different architectures, remote execution of this function can result in unpredictable results.

To delete an attribute, perform a set of the attribute with a length of zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, EnumerateNtmsObject, GetNtmsObjectAttribute


SetNtmsObjectInformation

The SetNtmsObjectInformation function changes the information structure of the specified object.

DWORD WINAPI SetNtmsObjectInformation(
  HANDLE hSession,
  LPNTMS_GUID lpObjectId,
  LPNTMS_OBJECTINFORMATION lpInfo
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpObjectId
Specifies the unique identifier of the RSM object.
lpInfo
Pointer to the NTMS_OBJECTINFORMATION structure.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED NTMS_MODIFY_ACCESS or NTMS_CONTROL_ACCESS is denied to the object being written or no modifications are allowed to the object type specified. Access required is as follows:
NTMS_MEDIA_POOL
NTMS_CONTROL_ACCESS to the media pool.
NTMS_LOGICAL_MEDIA
NTMS_MODIFY_ACCESS to the media pool of the logical media.
NTMS_LIBRARY
NTMS_CONTROL_ACCESS to the library.
NTMS_CHANGER
No write fields.
NTMS_DRIVE
No write fields.
NTMS_CHANGER_TYPE
No write fields.
NTMS_DRIVE_TYPE
No write fields.
NTMS_STORAGESLOT
No write fields.
NTMS_IEDOOR
No write fields.
NTMS_IEPORT
No write fields.
NTMS_PHYSICAL_MEDIA
No write fields.
NTMS_PARTITION
NTMS_MODIFY_ACCESS to the media pool of the side.
NTMS_MEDIA_TYPE
No write fields.
NTMS_OPREQUEST
No write fields.
NTMS_LIBREQUEST
No write fields.
ERROR_SUCCESS | The function was successful.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_PARAMETER | The object ID or information structure is missing, or the object information size or object type is invalid.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_OBJECT_NOT_FOUND | The object ID is invalid.

Remarks

Not all information in an object can be set using the SetNtmsObjectInformation function. For writable fields, see object definitions.

The information size and type must be set before you can use SetNtmsObjectInformation.

All writable properties for the object are read from the NTMS_OBJECTINFORMATION structure and written to the database without regard for any write operations that have occurred between the time this application called the GetNtmsObjectInformation function and the SetNtmsObjectInformation function. Because of this you can lose changes.

To avoid unpredictable results, applications must call GetNtmsObjectInformation before calling SetNtmsObjectInformation. As noted above, SetNtmsObjectInformation updates all writable fields, therefore the application is responsible for providing a value for all writable fields.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, GetNtmsObjectInformation, GetNtmsObjectSecurity, NTMS_OBJECTINFORMATION


SetNtmsObjectSecurity

The SetNtmsObjectSecurity function writes the security descriptor for the specified RSM object.

DWORD WINAPI SetNtmsObjectSecurity(
  HANDLE hSession,
  LPNTMS_GUID lpObjectId,
  DWORD dwType,
  SECURITY_INFORMATION lpSecurityInformation,
  PSECURITY_DESCRIPTOR lpSecurityDescriptor
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpObjectId
Specifies the unique identifier of the RSM object.
dwType
Specifies the RSM object type. See the EnumerateNtmsObject function for object types.
lpSecurityInformation
Specifies the security information to write to the RSM object.
lpSecurityDescriptor
Specifies the security descriptor to write to the RSM object: NTMS_USE_ACCESS, NTMS_CONTROL_ACCESS, or NTMS_MODIFY_ACCESS.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | The privileges required to modify the security descriptor are denied.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_PARAMETER | The object ID is missing.
ERROR_NO_SECURITY_ON_OBJECT | There is no security information for this object.
ERROR_OBJECT_NOT_FOUND | The object ID is invalid.
ERROR_SUCCESS | The function was successful.

Remarks

If an application uses the SetNtmsObjectSecurity function to set the owner of an object, the application must have WRITE_OWNER permission or be the owner of the object.

If an application uses SetNtmsObjectSecurity to set the discretionary access-control list (ACL) of an object, the application must have WRITE_DAC permission or be the owner of the object.

If an application uses SetNtmsObjectSecurity to set the system ACL of an object, the SE_SECURITY_NAME privilege must be enabled for the application.

For more information on Windows 2000 security, see the SetPrivateObjectSecurity function and the security section in the Platform SDK. For more information on RSM security, see RSM Security.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Object Management Functions, EnumerateNtmsObject, GetNtmsObjectSecurity


SetNtmsRequestOrder

The SetNtmsRequestOrder function sets the order that the specified request will be processed in the library queue.

DWORD WINAPI SetNtmsRequestOrder(
  HANDLE hSession,
  LPNTMS_GUID lpRequestId,
  DWORD dwOrderNumber
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpRequestId
Specifies the unique identifier of a library request.
dwOrderNumber
Specifies the order that the request will be processed in the queue.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_INVALID_HANDLE | The request ID is invalid or missing.
ERROR_INVALID_PARAMETER | The library ID or operation ID pointer is missing.
ERROR_SUCCESS | An insert is queued.

Remarks

Currently NTMS_LM_MOUNT requests are sorted using the order number.

The order number set by the SetNtmsRequestOrder function is specific to the type of request because the types are processed in a predetermined order. For example, an NTMS_LM_DISMOUNT request is processed prior to an NTMS_LM_MOUNT request. Within a specific class of requests the queue can be ordered, however. The lower ordered requests are processed first; for example, 1 is the first request processed, 2 is the next request processed, and so forth.

To process a request immediately, an application can set the order number to 1. To defer processing, an application should set the order number to a very large number or 0xFFFFFFFF. The order number of a request, which currently has an order number of 0, cannot be changed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Library Control Functions, GetNtmsRequestOrder


SubmitNtmsOperatorRequest

The SubmitNtmsOperatorRequest function submits an RSM operator request.

DWORD WINAPI SubmitNtmsOperatorRequest(
  HANDLE hSession,
  DWORD dwRequest,
  LPCTSTR lpMessage,
  LPNTMS_GUID lpArg1Id,
  LPNTMS_GUID lpArg2Id,
  LPNTMS_GUID lpRequestId
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
dwRequest
Specifies the type of operator request. This parameter can be one of the following values.
Value | Meaning
NTMS_OPREQ_CLEANER | RSM sends an operator request to insert a cleaner when a clean operation is queued and no cleaner is available to the drive.
NTMS_OPREQ_DEVICESERVICE | An application or RSM sends an operator request for drive service when a changer device or drive is experiencing problems. The lpArg1Id parameter specifies the device that needs service.
NTMS_OPREQ_MESSAGE | Application message only.
NTMS_OPREQ_MOVEMEDIA | An application or RSM sends an operator request to move media from one library to another for a mount of offline media or to eject existing media to the offline library. The lpArg1Id parameter specifies the piece of physical media that must be moved and the lpArg2Id parameter specifies the target library.
NTMS_OPREQ_NEWMEDIA | An application or RSM sends an operator request for new media when no media is available. The lpArg1Id parameter specifies the media pool object and the lpArg2Id parameter is the optional library identifier to which to add the new medium.

lpMessage
Specifies an optional message string sent to the user.
lpArg1Id
Specifies an object identifier for the operator request. Refer to the descriptions of the values in the dwRequest parameter for a description of what type of object must be passed for this argument.
lpArg2Id
Specifies an object identifier for the operator request. Refer to the descriptions of the values in the dwRequest parameter for details on what type of object must be passed for this argument.
lpRequestId
Pointer to an NTMS_GUID to receive the identifier of the operator request that was created.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to one or more RSM objects is denied.
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is NULL or invalid.
ERROR_INVALID_PARAMETER | Invalid parameters were passed to the function.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_OBJECT_NOT_FOUND | Unable to find the source or destination object.
ERROR_SUCCESS | The function was successful.

Remarks

The SubmitNtmsOperatorRequest function submits an operator request and returns the status of the request (Satisfied or Cancelled) or times out (if the operator does not act upon the request). Operator requests are used to request media, to request that the specified medium be moved from one library to another, or to request RSM device service.

The NTMS_OPEREQ_MESSAGE value (in the dwRequest parameter) is the request type most often used by applications. RSM cannot use NTMS_OPEREQ_MESSAGE. RSM uses the other request types as needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Operator Request Functions, AllocateNtmsMedia, MountNtmsMedia, CancelNtmsOperatorRequest, SatisfyNtmsOperatorRequest, WaitForNtmsOperatorRequest


SwapNtmsMedia

The SwapNtmsMedia function swaps the sides associated with the two specified LMIDs. The specified LMID's must be in the same media pool.

DWORD WINAPI SwapNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId1,
  LPNTMS_GUID lpMediaId2
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId1
Specifies the unique identifier of a piece of logical media.
lpMediaId2
Specifies the unique identifier of a piece of logical media.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | NTMS_MODIFY_ACCESS to either media's media pool is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_BAD_FORMAT | No media label library recognizes the media label.
ERROR_DATABASE_FAILURE | The database is inaccessible or damaged.
ERROR_DATABASE_FULL | The database is full.
ERROR_INVALID_HANDLE | The session handle is invalid or missing.
ERROR_INVALID_MEDIA | At least one of the media IDs is invalid.
ERROR_INVALID_MEDIA_POOL | One or more media pools for the logical media are invalid.
ERROR_INVALID_PARAMETER | At least one media identifier is missing.
ERROR_NOT_ENOUGH_MEMORY | An allocation failure occurred during processing.
ERROR_SUCCESS | The function was successful.

Remarks

The SwapNtmsMedia function is used to update physical media without affecting the application.

The media for both LMIDs must not be in use for this function to succeed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Media Services Functions, AllocateNtmsMedia


UpdateNtmsOmidInfo

The UpdateNtmsOmidInfo function updates the RSM database with label information immediately after writing to the newly allocated medium.

DWORD WINAPI UpdateNtmsOmidInfo(
  HANDLE hSession,
  LPNTMS_GUID lpMediaId,
  DWORD labelType,
  DWORD numberOfBytes,
  LPVOID lpBuffer
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpMediaId
Specifies the unique identifier of a piece of logical media.
labelType
Specifies whether the label is a string contained in lpBuffer, or is a FILESTSYSTEM_INFO structure contained in lpBuffer. This parameter can be set to one of the following values.
Value | Meaning
NTMS_OMID_TYPE_FILESYSTEM_INFO | The lpBuffer argument contains the FILESYSTEM_INFO structure. This flag is used for media that contain file systems.
NTMS_OMID_TYPE_RAW_LABEL | The lpbufer argument contains the raw bytes of the application label. This flag is used for media that contain application written labels.

numberOfBytes
Specifies the number of bytes sent in the lpBuffer parameter.
lpBuffer
Contains the actual label information, either raw bytes or a FILESYSTEM_INFO structure, depending on the setting of the labelType argument.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to one or more RSM objects is denied.
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is invalid.
ERROR_INVALID_MEDIA | Unable to retrieve the logical media definition from the database.
ERROR_INVALID_PARTITION | Unable to retrieve the side definition from the database.
ERROR_INVALID_PARAMETER | The lpMediaId parameter is NULL.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_SUCCESS | The function was successful.

Remarks

The application updates RSM with the information supplied by the UpdateNtmsOmidInfo function and RSM verifies the information in the database. The label information is stored in the RSM database with the side associated with this LMID.

The UpdateNtmsOmidInfo function must be executed on the RSM server. Remote execution of this function results in an error.

For tape media lpBuffer must point to a buffer that holds the label just written on the tape. The data in this buffer is passed directly to the ClaimMediaLabel entry point of each MLL. One of the installed MLLs must recognize a valid label in this data.

For media with file systems, lpBuffer must be a pointer to a buffer that contains the following structure:

typedef struct
  {
    WCHAR   FileSystemType[64];
    WCHAR   VolumeName[256];
    DWORD   SerialNumber;
} FILESYSTEM_INFO;

RSM uses this file system info as the OMID. The Windows 2000 format utilities (LDM, explorer, format.com, etc.) effectively performs the same functionality as this call. An application that performs its own formatting or formats with a third-party file system type should only need to call UpdateNtmsOmidInfo for file system media.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

On-Media-Identifier Management Functions


WaitForNtmsNotification

The WaitForNtmsNotification function waits for the next object change notification.

DWORD WINAPI WaitForNtmsNotification(
  HANDLE hNotification,
  LPNTMS_NOTIFICATIONINFORMATION lpNotificationInformation,
  DWORD dwTimeout
);

Parameters

hNotification
Notification handle generated by the OpenNtmsNotification function.
lpNotificationInformation
Specifies notification information. For more information, see the NTMS_NOTIFICATIONINFORMATION data structure.
dwTimeout
Specifies the maximum number of milliseconds to wait. If you specify a value of INFINITE, this function will not time-out.

Return Values

Value | Meaning
ERROR_DATABASE_FAILURE | The database query or update failed.
ERROR_INVALID_HANDLE | The value specified in the hNotification parameter is invalid or NULL.
ERROR_NO_DATA | Notification pipe failed. Attempt to set up notification again.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_TIMEOUT | The time-out event expired.
ERROR_SUCCESS | The function was successfully executed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Database Notification Functions, CloseNtmsNotification, OpenNtmsNotification


WaitForNtmsOperatorRequest

The WaitForNtmsOperatorRequest function waits for the specified RSM operator request.

DWORD WINAPI WaitForNtmsOperatorRequest(
  HANDLE hSession,
  LPNTMS_GUID lpRequestId,
  DWORD dwTimeout
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpRequestId
Specifies the operator request identifier created by the SubmitNtmsOperatorRequest function.
dwTimeout
Specifies the number of milliseconds to wait. To check for an operator request, pass a time-out value of zero. If you specify a value of INFINITE, this function does not time-out.

Return Values

Value | Meaning
ERROR_ACCESS_DENIED | Access to one or more RSM objects is denied.
ERROR_CANCELLED | The operator request was canceled by an administrator.
ERROR_INVALID_HANDLE | The value specified in the hSession parameter is NULL or invalid.
ERROR_INVALID_PARAMETER | Invalid parameters were passed to the function.
ERROR_NOT_CONNECTED | Unable to connect to the RSM service.
ERROR_OBJECT_NOT_FOUND | Unable to find the operator request object. Object requests are flushed from the database. Application should call a function like AllocateNtmsMedia if RSM returns this error.
ERROR_SUCCESS | The function was successful.
ERROR_TIMEOUT | The time specified in the dwTimeout parameter elapsed before the completion of the operator request.

Remarks

Operator requests specified with the WaitForNtmsOperatorRequest function are used to request media, to request that the medium be moved from one library to another, or to request RSM device service.

An application uses WaitForNtmsOperatorRequest to wait for resolution of an operator request. The request can be satisfied, rejected, deleted, or timed out.

Typically, applications use the SubmitNtmsOperatorRequest function to submit operator requests and use the WaitForNtmsOperatorRequest function to wait for their resolution.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

Operator Request Functions, CancelNtmsOperatorRequest, SatisfyNtmsOperatorRequest, SubmitNtmsOperatorRequest


BeginNtmsDeviceChangeDetection

The BeginNtmsDeviceChangeDetection function allows the application to begin a device change detection session. The application can then set the stand-alone libraries for which media change detection is required using the SetNtmsDeviceChangeDetection function. The Removable Storage Manager continues to detect changes for the devices specified until the change detection session is closed using the EndNtmsDeviceChangeDetection function.

DWORD WINAPI BeginNtmsDeviceChangeDetection(
  HANDLE hSession,
  LPHANDLE lpDetectHandle
);

Parameters

hSession
Handle to the session returned by the OpenNtmsSession function.
lpDetectHandle
Pointer to variable that receives the device change detection handle.

Return Values

Value | Meaning
ERROR_INVALID_HANDLE | Invalid session.
ERROR_SUCCESS | The operator request has been canceled.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

SetNtmsDeviceChangeDetection, EndNtmsDeviceChangeDetection


EndNtmsDeviceChangeDetection

The EndNtmsDeviceChangeDetection function ends device change detection for any target devices specified using the SetNtmsDeviceChangeDetection function and closes the change detection handle. Note that closing the Removable Storage Manager session also ends all device change detection sessions.

DWORD WINAPI EndNtmsDeviceChangeDetection(
  HANDLE hSession,
  HANDLE hDetectHandle
);

Parameters

hSession
The handle generated by the OpenNtmsSession function
hDetectHandle
Device change detection handle

Return Values

Value | Meaning
ERROR_INVALID_HANDLE | Invalid Session or Detection handle.
ERROR_SUCCESS | The operator request has been canceled.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

SetNtmsDeviceChangeDetection, BeginNtmsDeviceChangeDetection


SetNtmsDeviceChangeDetection

The SetNtmsDeviceChangeDetection function sets one or more target devices for change detection. The device can be specified directly by passing NTMS_LIBRARY object GUIDs or indirectly by passing NTMS_PHYSICAL_MEDIA or NTMS_MEDIA_TYPE GUIDs. When using the indirect specification, all stand-alone libraries that could contain the media or media type are detected. All devices specified continue to be detected until the DetectHandle is closed using EndNtmsDeviceChangeDetection. This function can also be used as a refresh by providing a NULL DetectHandle. In this case, RSM signals a single poll of all target devices provided by lpObjectId and thereby schedule classification of any changed media in those devices. This is typically used by a UI when opening a leaf node or implementing a Refresh option.

DWORD WINAPI SetNtmsDeviceChangeDetection(
  HANDLE hSession,
  HANDLE hDetectHandle,
  LPNTMS_GUID lpObjectId,
  DWORD dwType,
  DWORD dwCount
);

Parameters

hSession
The handle generated by the OpenNtmsSession function.
hDetectHandle
Device change detection handle or NULL for a single poll.
lpObjectId
One or more NTMS_LIBRARY, NTMS_PHYSICAL_MEDIA or NTMS_MEDIA_TYPE object identifiers used to specify the target devices for change detection. All of the identifiers must be the same type.
dwType
Type of object identifiers. Must be NTMS_LIBRARY, NTMS_PHYSICAL_MEDIA or NTMS_MEDIA_TYPE.
dwCount
Number of object identifiers.

Return Values

Value | Meaning
ERROR_INVALID_HANDLE | Invalid Session or Detection Handle.
ERROR_INVALID_PARAMETER | Invalid Object type.
ERROR_INVALID_LIBRARY | Specified Library not Found.
ERROR_INVALID_MEDIA | Specified Media or Type not found.
ERROR_SUCCESS | The operator request has been canceled.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.
Library: Use Ntmsapi.lib.

See Also

EndNtmsDeviceChangeDetection, BeginNtmsDeviceChangeDetection


RSM Security

RSM provides security for media pool and library objects. Media pool security controls access to media, including physical media, sides, and logical media. Library security controls access to physical library units, including drives, changers, slots, and insert/eject ports.

Applications can use the SetNtmsObjectSecurity and GetNtmsObjectSecurity functions to set and check security for an RSM object.

When you use nested media pools, the security of the lowest-level media pool determines the security of the media objects.

The following table lists RSM functions and the RSM security descriptors required to successfully perform each operation. This table uses the following key.

  • U = NTMS_USE_ACCESS
  • M = NTMS_MODIFY_ACCESS
  • C = NTMS_CONTROL_ACCESS
  • na = Contains no writable fields.
Function | Media Pool | Library | Computer
AddNtmsMediaType |  | C |
AccessNtmsLibraryDoor |  | C |
AllocateNtmsMedia | M |  |
CancelNtmsLibraryRequest |  | C |
CancelNtmsOperatorRequest |  |  |
ChangeNtmsMediaType | M |  |
CleanNtmsDrive |  | C |
CreateNtmsMediaPool | M |  |
DeallocateNtmsMedia | M |  |
DecommissionNtmsMedia | M |  |
DeleteNtmsLibrary |  | M |
DeleteNtmsMedia | M |  |
DeleteNtmsMediaPool | C |  |
DeleteNtmsMediaType |  | C |
DismountNtmsDrive |  | C |
DismountNtmsMedia | U | U |
EjectNtmsCleaner |  | C |
EjectNtmsMedia |  | C |
GetNtmsObjectInformation |  |  |
NTMS_DRIVE |  | C |
NTMS_LIBRARY |  | C |
NTMS_CHANGER |  | C |
NTMS_STORAGESLOT |  | C |
NTMS_IEDOOR |  | C |
NTMS_IEPORT |  | C |
NTMS_PHYSICAL_MEDIA | C |  |
NTMS_MEDIA_POOL | C |  |
NTMS_PARTITION | C |  |
NTMS_LOGICAL_MEDIA | C |  |
NTMS_OPREQUEST |  |  | M
NTMS_MEDIA_TYPE |  |  | M
NTMS_DRIVE_TYPE |  |  | M
NTMS_CHANGER_TYPE |  |  | M
NTMS_LIBREQUEST |  | M |
SetNtmsObjectInformation |  |  |
NTMS_DRIVE | na |  |
NTMS_LIBRARY |  | C |
NTMS_CHANGER | na |  |
NTMS_STORAGESLOT | na |  |
NTMS_IEDOOR | na |  |
NTMS_IEPORT | na |  |
NTMS_PHYSICAL_MEDIA | na |  |
NTMS_MEDIA_POOL | C |  |
NTMS_PARTITION | C |  |
NTMS_LOGICAL_MEDIA | M |  |
NTMS_OPREQUEST | na |  |
NTMS_MEDIA_TYPE | na |  |
NTMS_DRIVE_TYPE | na |  |
NTMS_CHANGER_TYPE | na |  |
NTMS_LIBREQUEST | na |  |
InjectNtmsCleaner |  | C |
InjectNtmsMedia |  | C |
InventoryNtmsLibrary |  | C |
MountNtmsMedia | U | U |
MoveToNtmsMediaPool | M |  |
OpenNtmsSession |  |  | U
ReleaseNtmsCleanerSlot |  | C |
ReserveNtmsCleanerSlot |  | C |
SatisfyNtmsOperatorRequest |  |  | C
SetNtmsMediaComplete | M |  |
SubmitNtmsOperatorRequest |  |  |
SwapNtmsMedia | M |  |
UpdateNtmsOmidInfo |  | C |
WaitForNtmsOperatorRequest |  |  | C


Media Label Library Function Reference

Your media label library must support the following functions. RSM uses these functions to communicate with media label libraries.

ClaimMediaLabel

MaxMediaLabel

MediaLabelInfo Data Structure


ClaimMediaLabel

The ClaimMediaLabel function determines whether a specified media label was created by the media's associated application.

DWORD __stdcall ClaimMediaLabel(
  const BYTE *const pBuffer,
  const DWORD nBufferSize,
  MediaLabelInfo *const pLabelInfo
);

Parameters

pBuffer
Pointer to a buffer that contains the media label.
nBufferSize
Specifies the size of the buffer. Must be equal to the size of pBuffer.
pLabelInfo
Pointer to the MediaLabelInfo data structure. The media label library fills in this structure if the library recognizes the media label.

Return Values

Value | Meaning
NO_ERROR | The media label library filled in the MediaLabelInfo structure.
ERROR_BAD_FORMAT | The media label library does not recognize the media label.

Remarks

When a media label library uses the ClaimMediaLabel function to identify the media label as one created by its associated application, the media label library must fill in the MediaLabelInfo structure and return NO_ERROR. If the media label library does not recognize the media label, it returns ERROR_BAD_FORMAT.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.


MaxMediaLabel

The MaxMediaLabel function determines the maximum size of the media label for the applications supported by the media label library.

DWORD __stdcall MaxMediaLabel(
  DWORD *const pMaxSize
);

Parameters

pMaxSize
Pointer to the maximum size of the buffer that is sent to the ClaimMediaLabel function.

Return Values

Value | Meaning
NO_ERROR | The function was successful.

Remarks

When the media format of the media specified in the MaxMediaLabel function does not have a theoretical size limit, the application should return the size of the largest media label the application can possibly generate.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.


MediaLabelInfo Data Structure

The MediaLabelInfo data structure conveys information to the RSM database about a tape OMID. The media label library fills in this data structure for all media labels the library recognizes.

struct MediaLabelInfo
  WCHAR    LabelType[64];
  DWORD    LabelIDSize;
  BYTE     LabelID[256];
  WCHAR    LabelAppDescr[256];
}

Members

LabelType
Unicode string that identifies the source of the media label. For example, the LabelType for a Windows NT/Windows 2000 backup media label is "Microsoft Windows NTBackup".
LabelIDSize
Number of bytes that are used in the LabelID field.
LabelID
Unique identifier for the media label.
LabelAppDescr
Unicode string that describes the media. For example, the LabelAppDescr for a Windows 2000 backup media label would be similar to "Tape created on 04/14/97".

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.


Removable Storage Manager Structure Reference

The following are Removable Storage Manager structures:

NTMS_OBJECTINFORMATION

NTMS_ALLOCATION_INFORMATION

NTMS_CHANGERINFORMATION

NTMS_CHANGERTYPEINFORMATION

NTMS_COMPUTERINFORMATION

NTMS_DRIVEINFORMATION

NTMS_DRIVETYPEINFORMATION

NTMS_IEDOORINFORMATION

NTMS_IEPORTINFORMATION

NTMS_LIBRARYINFORMATION

NTMS_LIBREQUESTINFORMATION

NTMS_LMIDINFORMATION

NTMS_MEDIAPOOLINFORMATION

NTMS_MEDIATYPEINFORMATION

NTMS_NOTIFICATIONINFORMATION

NTMS_OPREQUESTINFORMATION

NTMS_PARTITIONINFORMATION

NTMS_PMIDINFORMATION

NTMS_STORAGESLOTINFORMATION


NTMS_OBJECTINFORMATION

The NTMS_OBJECTINFORMATION data structure defines the properties that an application can get and set for RSM devices, media and system controls (such as libraries, drives, media, operator requests). This structure defines the common structure of objects in the RSM database.

typedef struct _NTMS_OBJECTINFORMATION
{
  DWORD        dwSize;
  DWORD        dwType;
  SYSTEMTIME   Created;
  SYSTEMTIME   Modified;
  NTMS_GUID    ObjectGuid;
  BOOL         Enabled;
  DWORD        dwOperationalState;
  TCHAR        szName[NTMS_OBJECTNAME_LENGTH];
  TCHAR        szDescription[NTMS_DESCRIPTION_LENGTH];
  union {
  NTMS_LIBRARYINFORMATION Library;
  NTMS_CHANGERINFORMATION Changer;
  NTMS_CHANGERTYPEINFORMATION ChangerType;
  NTMS_COMPUTERINFORMATION Computer,
  NTMS_DRIVEINFORMATION Drive;
  NTMS_DRIVETYPEINFORMATION DriveType;
  NTMS_STORAGESLOTINFORMATION StorageSlot;
  NTMS_IEDOORINFORMATION IEDoor;
  NTMS_IEPORTINFORMATION IEPort;
  NTMS_LMIDINFORMATION LogicalMedia;
  NTMS_PARTITIONINFORMATION Partition;
  NTMS_PMIDINFORMATION PhysicalMedia;
  NTMS_MEDIAPOOLINFORMATION MediaPool;
  NTMS_MEDIATYPEINFORMATION MediaType;
  NTMS_OPREQUESTINFORMATION OpRequest;
  NTMS_LIBREQUESTINFORMATION LibRequest;
  } Info;
} NTMS_OBJECTINFORMATION, *LPNTMS_OBJECTINFORMATION;

Members

dwSize
Size of the information structure. This member must be set to the correct size of the structure prior to using either the GetNtmsObjectInformation function or the SetNtmsObjectInformation function.
dwType
The type of device or system control for which to get/set information. This member must be set to one of the following values.
Value | Meaning
NTMS_CHANGER | A changer object represents the robotic element of an online library unit. The Info member is a pointer to an NTMS_CHANGERINFORMATION structure.
NTMS_CHANGER_TYPE | A changer type object is created for each unique changer device type attached to a system. The Info member is a pointer to an NTMS_CHANGERTYPEINFORMATION structure.
NTMS_COMPUTER | The current computer object. There is no structure for the computer object. The Info member is a pointer to an NTMS_COMPUTERINFORMATION structure.
NTMS_DRIVE | A drive object represents a tape drive or disk drive. The Info member is a pointer to an NTMS_DRIVEINFORMATION structure.
NTMS_DRIVE_TYPE | A drive type object is created for each unique drive device type attached to a system. The Info member is a pointer to an NTMS_DRIVETYPEINFORMATION structure.
NTMS_IEDOOR | An NTMS_IEDOOR object represents the door-access mechanism of an online library unit. The Info member is a pointer to an NTMS_IEDOORINFORMATION structure.
NTMS_IEPORT | An NTMS_IEPORT object represents the insert/eject port of an online library unit. The Info member is a pointer to an NTMS_IEPORTINFORMATION structure.
NTMS_LIBRARY | A library object represents an online or offline library. The Info member is a pointer to an NTMS_LIBRARYINFORMATION structure.
NTMS_LIBREQUEST | A library request object is created for each request for an online library to perform an action. A list of library requests is maintained by RSM as a queue of work to be performed. The Info member is a pointer to an NTMS_LIBREQUESTINFORMATION structure.
NTMS_LOGICAL_MEDIA | The primary handle used by applications to access the specified medium. In the case of multisideed media, each side is treated as an individual piece of physical media. The Info member is a pointer to an NTMS_LMIDINFORMATION structure.
NTMS_MEDIA_POOL | A media pool is a logical grouping of media. All media in a media pool must be the same media type. The Info member is a pointer to an NTMS_MEDIAPOOLINFORMATION structure.
NTMS_MEDIA_TYPE | A media type object is created for each unique media type in a system. The Info member is a pointer to an NTMS_MEDIATYPEINFORMATION structure.
NTMS_OPREQUEST | An operator request object represents an RSM request for a user to get the information. The Info member is a pointer to an NTMS_OPREQUESTINFORMATION structure.
NTMS_PARTITION | A side object represents a side of a piece of physical media. The Info member is a pointer to an NTMS_PARTITIONINFORMATION structure.
NTMS_PHYSICAL_MEDIA | A physical media object represents a magnetic tape or removable disk. A piece of physical media can contain one or more sides. The Info member is a pointer to an NTMS_PMIDINFORMATION structure.
NTMS_STORAGESLOT | A storage slot object represents one of the slots that can hold the specified medium in an online library. The Info member is a pointer to an NTMS_STORAGESLOTINFORMATION structure.

Created
A date/time stamp when the object was created.
Modified
A date/time stamp when the object was modified.
ObjectGuid
The GUID of the object.
Enabled
Indicates whether the device or system control object is enabled.
dwOperationalState
Defines the current operational state of the object. This can be one of the following values.
Value | Meaning
NTMS_NOT_PRESENT | This device or object is not currently present.
NTMS_READY | This device or object is available and ready.
NTMS_NEEDS_SERVICE | This device or object has failed and needs service.

szName
The name of the media, device, or system control object. Media pool and logical media names can be changed using the SetNtmsObjectInformation function. All other object names are read-only.
szDescription
A description of the device or system control object. The description of device and system control objects can be changed using the SetNtmsObjectInformation function. (Writable for all objects)
Info
Device or system control object-specific information.

Remarks

All members of the NTMS_OBJECTINFORMATION data structure are read-only at the RSM function-level unless specified as WRITABLE in the definition of the member.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_ALLOCATION_INFORMATION

The NTMS_ALLOCATION_INFORMATION data structure returns the source media pool from which a medium was taken.

typedef struct _NTMS_ALLOCATION_INFORMATION {
  DWORD      dwSize;
  LPVOID     lpReserved;
  NTMS_GUID  AllocatedFrom;
} NTMS_ALLOCATION_INFORMATION, *LPNTMS_ALLOCATION_INFORMATION;

Members

dwSize
Size of the structure.
lpReserved
Reserved.
AllocatedFrom
Represents the original source of the media.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_CHANGERINFORMATION

The NTMS_CHANGERINFORMATION data structure defines properties specific to a robotic changer object.

typedef struct _NTMS_CHANGERINFORMATION {
  DWORD       Number
  NTMS_GUID   ChangerType;
  TCHAR       szSerialNumber[NTMS_SERIALNUMBER_LENGTH];
  TCHAR       szRevision[NTMS_REVISION_LENGTH];
  TCHAR       szDeviceName[NTMS_DEVICENAME_LENGTH];
  WORD        ScsiPort;
  WORD        ScsiBus;
  WORD        ScsiTarget;
  WORD        ScsiLun;
  NTMS_GUID   Library;
} NTMS_CHANGERINFORMATION;

Members

Number
Number of the changer within the online library.
ChangerType
The changer type of this changer.
szSerialNumber
A serial number for the changer represented as a string. Devices that do not support serial numbers report NULL for this member.
szRevision
A revision for the changer represented as a string.
szDeviceName
The name of the device used to access the changer.
ScsiPort
SCSI host adapter to which the changer is connected.
ScsiBus
SCSI bus to which the changer is connected.
ScsiTarget
SCSI target ID for the changer.
ScsiLun
SCSI logical unit ID for the changer.
Library
Unique ID of the library that contains the changer.

Remarks

The NTMS_CHANGERINFORMATION data structure is included in the NTMS_OBJECTINFORMATION structure used for the GetNtmsObjectInformation and SetNtmsObjectInformation functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_CHANGERTYPEINFORMATION

The NTMS_CHANGERTYPEINFORMATION data structure defines the properties specific to a type of robotic changer supported by RSM.

typedef struct _NTMS_CHANGERTYPEINFORMATION {
  TCHAR    szVendor[NTMS_VENDORNAME_LENGTH];
  TCHAR    szProduct[NTMS_PRODUCTNAME_LENGTH];
  DWORD    DeviceType;
} NTMS_CHANGERTYPEINFORMATION;

Members

szVendor
Name of the vendor of the changer. This is acquired directly from the device inquiry data.
szProduct
Product name of the changer. This is acquired directly from the device inquiry data.
DeviceType
SCSI device type as reported from device inquiry data. From Winioctl.h. This can be the following value.
Value | Meaning
FILE_DEVICE_CHANGER | Changer device.

Remarks

The NTMS_CHANGERTYPEINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is read-only.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_COMPUTERINFORMATION

The NTMS_COMPUTERINFORMATION data structure defines the properties specific to the RSM server.

typedef struct _NTMS_COMPUTERINFORMATION {
  DWORD        dwLibRequestPurgeTime;
  DWORD        dwOpRequestPurgeTime;
  DWORD        dwLibRequestFlags;
  DWORD        dwOpRequestFlags;
  DWORD        dwMediaPoolPolicy;
} NTMS_COMPUTERINFO;

Members

dwLibRequestPurgeTime
Number of seconds completed library requests are maintained in the work queue.
dwOpRequestPurgeTime
Number of seconds that completed operator requests are maintained in the operator request queue.
dwLibRequestFlags
Value | Meaning
NTMS_LIBREQFLAGS_NOAUTOPURGE | If dwLibRequestFlags is set to this value, library requests are not purged from the work queue. Set to NULL by default.
NTMS_LIBREQFLAGS_NOFAILEDPURGE | If dwLibRequestFlags is set to this value, failed work items are not purged from the work queue. Set to NULL by default.

dwOpRequestFlags
Value | Meaning
NTMS_OPREQFLAGS_NOAUTOPURGE | If dwOpRequestFlags is set to this value, operator requests are not purged from the work queue. Set to NULL by default.
NTMS_OPREQFLAGS_NOFAILEDPURGE | If dwOpRequestFlags is set to this value, operator requests are not purged from the queue. Set to NULL by default.
NTMS_OPREQFLAGS_NOALERTS | If dwOpRequestFlags is set to this value, the alert pop-up for operator requests is disabled.
NTMS_OPREQFLAGS_NOTRAYICON | If dwOpRequestFlags is set to this value, the taskbar icon for operator requests is disabled.

dwMediaPoolPolicy
Value | Meaning
NTMS_POOLPOLICY_PURGEOFFLINESCRATCH | If dwMediaPoolPolicy is set to this value, any free media ejected are automatically deleted. Set to NULL by default.
NTMS_POOLPOLICY_KEEPOFFLINEIMPORT | If dwMediaPoolPolicy is set to this value, any Import media ejected is not deleted automatically. Set to NULL by default.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_DRIVEINFORMATION

The NTMS_DRIVEINFORMATION data structure defines properties specific to a drive object.

typedef struct _NTMS_DRIVEINFORMATION {
  DWORD        Number;
  DWORD        State;
  NTMS_GUID    DriveType;
  TCHAR        szSerialNumber[NTMS_SERIALNUMBER_LENGTH];
  TCHAR        szRevision[NTMS_REVISION_LENGTH];
  TCHAR        szDeviceName[NTMS_DEVICENAME_LENGTH];
  WORD         ScsiPort;
  WORD         ScsiBus;
  WORD         ScsiTarget;
  WORD         ScsiLun;
  SYSTEMTIME   LastCleanedTs;
  DWORD        dwMountCount;
  NTMS_GUID    SavedPartitionId;
  NTMS_GUID    Library;
  GUID         Reserved;
  DWORD        dwDeferDismountDelay;
} NTMS_DRIVEINFORMATION;

Members

Number
Number of the drive in the library. This is set zero or one relative the value based on the drive numbering system of the device. Some changers number drives beginning with zero, and some changers begin with one.
State
State of the drive. This can be one of the following values.
Value | Meaning
NTMS_DRIVESTATE_BEING_CLEANED | The drive is being cleaned and is unavailable.
NTMS_DRIVESTATE_DISMOUNTABLE | If a library is set for lazy dismounts, the medium might be left in the library's drive on a dismount. RSM can satisfy mount requests for loaded and dismounted drives.
NTMS_DRIVESTATE_DISMOUNTED | No medium in the drive.
NTMS_DRIVESTATE_LOADED | The medium is mounted in the drive and is loaded for read and write access.
NTMS_DRIVESTATE_MOUNTED | The medium is mounted in the drive but is not ready for read and write access. This is a temporary state that is used while a drive is waiting for spindle synchronization or loading tape media into the head mechanism.
NTMS_DRIVESTATE_UNLOADED | The medium has been dismounted by the drive and is ready to be opened. This state indicates that the spindle has stopped or a tape media has been returned to the tape cartridge.

DriveType
The drive type object containing the attributes for the drive.
szSerialNumber
A serial number for the drive represented as a string. Devices that do not support serial numbers report NULL for this member.
szRevision
A revision for the drive represented as a string.
szDeviceName
Name of the device used to access the drive. For a tape drive this contains the device name \\.\tape0 or \\.\tape1. Other devices provide the name of a SCSI disk drive or the root of a file system that currently has the device mounted (raw, NTFS, FAT and so forth).
ScsiPort
SCSI host adapter to which the drive is connected.
ScsiBus
SCSI bus to which the drive is connected.
ScsiTarget
SCSI target ID for the drive.
ScsiLun
SCSI logical unit ID for the drive.
LastCleanedTs
Last time the drive was cleaned.
dwMountCount
Number of times the drive has had a medium mounted to it. If the drive supports the reporting of a unique serial number, this value is the number of times the drive has been mounted since it was installed. If the drive does not support the reporting of serial numbers, this member reflects the number of mounts to all of the drives at that location.
SavedPartitionId
Partition ID of the medium that is in the drive. If this value is NULL and the drive is found to be full, the media was loaded by a user and needs to be classified.
Library
Unique ID of the library that contains the drive.
Reserved
Reserved.
dwDeferDismountDelay
Minimum number of seconds a medium will remain in a drive of an online library after a deferred dismount has been performed. The default is 5 minutes. This member does not apply to stand-alone libraries. This member is writable.

Remarks

The NTMS_DRIVEINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure used for the GetNtmsObjectInformation and SetNtmsObjectInformation functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_DRIVETYPEINFORMATION

The NTMS_DRIVETYPEINFORMATION data structure defines the properties specific to a type of drive supported by RSM.

typedef struct _NTMS_DRIVETYPEINFORMATION {
  TCHAR    szVendor[NTMS_VENDORNAME_LENGTH];
  TCHAR    szProduct[NTMS_PRODUCTNAME_LENGTH];
  DWORD    NumberOfHeads;
  DWORD    DeviceType;
} NTMS_DRIVETYPEINFORMATION;

Members

szVendor
Name of the vendor of the drive. This is acquired directly from the device inquiry data.
szProduct
Name of the product of the drive. This is acquired directly from the device inquiry data.
NumberOfHeads
This field is reserved for future use and should be ignored.
DeviceType
The SCSI device type as reported from device inquiry data. From Winioctl.h. This can be one of the following values.
Value | Meaning
FILE_DEVICE_CD_ROM | CD-ROM device.
FILE_DEVICE_DISK | Direct access device.
FILE_DEVICE_DVD | DVD device
FILE_DEVICE_TAPE | Sequential access device.

Remarks

The NTMS_DRIVETYPEINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_IEDOORINFORMATION

The NTMS_IEDOORINFORMATION data structure defines properties specific to an insert/eject door object.

typedef struct _NTMS_IEDOORINFORMATION {
  WORD         Number;
  WORD         State;
  WORD         MaxOpenSecs;
  NTMS_GUID    Library
} NTMS_IEDOORINFORMATION;

Members

Number
Number of the door in the library. Typically, libraries have one door.
State
State of the door. This can be one of the following values.
Value | Meaning
NTMS_DOORSTATE_CLOSED | Library door is closed.
NTMS_DOORSTATE_OPEN | Library door is open.
NTMS_DOORSTATE_UNKNOWN | State of the library is unknown.

MaxOpenSecs
Maximum number of seconds the door is to remain open. Valid values are between 0-65,535 seconds This member is writable.
Library
Library that contains this door.

Remarks

The NTMS_IEDOORINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure used for the GetNtmsObjectInformation and SetNtmsObjectInformation functions.

If the MaxOpenSecs member is zero, an operator request to close the door is generated as soon as the door is open.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_IEPORTINFORMATION

The NTMS_IEPORTINFORMATION data structure defines properties specific to an insert/eject port object.

typedef struct _NTMS_IEPORTINFORMATION {
  DWORD      Number;
  DWORD      Content;
  DWORD      Position;
  WORD       MaxExtendSecs;
  NTMS_GUID  Library;
} NTMS_IEPORTINFORMATION;

Members

Number
The library port number.
Content
Full/Empty state of the NTMS_IEPORT object. This can be one of the following values.
Value | Meaning
NTMS_PORTCONTENT_FULL | Port is full.
NTMS_PORTCONTENT_EMPTY | Port is empty.
NTMS_PORTCONTENT_UNKNOWN | Content of port is not known.

Position
Position of the NTMS_IEPORT object. This can be one of the following values.
Value | Meaning
NTMS_PORTPOSITION_EXTENDED | Port is extended.
NTMS_PORTPOSITION_RETRACTED | Port is retracted.
NTMS_PORTPOSITION_UNKNOWN | Port position is unknown.

MaxExtendSecs
Maximum number of seconds the port is allowed to remain open before an operator request is issued. Valid values are between 0 and 65,535 seconds. This member is writable.
Library
Library that contains the port.

Remarks

The NTMS_IEPORTINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure used for the GetNtmsObjectInformation and SetNtmsObjectInformation functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_LIBRARYINFORMATION

The NTMS_LIBRARYINFORMATION data structure defines properties specific to a library object.

typedef struct _NTMS_LIBRARYINFORMATION {
  DWORD      LibraryType;
  NTMS_GUID  CleanerSlot;
  NTMS_GUID  CleanerSlotDefault;
  BOOL       LibrarySupportsDriveCleaning;
  BOOL       BarCodeReaderInstalled;
  DWORD      InventoryMethod;
  DWORD      dwCleanerUsesRemaining;
  DWORD      FirstDriveNumber;
  DWORD      dwNumberOfDrives;
  DWORD      FirstSlotNumber;
  DWORD      dwNumberOfSlots;
  DWORD      FirstDoorNumber;
  DWORD      dwNumberOfDoors;
  DWORD      FirstPortNumber;
  DWORD      dwNumberOfPorts;
  DWORD      FirstChangerNumber;
  DWORD      dwNumberOfChangers;
  DWORD      dwNumberOfMedia;
  DWORD      dwNumberOfMediaTypes;
  DWORD      dwNumberOfLibRequests;
  GUID       Reserved;
  BOOL       AutoRecovery;
  DWORD      dwFlags;
} NTMS_LIBRARYINFORMATION;

Members

LibraryType
Library type object. This can be one of the following values.
Value | Meaning
NTMS_LIBRARYTYPE_ONLINE | A robotic element that automates the mounting and dismounting of media into one or more drives.
NTMS_LIBRARYTYPE_STANDALONE | A stand-alone drive that is modeled as a library with one drive in RSM.
NTMS_LIBRARYTYPE_OFFLINE | Media that is not in an online library is in an offline library. There is one offline library unit per RSM system.
NTMS_LIBRARYTYPE_UNKNOWN | Library type cannot be determined.

CleanerSlot
For each online library, this represents the slot that was assigned to the cleaner cartridge. If this member is NULL, there is no cleaner slot defined for this library.
CleanerSlotDefault
Represents a libraries' default or preferred cleaner slot. If NULL, there is not a preferred slot.
LibrarySupportsDriveCleaning
Used by drives that require cleaning under robotics control. If TRUE, automatic drive cleaning operations are enabled.
BarCodeReaderInstalled
Returns TRUE if a bar code reader is installed in a library; otherwise returns FALSE.
InventoryMethod
The default or user-selected method for performing inventory of this online library. (This member is writable.) This can be one of the following values.
Value | Meaning
NTMS_INVENTORY_FAST | If the library has a bar-code reader installed, this value causes a bar-code inventory to be performed. If the library does not have a bar-code reader, this flag causes a differential inventory to be performed (slots which transitioned from empty to full are classified).
NTMS_INVENTORY_OMID | A full inventory involves mounting each side in a library and reading the on-media identification from the media. This type of inventory can be very time consuming for some library units.
NTMS_INVENTORY_NONE | After the library door is closed, no inventory is performed. Inventory might be required if a mount label-check fails.

dwCleanerUsesRemaining
Number of uses remaining on the cleaner in the library. This member is zero if no cleaner is present or if the library does not support cleaning.
FirstDriveNumber
Number of the first drive in the online library.
dwNumberOfDrives
Number of drives in the online library.
FirstSlotNumber
Number of the first slot in the online library.
dwNumberOfSlots
Number of slots in the online library.
FirstDoorNumber
Number of the first access door in the online library.
dwNumberOfDoors
Number of access doors in the online library.
FirstPortNumber
Number of the first insert/eject port in the online library.
dwNumberOfPorts
Number of insert/eject ports in the online library.
FirstChangerNumber
Number of the first changer in the online library.
dwNumberOfChangers
Number of changers in the online library.
dwNumberOfMedia
Number of media in the online or offline library.
dwNumberOfMediaTypes
Number of media types supported by the library.
dwNumberOfLibRequests
Number of current library requests.
Reserved
Reserved.
AutoRecovery
If set a full inventory will be performed if a mount fails. The failure may be either hardware or label mismatch. For ATAPI CD libraries, AutoRecovery cannot be disabled. The default is true. Large library owners should disable this feature.
dwFlags
Value | Meaning
NTMS_LIBRARYFLAG_FIXEDOFFLINE | If dwFlags is set to this value, the library is an offline library, not a library that is not present.
NTMS_LIBRARYFLAG_CLEANERPRESENT | If dwFlags is set to this value, a cleaner is present in the changer.

Remarks

For offline libraries, only LibraryType and dwNumberOfMedia are reported. All other values should be ignored.

The NTMS_LIBRARYINFORMATION data structure is included in the NTMS_OBJECTINFORMATION structure used for the GetNtmsObjectInformation and SetNtmsObjectInformation functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_LIBREQUESTINFORMATION

The NTMS_LIBREQUESTINFORMATION data structure defines the properties specific to a work request, which are queued to RSM.

typedef struct _NTMS_LIBREQUESTINFORMATION {
  DWORD      OperationCode;
  DWORD      OperationOption;
  DWORD      State;
  NTMS_GUID  PartitionId;
  NTMS_GUID  DriveId;
  NTMS_GUID  PhysMediaId;
  NTMS_GUID  Library;
  NTMS_GUID  SlotId;
  SYSTEMTIME TimeQueued;
  SYSTEMTIME TimeCompleted;
  TCHAR      szApplication[NTMS_APPLICATIONNAME_LENGTH];
  TCHAR      szUser[NTMS_USERNAME_LENGTH];
  TCHAR      szComputer[NTMS_COMPUTERNAME_LENGTH];
  DWORD      dwErrorCode;
  NTMS_GUID  WorkItemId;
  DWORD      dwPriority;
} NTMS_LIBREQUESTINFORMATION;

Members

OperationCode
Item operation. This can be one of the following values.
Value | Meaning
NTMS_LM_CLASSIFY | Classify the medium.
NTMS_LM_CLEANDRIVE | Clean a drive.
NTMS_LM_DISABLELIBRARY | Disable the changer.
NTMS_LM_DISABLEDRIVE | Disable a drive.
NTMS_LM_DISABLEMEDIA | Disable the medium.
NTMS_LM_DISMOUNT | Dismount the medium from a drive.
NTMS_LM_DOORACCESS | Allow access to media through a library unit door.
NTMS_LM_EJECT | Eject the medium from the library.
NTMS_LM_EJECTCLEANER | Eject a cleaner.
NTMS_LM_ENABLELIBRARY | Enable the changer.
NTMS_LM_ENABLEDRIVE | Enable a drive.
NTMS_LM_ENABLEMEDIA | Enable the medium.
NTMS_LM_INJECT | Insert the medium into the library.
NTMS_LM_INJECTCLEANER | Insert a cleaner.
NTMS_LM_INVENTORY | Perform an inventory of the library.
NTMS_LM_MOUNT | Mount a side to a drive.
NTMS_LM_PROCESSOMID | Process the OMID.
NTMS_LM_RELEASECLEANER | Release a cleaner slot.
NTMS_LM_REMOVE | Remove a work item from the queue.
NTMS_LM_RESERVECLEANER | Reserve a cleaner slot.
NTMS_LM_UPDATEOMID | Update the OMID.
NTMS_LM_WRITESCRATCH | Write a free label.

OperationOption
Work item options (command specific).
State
Current state of this work item. This can be one of the following values.
Value | Meaning
NTMS_LM_QUEUED | Operation is queued.
NTMS_LM_INPROCESS | Operation is being processed.
NTMS_LM_PASSED | Operation completed successfully.
NTMS_LM_FAILED | Operation has completed with an error.
NTMS_LM_WAITING | Operation is blocked.
NTMS_LM_CANCELLED | Operation has been canceled.
NTMS_LM_INVALID | Operation is invalid.

PartitionId
Unique identifier of a side being serviced.
DriveId
Unique identifier of a drive being serviced.
PhysMediaId
Unique identifier of a piece of physical media being serviced.
Library
Library for this request.
SlotId
Unique identifier of a slot of the piece of physical media being serviced.
TimeQueued
System time that this request was queued to RSM.
TimeCompleted
System time that this request was completed by RSM.
szApplication
Application that submitted the operator request.
szUser
Interactive user logged on to the computer that submitted the operator request.
szComputer
Computer that submitted the operator request.
dwErrorCode
Error return for requests that return with state NTMS_LM_FAILED. This is a Win32 error code.
WorkItemId
Associated work item ID for this request. This is currently used to contain the work item ID to be canceled on an NTMS_LM_REMOVE request.
dwPriority
Priority of the work item.

Remarks

The NTMS_LIBREQUESTINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

GUID in the work times may become invalid over time. For example, an eject of a free medium deletes the PMID after the media is ejected. However the work item is not updated upon completion of the eject.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_LMIDINFORMATION

The NTMS_LMIDINFORMATION data structure defines the properties specific to a logical media object.

typedef struct _NTMS_LMIDINFORMATION {
  NTMS_GUID    MediaPool;
  DWORD        dwNumberOfPartitions;
} NTMS_LMIDINFORMATION;

Members

MediaPool
The media pool that contains this logical media.
dwNumberOfPartitions
Number of sides in the media object.

Remarks

The NTMS_LMIDINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_MEDIAPOOLINFORMATION

The NTMS_MEDIAPOOLINFORMATION data structure defines the properties specific to a media pool object.

typedef struct _NTMS_MEDIAPOOLINFORMATION {
  DWORD       PoolType;
  NTMS_GUID   MediaType;
  NTMS_GUID   Parent;
  DWORD       AllocationPolicy;
  DWORD       DeallocationPolicy;
  DWORD       dwMaxAllocates;
  DWORD       dwNumberOfPhysicalMedia;
  DWORD       dwNumberOfLogicalMedia;
  DWORD       dwNumberOfMediaPools;
} NTMS_MEDIAPOOLINFORMATION;

Members

PoolType
NTMS supports the following media pool types.
Value | Meaning
NTMS_POOLTYPE_UNKNOWN | Unknown pool type.
NTMS_POOLTYPE_SCRATCH | Media that is available to other applications.
NTMS_POOLTYPE_FOREIGN | Media that has been written to and does not contain a recognizable on-media identifier label-type or label ID.
NTMS_POOLTYPE_IMPORT | Media that has been written to, has a recognizable on-media identifier label type but an unrecognizable label ID.
NTMS_POOLTYPE_APPLICATION | Media pool created by an application. One or more application media pools can be created per system.

MediaType
The single media type that makes up each media pool.
Parent
Parent media pool or NULL.
AllocationPolicy
Bit field indicating action at allocation time. This member is writable. This can be the following value.
Value | Meaning
NTMS_ALLOCATE_FROMSCRATCH | Draw media from free if none is available in the pool. The default is not to draw from free.

DeallocationPolicy
Bit field indicating action at deallocation time. This member is writable. This can be the following value.
Value | Meaning
NTMS_DEALLOCATE_TOSCRATCH | Return media to free when available. The default is not to return to free.

dwMaxAllocates
Number of times the medium can be allocated and deallocated. This member is writable.
dwNumberOfPhysicalMedia
Number of physical media in this media pool.
dwNumberOfLogicalMedia
Number of logical media in this media pool.
dwNumberOfMediaPools
Number of media pools in this media pool.

Remarks

The NTMS_MEDIAPOOLINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_MEDIATYPEINFORMATION

The NTMS_MEDIATYPEINFORMATION data structure defines the properties specific to a type of media supported by RSM.

typedef struct _NTMS_MEDIATYPEINFORMATION {
  DWORD    MediaType;
  DWORD    NumberOfSides;
  DWORD    ReadWriteCharacteristics;
  DWORD    DeviceType;
} NTMS_MEDIATYPEINFORMATION;

Members

MediaType
Each disk or tape driver reports the media-type enumeration value of the medium that is currently mounted in the drive. The enumeration values are specified in Winoclt.h. This unique media type value is mapped to a human-readable string in the MediaType object szName member. Some examples of MediaType names are MP_8mm and MO_5_RW.
NumberOfSides
Number of sides on the media.
ReadWriteCharacteristics
Identifies the read/write characteristics of the media type. This can be one of the following values.
Value | Meaning
NTMS_MEDIARW_REWRITABLE | Media that can be rewritten. This includes magnetic tape, magnetic disk, and some optical disk media.
NTMS_MEDIARW_WRITEONCE | Media that can only be written to one time. Some optical media, for example, 5.25", 12", 14" WORM, and CD-R, are designed to be write-once.
NTMS_MEDIARW_READONLY | Media that cannot be written to CD-ROM and DVD-ROM.

DeviceType
The SCSI device type as reported from device inquiry data. From Winioctl.h. This can be one of the following values.
Value | Meaning
FILE_DEVICE_CD_ROM | CD-ROM device.
FILE_DEVICE_DISK | Direct access device.
FILE_DEVICE_TAPE | Sequential access device.

Remarks

The NTMS_MEDIATYPEINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_NOTIFICATIONINFORMATION

The NTMS_NOTIFICATIONINFORMATION data structure defines an object and operation that occurred in the RSM database.

typedef struct _NTMS_NOTIFICATIONINFORMATION {
  DWORD       dwOperation;
  NTMS_GUID   ObjectId
} NTMS_NOTIFICATIONINFORMATION, *LPNTMS_NOTIFICATIONINFORMATION;

Members

dwOperation
Operation that occurred on the object. This can be one of the following values.
Value | Meaning
NTMS_OBJ_INSERT | New object was inserted.
NTMS_OBJ_DELETE | Object was deleted.
NTMS_OBJ_UPDATE | Object was updated.

ObjectId
Object identifier.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_OPREQUESTINFORMATION

The NTMS_OPREQUESTINFORMATION data structure defines the properties specific to operator-request system control for RSM.

typedef struct _NTMS_OPREQUESTINFORMATION {
  DWORD        Request;
  SYSTEMTIME   Submitted;
  DWORD        State;
  TCHAR        szMessage[NTMS_MESSAGE_LENGTH];
  DWORD        Arg1Type;
  NTMS_GUID    Arg1;
  DWORD        Arg2Type;
  NTMS_GUID    Arg2;
  TCHAR        szApplication[NTMS_APPLICATIONNAME_LENGTH];
  TCHAR        szUser[NTMS_USERNAME_LENGTH];
  TCHAR        szComputer[NTMS_COMPUTERNAME_LENGTH];
} NTMS_OPREQUESTINFORMATION;

Members

Request
Type of operator request. This can be one of the following values.
Value | Meaning
NTMS_OPREQ_NEWMEDIA | An application attempting to allocate media sends an operator request for new media when no media is available. When this flag is set, the Arg1 member should be set to the GUID of the media pool requiring new media. Optionally, the Arg2 parameter can be set to the particular library in which the new media should be placed.
NTMS_OPREQ_CLEANER | RSM sends an operator request for a cleaner when a clean operation is queued and no cleaner is online and available to the drive. When this flag is set, the Arg1 member should be set to the GUID of the library requiring the cleaning cartridge.
NTMS_OPREQ_DEVICESERVICE | An application or RSM sends an operator request for drive service when a changer device or drive is experiencing problems. When this flag is set, the Arg1 member should be set to the GUID of the device requiring service.
NTMS_OPREQ_MOVEMEDIA | An application or RSM sends an operator request to move the specified medium to service a mount for offline media or to eject media to an offline library. When this flag is set, the Arg1 member should be set to the GUID of the physical media to move and the Arg2 member should be set to the GUID of the library this media should be moved to.
NTMS_OPREQ_MESSAGE | An application-specific operator request. Text only.

Submitted
System time when the operator request was submitted.
State
Current state of the operator service request. This can be one of the following values.
Value | Meaning
NTMS_OPSTATE_SUBMITTED | The operator request has been submitted but not read by an operator console.
NTMS_OPSTATE_ACTIVE | The operator request has been read by one or more operator consoles and might be in process.
NTMS_OPSTATE_INPROGRESS | The user has acknowledged this operator request and is in the process of performing the service.
NTMS_OPSTATE_REFUSED | The user has rejected the operator service request.
NTMS_OPSTATE_COMPLETE | The user has completed the operator service request.

szMessage
Operator message text.
Arg1Type
Type of the Arg1 object. This can be one of the following values.
Value | Meaning
NTMS_UNKNOWN | No object provided in Arg1Type.
NTMS_CHANGER | Medium changer object.
NTMS_DRIVE | Drive object.
NTMS_IEDOOR | Library door object.
NTMS_IEPORT. | Library IE port object
NTMS_LIBRARY | Library object.
NTMS_PARTITION | Side object.
NTMS_PHYSICAL_MEDIA | Physical media object.
NTMS_STORAGESLOT | Library slot object.

Arg1
Arg1 object ID used for move requests or other operator requests that require a reference object. The purpose of this object varies based on the type of operator request. For appropriate uses of Arg1, see the Request description.
Arg2Type
Type of Arg2 object. This can be one of the following values.
Value | Meaning
NTMS_UNKNOWN | No object provided in Arg2Type.
NTMS_LIBRARY | Library object.

Arg2
Arg2 object ID used for operator requests that require a second reference object. The purpose of this object varies based on the type of operator request. For appropriate uses of Arg2, see the Request description.
szApplication
The application that submitted the operator request.
szUser
The interactive user logged on to the computer that submitted the operator request.
szComputer
The computer that submitted the operator request.

Remarks

The NTMS_OPREQUESTINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_PARTITIONINFORMATION

The NTMS_PARTITIONINFORMATION structure defines the properties specific to the side object.

typedef struct _NTMS_PARTITIONINFORMATION {
  NTMS_GUID      PhysicalMedia;
  NTMS_GUID      LogicalMedia;
  DWORD          State;
  WORD           Side;
  DWORD          dwOmidLabelIdLength;
  BYTE           OmidLabelId[255];
  TCHAR          szOmidLabelType[64];
  TCHAR          szOmidLabelInfo[256];
  DWORD          dwMountCount;
  DWORD          dwAllocateCount;
  LARGE_INTEGER  Capacity;
} NTMS_PARTITIONINFORMATION;

Members

PhysicalMedia
Unique physical media identifier for the medium that contains this side.
LogicalMedia
Unique logical media identifier for a piece of logical media that contains this side. This is a NULL ID if the side is not allocated.
State
Side life cycle information. This can be one of the following values.
Value | Meaning
NTMS_PARTSTATE_ALLOCATED | The media has been allocated to an application.
NTMS_PARTSTATE_AVAILABLE | The media is available to be allocated.
NTMS_PARTSTATE_COMPLETE | The media has been completely written and marked as complete by an application.
NTMS_PARTSTATE_DECOMMISIONED | The media is unsuitable for data storage and is no longer usable.
NTMS_PARTSTATE_INCOMPATIBLE | The media has been found to be and marked as incompatible with the drive.
NTMS_PARTSTATE_FOREIGN | The media is in a unrecognized pool.
NTMS_PARTSTATE_IMPORT | The media is in the import pool.
NTMS_PARTSTATE_UNPREPARED | The media is waiting for a free label to be applied.
NTMS_PARTSTATE_RESERVED | The side has been reserved by the AllocateNtmsMedia function with the dwOption parameter set to NTMS_ALLOCATE_NEW.

Side
A zero-relative value which indicates which side of a multi-sided media this is. For single-sided media, such as tape, this value is always zero. For dual-sided media one NTMS_PARITIONINFORMATION record has this property set to zero - the "A" side - and a second NTMS_PARTITIONINFORMATION record has it set to 1 - the "B" side.
dwOmidLabelIdLength
The length of the label ID string of the on-media identifier.
OmidLabelId
The label ID unique identifier of the on-media identifier.
szOmidLabelType
A string representing the label type of the on-media identifier.
szOmidLabelInfo
A string representing the label information of the on-media identifier.
dwMountCount
Number of times this media has been mounted into a drive. This is initialized to zero when the objects are created in the database.
dwAllocateCount
Number of times this media has been allocated.
Capacity
Number bytes of storage available on this side.

Remarks

The NTMS_PARTITIONINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_PMIDINFORMATION

The NTMS_PMIDINFORMATION data structure defines the properties specific to a physical media object.

typedef struct _NTMS_PMIDINFORMATION {
  NTMS_GUID     CurrentLibrary,
  NTMS_GUID     MediaPool;
  NTMS_GUID     Location;
  DWORD         LocationType;
  NTMS_GUID     HomeSlot;
  NTMS_GUID     MediaType;
  TCHAR         szBarCode[NTMS_BARCODE_LENGTH];
  DWORD         BarCodeState;
  TCHAR         szSequenceNumber[NTMS_SEQUENCE_LENGTH];
  DWORD         MediaState;
  DWORD         dwNumberOfPartitions;
  DWORD         dwMediaTypeCode;
  DWORD         dwDensityCode;
  NTMS_GUID     MountedPartition;
} NTMS_PMIDINFORMATION;

Members

CurrentLibrary
Unique ID of the library in which the media is contained.
MediaPool
Unique ID of the media pool to which the media is assigned.
Location
Unique ID of the physical location object for the media.
LocationType
Current location type of a piece of physical media. The value of this member can be set to NTMS_STORAGESLOT, NTMS_DRIVE, NTMS_IEPORT. (Offline media are in slots.)
HomeSlot
Unique ID of the library storage slot in which media is stored.
MediaType
Unique ID of a media type object.
szBarCode
String that matches the bar-code value on a bar-code label of a piece of physical media.
BarCodeState
Current state of the bar code. This can be one of the following values.
Value | Meaning
NTMS_BARCODESTATE_OK | The media has a bar code and it is readable.
NTMS_BARCODESTATE_UNREADABLE | The media either does not have a bar code or the bar code is unreadable.

szSequenceNumber
A sequential number assigned to the specified medium as a human-readable value that must be transcribed by a user on the medium so that the medium can be located in an offline library.
MediaState
Current state for the piece of physical media. This can be one of the following values.
Value | Meaning
NTMS_MEDIASTATE_IDLE | The media is in a slot in the library, in a drive dismounted, or in an offline library.
NTMS_MEDIASTATE_INUSE | The media is marked as in use as soon as a request for an operation is successfully made to RSM.
NTMS_MEDIASTATE_LOADED | The state of the media when RSM has determined that the media is available for reading and writing.
NTMS_MEDIASTATE_MOUNTED | The state of a piece of physical media when the media is placed in a drive.
NTMS_MEDIASTATE_OP_ERROR | The physical media is in an error state that is recoverable. No operator intervention is required.
NTMS_MEDIASTATE_UNLOADED | The state of the media when it is ready to be removed from a drive. The drive state, DISMOUNTABLE, also indicates that a drive can be removed at any time.
NTMS_MEDIASTATE_OPREQ | Media is waiting for operator request.

dwNumberOfPartitions
Number of sides on the medium.
dwMediaTypeCode
SCSI media type code.
dwDensityCode
SCSI density code.
MountedPartition
Globally unique ID of the side of the media that is currently mounted.

Remarks

The NTMS_PMIDINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure and is not used separately.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


NTMS_STORAGESLOTINFORMATION

The NTMS_STORAGESLOTINFORMATION data structure defines properties specific to a storage slot object.

typedef struct _NTMS_STORAGESLOTINFORMATION {
  DWORD         Number;
  DWORD         State;
  NTMS_GUID     Library;
} NTMS_STORAGEINFORMATION;

Members

Number
Number of the slot in the online library.
State
Current state of the slot. This can be one of the following values.
Value | Meaning
NTMS_SLOTSTATE_EMPTY | Slot is present, but does not contain a piece of physical media.
NTMS_SLOTSTATE_FULL | Slot is present and contains a piece of physical media.
NTMS_SLOTSTATE_NOTPRESENT | Slot is not present. If the library contains magazines, this value is reported for each slot when the associated magazine is missing.
NTMS_SLOTSTATE_UNKNOWN | Slot state cannot be determined.
NTMS_SLOTSTATE_NEEDSINVENTORY | Slot needs inventory.

Library
Online library that contains the slot.

Remarks

The NTMS_STORAGESLOTINFORMATION data structure is part of the NTMS_OBJECTINFORMATION structure used for the GetNtmsObjectInformation and SetNtmsObjectInformation functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Header: Declared in Ntmsapi.h.


Glossary

This glossary contains definitions for terms used in the documentation of Removable Storage Manager.

A B C D F I L M O P S U


A

Allocate
Mark media for use by an application. You can allocate media in the Available state.
Allocated state
Indicates media that are in use and assigned to application media pools.
Application media pool
Created by applications. Application media pools determine which media can be accessed by which applications and set the policies for that media. There can be any number of application media pools in a Media Service system.
Available state
Indicates media that can be allocated for use by applications.


B

Bar code
A machine-readable adhesive label that identifies a medium. It is assumed that all bar codes are unique in a system.


C

Changer
The robotic element of an online library unit that is capable of manipulating data.
Completed state
Indicates media that can no longer be used for write operations.


D

Data path
The software used by the application to read and write data to a medium. This is made up of a device driver and a small interface layer.
Deallocate
Return media to the Available state after the media has been used by an application.
Decommissioned state
Media in the decommissioned state are no longer usable.
Drive
A device used to write and read physical media. Drives can be in a library unit or stand-alone (directly accessible by the user).


F

Free media pool
Contains media that are not allocated by an application and do not contain data. There is a one free media pool for each media type in a Media Service system.


I

Import media pool
Media Service for Windows 2000 puts media in an import media pool when the Media Service recognizes the on-media identifier, but the medium is not cataloged in the current Media Service database.
Imported state
Indicates media whose label types are recognized by Media Service for Windows 2000, but whose label IDs are not cataloged by the Media Service.
Incompatible state
Indicates media that are not compatible with the library in which they were identified. This media should be immediately ejected from the library hardware unit. Media Service for Windows 2000 puts Incompatible media in the unrecognized media pool.


L

Library
A media storage location. There are two types of libraries: robotic and stand-alone drives.
Library request
A request for a library to perform a task. This request can be issued by an application or by Media Service for Windows 2000.
LMID
Logical media identifier. A logical representation of a physical storage location. Media Service for Windows 2000 generally defines sides of the logical media for use by the application. The intent of logical media is to allow the underlying physical medium of the data to change without affecting the application.
Logical media
Abstract representations of sides of physical media. All media that are currently allocated in Media Service for Windows 2000 are represented as logical media. Logical media are referenced by LMIDs (logical media identifiers).


M

Media label
Written and used by an application to track media. Applications write media labels when media are moved from a free media pool to an application media pool. Media Service for Windows 2000 uses a subset of the media label known as the on-media identifier to track media.
Media label library
A DLL that interprets the format of a media label written by a Media Service application.
Media pool
Logical collections of media that have the same media management policies. They are used by applications to control access to media within a Media Service system. One medium is contained in exactly one media pool.
Media Service for Windows NT
The service included with Windows NT/Windows 2000 that facilitates communication among applications, robotic changers, and media libraries.
Media Service for Windows NT MMC snap-in
The user interface for the Media Service that is a snap-in for the Microsoft Management Console (MMC) for Windows NT/Windows 2000. It provides administrators with the ability to add Media Service objects, view and modify properties of Media Service objects, insert and eject media, perform inventories, mount and dismount media, and check status information.


O

Offline media location
Contains all media that are known by Media Service for Windows 2000 but are not in a library. Media can only be moved from an offline location to a library by the administrator physically inserting the media into a library unit.
OMID
On-media identifier. On-media identifiers are labels that are electronically recorded on each medium in a Media Service system. The Media Service uses on-media identifiers to track media in the Media Service database. An application on-media identifier is a subset of the media label.
Operator request
A request for the operator to perform a task. This request can be issued by an application or by the Media Service.


P

Partition
A physical portion of media that is addressed to a logical unit of storage. Sides of an optical disk or a tape are examples of partitions. Partitions are referenced by part IDs. Also referred to as side.
Physical media
Media referenced by PMIDs (physical media identifiers). Disks and magnetic tapes are examples of physical media.
PMID
Physical media identifier. Representation of media.
Port
An opening in a library hardware unit that is used to insert and eject media.


S

Sequence numbers
Assigned to media by the Media Service for visual reference by the administrator during inserting, ejecting, and offline tracking of media.
Side
A physical portion of media that is addressed to a single unit of storage. Sides of an optical disk or a tape are examples. Sides are referenced by Part IDs.
System media pool
Include free, unrecognized, and import media pools. RSM creates one free, one unrecognized, and one import media pool for each media type in an RSM system.


U

Unrecognized media pool
Contains blank media. Unrecognized media pools also contain media that have unrecognizable on-media identifiers or no on-media identifiers.
Unrecognized state
Indicates media that is new to the Media Service for Microsoft® Windows® 2000, or media whose label types and label IDs are not recognized by the Media Service.


Power Management

This overview describes the power management support in the Microsoft® Win32® API, and explains how to use it in your applications. It also describes the OnNow initiative and how your applications can take advantage of computers that are "always on" to enhance the user's experience and save power.

  • About Power Management
  • Power Management Reference


About Power Management

To save power and ensure that no data is lost when a computer or device is turned off or placed in a low power state, the system provides power management support. The power management functions and messages retrieve the system power status, notify applications of power management events, and notify the system of each application's power requirements. This overview contains the following topics:

  • OnNow Power Management
  • System Power Status
  • System Power States
  • System Power Management Events
  • Power Management Policy
  • System Sleep Criteria
  • System Wake-up Events
  • Battery Information


OnNow Power Management

Computers that comply with OnNow are designed to be instantly accessible to users at the touch of a button. As with appliances, the computer must always be on and ready for use, but appear to be off when not in use. This state of low power consumption is called the sleeping state.

When the computer is in the sleeping state, the computer hardware, the system, and applications running on the computer must be capable of responding immediately to the power switch, communications events, and other actions. If all applications handle power state transitions gracefully, the user will perceive a more elegant and integrated system. Applications that do not handle these transitions can fail when the power is turned off and then on, because of data loss or a dependency on a device that may have been removed.

The following are other benefits of OnNow:

  • Eliminates startup and shutdown delays. The computer need not perform a full system boot when starting or a full system shutdown when turned off. Instead, the computer enters and leaves the sleeping state.
  • Enables automated tasks to run while the computer is "off." The Task Scheduler provides a user interface that enables the user to schedule applications to run, even when the system is in the sleeping state. The Task Scheduler uses waitable timers to ensure that the system is ready when the application is scheduled to run. For more information, see the help file included with the Task Scheduler.
  • Enables per-device power management. Devices that are not in use can save power by entering the sleeping state.
  • Improves power efficiency. Power efficiency is particularly important on portable computers. The life of a battery on a portable computer is significantly reduced by use of the CPU and hard drive. When the computer is running on batteries, the system attempts to put the CPU and hard drive into a low power state whenever they are idle.
  • The Power Management control panel application provides a simple user interface through which the user can specify preferences. The user can create power schemes, set alarms, and specify battery options. The operating system coordinates all power management activities, based on power management policies. For more information, see the help file included with the Power Management control panel application.


System Power Status

The system power status indicates whether the source of power for a computer is a system battery or AC power. For computers that use batteries, the system power status also indicates how much battery life remains and whether the battery is currently charging.

You can retrieve the system power status by using the GetSystemPowerStatus function. This function copies information about the power supply and battery status to a SYSTEM_POWER_STATUS structure. This structure indicates whether the system has a battery, and if it does, whether the battery is being used, and what percentage of the charge remains. The system broadcasts the PBT_APMPOWERSTATUSCHANGE event to all applications when the power status changes. When your application receives this event, it should call GetSystemPowerStatus again to determine what changed.

Applications and installable drivers typically use the system power status to determine whether continued operation is feasible. For example, before an application performs background operations such as compressing or paginating a file, it should call GetSystemPowerStatus to check whether the system is on batteries. As another example, an application that is beginning a lengthy operation should call GetSystemPowerStatus to check the status to determine whether enough battery power exists to complete the operation.

If power is low, an application can request user intervention or request that the system shut itself down. You can suspend system operation by using the SetSystemPowerState function. This generates a power management event that, if approved by all applications and drivers in the system, shuts down the system until the user restores power. Even if a computer uses AC power, an application that determines that the system is idle can request that the system shut itself down to save power.

Applications should also use the GetDevicePowerState function to check whether the hard disk is powered down. Applications that do not perform these checks can cause the hard disk to power up frequently, reducing any power saved by the system through power management. Instead, applications should wait until the user performs an action that causes the hard disk to power up before performing background operations. Applications should also shut down when possible, to save power and reduce noise.


System Power States

To the user, the system appears to be either on or off. There are no other detectable states. However, you should be aware that the system supports these power states. The following table lists the power states from highest to lowest power consumption.

Power State | Description
Working | The system is fully usable; power saving occurs on a per-device basis. Devices that are not in use can save power by entering a lower power state.
Sleeping | Appears to be off. Power consumption is reduced to one of several levels of power consumption, depending on how the system is to be used. The lower the level of power consumption, the more time it takes the system to return to the working state.
Soft Off | Appears to be off. Very low power consumption. The working context can be restored if it is stored on nonvolatile media.
Mechanical Off | No power consumption. The system returns to the working state only after a full reboot.

Applications that assume the system is always in the working state can inadvertently keep it from entering a lower power state. To avoid this, applications should watch for the WM_POWERBROADCAST message. WM_POWERBROADCAST notifies applications of changes in the power state. The Sleeping State

There are different levels in the sleeping state. The following table shows the system sleep states and their corresponding advanced configuration and power interface (ACPI) and advanced power management (APM) states.

System Sleep State | ACPI State | APM State
PowerSystemWorking | S0 | Working
PowerSystemSleeping1 | S1 | SUSPEND
PowerSystemSleeping2 | S2 | SUSPEND
PowerSystemSleeping3 | S3 | SUSPEND
PowerSystemHibernate | S4 | SUSPEND

It takes longer to restore a system from a lower power state than from a higher power state because of the extra work the hardware may have to do (stabilize power supply, reinitialize the processor, and so forth). By default, the system will use the lowest sleeping state supported by all enabled wake-up devices, within the specified latency requirements. To set the default sleep state, the user can use the Power Management control panel application. An application can specify its latency requirements using the RequestWakeupLatency function.

After the system has selected the sleeping state the system will enter, it requests permission to enter the sleeping state from all applications, using the PBT_APMQUERYSUSPEND event. If no applications deny the request, the system broadcasts it to the drivers by using IRP_MJ_POWER and IRP_MN_QUERY_POWER. If any drivers deny the request, the system requests the next highest sleeping state, until a sleep state is successfully entered or there are no more available sleep states. The user can configure the system to take one of the following actions if the requested sleep state is higher than the preferred sleep state:

  • Display a dialog box indicating the problem.
  • Ignore the chosen state and use a preferred power state.
  • Ignore the preferred power state and use the chosen state.


System Power Management Events

A power management event is a change in either the system power status or the operational mode of a device or the system. Because these events can affect the operation of applications and installable drivers and can lead to loss of data, the system notifies all applications and installable drivers by broadcasting a WM_POWERBROADCAST message for each event.

System Power Status Events

A system power status event occurs when there is a change in the power supply or in the system battery status. For example, the system broadcasts a PBT_APMPOWERSTATUSCHANGE event whenever the user switches from battery to AC power or vice versa. The system also broadcasts this event when remaining battery power slips below the threshold specified by the user or if the battery power changes by a specified percentage.

Operational Mode Events

An operational mode event occurs when there is a change in power consumption, such as the system shutting itself down or the user turning the system off. If applications and drivers do not prepare for changes in operational mode, they can lose data. Therefore, the system broadcasts events about these changes before they actually occur. For example, if the system determines that it is idle, it broadcasts a PBT_APMSUSPEND event notifying applications and drivers that it is about to suspend operation and shut itself down to save power. The applications and drivers can prepare for this suspension by closing files and saving data that may otherwise be lost when power is shut off.

The system has two ways to shut itself down. It can suspend operation or carry out critical suspension. An application can also shut the system down by using the SetSystemPowerState function to suspend operation.

When system operation is suspended, power to all devices is lost. The WM_POWERBROADCAST message, broadcast immediately before suspension, allows device drivers to save the state of the device. For many devices (but not all), saving the state means the driver can restore the state when power is eventually restored, allowing the device to continue operation as if power had not been lost.

When the system carries out a critical suspension, the system is shut down immediately because battery power is too low to let the system continue to run. In contrast to suspended operation, the system does not notify applications and drivers before carrying out a critical suspension. This means data may be lost.

When system operation is restored after having been suspended, the system notifies all applications and drivers. It also indicates the manner in which the system was previously shut down so the application or driver can take appropriate steps to restore its data and continue its own operation.

Applications should make every attempt to handle the transition to the sleeping state without any user intervention. When the system requests permission to enter the sleeping state, your application should check to see if it has any open files on removable drives or on the network. If so, the application should autosave and close its files. Applications should deny permission to enter the sleeping state only if an uninterruptible operation is in progress.


Power Management Policy

The system broadcasts a message to all applications and installable drivers whenever a power management event occurs or whenever an application calls the SetSystemPowerState function to suspend operation. The system broadcasts these events through the WM_POWERBROADCAST message, setting the wParam parameter to the appropriate power management event. For example, the PBT_APMPOWERSTATUSCHANGE event indicates a system power status change. You must ensure that your application responds to the WM_POWERBROADCAST message to properly stop activity when the system enters the sleeping state and to recover transparently when the system enters the working state. When the system enters the sleeping state, it closes network connections. The user can change the hardware configuration or power supply while the system is in the sleeping state.

The system broadcasts a PBT_APMQUERYSUSPEND event to request permission to suspend system operation. The system expects each application and driver to determine whether the requested event should occur and to return TRUE if it occurs, or return BROADCAST_QUERY_DENY otherwise. Any application or driver can deny the request and prevent the event from occurring.

The system broadcasts a PBT_APMSUSPEND event immediately before suspending operation. This gives applications and drivers one last chance to prepare for the event. In many cases, the system broadcasts these messages without requesting permission to do so. This happens, for example, if an application forces suspension with the SetSystemPowerState function.

The system broadcasts the PBT_APMQUERYSUSPENDFAILED event whenever a requested event is denied. These events notify applications and drivers to continue operation as usual.

The system broadcasts the PBT_APMRESUMESUSPEND or PBT_APMRESUMECRITICAL event when system operation has been restored. If an application received a PBT_APMSUSPEND event before the computer was suspended, it will receive the PBT_APMRESUMESUSPEND event. Otherwise, it will receive the PBT_APMRESUMECRITICAL event.


System Sleep Criteria

As long as the system determines that there is application activity, it will not put the system or any devices into the sleeping state. The system can detect certain activities, such as user input or network communications. However, there are other activities that the system cannot track. For example, a presentation application requires the screen for display. However, it may appear that the application is idle during the presentation, causing the system to turn off the screen. To notify the system that your application is busy, use the SetThreadExecutionState function. This function prevents the system from placing the system or any devices into the sleeping state while the application is running.

Presentation and multimedia applications must call SetThreadExecutionState with ES_DISPLAY_REQUIRED so that the system will know that it should not put the display device into the sleeping state. Event-handling applications, such as utilities for managing incoming faxes, must call SetThreadExecutionState with ES_SYSTEM_REQUIRED, handle the event, then clear the flag so the system can put the system back into the sleeping state. Note that most productivity applications do not need to use SetThreadExecutionState because the system can usually determine activity by user input.

To maintain the time since the last user input, the system uses a display idle timer and a system idle timer. The system compares the idle timers to the time-out values the user sets for the display and system by using the Power Management control panel application. If the display idle timer value is greater than the display time-out value, and no threads have requested the display by calling SetThreadExecutionState with ES_DISPLAY_REQUIRED, the system puts the display into the sleeping state. Similarly, if the system idle timer is greater than the system time-out value, and no applications have requested the system by calling SetThreadExecutionState with ES_SYSTEM_REQUIRED, the system puts the system into the sleeping state.

The system maintains a count of applications that have called SetThreadExecutionState. The system tracks each thread that calls SetThreadExecutionState and adjusts the counter accordingly. If this counter reaches zero and there has not been any user input, the system puts the system into the sleeping state by calling SetSystemPowerState.

When you call the SetSystemPowerState function with fForce set to TRUE, the system generally puts the system into the sleeping state. However, if the next scheduled wake-up time is less than 30 seconds from the current time, SetSystemPowerState leaves the system in the working state and returns FALSE, regardless of the value of fForce.


System Wake-up Events

Your application can restore an On-Now capable computer that is in a sleeping state to the working state by using a scheduled time or a device event. This is known as a wake-up event. Use a waitable timer object to specify the time at which the system should wake. To create the object, use the CreateWaitableTimer function. To set the timer, use the SetWaitableTimer function. The pDueTime parameter specifies when the timer will be signaled. To specify that the system should wake when the timer is signaled, set the fResume parameter to TRUE.

When the system wakes automatically because of an event (other than power switch or user activity), the system automatically sets its idle timer to at least 1 minute. This timer allows applications to call the SetThreadExecutionState function to indicate that they are busy. This enables the system to shut down without affecting the user. The following criteria determine whether a system shutdown is needed:

  • If the system wakes automatically, it shuts down as soon as the last job is completed, as indicated by the process calling SetThreadExecutionState.
  • If the system wakes automatically, but the user provides new input while the event is handled, the system does not shut down when the last job finishes.
  • If the system is on and the user is active, the system does not enter the sleeping state.
  • If the system is on, no applications are busy, and the user is inactive for a long time, the system enters the sleeping state when the timer expires.

When the system wakes automatically, the system broadcasts the PBT_APMRESUMEAUTOMATIC event to all applications. Because the user is not present, most applications should do nothing. Event-handling applications, such as fax servers, should handle their events. If you wish to determine whether the system is in this state, call the IsSystemResumeAutomatic function.

If the system wakes due to user activity after broadcasting PBT_APMRESUMEAUTOMATIC, the system broadcasts the PBT_APMRESUMESUSPEND event and turns on the display. Your application should reopen files that it closed when the system entered the sleeping state, and it should prepare for user input.

If an application called SetSystemPowerState with fForce set to TRUE, no applications will receive the PBT_APMQUERYSUSPEND event when the system enters the sleeping state. If the system is carrying out a critical suspension, no applications will receive the PBT_APMQUERYSUSPEND or PBT_APMSUSPEND event; they will receive only the PBT_APMRESUMECRITICAL event.


Battery Information

Batteries can provide power for portable computers and computers running on an uninterruptible power supply (UPS). On these computers, the operating system provides information on the state of the battery so applications can provide useful functions for the user. (Some older nonstandard battery systems and UPSs are not supported.)

Note that this overview assumes you are familiar with device management.

To obtain information about the battery status, use the GetSystemPowerStatus function. This function which returns general information about all power sources in the system. You should use GetSystemPowerStatus whenever possible.

In some cases, however, detailed information about each individual battery is necessary. For this purpose, each battery device exposes an IOCTL interface. These IOCTL operations are performed using the DeviceIoControl function:

IOCTL_BATTERY_QUERY_INFORMATION
IOCTL_BATTERY_QUERY_STATUS
IOCTL_BATTERY_QUERY_TAG
IOCTL_BATTERY_SET_INFORMATION

To use this interface, an application must follow several steps. First, it must use setup routines to enumerate all devices that have a battery class interface. Note that these devices represent the battery ports, not actual batteries present in the system. The application must then open a handle to each device so it can use DeviceIoControl to send requests to the device, and then acquire tags for any batteries that are inserted. After completing these steps, the application can send queries to each battery device.

Enumerating Battery Devices

To enumerate the battery devices currently on the computer, use the SetupDiGetClassDevs function. The ClassGuid parameter is a pointer to GUID_DEVICE_BATTERY (defined in batclass.h). To enumerate all of the batteries, set the Enumerator parameter to NULL and set the Flags parameter to DIGCF_PRESENT | DIGCF_INTERFACEDEVICE. To obtain the names of the battery devices, use the SetupDiEnumInterfaceDevice and SetupDiGetInterfaceDeviceDetail functions on the data returned. To open a file handle for each of the battery devices, call the CreateFile function with these names .

Battery Tags

Because each battery device represents a slot into which a battery can be inserted, there must be a way to determine when the battery is removed or changed. To do this, each battery that is inserted in a particular slot is assigned a tag. This tag must be used for all queries for information. If the tag provided by the application doesn't match the battery, the query fails, indicating to the application that the battery has been removed or changed. Acquire the tag using the IOCTL_BATTERY_QUERY_TAG operation. If a battery is present in that slot, the tag returned can be passed to any of the other battery IOCTLs to perform other functions. If the battery is changed, any further requests using this tag will fail, and a new one must be acquired using the IOCTL_BATTERY_QUERY_TAG operation. Note that this tag is unique for each battery device, not throughout the system.


Power Management Reference

The following elements are used with power management.

  • Power Management Functions
  • Power Management Structures
  • Power Management Messages
  • Power Management Events


Power Management Functions

The following functions are used with power management.

Function | Description
GetDevicePowerState | Retrieves the current power state of the specified device.
GetSystemPowerStatus | Retrieves the power status of the system.
IsSystemResumeAutomatic | Indicates the current state of the computer.
RequestWakeupLatency | Specifies roughly how quickly the computer should enter the working state.
SetSystemPowerState | Suspends the system by shutting power down.
SetThreadExecutionState | Enables applications to inform the system that it is in use.


GetDevicePowerState

The GetDevicePowerState function retrieves the current power state of the specified device.

BOOL GetDevicePowerState(
  HANDLE hDevice,    // device-context handle
  BOOL *pfOn         // receives power state
);

Parameters

hDevice
[in] Handle to an object on the device, such as a file or socket, or a handle to the device itself.
pfOn
[out] Pointer to the variable that receives the power state. This value is TRUE if the device is fully on. Otherwise, it is FALSE.

Return Values

If the function succeeds, it returns a nonzero value. Otherwise, the function returns zero.

Remarks

An application can use GetSystemPowerState to determine whether a disk or other device is spun up. If the device is not spun up, the application should defer accessing it.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Power Management Overview, Power Management Functions, GetSystemPowerStatus


GetSystemPowerStatus

The GetSystemPowerStatus function retrieves the power status of the system. The status indicates whether the system is running on AC or DC power, whether the battery is currently charging, and how much battery life remains.

BOOL GetSystemPowerStatus(
  LPSYSTEM_POWER_STATUS lpSystemPowerStatus  // status
);

Parameters

lpSystemPowerStatus
[out] Pointer to a SYSTEM_POWER_STATUS structure that receives status information.

Return Values

If the function succeeds, the return value is nonzero.

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

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Power Management Overview, Power Management Functions, SYSTEM_POWER_STATUS


IsSystemResumeAutomatic

The IsSystemResumeAutomatic function indicates the current state of the computer.

BOOL IsSystemResumeAutomatic(VOID);

Parameters

This function has no parameters.

Return Values

If the system was restored to the working state automatically and the user is not active, the function returns TRUE. Otherwise, the function returns FALSE.

Remarks

The PBT_APMRESUMEAUTOMATIC event is broadcast when the system wakes automatically to handle an event. The user is generally not present. If the system detects any user activity after broadcasting the PBT_APMRESUMEAUTOMATIC event, it will broadcast the PBT_APMRESUMESUSPEND event to let applications know they can resume full interaction with the user.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Power Management Overview, Power Management Functions, PBT_APMRESUMEAUTOMATIC, PBT_APMRESUMESUSPEND


RequestWakeupLatency

The RequestWakeupLatency function specifies roughly how quickly the computer should enter the working state.

BOOL RequestWakeupLatency(
  LATENCY_TIME latency      // latency requirement
);

Parameters

latency
[in] Specifies the latency requirement on the time is takes to wake the computer. This parameter can be one of the following values.
Value | Description
LT_LOWEST_LATENCY | PowerSystemSleeping1 state (equivalent to ACPI state S0 and APM state Working).
LT_DONT_CARE | Any latency (default).

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. The function will fail if the device does not support wake-up operations or if the system is entering the sleeping state.

Remarks

The system uses the wake-up latency requirement when choosing a sleeping state. The latency is not guaranteed, because wake-up time is determined by the hardware design of the particular computer.

To cancel a latency request, call RequestWakeupLatency with LT_DONT_CARE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Power Management Overview, Power Management Functions


SetSystemPowerState

The SetSystemPowerState function suspends the system by shutting power down. Depending on the ForceFlag parameter, the function either suspends operation immediately or requests permission from all applications and device drivers before doing so.

The calling process must have the SE_SHUTDOWN_NAME privilege. To enable the SE_SHUTDOWN_NAME privilege, use the AdjustTokenPrivileges function. For more information, see Privileges.

BOOL SetSystemPowerState(
  BOOL fSuspend,  // system state
  BOOL fForce     // forced suspension option
);

Parameters

fSuspend
Windows NT/2000 or later: [in] Specifies the state of the system. If TRUE, the system is suspended. If FALSE, the system hibernates.

Windows 95/98/Me: Ignored.

fForce
[in] Forced suspension. If TRUE, the function broadcasts a PBT_APMSUSPEND event to each application and driver, then immediately suspends operation. If FALSE, the function broadcasts a PBT_APMQUERYSUSPEND event to each application to request permission to suspend operation.

Return Values

If power has been suspended and subsequently restored, the return value is nonzero.

If the system was not suspended, the return value is zero. To get extended error information, call GetLastError.

Remarks

If any application or driver denies permission to suspend operation, the function broadcasts a PBT_APMQUERYSUSPENDFAILED event to each application and driver. If power is suspended, this function returns only after system operation is resumes and related WM_POWERBROADCAST messages have been broadcast to all applications and drivers.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Power Management Overview, Power Management Functions, PBT_APMQUERYSUSPEND, PBT_APMQUERYSUSPENDFAILED, PBT_APMSUSPEND, WM_POWERBROADCAST


SetThreadExecutionState

The SetThreadExecutionState function enables applications to inform the system that it is in use, thereby preventing the system from entering the sleeping power state while the application is running.

EXECUTION_STATE SetThreadExecutionState(
  EXECUTION_STATE esFlags  // execution requirements
);

Parameters

esFlags
[in] Specifies the thread's execution requirements. This parameter can be one or more of the following values.
Flag | Description
ES_SYSTEM_REQUIRED | Informs the system that the thread is performing some operation that is not normally detected as activity by the system.
ES_DISPLAY_REQUIRED | Informs the system that the thread is performing some operation that is not normally detected as display activity by the system.
ES_USER_PRESENT | Informs the system that a user is present. If a user is present, the system will use the power management policies set by the user. Otherwise, the system will not wake the display device and will return to the sleeping state as soon as possible.
ES_CONTINUOUS | Informs the system that the state being set should remain in effect until the next call that uses ES_CONTINUOUS and one of the other state flags is cleared.

Return Values

If the function succeeds, the return value is the previous thread execution state.

If the function fails, the return value is NULL.

Remarks

Activities that are automatically detected include local keyboard or mouse input, server activity, and changing window focus. Activities that are not automatically detected include disk or CPU activity and video display.

Calling SetThreadExecutionState with ES_SYSTEM_REQUIRED prevents the system from putting the computer in the sleeping state by resetting the system idle timer. Calling SetThreadExecutionState with ES_DISPLAY_REQUIRED prevents the system from turning off the display by resetting the display idle timer. Calling SetThreadExecutionState without ES_CONTINUOUS simply resets the idle timer; to keep the display or system in the working state, the thread must call SetThreadExecutionState periodically.

To run properly on a power-managed computer, applications such as fax servers, answering machines, backup agents, and network management applications must use ES_SYSTEM_REQUIRED | ES_CONTINUOUS when they process events. Multimedia applications, such as video players and presentation applications, must use ES_DISPLAY_REQUIRED when they display video for long periods of time without user input. Applications such as word processors, spreadsheets, browsers, and games do not need to call SetThreadExecutionState.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Power Management Overview, Power Management Functions, SetSystemPowerState, WM_POWERBROADCAST


Power Management Structures

The following structure is used with power management.

SYSTEM_POWER_STATUS


SYSTEM_POWER_STATUS

The SYSTEM_POWER_STATUS structure contains information about the power status of the system.

typedef struct _SYSTEM_POWER_STATUS {
    BYTE ACLineStatus;
    BYTE  BatteryFlag;
    BYTE  BatteryLifePercent;
    BYTE  Reserved1;
    DWORD  BatteryLifeTime;
    DWORD  BatteryFullLifeTime;
} SYSTEM_POWER_STATUS, *LPSYSTEM_POWER_STATUS;

Members

ACLineStatus
AC power status. This parameter can be one of the following values.
Value | Meaning
0 | Offline
1 | Online
255 | Unknown status

All other values are reserved.

BatteryFlag
Battery charge status. This parameter can be a combination of the following values.
Value | Meaning
1 | High
2 | Low
4 | Critical
8 | Charging
128 | No system battery
255 | Unknown status

All other values are reserved.

BatteryLifePercent
Percentage of full battery charge remaining. This member can be a value in the range 0 to 100, or 255 if status is unknown. All other values are reserved.
Reserved1
Reserved; must be zero.
BatteryLifeTime
Number of seconds of battery life remaining, or –1 if remaining seconds are unknown.
BatteryFullLifeTime
Number of seconds of battery life when at full charge, or –1 if full battery lifetime is unknown.

Remarks

The system is only capable of estimating BatteryFullTime based on calculations on BatteryLifeTime and BatteryLifePercent. Without smart battery subsystems, this value may not be accurate enough to be useful.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winbase.h; include Windows.h.

See Also

Power Management Overview, Power Management Structures


Power Management Messages

The following message is used with power management.

WM_POWERBROADCAST

Obsolete Message

WM_POWER


WM_POWER

The WM_POWER message is broadcast when the system, typically a battery-powered personal computer, is about to enter suspended mode.

Note The WM_POWER message is obsolete. It is provided only for compatibility with 16-bit Windows-based applications. Win32-based applications should use the WM_POWERBROADCAST message.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWER
  WPARAM wParam,   // power-event notification
  LPARAM lParam    // not used
);

Parameters

wParam
Specifies a power-event notification. This parameter can be one of the following values.
Value | Meaning
PWR_CRITICALRESUME | Indicates that the system is resuming operation after entering suspended mode without first broadcasting a PWR_SUSPENDREQUEST notification message to the application. An application should perform any necessary recovery actions.
PWR_SUSPENDREQUEST | Indicates that the system is about to enter suspended mode.
PWR_SUSPENDRESUME | Indicates that the system is resuming operation after having entered suspended mode normally — that is, the system broadcast a PWR_SUSPENDREQUEST notification message to the application before the system was suspended. An application should perform any necessary recovery actions.

lParam
This parameter is not used.

Return Values

The value an application returns depends on the value of the wParam parameter. If wParam is PWR_SUSPENDREQUEST, the return value is PWR_FAIL to prevent the system from entering the suspended state; otherwise, it is PWR_OK. If wParam is PWR_SUSPENDRESUME or PWR_CRITICALRESUME, the return value is zero.

Remarks

This message is broadcast only to an application that is running on a system that conforms to the Advanced Power Management (APM) basic input/output system (BIOS) specification. The message is broadcast by the power-management driver to each window returned by the EnumWindows function.

The suspended mode is the state in which the greatest amount of power savings occurs, but all operational data and parameters are preserved. Random-access memory (RAM) contents are preserved, but many devices are likely to be turned off.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Power Management Overview, Power Management Messages, EnumWindows, WM_POWERBROADCAST


WM_POWERBROADCAST

The WM_POWERBROADCAST message is broadcast to an application to notify it of power-management events.

A window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Specifies the power-management event. This parameter can be one of the following events.
Event | Meaning
PBT_APMBATTERYLOW | Battery power is low.
PBT_APMOEMEVENT | OEM-defined event occurred.
PBT_APMPOWERSTATUSCHANGE | Power status has changed.
PBT_APMQUERYSUSPEND | Request for permission to suspend.
PBT_APMQUERYSUSPENDFAILED | Suspension request denied.
PBT_APMRESUMEAUTOMATIC | Operation resuming automatically after event.
PBT_APMRESUMECRITICAL | Operation resuming after critical suspension.
PBT_APMRESUMESUSPEND | Operation resuming after suspension.
PBT_APMSUSPEND | System is suspending operation.

lParam
Function-specific data. For most events, this parameter is reserved and not used.

However, if wParam is one of the resume events (PBT_APMRESUME*), the lParam parameter can specify the PBTF_APMRESUMEFROMFAILURE flag. This flag indicates that a suspend operation failed after the PBT_APMSUSPEND event was broadcast.

Return Values

Return TRUE to grant a request.

Return BROADCAST_QUERY_DENY to deny a request.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Power Management Overview, Power Management Messages


Power Management Events

The following are the power management events.

PBT_APMBATTERYLOW
PBT_APMOEMEVENT
PBT_APMPOWERSTATUSCHANGE
PBT_APMQUERYSUSPEND
PBT_APMQUERYSUSPENDFAILED
PBT_APMRESUMEAUTOMATIC
PBT_APMRESUMECRITICAL
PBT_APMRESUMESUSPEND
PBT_APMSUSPEND


PBT_APMBATTERYLOW

The PBT_APMBATTERYLOW event is broadcast to notify applications that battery power is low.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMBATTERYLOW.
lParam
Reserved, must be zero.

Return Values

No return value.

Remarks

This event is broadcast when a system's APM BIOS signals an APM battery low notification. Because some APM BIOS implementations do not provide notifications when batteries are low, this event may never be broadcast on some computers.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, WM_POWERBROADCAST


PBT_APMOEMEVENT

The PBT_APMOEMEVENT event is broadcast when an APM BIOS signals an APM OEM event.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMOEMEVENT.
lParam
A DWORD value that specifies the OEM-defined event code that was signaled by the system's APM BIOS. OEM event codes are in the range 0200h - 02FFh.

Return Values

No return value.

Remarks

Because not all APM BIOS implementations provide OEM event notifications, this event may never be broadcast on some computers.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, WM_POWERBROADCAST


PBT_APMPOWERSTATUSCHANGE

The PBT_APMPOWERSTATUSCHANGE event is broadcast when a change in the power status of the computer is detected, such as a switch from battery power to A/C. The system also broadcasts this event when remaining battery power slips below the threshold specified by the user or if the battery power changes by a specified percentage.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMPOWERSTATUSCHANGE.
lParam
Reserved; must be 0.

Return Values

No return value.

Remarks

An application should process this event by calling the GetSystemPowerStatus function to retrieve the current power status of the computer. In particular, the application should check the ACLineStatus, BatteryFlag, BatteryLifeTime, and BatteryLifePercent members of the SYSTEM_POWER_STATUS structure for any changes. This event can occur when battery life drops to less than 5 minutes, or when the percentage of battery life drops below 10 percent, or if the battery life changes by 3 percent.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, GetSystemPowerStatus, SYSTEM_POWER_STATUS, WM_POWERBROADCAST


PBT_APMQUERYSUSPEND

The PBT_APMQUERYSUSPEND event is broadcast to request permission to suspend the computer. An application that grants permission should carry out preparations for the suspension before returning.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMQUERYSUSPEND.
lParam
A DWORD value that specifies action flags. If bit 0 is 1, the application can prompt the user for directions on how to prepare for the suspension; otherwise, the application must prepare without user interaction. All other bit values are reserved.

Return Values

Return TRUE to grant the request to suspend. To deny the request, return BROADCAST_QUERY_DENY.

Remarks

An application should process this event by first determining whether permission to suspend can be granted. It must not grant permission if doing so would cause a loss of data. The application can prompt the user for directions on how to prepare for suspension only if bit 0 in the Flags parameter is set.

The system allows approximately 20 seconds for an application to remove the WM_POWERBROADCAST message that is sending the PBT_APMQUERYSUSPEND event from the application's message queue. If an application does not remove the message from its queue in less then 20 seconds, the system will assume that the application is in a non-responsive state, and that the application agrees to the sleep request. Applications that do not process their message queues may have their operations interrupted. After it removes the message from the message queue, an application can take as much time as needed to perform any required operations before entering the sleep state. Any operations that could take longer then 20 seconds should be performed at this time, since the system allows only 20 seconds for operations to complete during PBT_APMSUSPEND processing.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, WM_POWERBROADCAST


PBT_APMQUERYSUSPENDFAILED

The PBT_APMQUERYSUSPENDFAILED event is broadcast as a notification that permission to suspend the computer was denied. This event is broadcast if any application or driver returned BROADCAST_QUERY_DENY to a previous PBT_APMQUERYSUSPEND event.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMQUERYSUSPENDFAILED.
lParam
Reserved; must be zero.

Return Values

No return value.

Remarks

Applications typically respond to this event by resuming normal operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, PBT_APMQUERYSUSPEND, WM_POWERBROADCAST


PBT_APMRESUMEAUTOMATIC

The PBT_APMRESUMEAUTOMATIC event is broadcast when the computer wakes up automatically to handle an event. An application will not generally respond unless it is handling the event, because the user is not present.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMRESUMEAUTOMATIC.
lParam
Reserved; must be 0.

Return Values

No return value.

Remarks

If the system detects any user activity after broadcasting PBT_APMRESUMEAUTOMATIC, it will broadcast a PBT_APMRESUMESUSPEND event to let applications know they can resume full interaction with the user.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 98 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, PBT_APMRESUMESUSPEND, WM_POWERBROADCAST


PBT_APMRESUMECRITICAL

The PBT_APMRESUMECRITICAL event is broadcast as a notification that the system has resumed operation after a critical suspension caused by a failing battery.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMRESUMECRITICAL.
lParam
Reserved; must be 0.

Return Values

No return value.

Remarks

Because a critical suspension occurs without prior notification, resources and data previously available may not be present when the application receives this event. The application should attempt to restore its state to the best of its ability. While in a critical suspension, the system maintains the state of the DRAM and local hard disks, but may not maintain net connections. An application may need to take action with respect to files that were open on the network before critical suspension.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, WM_POWERBROADCAST


PBT_APMRESUMESUSPEND

The PBT_APMRESUMESUSPEND event is broadcast as a notification that the system has resumed operation after being suspended.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMRESUMESUSPEND.
lParam
Reserved; must be 0.

Return Values

No return value.

Remarks

An application can receive this event only if it received the PBT_APMSUSPEND event before the computer was suspended. Otherwise, the application will receive a PBT_APMRESUMECRITICAL event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, PBT_APMSUSPEND, PBT_APMRESUMECRITICAL, WM_POWERBROADCAST


PBT_APMSUSPEND

The PBT_APMSUSPEND event is broadcast immediately before the computer enters a suspended state. This event is typically broadcast when all applications and installable drivers have returned TRUE to a previous PBT_APMQUERYSUSPEND event.

A window receives this event through the WM_POWERBROADCAST message. The wParam and lParam parameters are set as described following.

LRESULT CALLBACK WindowProc(
  HWND hwnd,       // handle to window
  UINT uMsg,       // WM_POWERBROADCAST
  WPARAM wParam,   // power-management event
  LPARAM lParam    // function-specific data
);

Parameters

wParam
Set to PBT_APMSUSPEND.
lParam
Reserved; must be 0.

Return Values

No return value.

Remarks

An application should process this event by completing all tasks necessary to save data. This event may also be broadcast, without a prior PBT_APMQUERYSUSPEND event, if an application or device driver uses the SetSystemPowerState function to force suspension.

The system allows approximately 20 seconds for an application to handle this notification. If an application is still performing operations after its time allotment has expired, the system may interrupt the application.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Pbt.h.

See Also

Power Management Overview, Power Management Events, PBT_APMQUERYSUSPEND, SetSystemPowerState, WM_POWERBROADCAST


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.