Función IoCreateFileEx (ntddk.h)

Artículo
03/08/2023

La rutina IoCreateFileEx hace que se cree un nuevo archivo o directorio, o abra un archivo, un dispositivo, un directorio o un volumen existentes y proporcione al autor de la llamada un identificador para el objeto de archivo. Los controladores de filtro del sistema de archivos (controladores de filtro heredados) llaman a esta rutina.

Sintaxis

NTSTATUS IoCreateFileEx(
  [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                     Disposition,
  [in]           ULONG                     CreateOptions,
  [in, optional] PVOID                     EaBuffer,
  [in]           ULONG                     EaLength,
  [in]           CREATE_FILE_TYPE          CreateFileType,
  [in, optional] PVOID                     InternalParameters,
  [in]           ULONG                     Options,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parámetros

[out] FileHandle

Puntero a una variable que recibe el identificador de archivo si la llamada se realiza correctamente. El controlador debe cerrar el controlador con ZwClose tan pronto como ya no se use el identificador.

[in] DesiredAccess

Máscara de bits de marcas (vea ACCESS_MASK) que especifica el tipo de acceso que requiere el autor de la llamada al archivo o directorio. Este conjunto de marcas DesiredAccess definidas por el sistema determina los siguientes derechos de acceso específicos para los objetos de archivo.

Marca DesiredAccess	Significado
Delete	El archivo se puede eliminar.
FILE_READ_DATA	Se pueden leer datos de este archivo.
FILE_READ_ATTRIBUTES	Se pueden leer las marcas FileAttributes, que se describen a continuación.
FILE_READ_EA	Se pueden leer los atributos extendidos (CA) asociados al archivo.
READ_CONTROL	Se puede leer la lista de control de acceso (ACL) y la información de propiedad asociada al archivo.
FILE_WRITE_DATA	En este archivo se pueden escribir datos.
FILE_WRITE_ATTRIBUTES	Se pueden escribir marcas FileAttributes.
FILE_WRITE_EA	Las entidades de certificación asociadas con el archivo se pueden escribir.
FILE_APPEND_DATA	Los datos se pueden anexar al archivo.
WRITE_DAC	Se puede escribir la lista de control de acceso discrecional (DACL) asociada al archivo.
WRITE_OWNER	La información de propiedad asociada al archivo se puede escribir.
SYNCHRONIZE	El autor de la llamada puede sincronizar la finalización de una operación de E/S esperando a que fileHandle devuelto se establezca en el estado Señalizado. Esta marca debe establecerse si se establece la marca CreateOptions FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT.
FILE_EXECUTE	Los datos se pueden leer en la memoria del archivo mediante la E/S de paginación del sistema.

Como alternativa, para cualquier objeto de archivo que no represente un directorio, puede especificar una o varias de las marcas de ACCESS_MASK genéricas siguientes. Las marcas de STANDARD_RIGHTS_XXX son valores del sistema predefinidos que se usan para aplicar la seguridad en los objetos del sistema. También puede combinar estas marcas genéricas con marcas adicionales de la tabla anterior.

Acceso deseado a los valores de archivo	Se asigna a las marcas DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

En el caso de los directorios (se establece la marca de FILE_DIRECTORY_FILE CreateOptions ), puede especificar una o varias de las siguientes marcas de ACCESS_MASK, que también puede combinar con las marcas compatibles que se describieron anteriormente.

Acceso deseado a los valores de directorio	Significado
FILE_LIST_DIRECTORY	Los archivos del directorio se pueden enumerar.
FILE_TRAVERSE	Se puede recorrer el directorio; es decir, puede formar parte del nombre de ruta de acceso de un archivo.

Las marcas FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE y FILE_APPEND_DATA DesiredAccess no son compatibles con la creación o apertura de un archivo de directorio.

[in] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES ya inicializada por la rutina InitializeObjectAttributes . Si el autor de la llamada se ejecuta en el contexto del proceso del sistema, este parámetro puede ser NULL. De lo contrario, el autor de la llamada debe establecer el atributo OBJ_KERNEL_HANDLE en la llamada a InitializeObjectAttributes. Los miembros de esta estructura para un objeto de archivo incluyen lo siguiente.

Miembro	Valor
Longitud de ULONG	Número de bytes de los datos ObjectAttributes proporcionados . Este valor debe ser al menos `sizeof(OBJECT_ATTRIBUTES)`.
PUNICODE_STRING ObjectName	Puntero a una cadena Unicode almacenada en búfer que contiene el nombre del archivo que se va a crear o abrir. Este valor debe ser una especificación de archivo completa, a menos que sea el nombre de un archivo relativo al directorio especificado por RootDirectory. Por ejemplo, "\Device\Floppy1\myfile.dat" o "?? \B:\myfile.dat" podría ser la especificación de archivo completa, siempre y cuando el controlador de la unidad de disco disquete y el sistema de archivos sobresalido ya estén cargados. (Nota: "??" reemplaza "\DosDevices" como nombre del espacio de nombres del objeto Win32. "\DosDevices" sigue funcionando, pero "??" se traduce más rápido por el administrador de objetos).
HANDLE RootDirectory	Identificador opcional de un directorio obtenido por una llamada anterior a IoCreateFileEx. Si este valor es NULL, el miembro ObjectName debe ser una especificación de archivo completa que incluya la ruta de acceso completa al archivo de destino. Si este valor no es NULL, el miembro ObjectName especifica un nombre de archivo relativo a este directorio.
PSECURITY_DESCRIPTOR SecurityDescriptor	Descriptor de seguridad opcional que se va a aplicar a un archivo. Las ACL especificadas por este descriptor de seguridad solo se aplican al archivo cuando se crea. Si el valor es NULL cuando se crea un archivo, la ACL colocada en el archivo depende del sistema de archivos; la mayoría de los sistemas de archivos propagan parte de dicha ACL desde el archivo de directorio primario combinado con la ACL predeterminada del autor de la llamada.
Atributos de ULONG	Conjunto de marcas que controla los atributos del objeto de archivo. Si el autor de la llamada se ejecuta en el contexto del proceso del sistema, este parámetro puede ser cero. De lo contrario, el autor de la llamada debe establecer la marca OBJ_KERNEL_HANDLE . El autor de la llamada también puede establecer opcionalmente la marca de OBJ_CASE_INSENSITIVE , que indica que el código de búsqueda de nombres debe omitir el caso de ObjectName en lugar de realizar una búsqueda de coincidencia exacta.

[out] IoStatusBlock

Puntero a una variable de tipo IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación solicitada. Al devolver desde IoCreateFileEx, el miembro Information de la variable contiene uno de los siguientes valores:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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

[in] FileAttributes

Los atributos especificados explícitamente solo se aplican cuando se crea, reemplaza o, en algunos casos, se sobrescribe el archivo. De forma predeterminada, este valor es FILE_ATTRIBUTE_NORMAL, que cualquier otra marca o una combinación (mediante una operación OR bit a bit) de marcas compatibles puede invalidar. Las marcas fileAttributes posibles incluyen lo siguiente.

Marcas fileAttributes	Significado
FILE_ATTRIBUTE_NORMAL	Se debe crear un archivo que tenga atributos estándar.
FILE_ATTRIBUTE_READONLY	Se debe crear un archivo de solo lectura.
FILE_ATTRIBUTE_HIDDEN	Se debe crear un archivo oculto.
FILE_ATTRIBUTE_SYSTEM	Se debe crear un archivo del sistema.
FILE_ATTRIBUTE_ARCHIVE	El archivo debe marcarse para que se archive.
FILE_ATTRIBUTE_TEMPORARY	Se debe crear un archivo temporal.

[in] ShareAccess

Especifica el tipo de acceso compartido al archivo que el autor de la llamada desea, como cero o uno, o una combinación de las marcas siguientes. Para solicitar acceso exclusivo, establezca este parámetro en cero. Si la marca IO_IGNORE_SHARE_ACCESS_CHECK se especifica en el parámetro Options , 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 este parámetro, incluso cuando se usa la marca IO_IGNORE_SHARE_ACCESS_CHECK. Para ayudarle a evitar errores de infracción de uso compartido, especifique todas las marcas de acceso a recursos compartidos siguientes.

Marcas de ShareAccess	Significado
FILE_SHARE_READ	El archivo se puede abrir para el acceso de lectura mediante llamadas de creación de archivos de otros subprocesos.
FILE_SHARE_WRITE	El archivo se puede abrir para el acceso de escritura mediante llamadas de creación de archivos de otros subprocesos.
FILE_SHARE_DELETE	El archivo se puede abrir para eliminar el acceso mediante llamadas de creación de archivos de otros subprocesos.

Los controladores de dispositivo y los controladores intermedios suelen establecer ShareAccess en cero, lo que proporciona al autor de la llamada acceso exclusivo al archivo abierto.

[in] Disposition

Valor que determina cómo se debe controlar el archivo cuando el archivo ya existe. La disposición puede ser una de las siguientes.

Valor	Significado
FILE_SUPERSEDE	Si el archivo ya existe, reemplácelo por el archivo especificado. Si no existe, cree el archivo especificado.
FILE_CREATE	Si el archivo ya existe, produzca un error en la solicitud y no cree ni abra el archivo especificado. Si no existe, cree el archivo especificado.
FILE_OPEN	Si el archivo ya existe, ábralo en lugar de crear un nuevo archivo. Si no existe, genere un error en la solicitud y no cree un nuevo archivo.
FILE_OPEN_IF	Si el archivo ya existe, ábralo. Si no existe, cree el archivo especificado.
FILE_OVERWRITE	Si el archivo ya existe, ábralo y sobrescriba. Si no existe, produzca un error en la solicitud.
FILE_OVERWRITE_IF	Si el archivo ya existe, ábralo y sobrescriba. Si no existe, cree el archivo especificado.

[in] CreateOptions

Especifica las opciones que se van a aplicar al crear o abrir el archivo, como una combinación compatible de las marcas siguientes.

Marca CreateOptions	Significado
FILE_DIRECTORY_FILE (0x00000001)	El archivo que se va a crear o abrir es un archivo de directorio. Con esta marca, el parámetro Disposition debe establecerse en uno de FILE_CREATE, FILE_OPEN o FILE_OPEN_IF. Las marcas CreateOptions que son compatibles con esta marca son las siguientes: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT y FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002)	Los servicios del sistema, los sistemas de archivos y los controladores que escriben datos en el archivo deben transferir realmente los datos al archivo antes de que se considere completada cualquier operación de escritura solicitada.
FILE_SEQUENTIAL_ONLY (0x00000004)	Todos los accesos al archivo serán secuenciales.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	El archivo no se puede almacenar en caché ni almacenarse en búferes internos de un controlador. Esta marca no es compatible con la marca DesiredAccessFILE_APPEND_DATA.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Todas las operaciones del archivo se realizan de forma sincrónica. Cualquier espera en nombre del autor de la llamada está sujeta a la finalización prematura de las alertas. Esta marca también hace que el sistema de E/S mantenga el contexto de posición del archivo. Si se establece esta marca, también se debe establecer la marca DesiredAccess SYNCHRONIZE para que el Administrador de E/S use el objeto de archivo como un objeto de sincronización.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Todas las operaciones del archivo se realizan de forma sincrónica. Las esperas en el sistema para sincronizar la cola de E/S y la finalización no están sujetas a alertas. Esta marca también hace que el sistema de E/S mantenga el contexto de posición del archivo. Si se establece esta marca, también se debe establecer la marca DesiredAccess SYNCHRONIZE para que el Administrador de E/S use el objeto de archivo como un objeto de sincronización.
FILE_NON_DIRECTORY_FILE (0x00000040)	El archivo que se abre no debe ser un archivo de directorio o se produce un error en esta llamada. El objeto de archivo que se abre puede representar un archivo de datos; un dispositivo lógico, virtual o físico; o un volumen.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Cree una conexión de árbol para este archivo con el fin de abrirlo a través de la red.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Complete esta operación inmediatamente con un código correcto alternativo si el archivo de destino está bloqueado, en lugar de bloquear el subproceso del autor de la llamada. Si el archivo está interbloqueado, otro autor de la llamada ya tiene acceso al archivo a través de la red.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Si los atributos extendidos de un archivo existente que se abre indican que el autor de la llamada debe comprender los atributos extendidos para interpretar correctamente el archivo, produzca un error en esta solicitud porque el autor de la llamada no entiende cómo tratar con atributos extendidos.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Reservado para uso del sistema; no use.
FILE_RANDOM_ACCESS (0x00000800)	Los accesos al archivo pueden ser aleatorios, por lo que los sistemas de archivos o el sistema operativo no deben realizar operaciones de lectura anticipada secuenciales en el archivo.
FILE_DELETE_ON_CLOSE (0x00001000)	Elimine el archivo cuando se pase el último identificador a FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000)	El archivo se está abriendo por identificador. El nombre de archivo contiene el nombre de un dispositivo y un identificador de 64 bits que se usará para abrir el archivo.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	El archivo se está abriendo para la intención de copia de seguridad; por lo tanto, el sistema debe comprobar ciertos derechos de acceso y conceder al autor de la llamada los accesos adecuados al archivo antes de comprobar la entrada DesiredAccess en el descriptor de seguridad del archivo.
FILE_NO_COMPRESSION (0x00008000)	Suprima la herencia de FILE_ATTRIBUTE_COMPRESSED del directorio primario. Esto permite la creación de un archivo no comprimido en un directorio marcado como comprimido.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	El archivo se está abriendo y se solicita un bloqueo oportunista (oplock) en el archivo como una única operación atómica. El sistema de archivos comprueba si hay interbloqueos antes de realizar la operación de creación y la operación de creación producirá un error con un código de retorno de STATUS_CANNOT_BREAK_OPLOCK si la operación de creación interrumpiría un interbloqueo existente. Esta marca está disponible en windows 7, Windows Server 2008 R2 y sistemas operativos Windows posteriores.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Al abrir un archivo existente, si no se especifica FILE_SHARE_READ y las comprobaciones de acceso del sistema de archivos no concederían al autor de la llamada acceso de escritura al archivo, no se pudo abrir con STATUS_ACCESS_DENIED. Este era el comportamiento predeterminado anterior a Windows 7.
FILE_SESSION_AWARE (0x00040000)	El archivo o dispositivo se abre con reconocimiento de sesión. Si no se especifica esta marca, los procesos que se ejecutan en la sesión 0 no pueden abrir los dispositivos por sesión (por ejemplo, un dispositivo mediante el redireccionamiento USB de RemoteFX). Esta marca no tiene ningún efecto para los autores de llamadas que no están en la sesión 0. Esta marca solo se admite en las ediciones de servidor de Windows. Esta marca no se admite antes de Windows Server 2012.
FILE_RESERVE_OPFILTER (0x00100000)	Esta marca permite a una aplicación solicitar un bloqueo oportunista de filtro (oplock) para evitar que otras aplicaciones obtengan infracciones de recursos compartidos. Si ya hay identificadores abiertos, se producirá un error en la solicitud de creación con STATUS_OPLOCK_NOT_GRANTED. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
FILE_OPEN_REPARSE_POINT (0x00200000)	Abra un archivo con un punto de reanálisis y omita el procesamiento normal del punto de reanálisis para el archivo. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
FILE_OPEN_NO_RECALL (0x00400000)	Indica a los filtros que realizan almacenamiento sin conexión o virtualización que no recuerden el contenido del archivo como resultado de esta apertura.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Esta marca indica al sistema de archivos que capture el usuario asociado al subproceso que llama. Las llamadas posteriores a FltQueryVolumeInformation o ZwQueryVolumeInformationFile mediante el identificador devuelto asumen que el usuario capturado, en lugar del usuario que realiza la llamada en el momento, con el fin de calcular el espacio libre disponible para el autor de la llamada. Esto se aplica a los siguientes valores FsInformationClass: FileFsSizeInformation, FileFsFullSizeInformation y FileFsFullSizeInformationEx.

