Función FltCreateFileEx2 (fltkernel.h)

Artículo
03/08/2023

Los controladores de minifiltro llaman a FltCreateFileEx2 para crear un archivo o abrir un archivo existente. Esta rutina incluye un parámetro de contexto de creación opcional (ECP).

Sintaxis

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parámetros

[in] Filter

Puntero de filtro opaco para el autor de la llamada.

[in, optional] Instance

Puntero de instancia opaco para la instancia del controlador de minifiltro a la que se va a enviar la solicitud de creación. La instancia debe adjuntarse al volumen donde reside el archivo o directorio. Este parámetro es opcional y se puede NULL. Si este parámetro es NULL, la solicitud se envía al objeto de dispositivo en la parte superior de la pila de controladores del sistema de archivos para el volumen. Si este parámetro no esNULL, la solicitud solo se envía a las instancias de controlador de minifiltro que se adjuntan debajo de la instancia especificada.

[out] FileHandle

Puntero a una variable asignada por el autor de la llamada que recibe el identificador de archivo si la llamada a FltCreateFileEx2 se realiza correctamente.

[out, optional] FileObject

Puntero a una variable asignada por el autor de la llamada que recibe el puntero del objeto de archivo si la llamada a FltCreateFileEx2 se realiza correctamente. Este parámetro es opcional y se puede NULL.

[in] DesiredAccess

Máscara de bits de marcas que especifican el tipo de acceso al archivo o directorio que requiere el autor de la llamada. Consulte el parámetro DesiredAccess de IoCreateFileEx para obtener más información sobre este parámetro y para obtener la lista de valores de marca.

[in] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES opaca que ya se ha inicializado con InitializeObjectAttributes. Consulte el parámetro ObjectAttributes de ioCreateFileEx para obtener más información y para obtener una descripción de cada miembro de estructura.

[out] IoStatusBlock

Puntero a una estructura IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación solicitada. Consulte el parámetro IoStatusBlock de IoCreateFileEx para obtener más información sobre este parámetro.

[in, optional] AllocationSize

Opcionalmente, especifica el tamaño de asignación inicial, en bytes, para la secuencia de archivos. Un valor distinto de cero no tiene ningún efecto a menos que se cree, sobrescriba o sustituya el archivo.

[in] FileAttributes

Especifica una o varias marcas de FILE_ATTRIBUTE_XXX, que representan los atributos de archivo que se van a establecer si va a crear, supersedar o sobrescribir un archivo. Consulte el parámetro FileAttributes de IoCreateFileEx para obtener más detalles y para obtener más información y para la lista de marcas.

[in] ShareAccess

Especifica el tipo de acceso compartido al archivo que requiere el autor de la llamada, como cero o uno, o una combinación de las marcas. Consulte el parámetro de ShareAccess de ioCreateFileEx para obtener más detalles y para obtener más información y para la lista de marcas.

[in] CreateDisposition

Especifica un valor que determina la acción que se va a realizar, en función de si el archivo ya existe. Consulte el parámetro Disposition de IoCreateFileEx para obtener la lista de valores posibles.

[in] CreateOptions

Especifica las opciones que se van a aplicar al crear o abrir el archivo. Este parámetro es una combinación compatible de las marcas enumeradas y descritas en el parámetro CreateOptions de IoCreateFileEx.

[in, optional] EaBuffer

Puntero a un búfer de FILE_FULL_EA_INFORMATION proporcionado por el autor de la llamada que contiene información de atributo extendido (EA) que se va a aplicar al archivo.

[in] EaLength

Longitud, en bytes, de eaBuffer.

[in] Flags

Especifica las opciones que se usarán durante la creación de la solicitud de creación. Consulte el parámetro Opciones de de IoCreateFileEx para obtener la lista de opciones posibles.

[in, optional] DriverContext

Puntero opcional a una estructura de IO_DRIVER_CREATE_CONTEXT ya inicializada por IoInitializeDriverCreateContext.

Valor devuelto

fltCreateFileEx2 devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado. Consulte la sección valor devuelto de de IoCreateFileEx para obtener una lista de posibles códigos de retorno.

Nota

