Función FltCreateFileEx2 (fltkernel.h)

Artículo
03/08/2023

Los controladores de Minifilter llaman a FltCreateFileEx2 para crear un nuevo 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 enviará la solicitud de creación. La instancia debe adjuntarse al volumen donde reside el archivo o directorio. Este parámetro es opcional y puede ser NULL. Si este parámetro es NULL, la solicitud se envía al objeto de dispositivo en la parte superior de la pila del controlador del sistema de archivos para el volumen. Si este parámetro no es NULL, la solicitud solo se envía a las instancias del controlador de minifiltro asociadas 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 puede ser 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 de 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 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 sobre 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 ShareAccess de IoCreateFileEx para obtener más detalles y para obtener la lista de marcas.

[in] CreateDisposition

Especifica un valor que determina la acción que se va a realizar, dependiendo 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 Options 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 IoCreateFileEx para obtener una lista de posibles códigos de retorno.

Nota

FltCreateFileEx2 podría devolver STATUS_FILE_LOCK_CONFLICT como valor devuelto o en el miembro Status 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.

Comentarios

FltCreateFileEx2 es similar a FltCreateFile y FltCreateFileEx, excepto que admite el parámetro de entrada DriverContext .

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, se deben crear, manipular y liberar mediante las rutinas adecuadas.

Los controladores de filtro debajo del autor de la llamada de FltCreateFileEx2 no deben 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 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 miembro TxnParameters de la estructura IO_DRIVER_CREATE_CONTEXT en el valor devuelto por la rutina IoGetTransactionParameterBlock .

FltCreateFileEx2 envía la solicitud de creación solo a las instancias adjuntas debajo de la instancia de controlador minifiltro especificada y al sistema de archivos. La instancia especificada y las instancias adjuntas encima no reciben la solicitud de creación. Si no se especifica ninguna instancia, la solicitud va a la parte superior de la pila y la reciben 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 miembro ObjectName de la entrada ObjectAttributes.
Como nombre de ruta de acceso relativo al archivo de directorio representado por el identificador en el miembro RootDirectory de la entrada ObjectAttributes.

Cualquier FileHandle que se obtenga de FltCreateFileEx2 debe publicarse al llamar a FltClose. Además, cualquier puntero FileObject devuelto debe 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. Al establecer este atributo, se 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 ejecuta 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.

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

Para que un autor de la llamada sincronice una finalización de E/S esperando a que 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 de 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 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 acceder 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 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 en 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 IO_IGNORE_SHARE_ACCESS_CHECK se especifica en el parámetro Flags , 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, las llamadas abiertas posteriores en el mismo archivo pueden realizarse correctamente.

El valor 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 eficazmente 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 de 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 CreateDisposition FILE_OVERWRITE_IF y FILE_SUPERSEDE son similares. Si se llama a FltCreateFileEx2 con un archivo existente y cualquiera de estos valores CreateDisposition , el archivo se reemplaza.

La sobrescritura de un archivo es semánticamente equivalente a una operación de sustitución, excepto 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 de entrada de ShareAccess .
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 fileAttributes existentes, 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 FILE_DIRECTORY_FILE CreateOptions 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 para abrir no es un archivo de directorio o si el autor de la llamada especificó un valor CreateOptions o CreateDisposition incoherente, 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. Si se especifica este valor, se aplican ciertas restricciones a los parámetros del autor de la llamada a otros flt.. Rutinas de archivo o Zw.. Rutinas de archivo , incluidas las siguientes:

Cualquier valor de desplazamiento de bytes pasado al parámetro ByteOffset de FltReadFile, ZwReadFile, FltWriteFile o ZwWriteFile debe ser un múltiplo del tamaño del sector.
El parámetro Length pasado a FltReadFile, ZwReadFile, FltWriteFile o 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 el valor del parámetro FileInformationClass . Para obtener más información sobre los valores del sistema FILE_XXX_ALIGNMENT, que se definen en Ntifs.h, consulte DEVICE_OBJECT e Inicialización de un objeto device.
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 está abriendo para E/S sincrónica. Esto significa que todas las operaciones de E/S del archivo deben ser sincrónicas siempre y cuando se produzcan a través del objeto de archivo al que hace referencia fileHandle devuelto. Todas las E/S de este tipo de archivo se serializan en todos los subprocesos mediante el identificador devuelto. Con cualquiera de estas marcas CreateOptions establecidas, el Administrador de E/S mantiene el desplazamiento de posición del archivo actual en el campo CurrentByteOffset 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 no se especifica la marca CreateOptions FILE_OPEN_REPARSE_POINT y FltCreateFileEx2 intenta abrir un archivo con un punto de reanálisis, se produce el procesamiento normal del punto de reanálisis para el archivo. Si, por otro lado, se especifica la marca FILE_OPEN_REPARSE_POINT, no se produce el procesamiento de reanálisis normal 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.

La marca CreateOptions FILE_OPEN_REQUIRING_OPLOCK elimina el tiempo entre abrir el archivo y solicitar 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 FILE_OPEN_REQUIRING_OPLOCK en FltCreateFileEx2 y, a continuación, solicitar cualquier interbloqueo. Esto garantiza que un propietario de oplock recibirá una notificación de 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 usa 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 Los sistemas operativos Windows 7, Windows Server 2008 R2 y versiones posteriores. Los sistemas de archivos de Microsoft que implementan esta marca en Windows 7 son NTFS, FAT y exFAT.

La marca CreateOptions FILE_RESERVE_OPFILTER permite que una aplicación solicite un oplock de nivel 1, lote o filtro para evitar que otras aplicaciones obtengan infracciones de recursos compartidos. Sin embargo, FILE_RESERVE_OPFILTER solo resulta 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 ShareAccess de 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 bloqueo de operación 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, independientemente del sistema de archivos, que tenga acceso directo al dispositivo de almacenamiento para el volumen.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

No debe usar FltCreateFileEx2 para abrir un identificador con acceso directo al dispositivo de almacenamiento para el volumen o perderá los recursos del sistema. Si desea abrir un identificador con acceso directo a un dispositivo de almacenamiento, llame a la función IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint o 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	Value
Cliente mínimo compatible	Disponible a partir de Windows Vista.
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya FltKernel.h)
Library	Fltmgr.lib
IRQL	PASSIVE_LEVEL