[in, optional] EaBuffer

Puntero a una variable proporcionada por el autor de la llamada de tipo FILE_FULL_EA_INFORMATION que contiene información de atributo extendido (EA) que se va a aplicar al archivo. En el caso de los controladores intermedios y del dispositivo, este parámetro debe ser NULL.

[in] EaLength

Longitud, en bytes, de EaBuffer. Para los controladores de dispositivo y los controladores intermedios, este parámetro debe ser cero.

[in] CreateFileType

Los controladores deben establecer este parámetro en CreateFileTypeNone.

[in, optional] InternalParameters

Los controladores deben establecer este parámetro en NULL.

[in] Options

Especifica las opciones que se usarán durante la generación de la solicitud de creación. Se pueden usar cero o más de los siguientes valores de marca de bits.

Marca de opciones	Significado
IO_FORCE_ACCESS_CHECK	El administrador de E/S debe comprobar la solicitud de creación en el descriptor de seguridad del archivo. Para obtener más información, vea la sección Comentarios.
IO_IGNORE_SHARE_ACCESS_CHECK	El administrador de E/S no debe realizar comprobaciones de acceso a recursos compartidos en el objeto de archivo después de crearlo. Sin embargo, es posible que el sistema de archivos siga realizando estas comprobaciones.
IO_STOP_ON_SYMLINK	Si se encuentra una unión, un vínculo simbólico o un punto de reanálisis global al abrir o crear el archivo, el administrador de E/S devolverá STATUS_STOPPED_ON_SYMLINK. Además, se devolverá una estructura de REPARSE_DATA_BUFFER en IoStatusBlock-Information>. El autor de la llamada es responsable de liberar la estructura REPARSE_DATA_BUFFER .
IO_OPEN_TARGET_DIRECTORY	Abra el directorio primario del archivo.