FltCreateFileEx2 puede devolver STATUS_FILE_LOCK_CONFLICT como valor devuelto o en el miembro Status de de la estructura IO_STATUS_BLOCK a la que apunta el parámetro IoStatusBlock. Esto solo se produciría si el archivo de registro NTFS está lleno y se produce un error mientras FltCreateFileEx2 intenta controlar esta situación.

Observaciones

fltCreateFileEx2 es similar a fltCreateFile y FltCreateFileEx, salvo que admite el parámetro de entrada driverContext de.

Para especificar un ECP como parte de una operación de creación, inicialice el miembro ExtraCreateParameter de la estructura de IO_DRIVER_CREATE_CONTEXT con la rutina FltAllocateExtraCreateParameterList. Si se usan ECP, deben crearse, manipularse y liberarse mediante las rutinas adecuadas.

Filtre los controladores por debajo del autor de la llamada de FltCreateFileEx2 no debe agregar ni eliminar ECP en el autor de la llamada. Por lo tanto, al volver de la llamada a FltCreateFileEx2, la lista ECP debe no modificarse y se puede pasar a llamadas adicionales de FltCreateFileEx2 para otras operaciones de creación. Tenga en cuenta que el sistema operativo no desasigna automáticamente la estructura de la lista ECP: el autor de la llamada de FltCreateFileEx2 debe desasignar esta estructura llamando a la rutina FltFreeExtraCreateParameterList.

Para crear o abrir un archivo en el contexto de una transacción, establezca el txnParameters miembro de la estructura de IO_DRIVER_CREATE_CONTEXT en el valor devuelto por la rutina de IoGetTransactionParameterBlock.

FltCreateFileEx2 envía la solicitud de creación solo a las instancias adjuntas debajo de la instancia de controlador de minifiltro especificada y al sistema de archivos. La instancia especificada y las instancias adjuntas anteriormente no reciben la solicitud de creación. Si no se especifica ninguna instancia, la solicitud va a la parte superior de la pila y recibe todas las instancias y el sistema de archivos.

Hay dos maneras alternativas de especificar el nombre del archivo que se va a crear o abrir con FltCreateFileEx2:

Como nombre de ruta de acceso completo, proporcionado en el ObjectName miembro de la entrada ObjectAttributes.
Como nombre de ruta de acceso que es relativo al archivo de directorio representado por el identificador del rootDirectory miembro de la entrada ObjectAttributes.

Cualquier FileHandle que se obtenga de fltCreateFileEx2 debe publicarse llamando a FltClose. Además, los FileObject devueltos puntero deben desreferenciarse cuando ya no sea necesario llamando a ObDereferenceObject.

Las rutinas de controlador que no se ejecutan en el contexto del proceso del sistema deben establecer el atributo OBJ_KERNEL_HANDLE para el parámetro ObjectAttributes de FltCreateFileEx2. Establecer este atributo restringe el uso del identificador devuelto por FltCreateFileEx2 a los procesos que se ejecutan en modo kernel. De lo contrario, el proceso puede acceder al identificador en cuyo contexto se está ejecutando el controlador.

Nota

No llame a esta rutina con un valor IRP de nivel superior que no sea NULL, ya que esto puede provocar un interbloqueo del sistema.

Algunos DesiredAccess marcas y combinaciones de marcas tienen los siguientes efectos:

Para que un autor de llamada sincronice una finalización de E/S esperando a que el FileHandle devuelto se establezca en el estado Signaled, se debe establecer la marca SYNCHRONIZE.
Si solo se establecen las marcas FILE_APPEND_DATA y SYNCHRONIZE, el autor de la llamada solo puede escribir al final del archivo y se omite cualquier información de desplazamiento sobre las solicitudes de escritura en el archivo. Sin embargo, el archivo se extiende automáticamente según sea necesario para este tipo de operación de escritura.
Establecer la marca FILE_WRITE_DATA para un archivo también permite que se produzcan solicitudes de escritura más allá del final del archivo. El archivo también se extiende automáticamente para este tipo de solicitud de escritura.
Si solo se establecen las marcas FILE_EXECUTE y SYNCHRONIZE, el autor de la llamada no puede usar el identificador devuelto en el parámetro fileHandle de para leer o escribir directamente datos en o desde el archivo. Es decir, todas las operaciones del archivo deben usar la E/S de paginación del sistema para leer o escribir datos de archivo.

