Compartir a través de

Función CfOpenFileWithOplock (cfapi.h)

  • Artículo

Abre un identificador opaco asincrónico en un archivo o directorio (para los archivos normales y de marcador de posición) y configura un interbloqueo adecuado en función de las marcas abiertas.

Sintaxis

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

Parámetros

[in] FilePath

Ruta de acceso completa al archivo o directorio que se va a abrir.

[in] Flags

Marcas para especificar permisos para abrir el archivo. Las marcas se pueden establecer en una combinación de los valores siguientes:

  • Si se especifica CF_OPEN_FILE_FLAG_EXCLUSIVE, la API devuelve un identificador share-none y solicita un RH (OPLOCK_LEVEL_CACHE_READ|OPLOCK_LEVEL_CACHE_HANDLE) oplock en el archivo; De lo contrario, se abre un identificador de recurso compartido y se solicita un R (OPLOCK_LEVEL_CACHE_READ).

    1. Si se especifica CF_OPEN_FILE_FLAG_EXCLUSIVE , la apertura es "compartir ninguna" y obtiene un (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock.
      • Una llamada normal a CreateFile que se abre para cualquiera de FILE_EXECUTE | FILE_READ_DATA | FILE_WRITE_DATA | FILE_APPEND_DATA | DELETE (o ambos de GENERIC_READ | GENERIC_WRITE) interrumpirá el interbloqueo debido al conflicto de uso compartido. El propietario de oplock llegará a finalizar y confirmar.
    2. Si no se especifica CF_OPEN_FILE_FLAG_EXCLUSIVE, la apertura es "compartir todo" y obtiene un OPLOCK_LEVEL_CACHE_READ oplock.
      • Una llamada normal a CreateFile no interrumpirá el interbloqueo.
      • Si el createFile normal especifica un modo de uso compartido que entra en conflicto con el acceso del controlador Cf (por ejemplo, si el createFile normal no especifica FILE_SHARE_READ), se producirá un error en el createFile normal con ERROR_SHARING_VIOLATION.
      • El interbloqueo no se interrumpe hasta que el otro autor de la llamada emite una E/S en conflicto, como una escritura. Cuando esto sucede, la interrupción del interbloqueo es solo aviso.

  • Si se especifica CF_OPEN_FILE_FLAG_WRITE_ACCESS, la API intenta abrir el archivo o directorio con FILE_READ_DATA/FILE_LIST_DIRECTORY y FILE_WRITE_DATA/ accesoFILE_ADD_FILE; de lo contrario, la API intenta abrir el archivo o directorio con FILE_READ_DATA FILE_LIST_DIRECTORY/.

  • Si se especifica CF_OPEN_FILE_FLAG_DELETE_ACCESS , la API intenta abrir el archivo o directorio con acceso DELETE ; de lo contrario, abre el archivo normalmente.

  • Si se especifica CF_OPEN_FILE_FLAG_FOREGROUND , CfOpenFileWithOplock no solicita un oplock. Se debe usar cuando el autor de la llamada actúa como una aplicación en primer plano. Es decir, no les importa si el identificador de archivo creado por esta API provoca infracciones de uso compartido para otros autores de llamadas y no les importa interrumpir los interbloqueos que ya estén en el archivo. Por lo tanto, abren el identificador sin solicitar un interbloqueo.

    Nota

    El comportamiento en segundo plano predeterminado solicita un interbloqueo al abrir el identificador de archivo para que se produzca un error en su llamada si ya hay un interbloqueo y se les puede indicar que cierren su identificador si necesitan salir de la forma de evitar provocar una infracción de uso compartido más adelante.

    A menos que el autor de la llamada especifique CF_OPEN_FILE_FLAG_EXCLUSIVEa CfOpenFileWithOplock, el oplock que obtenga solo será OPLOCK_LEVEL_CACHE_READ, no (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE), por lo que no habrá la protección de infracciones de uso compartido que normalmente quiera una aplicación en segundo plano.

[out] ProtectedHandle

Identificador opaco del archivo o directorio que se acaba de abrir. Tenga en cuenta que esto no es un identificador win32 normal y, por lo tanto, no se puede usar directamente con las API Win32 que no son CfApi.

Valor devuelto

Si esta función se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

Cuando se interrumpe el interbloqueo, la API controlará la notificación de interrupción automáticamente en nombre del autor de la llamada mediante la purga de todas las solicitudes activas y, a continuación, cerrará el identificador win32 subyacente.

Esto tiene como objetivo quitar la complejidad relacionada con los usos de interbloqueo. El autor de la llamada debe cerrar el identificador devuelto por CfOpenFileWithOplock con CfCloseHandle.

Normalmente, una aplicación en segundo plano quiere funcionar de forma transparente en archivos. En concreto, quieren evitar que se produzcan infracciones de uso compartido a otros openers (en primer plano). Para ello, toman un (OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE) oplock, como se concedería mediante CF_OPEN_FILE_FLAG_EXCLUSIVE con CfOpenFileWithOplock. Si otro abiertor viene posteriormente cuyos modos de acceso/recurso compartido solicitado entran en conflicto con los de la aplicación en segundo plano, se interrumpe el interbloqueo de la aplicación en segundo plano. Esto pide a la aplicación en segundo plano que cierre su identificador de archivo (para un identificador Cf, lo que hace que no sea válido; se ha cerrado el identificador subyacente real). Una vez que la aplicación en segundo plano cierra su identificador, el otro abierto continúa sin encontrar la infracción de uso compartido. Todo esto funciona debido a la OPLOCK_LEVEL_CACHE_HANDLE parte del oplock. Sin CF_OPEN_FILE_FLAG_EXCLUSIVE, el interbloqueo solo tiene OPLOCK_LEVEL_CACHE_READ protección, por lo que no se produce la protección de infracción de uso compartido descrita.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 10, versión 1709 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2016 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado cfapi.h
Library CldApi.lib
Archivo DLL CldApi.dll

Consulte también

CfCloseHandle

CreateFile