Using Files In A Driver [펌 MSDN]

Windows Driver Kit: Kernel-Mode Driver Architecture

Using Files In A Driver

The Microsoft Windows executive represents files by file objects, which are executive objects that are managed by the object manager. (Directories are also represented by file objects.)

Kernel-mode components refer to a file by its object name, which is \DosDevices concatenated to the file's full path. (On Microsoft Windows 2000 and later versions of the operating system, \?? is equivalent to \DosDevices.) For example, the object name of the C:\WINDOWS\example.txt file is \DosDevices\C:\WINDOWS\example.txt. You use the object name to open a handle to a file. For more information about object names, see Object Names.

To use a file

1. Open a handle to the file.

   For more information, see Opening a Handle to a File.

2. Perform the intended operations by calling the appropriate ZwXxxFile routines.

   For more information, see Using a File Handle.

3. Close the handle by calling ZwClose.

Every time that you open a handle to a file, the Windows executive creates a file object that represents the file, and it returns an open handle to that object. Therefore, multiple file objects can exist for a single file. (Because a user-mode application can copy a handle, multiple handles can also exist for the same file object.) After all the open handles to a file object are closed, the Windows executive deletes the file object.

Windows Driver Kit: Kernel-Mode Driver Architecture

Opening a Handle to a File

To open a handle to a file, perform the following steps:

1. Create an OBJECT_ATTRIBUTES structure, and call the InitializeObjectAttributes routine to initialize the structure. You specify the file's object name as the ObjectName parameter to InitializeObjectAttributes.
2. Open a handle to the file by passing the OBJECT_ATTRIBUTES structure to IoCreateFile, ZwCreateFile, or ZwOpenFile.

   If the file does not exist, IoCreateFile and ZwCreateFile will create it, whereas ZwOpenFile will return STATUS_OBJECT_NAME_NOT_FOUND.

Note that drivers almost always use ZwCreateFile or ZwOpenFile rather than IoCreateFile.

When you call IoCreateFile, ZwCreateFile, or ZwOpenFile, the Windows executive creates a new file object to represent the file, and it provides an open handle to the object. This file object persists until you close all the open handles to it.

Whichever routine you call, you must pass the access rights you need as the DesiredAccess parameter. These rights must cover all the operations that your driver will perform. The following table lists these operations and the corresponding access right to request.

Operation	Required Access Right
Read from the file	FILE_READ_DATA or GENERIC_READ
Write to the file	FILE_WRITE_DATA or GENERIC_WRITE
Write only to the end of the file	FILE_APPEND_DATA
Read the file's metadata, such as the file's creation time	FILE_READ_ATTRIBUTES or GENERIC_READ
Write the file's metadata, such as the file's creation time	FILE_WRITE_ATTRIBUTES or GENERIC_WRITE

For more information about the values available for DesiredAccess, see ZwCreateFile.

Windows Driver Kit: Kernel-Mode Driver Architecture

Using a File Handle

The following table lists the operations that drivers can perform on a file handle and the corresponding routines that carry out those operations.

Operation	Routine to Call
Read data from the file	ZwReadFile
Write data to the file	ZwWriteFile
Read metadata for the file or file handle	ZwQueryInformationFile
Write metadata for the file or file handle	ZwSetInformationFile

To indicate where in the file to begin reading or writing data, you pass a ByteOffset parameter to ZwReadFile or ZwWriteFile, respectively.

If you opened the handle with FILE_APPEND_DATA access, all data is written to the end of the file, and the ByteOffset parameter is ignored.

Under certain conditions, the I/O manager maintains a current file-position pointer for the file. You can begin a read or write operation at that position by specifying NULL for ByteOffset. For more information about when the current file-position pointer exists, see Using the Current File Position later in this section.

To examine or change information about a file, call ZwQueryInformationFile or ZwSetInformationFile, respectively. You specify the particular type of information as the FileInformationClass parameter to each routine. For example, setting FileInformationClass to FileBasicInformation allows you to examine or change a FILE_BASIC_INFORMATION structure, which contains members for the file-creation time and the last-access time, among others. For information about all the possible values for FileInformationClass, see ZwQueryInformationFile and ZwSetInformationFile.