El parámetro ShareAccess determina si los subprocesos independientes pueden tener acceso al mismo archivo, posiblemente simultáneamente. Si ambos abiertores de archivos tienen el privilegio de acceder a un archivo de la manera especificada, el archivo se puede abrir y compartir correctamente. Si el autor de la llamada original de FltCreateFileEx2 no especifica FILE_SHARE_READ, FILE_SHARE_WRITE o FILE_SHARE_DELETE, no se puede realizar ninguna otra operación abierta en el archivo porque el autor de la llamada original tiene acceso exclusivo al archivo.

Para que un archivo compartido se abra correctamente, el DesiredAccess solicitado al archivo debe ser compatible con las especificaciones de DesiredAccess y ShareAccess de todas las solicitudes abiertas anteriores que aún no se han publicado con FltClose. Es decir, el parámetro DesiredAccess especificado para fltCreateFileEx2 para un archivo determinado no debe entrar en conflicto con los accesos a los que otros abiertores del archivo no se han permitido.

Nota

Si se especifica IO_IGNORE_SHARE_ACCESS_CHECK en el parámetro flags de, el administrador de E/S omite el parámetro shareAccess. Sin embargo, es posible que el sistema de archivos siga realizando comprobaciones de acceso. Por lo tanto, es importante especificar el modo de uso compartido que desea para el parámetro ShareAccess, incluso cuando se usa la marca IO_IGNORE_SHARE_ACCESS_CHECK. Además, tenga en cuenta que, cuando se especifica IO_IGNORE_SHARE_ACCESS_CHECK, el sistema de archivos no realiza un seguimiento del acceso deseado o el acceso compartido de la apertura actual. Debido a esto, es posible que las llamadas abiertas posteriores en el mismo archivo se realicen correctamente.

El FILE_SUPERSEDE CreateDisposition FILE_SUPERSEDE requiere que el autor de la llamada tenga acceso DELETE a un objeto de archivo existente. Si es así, una llamada correcta a FltCreateFileEx2 con FILE_SUPERSEDE en un archivo existente elimina ese archivo y, a continuación, lo vuelve a crear. Esto implica que si otro subproceso ya ha abierto el archivo, abrió el archivo especificando un parámetro ShareAccesscon la marca FILE_SHARE_DELETE establecida. Tenga en cuenta que este tipo de disposición es coherente con el estilo POSIX de sobrescribir archivos.

Los valores de CreateDisposition FILE_OVERWRITE_IF y FILE_SUPERSEDE son similares. Si fltCreateFileEx2 se llama con un archivo existente y cualquiera de estos valores CreateDisposition, se reemplaza el archivo.

Sobrescribir un archivo es semánticamente equivalente a una operación de sustitución, excepto por lo siguiente:

El autor de la llamada debe tener acceso de escritura al archivo, en lugar de eliminar el acceso. Esto implica que, si otro subproceso ya ha abierto el archivo, abrió el archivo con la marca FILE_SHARE_WRITE establecida en el parámetro ShareAccess de entrada.
Los atributos de archivo especificados se combinan con esos atributos que ya se aplican al archivo mediante una operación OR bit a bit. Esto implica que si otro subproceso ya ha abierto el archivo, un llamador posterior de FltCreateFileEx2 no puede deshabilitar las marcas existentes FileAttributes, pero puede habilitar marcas adicionales para el mismo archivo. Tenga en cuenta que este estilo de sobrescribir archivos es coherente con MS-DOS, Windows 3.1 y OS/2.

El valor CreateOptions FILE_DIRECTORY_FILE especifica que el archivo que se va a crear o abrir es un archivo de directorio. Cuando se crea un archivo de directorio, el sistema de archivos crea una estructura adecuada en el disco para representar un directorio vacío para la estructura en disco de ese sistema de archivos concreto. Si se especificó esta opción y el archivo especificado que se va a abrir no es un archivo de directorio o si el autor de la llamada especificó un createOptions o valor createDisposition, se produce un error en la llamada a FltCreateFileEx2.