[in, optional] DriverContext

Puntero opcional a una estructura de IO_DRIVER_CREATE_CONTEXT inicializada previamente por la rutina IoInitializeDriverCreateContext . La estructura IO_DRIVER_CREATE_CONTEXT se puede usar para pasar parámetros adicionales a las rutinas IoCreateFileEx y FltCreateFileEx2 . Consulte la sección Comentarios siguientes para obtener más información.

Valor devuelto

IoCreateFileEx devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes.

Código devuelto	Descripción
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	IoCreateFileEx devuelve este valor de estado si el parámetro DriverContext no es NULL y si el objeto de dispositivo especificado no está asociado a la pila de controladores del sistema de archivos para el volumen especificado en el nombre de archivo o directorio. El miembro DeviceObjectHint de la estructura IO_DRIVER_CREATE_CONTEXT especifica este objeto de dispositivo. Para obtener más información, consulte IO_DRIVER_CREATE_CONTEXT.
STATUS_MOUNT_POINT_NOT_RESOLVED	IoCreateFileEx devuelve este valor de estado si el parámetro DriverContext no es NULL y si el nombre del archivo o directorio contiene un punto de montaje que se resuelve en un volumen distinto del al que está asociado el objeto de dispositivo especificado. El miembro DeviceObjectHint de la estructura IO_DRIVER_CREATE_CONTEXT especifica este objeto de dispositivo. Para obtener más información, consulte IO_DRIVER_CREATE_CONTEXT.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx devuelve este valor de estado si el parámetro ObjectAttributes no contenía un miembro RootDirectory , pero el miembro ObjectName de la estructura OBJECT_ATTRIBUTES era una cadena vacía o no contenía un carácter OBJECT_NAME_PATH_SEPARATOR. Esto indica una sintaxis incorrecta para la ruta de acceso del objeto.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx devuelve este valor de estado si se establece la marca de parámetro OptionsIO_STOP_ON_SYMLINK y se encuentra un vínculo simbólico al abrir o crear el archivo.

