Edit

Opening a Handle to a File

  • Article

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

  1. Create an OBJECT_ATTRIBUTES structure, and call the InitializeObjectAttributes macro 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.