Función FltCreateFile (fltkernel.h)

Artículo
08/07/2023

Los controladores de minifiltro llaman a FltCreateFile para crear un nuevo archivo o abrir un archivo existente.

Sintaxis

NTSTATUS FLTAPI FltCreateFile(
  [in]           PFLT_FILTER        Filter,
  [in, optional] PFLT_INSTANCE      Instance,
  [out]          PHANDLE            FileHandle,
  [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
);

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 de controladores del sistema de archivos para el volumen. Si no es NULL, 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 FltCreateFile se realiza correctamente.

[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 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 la lista de marcas.

[in] ShareAccess

Especifica el tipo de acceso compartido al archivo que el autor de la llamada requiere, 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, 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 estructurado 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.

Valor devuelto

FltCreateFile 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

FltCreateFile puede 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 FltCreateFile intenta controlar esta situación.

Comentarios

En versiones de Windows anteriores a Microsoft Windows Update Rollup para Windows 2000 SP4 y Windows Server 2003 SP1, los controladores de minifiltro deben llamar a FltCreateFile en lugar de IoCreateFile, IoCreateFileSpecifyDeviceObjectHint o ZwCreateFile para obtener un identificador de archivo para su uso con rutinasde E/S Zw Xxx, como ZwReadFile y ZwQueryInformationFile.

En Microsoft Windows Update Rollup para Windows 2000 SP4, Windows Server 2003 SP1 y versiones posteriores, los controladores de minifiltro pueden usar FltCreateFileEx para obtener un puntero de objeto de archivo para su uso con rutinas de archivo FltXxx, como FltReadFile y FltWriteFile. En versiones anteriores de Windows, el identificador obtenido de FltCreateFile se puede convertir en un puntero de objeto de archivo llamando a ObReferenceObjectByHandle de la siguiente manera:

status = ObReferenceObjectByHandle(
           handle,                 //Handle
           0,                      //DesiredAccess
           NULL,                   //ObjectType
           KernelMode,             //AccessMode
           &handleFileObject,      //Object
           NULL);                  //HandleInformation</pre>

FltCreateFile 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 es recibida por 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 FltCreateFile:

Como pathname 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 identificador que se obtenga de FltCreateFile se debe liberar finalmente llamando a FltClose.

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 FltCreateFile. Al establecer este atributo, se restringe el uso del identificador devuelto por FltCreateFile 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.

No llames a esta rutina con LAS API deshabilitadas (un FsRtlEnterFileSystem o KeEnterCriticalRegion pendientes, ya que esto puede provocar un interbloqueo de subproceso.

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

Para que un autor de 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 escrituras 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 escrituras más allá del final del archivo. El archivo también se extiende automáticamente para este tipo de escritura.
Si solo se establecen las marcas FILE_EXECUTE y SYNCHRONIZE, el autor de la llamada no puede usar fileHandle devuelto 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 FltCreateFile 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, desiredAccess solicitado al archivo debe ser compatible con las especificaciones DesiredAccess y ShareAccess de todas las aperturas anteriores que aún no se han publicado con FltClose. Es decir, el DesiredAccess especificado en FltCreateFile 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. Por este motivo, 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 FltCreateFile 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 de ShareAccess con 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 FltCreateFile 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 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 la entrada de ShareAccess.
Los atributos de archivo especificados son lógicamente ORed con los que ya están en el archivo. Esto implica que si otro subproceso ya ha abierto el archivo, un llamador posterior de FltCreateFile no puede deshabilitar las marcas de 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 de 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 del sistema de archivos en particular. 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 FltCreateFile .

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 Zw.. Rutinas de archivo , incluidas las siguientes:

Cualquier valor de desplazamiento de bytes pasado a ZwReadFile o ZwWriteFile debe ser un múltiplo del tamaño del sector.
La longitud pasada a ZwReadFile 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 FltCreateFile 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 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 ZwSetInformationFile con el parámetro FileInformationClass establecido en FilePositionInformation deben especificar un desplazamiento que sea un múltiplo del tamaño del sector.

Los FILE_SYNCHRONOUS_IO_ALERT y FILE_SYNCHRONOUS_IO_NONALERT CreateOptions , 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 fileHandle devuelto. Todas las E/S de este archivo se serializan en todos los subprocesos mediante el identificador devuelto. Con cualquiera de estos conjuntos CreateOptions , 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 FltCreateFile 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 de FILE_OPEN_REPARSE_POINT, no se produce el procesamiento normal de reanálisis y FltCreateFile intenta abrir directamente el archivo de punto de reanálisis. En cualquier caso, si la operación de apertura se realizó correctamente, FltCreateFile devuelve STATUS_SUCCESS; de lo contrario, la rutina devuelve un código de error NTSTATUS. FltCreateFile nunca devuelve STATUS_REPARSE.

La 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 FILE_OPEN_REQUIRING_OPLOCK en FltCreateFile 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 de 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 típico de oplock. 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 oplock.

Nota

La marca FILE_OPEN_REQUIRING_OPLOCK está disponible en los sistemas operativos Windows 7, Windows Server 2008 R2 y versiones posteriores de Windows. 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 a una aplicación solicitar un oplock de nivel 1, por lotes o filtrar 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 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 para 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 la marca de FILE_RESERVE_OPFILTER sea inútil para esos tipos de interbloqueo.

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

Los controladores minifiltros 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 , FltCreateFile 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 FltCreateFile 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 función IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint o ZwCreateFile en su lugar.

Requisitos

Requisito	Value
Cliente mínimo compatible	Paquete acumulativo de actualizaciones de Windows 2000 1 para SP4, Windows XP SP2, Windows Server 2003 SP1
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya FltKernel.h)
Library	Fltmgr.lib
IRQL	PASSIVE_LEVEL