CfOpenFileWithOplock, fonction (cfapi.h)

Ouvre un handle opaque asynchrone dans un fichier ou un répertoire (pour les fichiers d’espace réservé et normal) 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 un rh (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) oplock sur le fichier ; sinon, un handle share-all est ouvert et un R (OPLOCK_LEVEL_CACHE_READ) est demandé.

  1. Si CF_OPEN_FILE_FLAG_EXCLUSIVE est spécifié, l’ouverture est « partager aucun » et obtient un (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
     • Un appel CreateFile normal qui s’ouvre pour l’une des FILE_EXECUTE | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (ou les deux de GENERIC_READ | GENERIC_WRITE) interrompt le blocage en raison du conflit de partage. Le propriétaire oplock se terminera et reconnaîtra.
  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 l’oplock.
     • Si le CreateFile normal spécifie un mode de partage qui est en conflit avec l’accès du handle Cf (par exemple, 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 émet une E/S en conflit, telle qu’une écriture. Lorsque cela se produit, le saut d’oplock n’est consultatif que.

• 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/FILE_ADD_FILE accès ; 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, il ouvre le fichier normalement.

• Si CF_OPEN_FILE_FLAG_FOREGROUND est spécifié, CfOpenFileWithOplock ne demande pas d’oplock. Cela doit être utilisé lorsque l’appelant agit en tant qu’application de premier plan. C’est-à-dire qu’ils ne s’occupent pas 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 verrous d’oplocks qui peuvent déjà se trouver sur le fichier. Ils ouvrent donc la poignée sans demander un oplock.

  Remarque

  Le comportement d’arrière-plan par défaut demande un oplock lors de l’ouverture du handle de fichier afin que son appel échoue s’il existe déjà un oplock, et qu’il peut être dit de fermer son handle s’il doit sortir 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 ne sera que 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 dans le fichier ou le 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 des API Win32 non CfApi.

Valeur retournée

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

Remarques

Lorsque l’oplock est rompu, l’API gère automatiquement la notification d’arrêt pour le compte de l’appelant en drainant 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 des fichiers. En particulier, ils veulent éviter de provoquer des violations de partage à d’autres openers (au premier plan). Pour ce faire, ils prennent un (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, tel qu’il serait accordé à l’aide de CF_OPEN_FILE_FLAG_EXCLUSIVE avec CfOpenFileWithOplock. Si un autre openeur est ensuite fourni dont les modes de partage/d’accès demandés sont en conflit avec l’application en arrière-plan, l’oplock 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, ce 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 open se poursuit sans rencontrer la violation de partage. Tout fonctionne en raison de la partie OPLOCK_LEVEL_CACHE_HANDLE de l’oplock. Sans CF_OPEN_FILE_FLAG_EXCLUSIVE, l’oplock n’a OPLOCK_LEVEL_CACHE_READ protection que, de sorte que la protection de violation de partage décrite ne se produit pas.

Spécifications

Voir aussi

CfCloseHandle

CreateFile