Função CfOpenFileWithOplock (cfapi.h)

Abre um identificador opaco assíncrono para um arquivo ou diretório (para arquivos normais e de espaço reservado) e configura um oplock adequado nele com base nos sinalizadores abertos.

Sintaxe

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

Parâmetros

[in] FilePath

Caminho totalmente qualificado para o arquivo ou diretório a ser aberto.

[in] Flags

Os sinalizadores para especificar permissões ao abrir o arquivo. Os sinalizadores podem ser definidos como uma combinação dos seguintes valores:

• Se CF_OPEN_FILE_FLAG_EXCLUSIVE for especificado, a API retornará um identificador share-none e solicitará um RH (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) oplock no arquivo; caso contrário, um identificador share-all é aberto e um R (OPLOCK_LEVEL_CACHE_READ) é solicitado.

  1. Se CF_OPEN_FILE_FLAG_EXCLUSIVE for especificado, o open será "share none" e obterá um (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
     • Uma chamada CreateFile normal que é aberta para qualquer um dos FILE_EXECUTE | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (ou ambos/ambos de GENERIC_READ | GENERIC_WRITE) interromperá o oplock devido ao conflito de compartilhamento. O proprietário do oplock poderá concluir e reconhecer.
  2. Se CF_OPEN_FILE_FLAG_EXCLUSIVE não for especificado, a abertura será "compartilhar tudo" e obterá um OPLOCK_LEVEL_CACHE_READ oplock.
     • Uma chamada CreateFile normal não interromperá o oplock.
     • Se o CreateFile normal especificar um modo de compartilhamento que está em conflito com o acesso do identificador cf (por exemplo, se o CreateFile normal não especificar FILE_SHARE_READ), o CreateFile normal falhará com ERROR_SHARING_VIOLATION.
     • O oplock não é interrompido até que o outro chamador emita uma E/S conflitante, como uma gravação. Quando isso acontece, a interrupção do oplock é apenas consultoria.

• Se CF_OPEN_FILE_FLAG_WRITE_ACCESS for especificado, a API tentará abrir o arquivo ou diretório com FILE_READ_DATA/FILE_LIST_DIRECTORY e FILE_WRITE_DATA/FILE_ADD_FILE acesso; caso contrário, a API tentará abrir o arquivo ou diretório com FILE_READ_DATA/FILE_LIST_DIRECTORY.

• Se CF_OPEN_FILE_FLAG_DELETE_ACCESS for especificado, a API tentará abrir o arquivo ou diretório com acesso DELETE ; caso contrário, ele abre o arquivo normalmente.

• Se CF_OPEN_FILE_FLAG_FOREGROUND for especificado, CfOpenFileWithOplock não solicitará um oplock. Isso deve ser usado quando o chamador está agindo como um aplicativo em primeiro plano. Ou seja, eles não se importam se o identificador de arquivo criado por essa API causa violações de compartilhamento para outros chamadores e eles não se importam em quebrar qualquer oplocks que já esteja no arquivo. Então, eles abrem o identificador sem solicitar um oplock.

  Observação

  O comportamento padrão em segundo plano solicita um oplock ao abrir o identificador de arquivo para que sua chamada falhe se já houver um oplock, e eles podem ser orientados a fechar o identificador se precisarem sair do caminho para evitar causar uma violação de compartilhamento mais tarde.

  A menos que o chamador especifique CF_OPEN_FILE_FLAG_EXCLUSIVE para CfOpenFileWithOplock, o oplock obtido será apenas OPLOCK_LEVEL_CACHE_READ, não (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE), portanto, não haverá a proteção contra violação de compartilhamento que um aplicativo em segundo plano normalmente deseja.

[out] ProtectedHandle

Um identificador opaco para o arquivo ou diretório que acaba de ser aberto. Observe que esse não é um identificador Win32 normal e, portanto, não pode ser usado diretamente com APIs Win32 não CfApi.

Retornar valor

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Quando o oplock for quebrado, a API manipulará a notificação de interrupção automaticamente em nome do chamador drenando todas as solicitações ativas e fechando o identificador Win32 subjacente.

Isso visa remover a complexidade relacionada aos usos de oplock. O chamador deve fechar o identificador retornado por CfOpenFileWithOplock com CfCloseHandle.

Um aplicativo em segundo plano normalmente deseja operar de forma transparente em arquivos. Em particular, eles querem evitar causar violações de compartilhamento para outros abridores (em primeiro plano). Para fazer isso, eles pegam um (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, como seria concedido usando CF_OPEN_FILE_FLAG_EXCLUSIVE com CfOpenFileWithOplock. Se outro abridor posteriormente aparecer cujos modos de compartilhamento/acesso solicitados entram em conflito com os do aplicativo em segundo plano, o oplock do aplicativo em segundo plano será interrompido. Isso solicita que o aplicativo em segundo plano feche seu identificador de arquivo (para um identificador cf, o que faz com que ele se torne inválido – o identificador subjacente real foi fechado). Depois que o aplicativo em segundo plano fecha seu identificador, a abertura do outro abridor continua sem encontrar a violação de compartilhamento. Tudo isso funciona devido à OPLOCK_LEVEL_CACHE_HANDLE parte do oplock. Sem CF_OPEN_FILE_FLAG_EXCLUSIVE, o oplock só tem proteção OPLOCK_LEVEL_CACHE_READ, portanto, a proteção contra violação de compartilhamento descrita não acontece.

Requisitos

Confira também

CfCloseHandle

CreateFile