Funzione FsRtlOplockFsctrl (ntifs.h)

Articolo
12/21/2024

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

Sintassi

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

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 .

Valore restituito

FsRtlOplockFsctrl 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 FsRtlOplockFsctrl per eseguire varie operazioni di oplock per un'operazione di I/O di controllo di creazione o file system. I minifiltri devono chiamare FltOplockFsctrl anziché FsRtlOplockFsctrl.

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 FsRtlOplockFsctrl con uno dei seguenti codici FSCTL, impostato in IrpSp->Parameters.FileSystemControl.FsControlCode:

Per informazioni dettagliate su questi file DITLS e sui blocchi opportunistici in generale, vedere la documentazione di Microsoft Windows SDK.

Se l'IRP è una richiesta di IRP_MJ_CREATE, è possibile usare fsRtlOplockFsctrl 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, fsRtlOplockFsctrl 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.