IoCheckShareAccess-Funktion (wdm.h)

Artikel
08/08/2023

Die IoCheckShareAccess-Routine wird von Dateisystemtreibern (FSDs) oder anderen Treibern der höchsten Ebene aufgerufen, um zu überprüfen, ob der freigegebene Zugriff auf ein Dateiobjekt zulässig ist.

Syntax

NTSTATUS IoCheckShareAccess(
  [in]      ACCESS_MASK   DesiredAccess,
  [in]      ULONG         DesiredShareAccess,
  [in, out] PFILE_OBJECT  FileObject,
  [in, out] PSHARE_ACCESS ShareAccess,
  [in]      BOOLEAN       Update
);

Parameter

[in] DesiredAccess

Gibt einen ACCESS_MASK Wert an, der den gewünschten Zugriffstyp auf das angegebene FileObject für die aktuelle offene Anforderung angibt. Treiber berechnen den Wert dieses Parameters, indem sie den angeforderten Zugriff in der IRP_MJ_CREATE-Anforderung übernehmen und dann SeAccessCheck für jeden Sicherheitsdeskriptor anwenden, um den tatsächlich gewährten Zugriff zu bestimmen. Wenn der gewährte Zugriff restriktiver ist als der gewünschte Zugriff, dann ist dies ein Fehler, und der Treiber sollte den aktuellen IRP mit einer status STATUS_ACCESS_DENIED abschließen. (Beachten Sie, dass SeAccessCheck das MAXIMUM_ALLOWED Bit im gewährten Zugriff löscht. Achten Sie darauf, dass Sie dieses Bit nicht verwenden, wenn Sie den gewünschten Zugriff mit dem gewährten Zugriff vergleichen.) Der Treiber übergibt dann den gewährten Zugriff als Wert von DesiredAccess.

[in] DesiredShareAccess

Gibt den gewünschten Typ des freigegebenen Zugriffs auf FileObject für die aktuelle offene Anforderung an. Der Wert dieses Parameters ist in der Regel der gleiche wie der ShareAccess , der vom E/A-Manager an das Dateisystem oder den Treiber der obersten Ebene übergeben wurde, als die offene Anforderung gestellt wurde. Dieser Wert kann null oder eine beliebige Kombination aus folgendem Wert sein:

FILE_SHARE_READ

FILE_SHARE_WRITE

FILE_SHARE_DELETE

[in, out] FileObject

Zeiger auf das Dateiobjekt, für das der Zugriff auf die aktuelle offene Anforderung überprüft werden soll.

[in, out] ShareAccess

Zeiger auf die common share-access-Datenstruktur, die FileObject zugeordnet ist. Treiber sollten diese Struktur als undurchsichtig behandeln.

[in] Update

Gibt an, ob die share-access-status für FileObject aktualisiert werden soll. Ein boolescher Wert von TRUE bedeutet, dass diese Routine die Freigabezugriffsinformationen für das Dateiobjekt aktualisiert, wenn die offene Anforderung zulässig ist.

Rückgabewert

IoCheckShareAccess gibt STATUS_SUCCESS zurück, wenn der Zugriff des Anforderers auf das Dateiobjekt mit der Art und Weise kompatibel ist, in der es derzeit geöffnet ist. Wenn die Anforderung aufgrund einer Freigabeverletzung abgelehnt wird, wird STATUS_SHARING_VIOLATION zurückgegeben.

Hinweise

IoCheckShareAccess überprüft eine offene Dateiobjektanforderung, um festzustellen, ob die angegebenen Typen von gewünschten und freigegebenen Zugriffen mit der Art und Weise kompatibel sind, in der derzeit von anderen Geöffneten auf das Dateiobjekt zugegriffen wird.

Dateisysteme verwalten den Zustand von Dateien über Strukturen, die als Dateisteuerungsblöcke (FCBs) bezeichnet werden. Die SHARE_ACCESS ist eine Struktur, die beschreibt, wie alle Geöffneten derzeit auf die Datei zugreifen. Dieser Zustand ist im FCB als Teil des geöffneten Zustands für jedes Dateiobjekt enthalten. Jedes Dateiobjekt sollte nur eine Freigabezugriffsstruktur aufweisen. Andere Treiber der höchsten Ebene können diese Routine aufrufen, um den angeforderten Zugriff zu überprüfen, wenn ein Dateiobjekt, das das Geräteobjekt eines solchen Treibers darstellt, geöffnet wird.

IoCheckShareAccess ist kein atomarer Vorgang. Daher müssen Treiber, die diese Routine aufrufen, das freigegebene Dateiobjekt, das an IoCheckShareAccess übergeben wird, durch eine Art von Sperre schützen, z. B. einen Mutex oder eine Ressourcensperre, um eine Beschädigung der Anzahl der freigegebenen Zugriffe zu verhindern.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), IrqlIoPassive2(wdm), PowerIrpDDis(wdm)