FSCTL_REQUEST_OPLOCK IOCTL (winioctl.h)
Richiede un blocco opportunistico (oplock) in un file e riconosce che si è verificata un'interruzione oplock.
Per eseguire questa operazione, chiamare la funzioneDeviceIoControlusando i parametri seguenti.
BOOL DeviceIoControl(
(HANDLE) hDevice, // handle to file
FSCTL_REQUEST_OPLOCK, // dwIoControlCode
(LPVOID) lpInBuffer, // pointer to REQUEST_OPLOCK_INPUT_BUFFER
(DWORD) nInBufferSize, // size of input buffer
(LPVOID) lpOutBuffer, // pointer to REQUEST_OPLOCK_OUTPUT_BUFFER
(DWORD) nOutBufferSize, // size of output buffer
NULL, // number of bytes returned
(LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);
Osservazioni
Questa operazione viene usata dalle applicazioni client per richiedere un blocco opportunistico (oplock) da un server locale. Le applicazioni client non devono richiedere blocchi opportunistici direttamente dai server remoti, ovvero il redirector di rete richiede in modo trasparente blocchi opportunistici per l'applicazione. L'utilizzo di questa operazione per richiedere blocchi opportunistici dai server remoti comporterà la negazione della richiesta.
Se l'operazione deviceIoControl restituisce il codice di errore ERROR_IO_PENDING, è stata concessa la richiesta di oplock. Se restituisce qualsiasi altro codice di errore, l'oplock non è stato concesso. Se il codice di errore è un valore di avviso, ad esempio ERROR_CANNOT_GRANT_REQUESTED_OPLOCK, le informazioni estese potrebbero essere disponibili nella struttura REQUEST_OPLOCK_OUTPUT_BUFFER.
Quando un oggetto oplock concesso si interrompe, l'oggetto evento nella strutturaOVERLAPPED verrà segnalato e le informazioni verranno restituite nella struttura REQUEST_OPLOCK_OUTPUT_BUFFER. Il membro interno della struttura di OVERLAPPED verrà impostato su un valore NTSTATUS che fornisce informazioni estese sulla modalità di rottura del blocco operativo.
| SOVRAPPOSTO. Valore interno | Significato |
|---|---|
| STATUS_SUCCESS 0x0 |
L'oplock è stato interrotto da un'altra operazione del file system. |
| STATUS_OPLOCK_HANDLE_CLOSED 0x00000216 |
L'oplock non è più in vigore perché l'handle di file usato per richiederlo è stato chiuso. Si noti che se un oplock si interrompe perché l'handle usato per richiederlo è stato chiuso, non è necessario confermare l'interruzione, indipendentemente dal tipo di oplock. |
| STATUS_OPLOCK_SWITCHED_TO_NEW_HANDLE 0x00000215 |
L'oplock è ancora in vigore, ma non è più associato all'handle di file usato per richiederlo. Un chiamante ha usato un handle diverso per il file per richiedere un nuovo oplock e che ora possiede l'oplock. |
Il codice di controllo FSCTL_REQUEST_OPLOCK offre funzionalità più efficienti rispetto ai codici di controllo correlati seguenti: FSCTL_REQUEST_OPLOCK_LEVEL_1, FSCTL_REQUEST_OPLOCK_LEVEL_2, FSCTL_REQUEST_FILTER_OPLOCKe FSCTL_REQUEST_BATCH_OPLOCK. La richiesta di diversi livelli di oplock può essere eseguita ripetutamente sullo stesso handle senza chiudere e riaprire l'handle quando si usa FSCTL_REQUEST_OPLOCK; gli altri codici di controllo richiedono che l'handle venga chiuso e riaperto con CreateFile per apportare tale modifica. Questa operazione viene eseguita modificando il membro RequestedOplockLevel della struttura REQUEST_OPLOCK_INPUT_BUFFER durante il nuovo rilascio del codice di controllo FSCTL_REQUEST_OPLOCK.
Nella tabella seguente viene riepilogato il modo in cui la capacità di memorizzazione nella cache dei tipi di oplock disponibili da FSCTL_REQUEST_OPLOCK corrisponde al livello 2, al livello 1 e agli oplock batch.
| Codice di controllo alternativo | Valore dei flag RequestedOplockLevel equivalente | Tipo oplock |
|---|---|---|
| FSCTL_REQUEST_BATCH_OPLOCK | OPLOCK_LEVEL_CACHE_READ \| OPLOCK_LEVEL_CACHE_WRITE \| OPLOCK_LEVEL_CACHE_HANDLE |
RWH |
| FSCTL_REQUEST_OPLOCK_LEVEL_1 | OPLOCK_LEVEL_CACHE_READ \| OPLOCK_LEVEL_CACHE_WRITE |
RW |
| FSCTL_REQUEST_OPLOCK_LEVEL_2 | OPLOCK_LEVEL_CACHE_READ |
R |
L'utilizzo del codice di controllo FSCTL_REQUEST_OPLOCK con il membro RequestedOplockLe vel impostato su OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE concede un oplock di tipo RH. Un oplock RH è simile all'oplock del filtro concesso dal codice di controllo FSCTL_REQUEST_FILTER_OPLOCK. Tuttavia, si noti che il filtro oplock consente a un solo client di contenere un oplock su un file alla volta; FSCTL_REQUEST_OPLOCK consente a più client alla volta di avere il RH blocco su un file. Un'altra differenza è che FSCTL_REQUEST_FILTER_OPLOCK richiede un riconoscimento di interruzione oplock prima che le scritture possano verificarsi, in cui FSCTL_REQUEST_OPLOCK non perché la notifica di interruzione oplock è di sola consulenza e le scritture possono andare avanti senza riconoscimento. Per altre informazioni, vedere breaking oplocks.
Un codice di controllo FSCTL_REQUEST_OPLOCK ha esito negativo se il file viene aperto in modalità non sovrapposta (sincrona).
Per le implicazioni dell'I/O sovrapposto in questa operazione, vedere la sezione Osservazioni dell'argomento DeviceIoControl.
In Windows 8 e Windows Server 2012 questo codice è supportato dalle tecnologie seguenti.
| Tecnologia | Sostenuto |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | No |
| SMB 3.0 Transparent Failover (TFO) | No |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | No |
| Cluster Shared Volume File System (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
Inoltre, a partire da Windows 8 e Windows Server 2012, il codice di controllo FSCTL_REQUEST_OPLOCK può essere usato per richiedere un oplock in una directory e un file. Una richiesta di oplock in una directory può specificare OPLOCK_LEVEL_CACHE_READ o OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE nel membro RequestedOplockLevel.
Un oplock R o RH in una directory si interrompe su Nessuno quando il contenuto di un'enumerazione della directory cambia. Ad esempio, l'aggiunta o l'eliminazione di un file nella directory, la modifica delle dimensioni di un file nella directory, la modifica del timestamp di un file nella directory e così via, interromperà tutti gli oplock nella directory. Questa interruzione di oplock non richiede un riconoscimento prima che si verifichino le modifiche nella directory; è solo consultivo.
Un oplock RH in una directory si interrompe su R quando la directory stessa viene rinominata o eliminata. Questa interruzione di oplock richiede un riconoscimento prima che la modifica alla directory possa verificarsi.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 7 [solo app desktop] |
| server minimo supportato | Windows Server 2008 R2 [solo app desktop] |
| intestazione | winioctl.h (include Windows.h) |