La marca CreateOptions FILE_NO_INTERMEDIATE_BUFFERING impide que el sistema de archivos realice cualquier almacenamiento en búfer intermedio en nombre del autor de la llamada. Al especificar este valor, se aplican ciertas restricciones a los parámetros del autor de la llamada a otros Flt.. Rutinas de de archivos o Zw.. Rutinas de de archivos, incluidas las siguientes:

Cualquier valor de desplazamiento de bytes pasado al parámetro de ByteOffset de FltReadFile, ZwReadFile, FltWriteFileo ZwWriteFile debe ser un múltiplo del tamaño del sector.
El parámetro Length pasado a FltReadFile, ZwReadFile, FltWriteFileo ZwWriteFile debe ser un múltiplo del tamaño del sector. Tenga en cuenta que especificar una operación de lectura en un búfer cuya longitud es exactamente el tamaño del sector puede dar lugar a que se transfieran menos bytes significativos a ese búfer si se alcanzó el final del archivo durante la transferencia.
Los búferes deben alinearse de acuerdo con el requisito de alineación del dispositivo de almacenamiento subyacente. Esta información se puede obtener llamando a FltCreateFileEx2 para obtener un identificador para el objeto de archivo que representa el dispositivo físico y, a continuación, llamando a ZwQueryInformationFile con ese identificador, especificando FileAlignmentInformation como valor para parámetro FileInformationClass. Para obtener más información sobre los valores del sistema FILE_XXX_ALIGNMENT, que se definen en Ntifs.h, vea DEVICE_OBJECT y Inicializar un objeto de dispositivo.
Las llamadas a FltSetInformationFile o ZwSetInformationFile con el parámetro FileInformationClass establecido en FilePositionInformation deben especificar un desplazamiento que sea un múltiplo del tamaño del sector.

Las marcas createOptions FILE_SYNCHRONOUS_IO_ALERT y FILE_SYNCHRONOUS_IO_NONALERT, que son mutuamente excluyentes como sus nombres sugieren, especifique que el archivo se abre para E/S sincrónica. Esto significa que todas las operaciones de E/S del archivo deben ser sincrónicas siempre que se produzcan a través del objeto de archivo al que hace referencia el FileHandle devuelto. Toda la E/S de dicho archivo se serializa en todos los subprocesos mediante el identificador devuelto. Con cualquiera de estos marcas de CreateOptions establecidas, el Administrador de E/S mantiene el desplazamiento de posición del archivo actual en el campo CurrentByteOff set del objeto de archivo. Este desplazamiento se puede usar en llamadas a ZwReadFile y ZwWriteFile. También se puede consultar o establecer llamando a ZwQueryInformationFile o ZwSetInformationFile.

Si la marca FILE_OPEN_REPARSE_POINT CreateOptions no está especificada y FltCreateFileEx2 intenta abrir un archivo con un punto de reanálisis, el procesamiento normal del punto de reanálisis se produce para el archivo. Si, por otro lado, se especifica la marca FILE_OPEN_REPARSE_POINT, el procesamiento normal de reanálisis no se produce y FltCreateFileEx2 intenta abrir directamente el archivo de punto de reanálisis. En cualquier caso, si la operación de apertura se realizó correctamente, FltCreateFileEx2 devuelve STATUS_SUCCESS; de lo contrario, la rutina devuelve un código de error NTSTATUS. fltCreateFileEx2 nunca devuelve STATUS_REPARSE.

El marca CreateOptions FILE_OPEN_REQUIRING_OPLOCK elimina el tiempo entre el momento en que abre el archivo y solicita un interbloqueo que podría permitir que un tercero abra el archivo y obtenga una infracción de uso compartido. Una aplicación puede usar la marca de FILE_OPEN_REQUIRING_OPLOCK en fltCreateFileEx2 y, a continuación, solicitar cualquier interbloqueo. Esto garantiza que se notificará al propietario de un interbloqueo cualquier solicitud abierta posterior que provoque una infracción de uso compartido.

En Windows 7, si existen otros identificadores en el archivo cuando una aplicación usa la marca FILE_OPEN_REQUIRING_OPLOCK, se producirá un error en la operación de creación con STATUS_OPLOCK_NOT_GRANTED. Esta restricción ya no existe a partir de Windows 8.