Si la rutina IoCreateFileEx devuelve un estado de error, el autor de la llamada puede encontrar información adicional sobre la causa del error comprobando el parámetro IoStatusBlock .

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

Comentarios

La rutina IoCreateFileEx es similar a la rutina IoCreateFile y a la rutina IoCreateFileSpecifyDeviceObjectHint, pero ofrece funcionalidad adicional, incluido el acceso a parámetros de creación adicionales (ECP), sugerencias de objetos de dispositivo e información de transacción a través del parámetro DriverContext de la rutina IoCreateFileEx. Para obtener más información sobre estos parámetros basados en estructuras, consulte IO_DRIVER_CREATE_CONTEXT.

Los controladores de filtro del sistema de archivos llaman a IoCreateFileEx para enviar una solicitud de creación solo a un objeto de dispositivo especificado, los filtros adjuntos debajo de él y el sistema de archivos. Los filtros asociados encima del objeto de dispositivo especificado en la pila de controladores no reciben la solicitud de creación. Sin embargo, si el miembro DeviceObjectHint de la estructura IO_DRIVER_CREATE_CONTEXT (que se pasa a través del parámetro DriverContext ) es NULL, la solicitud va a la parte superior de la pila y se recibe por todos los filtros y el sistema de archivos.

Si la solicitud de E/S no va a la parte superior de la pila de controladores, es decir, si el parámetro DriverContext no es NULL y el miembro DeviceObjectHint de la estructura de IO_DRIVER_CREATE_CONTEXT especifica un objeto de dispositivo válido, se aplica la siguiente restricción:

