Funzione FsRtlOplockFsctrlEx (ntifs.h)

Articolo
12/21/2024

La routine FsRtlOplockFsctrlEx esegue varie operazioni di blocco opportunistico (oplock) per conto di un file system o di un driver di filtro.

Sintassi

NTSTATUS FsRtlOplockFsctrlEx(
  [in] POPLOCK Oplock,
  [in] PIRP    Irp,
  [in] ULONG   OpenCount,
  [in] ULONG   Flags
);

Parametri

[in] Oplock

Puntatore oplock opaco per il file. Questo puntatore deve essere stato inizializzato da una chiamata precedente a FsRtlInitializeOplock.

[in] Irp

Puntatore all'IRP per l'operazione di I/O. Questo parametro è obbligatorio e non può essere NULL.

[in] OpenCount

Numero di handle utente per il file, se viene richiesto un oplock esclusivo. L'impostazione di un valore diverso da zero per una richiesta oplock di livello 2, R o RH indica che sono presenti blocchi di intervallo di byte nel file. Per informazioni sui tipi di oplock, vedere Panoramica di Oplock .

[in] Flags

Maschera di bit per le operazioni di oplock associate. Un file system o un driver di filtro imposta i bit per specificare il comportamento di FsRtlOplockFsctrlEx. Questo parametro include le opzioni seguenti:

Bandiera	Significato
OPLOCK_FSCTRL_FLAG_ALL_KEYS_MATCH (0x00000001)	Il file system ha verificato che tutte le chiavi oplock in qualsiasi handle aperto corrispondano. Specificando questo flag, si consente al pacchetto oplock di concedere un oplock di livello RW o RWH quando sono presenti più handle aperti per il file. Per altre informazioni sui tipi oplock, vedere Panoramica di Oplock.

Valore restituito

FsRtlOplockFsctrlEx restituisce uno dei valori NTSTATUS seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	Per una richiesta di IRP_MJ_CREATE, STATUS_SUCCESS indica che è stato concesso l'oplock del filtro richiesto. Per un'operazione FSCTL, il significato di STATUS_SUCCESS dipende dal codice FSCTL. Per altre informazioni, vedere le pagine di riferimento per i codici FSCTL elencati nella sezione Osservazioni seguente.
STATUS_CANCELLED	L'operazione di I/O è stata annullata. STATUS_CANCELLED è un codice di errore.
STATUS_INVALID_PARAMETER	Il codice FSCTL per l'operazione di I/O non è uno dei valori validi elencati nella sezione Osservazioni seguente. STATUS_INVALID_PARAMETER è un codice di errore.
STATUS_OPLOCK_NOT_GRANTED	Impossibile concedere l'oplock. STATUS_OPLOCK_NOT_GRANTED è un codice di errore.
STATUS_PENDING	Utilizzato solo per le operazioni FSCTL. Il significato di STATUS_PENDING dipende dal codice FSCTL. Per altre informazioni, vedere le pagine di riferimento per i codici FSCTL elencati nella sezione Osservazioni seguente. STATUS_PENDING è un codice riuscito.
STATUS_CANNOT_BREAK_OPLOCK	Non è stato possibile concedere un nuovo oplock. L'IRP è una richiesta di IRP_MJ_CREATE e FILE_OPEN_REQUIRING_OPLOCK è stato specificato nel parametro create options per l'operazione. STATUS_CANNOT_BREAK_OPLOCK è un codice riuscito.

Osservazioni

I file system e i driver di filtro legacy chiamano FsRtlOplockFsctrlEx per eseguire varie operazioni di oplock per un'operazione di I/O di controllo di creazione o file system. I minifiltri devono chiamare FltOplockFsctrlEx anziché FsRtlOplockFsctrlEx.

L'IRP a cui punta il parametro Irp deve essere un IRP valido per un'operazione di IRP_MJ_FILE_SYSTEM_CONTROL o IRP_MJ_CREATE.

Se L'IRP è una richiesta di IRP_MJ_FILE_SYSTEM_CONTROL, è possibile usare FsRtlOplockFsctrlEx con uno dei seguenti codici FSCTL, impostato in IrpSp->Parameters.FileSystemControl.FsControlCode:

Per altre informazioni su questi BLOCCHI FSCT e sui blocchi opportunistici in generale, vedere la documentazione di Microsoft Windows SDK.

Se L'IRP è una richiesta di IRP_MJ_CREATE, è possibile usare FsRtlOplockFsctrlEx per richiedere un oplock di filtro in sospeso se sono soddisfatte tutte le condizioni seguenti:

Il valore del parametro OpenCount deve essere 1.
Il valore del parametro desiredAccess per la richiesta di IRP_MJ_CREATE deve essere FILE_READ_ATTRIBUTES.
Il valore del parametro ShareAccess per la richiesta di IRP_MJ_CREATE deve essere FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Se viene concessa la richiesta di un oplock di filtro in sospeso, FsRtlOplockFsctrlEx restituisce STATUS_SUCCESS. Per altre informazioni sulla creazione di parametri, vedere la voce di riferimento per IRP_MJ_CREATE.

I filtri e i file system che chiamano questa funzione devono sincronizzare le chiamate nel pacchetto oplock fornito dal sistema. Per altre informazioni, vedere di sincronizzazione oplock.

Fabbisogno

Requisito	Valore
client minimo supportato	La routine FsRtlOplockFsctrlEx è disponibile a partire da Windows 7.
piattaforma di destinazione	Universale
intestazione	ntifs.h (include Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	<= APC_LEVEL