IoCheckShareAccess function (wdm.h)
The IoCheckShareAccess routine is called by file system drivers (FSDs) or other highest-level drivers to check whether shared access to a file object is permitted.
Syntax
NTSTATUS IoCheckShareAccess(
[in] ACCESS_MASK DesiredAccess,
[in] ULONG DesiredShareAccess,
[in, out] PFILE_OBJECT FileObject,
[in, out] PSHARE_ACCESS ShareAccess,
[in] BOOLEAN Update
);
Parameters
[in] DesiredAccess
Specifies an ACCESS_MASK value that indicates the desired type of access to the given FileObject for the current open request. Drivers compute the value of this parameter by taking the requested access in the IRP_MJ_CREATE request and then applying SeAccessCheck for each security descriptor to determine the actual access granted. If the granted access is more restrictive than the desired access, then that is an error, and the driver should complete the current IRP with a status of STATUS_ACCESS_DENIED. (Note that SeAccessCheck clears the MAXIMUM_ALLOWED bit in the granted access; be sure to not use that bit when comparing desired access to granted access.) The driver then passes the granted access as the value of DesiredAccess.
[in] DesiredShareAccess
Specifies the desired type of shared access to FileObject for the current open request. The value of this parameter is usually the same as the ShareAccess passed to the file system or highest-level driver by the I/O manager when the open request was made. This value can be zero, or any combination of the following:
FILE_SHARE_READ
FILE_SHARE_WRITE
FILE_SHARE_DELETE
[in, out] FileObject
Pointer to the file object for which to check access for the current open request.
[in, out] ShareAccess
Pointer to the common share-access data structure associated with FileObject. Drivers should treat this structure as opaque.
[in] Update
Specifies whether to update the share-access status for FileObject. A Boolean value of TRUE means this routine will update the share access information for the file object if the open request is permitted.
Return value
IoCheckShareAccess returns STATUS_SUCCESS if the requester's access to the file object is compatible with the way in which it is currently open. If the request is denied because of a sharing violation, then STATUS_SHARING_VIOLATION is returned.
Remarks
IoCheckShareAccess checks a file object open request to determine whether the types of desired and shared accesses specified are compatible with the way in which the file object is currently being accessed by other opens.
File systems maintain state about files through structures called file control blocks (FCBs). The SHARE_ACCESS is a structure describing how the file is currently accessed by all opens. This state is contained in the FCB as part of the open state for each file object. Each file object should have only one share access structure. Other highest-level drivers might call this routine to check the access requested when a file object representing such a driver's device object is opened.
IoCheckShareAccess is not an atomic operation. Therefore, drivers calling this routine must protect the shared file object passed to IoCheckShareAccess by means of some kind of lock, such as a mutex or a resource lock, in order to prevent corruption of the shared access counts.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 2000. |
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI compliance rules | HwStorPortProhibitedDDIs(storport), IrqlIoPassive2(wdm), PowerIrpDDis(wdm) |