Si la ruta de acceso del nombre de archivo que se pasa a la rutina IoCreateFileEx contiene un punto de montaje, el punto de montaje debe resolverse en el mismo volumen donde reside el archivo o directorio.

Las llamadas posteriores pueden usar el identificador obtenido por IoCreateFileEx para manipular datos dentro del archivo o el estado o los atributos del objeto de archivo. Cualquier identificador que se obtenga de IoCreateFileEx debe liberarse al llamar a ZwClose.

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

Como nombre de ruta de acceso completo, proporcionado en el miembro ObjectName del parámetro ObjectAttributes de entrada.
Como nombre de ruta de acceso relativo al identificador en el miembro RootDirectory del parámetro ObjectAttributes de entrada. (Este identificador puede representar un archivo de directorio).

Las rutinas de controlador que se ejecutan en un contexto de proceso distinto del del proceso del sistema deben establecer el atributo OBJ_KERNEL_HANDLE para el parámetro ObjectAttributes de IoCreateFileEx. Esto restringe el uso del identificador devuelto por IoCreateFileEx 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. Los controladores pueden llamar a InitializeObjectAttributes para establecer el atributo OBJ_KERNEL_HANDLE.

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. De lo contrario, un llamador que sea un dispositivo o un controlador intermedio debe sincronizar una finalización de E/S mediante un objeto de evento.
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 extenderá 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 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 leer ni escribir directamente ningún dato en el archivo con el FileHandle devuelto: es decir, todas las operaciones del archivo se producen a través del buscapersonas del sistema en respuesta a las instrucciones y a los accesos a datos. Los controladores intermedios y de dispositivo no deben establecer la marca FILE_EXECUTE en DesiredAccess.