Si esta operación de creación interrumpiría un interbloqueo que ya existe en el archivo, al establecer la marca FILE_OPEN_REQUIRING_OPLOCK se producirá un error en la operación de creación con STATUS_CANNOT_BREAK_OPLOCK. Esta operación de creación no romperá el interbloqueo existente.

Una aplicación que use esta marca debe solicitar un interbloqueo después de que esta llamada se realice correctamente, o todos los intentos posteriores de abrir el archivo se bloquearán sin la ventaja del procesamiento de interbloqueo típico. Del mismo modo, si esta llamada se realiza correctamente, pero se produce un error en la solicitud de interbloqueo posterior, una aplicación que use esta marca debe cerrar su identificador después de detectar que se ha producido un error en la solicitud de interbloqueo.

Nota

La marca FILE_OPEN_REQUIRING_OPLOCK está disponible en Windows 7, Windows Server 2008 R2 y sistemas operativos Windows posteriores. Los sistemas de archivos de Microsoft que implementan esta marca en Windows 7 son NTFS, FAT y exFAT.

El FILE_RESERVE_OPFILTER marca CreateOp tions permite a una aplicación solicitar un bloqueo de nivel 1, lote o filtro para evitar que otras aplicaciones obtengan infracciones de recursos compartidos. Sin embargo, FILE_RESERVE_OPFILTER solo es prácticamente útil para los interbloqueos de filtro. Para usarlo, debe completar los pasos siguientes:

Emita una solicitud de creación con createOptions de FILE_RESERVE_OPFILTER, DesiredAccess de exactamente FILE_READ_ATTRIBUTES y de ShareAccess exactamente FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Si ya hay identificadores abiertos, se produce un error en la solicitud de creación con STATUS_OPLOCK_NOT_GRANTED y también se produce un error en el siguiente interbloqueo solicitado.
- Si abre con más acceso o menos uso compartido también provocará un error de STATUS_OPLOCK_NOT_GRANTED.
Si la solicitud de creación se realiza correctamente, solicite un interbloqueo.
Abra otro identificador en el archivo para realizar E/S.

El paso tres hace que esto sea práctico solo para los interbloqueos de filtro. El identificador abierto en el paso 3 puede tener un desiredAccess que contenga un máximo de FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL y aún no interrumpen un interbloqueo de filtro. Sin embargo, cualquier DesiredAccess mayor que FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE interrumpirá un interbloqueo de nivel 1 o por lotes y hará que el FILE_RESERVE_OPFILTER marca sea inútil para esos tipos de interbloqueo.

NTFS es el único sistema de archivos de Microsoft que implementa FILE_RESERVE_OPFILTER.

Los controladores de minifiltro deben usar FltSetInformationFile, no ZwSetInformationFile, para cambiar el nombre de un archivo.

Nota

Si intenta abrir un volumen, pero solo especifica una combinación de las marcas siguientes para el parámetro DesiredAccess, FltCreateFileEx2 abrirá un identificador, independiente del sistema de archivos, que tiene acceso directo al dispositivo de almacenamiento para el volumen.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SINCRONIZAR

No debe usar fltCreateFileEx2 para abrir un identificador con acceso directo al dispositivo de almacenamiento para el volumen o filtrará los recursos del sistema. Si desea abrir un identificador con acceso directo a un dispositivo de almacenamiento, llame a la ioCreateFileEx, IoCreateFileSpecifyDeviceObjectHinto función ZwCreateFile en su lugar.

Cuando un autor de llamada de FltCreateFileEx2 desea habilitar el reparsing para un destino de volumen, se puede incluir un FLT_CREATEFILE_TARGET_ECP_CONTEXT como ECP en la lista ECP en el parámetro DriverContext. Si este ECP está presente, fltCreateFileEx2 ajustará el dispositivo de destino para la operación de creación e intentará buscar una instancia filtrada de un volumen adecuado para la información de archivo especificada. El uso de este ECP está disponible a partir de Windows 8.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible a partir de Windows Vista.
de la plataforma de destino de	Universal
encabezado de	fltkernel.h (incluya FltKernel.h)
biblioteca de	Fltmgr.lib
irQL	PASSIVE_LEVEL