Contains information that the GetFileInformationByHandle function retrieves.

Syntax

typedef struct _BY_HANDLE_FILE_INFORMATION {
  DWORD    dwFileAttributes;
  FILETIME ftCreationTime;
  FILETIME ftLastAccessTime;
  FILETIME ftLastWriteTime;
  DWORD    dwVolumeSerialNumber;
  DWORD    nFileSizeHigh;
  DWORD    nFileSizeLow;
  DWORD    nNumberOfLinks;
  DWORD    nFileIndexHigh;
  DWORD    nFileIndexLow;
}BY_HANDLE_FILE_INFORMATION, *PBY_HANDLE_FILE_INFORMATION;

Members

dwFileAttributes

The file attributes. This member can be a combination of one or more of the following values.

Attribute	Meaning
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	The file or directory is an archive file. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED 2048 (0x800)	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY 16 (0x10)	The handle identifies a directory.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	The file or directory is encrypted. For a file, this means that all data in the file is encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	The file does not have other attributes. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	The file data is not available immediately. This attribute indicates that the file data is physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software. Applications should not arbitrarily change this attribute.
FILE_ATTRIBUTE_READONLY 1 (0x1)	The file or directory is read-only. Applications can read the file, but cannot write to it or delete it. If it is a directory, applications cannot delete it.
FILE_ATTRIBUTE_REPARSE_POINT 1024 (0x400)	The file or directory has an associated reparse point.
FILE_ATTRIBUTE_SPARSE_FILE 512 (0x200)	The file is a sparse file.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	The file or directory is part of the operating system or is used exclusively by the operating system.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	The file is being used for temporary storage. File systems avoid writing data back to mass storage if sufficient cache memory is available, because often the application deletes the temporary file after the handle is closed. In that case, the system can entirely avoid writing the data. Otherwise, the data will be written after the handle is closed.
FILE_ATTRIBUTE_VIRTUAL 65536 (0x10000)	A file is a virtual file.

 

ftCreationTime

A FILETIME structure that specifies when a file or directory is created. If the underlying file system does not support creation time, this member is zero (0).

ftLastAccessTime

A FILETIME structure. For a file, the structure specifies the last time that a file is read from or written to. For a directory, the structure specifies when the directory is created. For both files and directories, the specified date is correct, but the time of day is always set to midnight. If the underlying file system does not support the last access time, this member is zero (0).

ftLastWriteTime

A FILETIME structure. For a file, the structure specifies the last time that a file is written to. For a directory, the structure specifies when the directory is created. If the underlying file system does not support the last write time, this member is zero (0).

dwVolumeSerialNumber

The serial number of the volume that contains a file.

nFileSizeHigh

The high-order part of the file size.

nFileSizeLow

The low-order part of the file size.

nNumberOfLinks

The number of links to this file. For the FAT file system this member is always 1. For the NTFS file system, it can be more than 1.

nFileIndexHigh

The high-order part of a unique identifier that is associated with a file. For more information, see nFileIndexLow.

nFileIndexLow

The low-order part of a unique identifier that is associated with a file.

The identifier (low and high parts) and the volume serial number uniquely identify a file on a single computer. To determine whether two open handles represent the same file, combine the identifier and the volume serial number for each file and compare them.

Remarks

The identifier that is stored in the nFileIndexHigh and nFileIndexLow members is called the file ID. Support for file IDs is file system-specific. File IDs are not guaranteed to be unique over time, because file systems are free to reuse them. In some cases, the file ID for a file can change over time.

In the FAT file system, the file ID is generated from the first cluster of the containing directory and the byte offset within the directory of the entry for the file. Some defragmentation products change this byte offset. (Windows in-box defragmentation does not.) Thus, a FAT file ID can change over time. Renaming a file in the FAT file system can also change the file ID, but only if the new file name is longer than the old one.

In the NTFS file system, a file keeps the same file ID until it is deleted. You can replace one file with another file without changing the file ID by using the ReplaceFile function. However, the file ID of the replacement file, not the replaced file, is retained as the file ID of the resulting file.

Not all file systems can record creation and last access time, and not all file systems record them in the same manner. For example, on a Windows FAT file system, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (the access date). On the NTFS file system, access time has a resolution of 1 hour. For more information, see File Times.

Requirements

See Also

FILETIME

GetFileInformationByHandle

Send comments about this topic to Microsoft

Build date: 7/9/2009