El parámetro ShareAccess determina si los subprocesos independientes pueden acceder al mismo archivo, posiblemente simultáneamente. Siempre que ambos abiertores de archivos tengan 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 IoCreateFileEx no especifica FILE_SHARE_READ, FILE_SHARE_WRITE o FILE_SHARE_DELETE, no se puede realizar ninguna otra operación abierta en el archivo: es decir, el autor de la llamada original tiene acceso exclusivo al archivo.

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

Si IO_IGNORE_SHARE_ACCESS_CHECK se especifica en el parámetro Options , 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.

El valor De disposición 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 IoCreateFileEx 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, el subproceso abrió el archivo especificando un parámetro de ShareAccess con la marca FILE_SHARE_DELETE establecida. Observe que este tipo de disposición es coherente con el estilo POSIX de sobrescribir archivos.

Los valores De disposición FILE_OVERWRITE_IF y FILE_SUPERSEDE son similares. Si se llama a IoCreateFileEx con un archivo existente y cualquiera de estos valores De disposición , el archivo se reemplazará.

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 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 IoCreateFileEx 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 con el sistema operativo/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 que se va a abrir no es un archivo de directorio, o si el autor de la llamada especificó un valor CreateOptions o Disposition incoherente, se producirá un error en la llamada a IoCreateFileEx .

