OpenFileById function (winbase.h)
Opens the file that matches the specified identifier.
Syntax
HANDLE OpenFileById(
[in] HANDLE hVolumeHint,
[in] LPFILE_ID_DESCRIPTOR lpFileId,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwFlagsAndAttributes
);
Parameters
[in] hVolumeHint
A handle to any file on a volume or share on which the file to be opened is stored.
[in] lpFileId
A pointer to a FILE_ID_DESCRIPTOR that identifies the file to open.
[in] dwDesiredAccess
The access to the object. Access can be read, write, or both.
For more information, see File Security and Access Rights. You cannot request an access mode that conflicts with the sharing mode that is specified in an open request that has an open handle.
If this parameter is zero (0), the application can query file and device attributes without accessing a device. This is useful for an application to determine the size of a floppy disk drive and the formats it supports without requiring a floppy in a drive. It can also be used to test for the existence of a file or directory without opening them for read or write access.
[in] dwShareMode
The sharing mode of an object, which can be read, write, both, or none.
You cannot request a sharing mode that conflicts with the access mode that is specified in an open request that has an open handle, because that would result in the following sharing violation: (ERROR_SHARING_VIOLATION). For more information, see Creating and Opening Files.
If this parameter is zero (0) and OpenFileById succeeds, the object cannot be shared and cannot be opened again until the handle is closed. For more information, see the Remarks section of this topic.
The sharing options remain in effect until you close the handle to an object.
To enable a processes to share an object while another process has the object open, use a combination of one or more of the following values to specify the access mode they can request to open the object.
[in, optional] lpSecurityAttributes
Reserved.
[in] dwFlagsAndAttributes
The file flags.
When OpenFileById opens a file, it combines the file flags with existing file attributes, and ignores any supplied file attributes. This parameter can include any combination of the following flags.
| Value | Meaning |
|---|---|
|
A file is being opened for a backup or restore operation. The system ensures that the calling process
overrides file security checks when the process has SE_BACKUP_NAME and
SE_RESTORE_NAME privileges. For more information, see
Changing Privileges in a Token.
You must set this flag to obtain a handle to a directory. A directory handle can be passed to some functions instead of a file handle. For more information, see Directory Handles. |
|
The system opens a file with no system caching. This flag does not affect hard disk caching. When combined
with FILE_FLAG_OVERLAPPED, the flag gives maximum asynchronous performance, because
the I/O does not rely on the synchronous operations of the memory manager. However, some I/O operations take
more time, because data is not being held in the cache. Also, the file metadata may still be cached. To flush
the metadata to disk, use the FlushFileBuffers
function.
An application must meet certain requirements when working with files that are opened with FILE_FLAG_NO_BUFFERING:
An application can determine a volume sector size by calling the GetDiskFreeSpace function. |
|
The file data is requested, but it should continue to be located in remote storage. It should not be transported back to local storage. This flag is for use by remote storage systems. |
|
When this flag is used, normal reparse point processing does not occur, and OpenFileById attempts to open the reparse point. When a file is opened, a file handle is returned, whether or not the filter that controls the reparse point is operational. This flag cannot be used with the CREATE_ALWAYS flag. If the file is not a reparse point, then this flag is ignored. |
|
The file is being opened or created for asynchronous I/O. When the operation is complete, the event
specified to the call in the OVERLAPPED structure is
set to the signaled state. Operations that take a significant amount of time to process return
ERROR_IO_PENDING.
If this flag is specified, the file can be used for simultaneous read and write operations. The system does not maintain the file pointer, therefore you must pass the file position to the read and write functions in the OVERLAPPED structure or update the file pointer. If this flag is not specified, then I/O operations are serialized, even if the calls to the read and write functions specify an OVERLAPPED structure. |
|
A file is accessed randomly. The system can use this as a hint to optimize file caching. |
|
A file is accessed sequentially from beginning to end. The system can use this as a hint to optimize file
caching. If an application moves the file pointer for random access, optimum caching may not occur. However,
correct operation is still guaranteed.
Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes. |
|
The system writes through any intermediate cache and goes directly to disk.
If FILE_FLAG_NO_BUFFERING is not also specified, so that system caching is in effect, then the data is written to the system cache, but is flushed to disk without delay. If FILE_FLAG_NO_BUFFERING is also specified, so that system caching is not in effect, then the data is immediately flushed to disk without going through the system cache. The operating system also requests a write-through the hard disk cache to persistent media. However, not all hardware supports this write-through capability. |
Return value
If the function succeeds, the return value is an open handle to a specified file.
If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.
Remarks
Use the CloseHandle function to close an object handle that OpenFileById returns.
If you call OpenFileById on a file that is pending deletion as a result of a previous call to DeleteFile, the function fails. The operating system delays file deletion until all handles to the file are closed. GetLastError returns ERROR_ACCESS_DENIED.
In Windows 8 and Windows Server 2012, this function is supported by the following technologies.
| Technology | Supported |
|---|---|
| Server Message Block (SMB) 3.0 protocol | No |
| SMB 3.0 Transparent Failover (TFO) | No |
| SMB 3.0 with Scale-out File Shares (SO) | No |
| Cluster Shared Volume File System (CsvFS) | Yes |
| Resilient File System (ReFS) | Yes |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | winbase.h (include Windows.h) |
| Library | Kernel32.lib; FileExtd.lib on Windows Server 2003 and Windows XP |
| DLL | Kernel32.dll |
| Redistributable | Windows SDK on Windows Server 2003 and Windows XP. |