OpenFileById function

Opens the file that matches the specified identifier.

Syntax

HANDLE OpenFileById(
  HANDLE                hVolumeHint,
  LPFILE_ID_DESCRIPTOR  lpFileId,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwFlagsAndAttributes
);

Parameters

hVolumeHint

TBD

lpFileId

TBD

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.

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.

Value Meaning
FILE_SHARE_DELETE
0x00000004
Enables subsequent open operations on an object to request delete access.

Otherwise, other processes cannot open the object if they request delete access.

If this flag is not specified, but the object has been opened for delete access, the function fails.

FILE_SHARE_READ
0x00000001
Enables subsequent open operations on an object to request read access.

Otherwise, other processes cannot open the object if they request read access.

If this flag is not specified, but the object has been opened for read access, the function fails.

FILE_SHARE_WRITE
0x00000002
Enables subsequent open operations on an object to request write access.

Otherwise, other processes cannot open the object if they request write access.

If this flag is not specified, but the object has been opened for write access or has a file mapping with write access, the function fails.

lpSecurityAttributes

Reserved.

dwFlagsAndAttributes

TBD

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

   
Windows version Windows Vista [desktop apps only] 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

See Also

ACCESS_MASK

CloseHandle

CreateFile

DeleteFile

FILE_ID_DESCRIPTOR

File Management Functions

GetFileInformationByHandleEx

GetOverlappedResult

OVERLAPPED

OpenFile

ReadFile

WriteFile