La marca CreateOptions FILE_NO_INTERMEDIATE_BUFFERING impide que el sistema de archivos realice un 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 Zw.. Rutinas de archivo , incluidas las siguientes:

Cualquier ByteOffset opcional pasado a ZwReadFile o ZwWriteFile debe ser entero (entero múltiple) del tamaño del sector.
La longitud pasada a ZwReadFile o ZwWriteFile debe ser una parte integral del tamaño del sector. Observe que especificar una operación de lectura en un búfer cuya longitud es exactamente el tamaño del sector podría dar lugar a un número menor de bytes significativos que se transfieren 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 subyacente. Esta información se puede obtener llamando a IoCreateFileEx 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. Para obtener una lista de los valores de FILE_XXX_ALIGNMENT del sistema, consulte DEVICE_OBJECT.
Las llamadas a ZwSetInformationFile con el parámetro FileInformationClass establecido en FilePositionInformation deben especificar un desplazamiento entero del tamaño del sector.

Las marcas CreateOptions, FILE_SYNCHRONOUS_IO_ALERT y FILE_SYNCHRONOUS_IO_NONALERT mutuamente excluyentes, especifican 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. Todas las E/S de este archivo se serializan en todos los subprocesos mediante el identificador devuelto. Con cualquiera de estos valores CreateOptions , se debe establecer la marca DesiredAccess SYNCHRONIZE para que el Administrador de E/S use el objeto de archivo como un objeto de sincronización. Con cualquiera de estos valores CreateOptions establecidos, el Administrador de E/S mantiene el "contexto de posición de archivo" para el objeto de archivo, un desplazamiento de posición de archivo interno y actual. Este desplazamiento se puede usar en llamadas a ZwReadFile y ZwWriteFile. También se puede consultar su posición llamando a ZwQueryInformationFile o estableciendo mediante una llamada a ZwSetInformationFile.

Si no se especifica la marca CreateOptions FILE_OPEN_REPARSE_POINT y IoCreateFileEx 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, no se produce el procesamiento normal de reanálisis y IoCreateFileEx intenta abrir directamente el archivo de punto de reanálisis. En cualquier caso, si la operación de apertura se realizó correctamente, IoCreateFileEx devuelve STATUS_SUCCESS; de lo contrario, la rutina devuelve un código de error NTSTATUS. IoCreateFileEx 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 IoCreateFileEx 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.

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 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 seguir estos pasos:

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.

Para crear solicitudes que se originan en modo de usuario, si el controlador establece IO_FORCE_ACCESS_CHECK en el parámetro Options de IoCreateFileEx , también debe establecer OBJ_FORCE_ACCESS_CHECK en el parámetro ObjectAttributes . Para obtener información sobre esta marca, consulte el miembro Atributos de OBJECT_ATTRIBUTES.

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

IoCreateFileEx se puede usar para obtener un identificador para un volumen.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	ntddk.h (incluya Ntddk.h, Ntifs.h, FltKernel.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL