Win32 File API GetFileInformationByHandle function

Download EaseFilter Monitor, Control and Encryption Filter Driver SDK Setup File
Download EaseFilter Monitor, Control and Encryption Filter Driver SDK Zip File

Retrieves file information for the specified file.

For a more advanced version of this function, see GetFileInformationByHandleEx.

To set file information using a file handle, see SetFileInformationByHandle.

Syntax

BOOL GetFileInformationByHandle(    
HANDLE                       hFile,    
LPBY_HANDLE_FILE_INFORMATION lpFileInformation 
);  

Parameters

hFile

A handle to the file that contains the information to be retrieved.

This handle should not be a pipe handle.

lpFileInformation

A pointer to a BY_HANDLE_FILE_INFORMATION structure that receives the file information.

Return Value

If the function succeeds, the return value is nonzero and file information data is contained in the buffer pointed to by the lpFileInformation parameter.

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

Remarks

Depending on the underlying network features of the operating system and the type of server connected to, theGetFileInformationByHandle function may fail, return partial information, or full information for the given file.

You can compare the VolumeSerialNumber and FileIndex members returned in the BY_HANDLE_FILE_INFORMATION structure to determine if two paths map to the same target; for example, you can compare two file paths and determine if they map to the same directory.

IIn Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Transacted Operations

If there is a transaction bound to the thread at the time of the call, then the function returns the compressed file size of the isolated file view. For more information, see About Transactional NTFS.

Examples

The following C++ example shows how to use SetFileInformationByHandle function.

//...
  HANDLE hFile = CreateFile( TEXT("tempfile"), 
                             GENERIC_READ | GENERIC_WRITE | DELETE,
                             0 /* exclusive access */,
                             NULL, 
                             CREATE_ALWAYS,
                             0, 
                             NULL);
if (hFile != INVALID_HANDLE_VALUE)
{
BY_HANDLE_FILE_INFORMATION fhi;

BOOL fResult = GetFileInformationByHandle( hFile, 
                                           &fhi);

if (fResult)
 {
  // File will be deleted upon CloseHandle.
  _tprintf( TEXT("GetFileInformationByHandle got file information\n") );
 
 }
else
 {
  _tprintf( TEXT("error %lu:  GetFileInformationByHandle failed.\n"), 
            GetLastError() );
 }

CloseHandle(hFile); 

// At this point, the file is closed.
}
else
{
_tprintf( TEXT("error %lu:  could not create tempfile\n"),
GetLastError() );
}
//...