Partager via

FSCTL_REQUEST_OPLOCK IOCTL (winioctl.h)

  • Article

Demande un verrou opportuniste (oplock) sur un fichier et reconnaît qu’un arrêt d’oplock s’est produit.

Pour effectuer cette opération, appelez la fonction DeviceIoControl à l’aide des paramètres suivants.

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
);

Remarques

Cette opération est utilisée par les applications clientes pour demander un verrou opportuniste (oplock) à partir d’un serveur local. Les applications clientes ne doivent pas demander directement des verrous opportunistes à partir de serveurs distants : le redirecteur réseau demande de manière transparente des verrous opportunistes pour l’application. L’utilisation de cette opération pour demander des verrous opportunistes à partir de serveurs distants entraîne le refus de la demande.

Si l’opération DeviceIoControl retourne le code d’erreur ERROR_IO_PENDING, la demande oplock a été accordée. S’il retourne un autre code d’erreur, l’oplock n’a pas été accordé. Si le code d’erreur est une valeur d’avertissement telle que ERROR_CANNOT_GRANT_REQUESTED_OPLOCK, les informations étendues peuvent être disponibles dans la structure REQUEST_OPLOCK_OUTPUT_BUFFER.

Lorsqu’un oplock accordé s’interrompt, l’objet d’événement dans la structure SE CHEVAUCHER est signalé et les informations sont retournées dans la structure REQUEST_OPLOCK_OUTPUT_BUFFER. Le membre interne de la structure SE CHEVAUCHER sera défini sur une valeur NTSTATUS qui fournit des informations étendues sur la façon dont l’oplock s’est rompu.

SE CHEVAUCHENT. Valeur interne Signification
STATUS_SUCCESS
0x0		 L’oplock a été rompu par une autre opération de système de fichiers.
STATUS_OPLOCK_HANDLE_CLOSED
0x00000216		 L’oplock n’est plus en vigueur, car le handle de fichier utilisé pour demander qu’il ait été fermé. Notez que si un verrou d’opération s’interrompt parce que le handle utilisé pour la demander a été fermé, il n’est pas nécessaire de reconnaître l’arrêt, quel que soit le type d’oplock.
STATUS_OPLOCK_SWITCHED_TO_NEW_HANDLE
0x00000215		 L’oplock est toujours en vigueur, mais il n’est plus associé au handle de fichier utilisé pour le demander. Un appelant a utilisé un handle différent pour le fichier pour demander un nouvel oplock, et ce handle possède maintenant l’oplock.

Le code de contrôle FSCTL_REQUEST_OPLOCK fournit des fonctionnalités plus efficaces que les codes de contrôle associés suivants : FSCTL_REQUEST_OPLOCK_LEVEL_1, FSCTL_REQUEST_OPLOCK_LEVEL_2, FSCTL_REQUEST_FILTER_OPLOCKet FSCTL_REQUEST_BATCH_OPLOCK. La demande de différents niveaux d’oplock peut être effectuée à plusieurs reprises sur le même handle sans fermer et rouvrir le handle lors de l’utilisation de FSCTL_REQUEST_OPLOCK; les autres codes de contrôle nécessitent que le handle soit fermé, puis rouvert avec CreateFile pour apporter une telle modification. Pour ce faire, manipulez le membre RequestedOplockLevel de la structure REQUEST_OPLOCK_INPUT_BUFFER lors de la réécriture du code de contrôle FSCTL_REQUEST_OPLOCK.

Le tableau suivant résume la façon dont la capacité de mise en cache des types oplock disponibles à partir de FSCTL_REQUEST_OPLOCK correspond au niveau 2, niveau 1 et oplocks par lots.

Code de contrôle alternatif Valeur d’indicateur RequestedOplockLevel Type d’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’utilisation du code de contrôle FSCTL_REQUEST_OPLOCK avec le membre RequestedOplockLevel défini sur OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE accorde un oplock de type RH. Un oplock RH est similaire au verrou d’oplock de filtre accordé par le code de contrôle FSCTL_REQUEST_FILTER_OPLOCK. Toutefois, notez que l’oplock de filtre autorise un seul client à conserver un oplock sur un fichier à la fois ; FSCTL_REQUEST_OPLOCK permet à plusieurs clients à la fois d’avoir le verrou RH sur un fichier. Une autre différence est que FSCTL_REQUEST_FILTER_OPLOCK nécessite un accusé de réception d’arrêt d’oplock avant que les écritures ne puissent se produire, où FSCTL_REQUEST_OPLOCK n’est pas parce que la notification d’arrêt d’oplock est consultatif uniquement et les écritures sont autorisées à aller de l’avant sans accusé de réception. Pour plus d’informations, consultez cassant lesoplocks .

Un code de contrôle FSCTL_REQUEST_OPLOCK échoue si le fichier est ouvert en mode non superposé (synchrone).

Pour connaître les implications des E/S superposées sur cette opération, consultez la section Remarques de la rubrique DeviceIoControl.

Dans Windows 8 et Windows Server 2012, ce code est pris en charge par les technologies suivantes.

Technologie Supporté
Protocole SMB (Server Message Block) 3.0 Non
Basculement transparent SMB 3.0 (TFO) Non
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) Non
Cluster Shared Volume File System (CsvFS) Oui
Système de fichiers résilient (ReFS) Oui

En outre, à partir de Windows 8 et Windows Server 2012, le code de contrôle FSCTL_REQUEST_OPLOCK peut être utilisé pour demander un oplock sur un répertoire ainsi qu’un fichier. Une requête oplock sur un répertoire peut spécifier OPLOCK_LEVEL_CACHE_READ ou OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE dans le membre RequestedOplockLevel.

Un oplock R ou RH sur un répertoire s’arrête à None lorsque le contenu d’une énumération du répertoire change. Par exemple, l’ajout/la suppression d’un fichier dans le répertoire, la modification de la taille d’un fichier dans le répertoire, la modification de l’horodatage d’un fichier dans le répertoire, etc., interrompt tout le blocage sur le répertoire. Ce saut d’oplock ne nécessite pas d’accusé de réception avant que les modifications apportées au répertoire ne se produisent ; c’est consultatif uniquement.

Un oplock RH sur un répertoire s’arrête à R lorsque le répertoire lui-même est renommé ou supprimé. Cet arrêt d’oplock nécessite un accusé de réception avant que la modification du répertoire puisse se produire.

Exigences

Exigence Valeur
client minimum pris en charge Windows 7 [applications de bureau uniquement]
serveur minimum pris en charge Windows Server 2008 R2 [applications de bureau uniquement]
d’en-tête winioctl.h (include Windows.h)

Voir aussi