Función IoCreateFileEx (ntddk.h)

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.

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.

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.

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.

[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.

[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.

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.

[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.

[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.

[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.

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:

1. 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.

2. Si la solicitud de creación se realiza correctamente, solicite un interbloqueo.

3. 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

Consulte también

ACCESS_MASK

ACL

DEVICE_OBJECT

FILE_FULL_EA_INFORMATION

FltAcknowledgeEcp

FltAllocateExtraCreateParameter

FltAllocateExtraCreateParameterList

FltClose

FltCreateFileEx2

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoCreateFile

IoCreateFileSpecifyDeviceObjectHint

UNICODE_STRING

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile