Partager via

Fonction CfOpenFileWithOplock (cfapi.h)

  • Article

Ouvre un handle opaque asynchrone dans un fichier ou un répertoire (pour les fichiers normaux et réservés) et configure un oplock approprié sur celui-ci en fonction des indicateurs ouverts.

Syntaxe

HRESULT CfOpenFileWithOplock(
  [in]  LPCWSTR            FilePath,
  [in]  CF_OPEN_FILE_FLAGS Flags,
  [out] PHANDLE            ProtectedHandle
);

Paramètres

[in] FilePath

Chemin complet du fichier ou du répertoire à ouvrir.

[in] Flags

Indicateurs permettant de spécifier des autorisations lors de l’ouverture du fichier. Les indicateurs peuvent être définis sur une combinaison des valeurs suivantes :

  • Si CF_OPEN_FILE_FLAG_EXCLUSIVE est spécifié, l’API retourne un handle share-none et demande une rh (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) oplock sur le fichier ; sinon, un handle de partage est ouvert et un R (OPLOCK_LEVEL_CACHE_READ) est demandé.

    1. Si CF_OPEN_FILE_FLAG_EXCLUSIVE est spécifié, l’ouverture est « partage aucun » et obtient un (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
      • Appel CreateFile normal qui s’ouvre pour l’un des FILE_EXECUTE | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (ou l’une ou l’autre des GENERIC_READ | GENERIC_WRITE) interrompt le blocage d’opération en raison du conflit de partage. Le propriétaire de l’oplock peut terminer et confirmer.
    2. Si CF_OPEN_FILE_FLAG_EXCLUSIVE n’est pas spécifié, l’ouverture est « partager tout » et obtient un OPLOCK_LEVEL_CACHE_READ oplock.
      • Un appel CreateFile normal n’interrompt pas le blocage d’opération.
      • Si le CreateFile normal spécifie un mode de partage qui entre en conflit avec l’accès du handle Cf (pour instance, si le CreateFile normal ne spécifie pas FILE_SHARE_READ), le CreateFile normal échoue avec ERROR_SHARING_VIOLATION.
      • L’oplock ne s’interrompt pas tant que l’autre appelant n’émet pas d’E/S en conflit, comme une écriture. Lorsque cela se produit, l’arrêt d’opération est un avertissement uniquement.

  • Si CF_OPEN_FILE_FLAG_WRITE_ACCESS est spécifié, l’API tente d’ouvrir le fichier ou le répertoire avec FILE_READ_DATA/FILE_LIST_DIRECTORY et FILE_WRITE_DATA/accès FILE_ADD_FILE ; sinon, l’API tente d’ouvrir le fichier ou le répertoire avec FILE_READ_DATA/FILE_LIST_DIRECTORY.

  • Si CF_OPEN_FILE_FLAG_DELETE_ACCESS est spécifié, l’API tente d’ouvrir le fichier ou le répertoire avec un accès DELETE ; sinon, le fichier s’ouvre normalement.

  • Si CF_OPEN_FILE_FLAG_FOREGROUND est spécifié, CfOpenFileWithOplock ne demande pas d’oplock. Cela doit être utilisé lorsque l’appelant agit comme une application de premier plan. c’est-à-dire qu’ils ne se soucient pas de savoir si le handle de fichier créé par cette API provoque des violations de partage pour d’autres appelants, et ils ne se soucient pas de briser les blocages d’opération qui peuvent déjà se trouver sur le fichier. Ainsi, ils ouvrent le handle sans demander un oplock.

    Notes

    Le comportement en arrière-plan par défaut demande un oplock lors de l’ouverture du handle de fichier afin que leur appel échoue s’il existe déjà un oplock, et qu’ils puissent être amenés à fermer leur handle s’ils doivent s’écarter du chemin pour éviter de provoquer une violation de partage ultérieurement.

    Sauf si l’appelant spécifie CF_OPEN_FILE_FLAG_EXCLUSIVE à CfOpenFileWithOplock, l’oplock qu’il obtient sera seulement OPLOCK_LEVEL_CACHE_READ, et non (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE), il n’y aura donc pas la protection contre les violations de partage qu’une application en arrière-plan peut normalement souhaiter.

[out] ProtectedHandle

Handle opaque du fichier ou du répertoire qui vient d’être ouvert. Notez qu’il ne s’agit pas d’un handle Win32 normal et ne peut donc pas être utilisé directement avec les API Win32 non CfApi.

Valeur retournée

Si cette fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Lorsque l’oplock est rompu, l’API gère automatiquement la notification d’arrêt pour le compte de l’appelant en vidant toutes les requêtes actives, puis en fermant le handle Win32 sous-jacent.

Cela vise à supprimer la complexité liée aux utilisations d’oplock. L’appelant doit fermer le handle retourné par CfOpenFileWithOplock avec CfCloseHandle.

Une application en arrière-plan souhaite généralement fonctionner de manière transparente sur les fichiers. En particulier, ils veulent éviter de provoquer des violations de partage avec d’autres ouvreurs (au premier plan). Pour ce faire, ils prennent un (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, tel que serait accordé à l’aide de CF_OPEN_FILE_FLAG_EXCLUSIVE avec CfOpenFileWithOplock. Si un autre ouvreur arrive par la suite dont les modes de partage/d’accès demandés entrent en conflit avec ceux de l’application en arrière-plan, le blocage d’opération de l’application en arrière-plan s’interrompt. Cela invite l’application en arrière-plan à fermer son handle de fichier (pour un handle Cf, qui le rend non valide , le handle sous-jacent réel a été fermé). Une fois que l’application en arrière-plan ferme son handle, l’ouverture de l’autre ouvreur se poursuit sans rencontrer la violation de partage. Tout cela fonctionne en raison de la partie OPLOCK_LEVEL_CACHE_HANDLE de l’oplock. Sans CF_OPEN_FILE_FLAG_EXCLUSIVE, l’oplock n’a que OPLOCK_LEVEL_CACHE_READ protection, de sorte que la protection contre les violations de partage décrite ne se produit pas.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 10, version 1709 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2016 (applications de bureau uniquement)
Plateforme cible Windows
En-tête cfapi.h
Bibliothèque CldApi.lib
DLL CldApi.dll

Voir aussi

CfCloseHandle

CreateFile