Función IoCreateFileSpecifyDeviceObjectHint (ntddk.h)

Artículo
03/08/2023

Los controladores de filtro del sistema de archivos usan la rutina IoCreateFileSpecifyDeviceObjectHint para enviar una solicitud de creación solo a los filtros debajo de un objeto de dispositivo especificado y al sistema de archivos.

Sintaxis

NTSTATUS IoCreateFileSpecifyDeviceObjectHint(
  [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] PVOID              DeviceObject
);

Parámetros

[out] FileHandle

Puntero a una variable que recibe un identificador para el objeto de archivo si esta llamada se realiza correctamente.

[in] DesiredAccess

Máscara de bits de marcas que especifican el tipo de acceso que requiere el autor de la llamada en el archivo o directorio. El conjunto de marcas DesiredAccess definidas por el sistema determina los siguientes derechos de acceso específicos para los objetos de archivo.

Marcas desiredAccess	Significado
Delete	El archivo se puede eliminar.
FILE_READ_DATA	Se pueden leer datos de este archivo.
FILE_READ_ATTRIBUTES	Las marcas FileAttributes , descritas más adelante, se pueden leer.
FILE_READ_EA	Se pueden leer los atributos extendidos (EA) 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	Se pueden escribir atributos extendidos asociados al archivo.
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.

Los autores de llamadas de IoCreateFileSpecifyDeviceObjectHint pueden especificar una o una combinación de las siguientes, posiblemente ORed con marcas compatibles adicionales de la lista anterior de marcasDesiredAccess , para cualquier objeto de archivo que no represente un archivo de directorio:

DesiredAccess 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 y SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA y SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES y FILE_EXECUTE.

El STANDARD_RIGHTS_XXX son valores del sistema predefinidos que se usan para aplicar la seguridad en los objetos del sistema.

Si se establece la marca CreateOptions de FILE_DIRECTORY_FILE, los autores de llamadas de IoCreateFileSpecifyDeviceObjectHint pueden especificar una o una combinación de las siguientes, posiblemente ORed con una o varias marcas compatibles de la lista anterior de marcasDesiredAccess .

DesiredAccess to directory values	Significado
FILE_LIST_DIRECTORY	Los archivos del directorio se pueden enumerar.
FILE_TRAVERSE	El directorio se puede recorrer: 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 (ObjectAttributes) puede ser NULL. De lo contrario, el llamador debe establecer el atributo OBJ_KERNEL_HANDLE en la llamada a la rutina InitializeObjectAttributes . Los miembros de la estructura OBJECT_ATTRIBUTES para un objeto de archivo incluyen lo siguiente.

Miembro	Valor
ULONGLength	Especifica el número de bytes de 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 asigna el nombre al 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 disquete y el sistema de archivos sobrescargo ya estén cargados. (Tenga en cuenta que \?? reemplaza a \DosDevices como el nombre del espacio de nombres de objeto Win32. \DosDevices seguirá funcionando, pero \?? se traduce más rápido por el administrador de objetos).
HANDLERootDirectory	Opcionalmente, especifica un identificador para un directorio obtenido por una llamada anterior a IoCreateFileSpecifyDeviceObjectHint. 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	Opcionalmente, especifica un descriptor de seguridad 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.
ULONGAttributes	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 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 estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación solicitada. Al devolver desde IoCreateFileSpecifyDeviceObjectHint, el miembro Information 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 de ORed de marcas compatibles puede invalidar. Las posibles marcas FileAttributes incluyen lo siguiente.

Marcas FileAttributes	Significado
FILE_ATTRIBUTE_NORMAL	Se debe crear un archivo con 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 se especifica la marca IO_IGNORE_SHARE_ACCESS_CHECK en el parámetro Options , el administrador de E/S omite este parámetro. 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 mayor probabilidad de evitar errores de infracción de uso compartido, especifique todas las siguientes marcas de acceso a recursos compartidos.

Marcas de ShareAccess	Significado
FILE_SHARE_READ	Otros subprocesos pueden abrir el archivo para el acceso de lectura.
FILE_SHARE_WRITE	Otros subprocesos pueden abrir el archivo para el acceso de escritura.
FILE_SHARE_DELETE	Otros subprocesos pueden abrir el archivo para eliminar el acceso.

[in] Disposition

Especifica un valor que determina la acción que se va a realizar, dependiendo de si el archivo ya existe. El valor puede ser cualquiera de los descritos a continuación.

Valores de disposición	Significado
FILE_SUPERSEDE	Si el archivo ya existe, reemplácelo por el archivo especificado. Si no es así, cree el archivo especificado.
FILE_CREATE	Si el archivo ya existe, produzca un error en la solicitud y no cree o abra el archivo especificado. Si no es así, cree el archivo especificado.
FILE_OPEN	Si el archivo ya existe, ábralo en lugar de crear un nuevo archivo. Si no es así, produzca un error en la solicitud y no cree un nuevo archivo.
FILE_OPEN_IF	Si el archivo ya existe, ábralo. Si no es así, cree el archivo especificado.
FILE_OVERWRITE	Si el archivo ya existe, ábralo y sobrescriba. Si no es así, se produce un error en la solicitud.
FILE_OVERWRITE_IF	Si el archivo ya existe, ábralo y sobrescriba. Si no es así, cree el archivo especificado.

[in] CreateOptions

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

Marcas CreateOptions	Significado
FILE_DIRECTORY_FILE	El archivo que se va a crear o abrir es un archivo de directorio. Si se establece esta marca, el parámetro Disposition debe establecerse en uno de FILE_CREATE, FILE_OPEN o FILE_OPEN_IF. Esta marca es compatible con las siguientes marcas CreateOptions : FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT y FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE	El archivo que se abre no debe ser un archivo de directorio o se producirá un error en esta llamada. El objeto de archivo que se abre debe representar un archivo de datos.
FILE_WRITE_THROUGH	Los servicios del sistema, los FSD 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	Todos los accesos al archivo serán secuenciales.
FILE_RANDOM_ACCESS	Los accesos al archivo pueden ser aleatorios, por lo que los FSD o el sistema no deben realizar operaciones de lectura anticipada secuenciales.
FILE_NO_INTERMEDIATE_BUFFERING	El archivo no se puede almacenar en caché ni almacenar en búferes internos de un controlador. Esta marca no es compatible con la marca DesiredAccess FILE_APPEND_DATA.
FILE_SYNCHRONOUS_IO_ALERT	Todas las operaciones del archivo se realizan de forma sincrónica. Cualquier espera en nombre del autor de la llamada está sujeta a la terminació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.
FILE_SYNCHRONOUS_IO_NONALERT	Todas las operaciones del archivo se realizan de forma sincrónica. Las esperas que existen 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.
FILE_CREATE_TREE_CONNECTION	Cree una conexión de árbol para este archivo para abrirlo a través de la red.
FILE_COMPLETE_IF_OPLOCKED	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	Si los atributos extendidos de un archivo existente que se abre indican que el autor de la llamada debe comprender las entidades de certificación para interpretar correctamente el archivo, produzca un error en esta solicitud porque el autor de la llamada no entiende cómo tratar con las CA.
FILE_OPEN_REPARSE_POINT	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 a continuación.
FILE_DELETE_ON_CLOSE	Elimine el archivo cuando se pase el último identificador a ZwClose.
FILE_OPEN_BY_FILE_ID	El nombre de archivo especificado en el parámetro ObjectAttributes incluye el número de referencia del archivo de 8 bytes para el archivo. El sistema de archivos asigna este número y es específico del sistema de archivos. Si el archivo es un punto de reanálisis, el nombre de archivo también incluye el nombre de un dispositivo. Nota: El sistema de archivos FAT no admite FILE_OPEN_BY_FILE_ID.
FILE_OPEN_FOR_BACKUP_INTENT	El archivo se abre 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_OPEN_REQUIRING_OPLOCK	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 se produce un error en la operación de creación con un código de retorno de STATUS_CANNOT_BREAK_OPLOCK si la creación interrumpiría un interbloqueo existente.
FILE_RESERVE_OPFILTER	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 produce 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.

[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] 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 creación de la solicitud de creación. En la siguiente tabla se enumeran las opciones disponibles.

Marcas de opciones	Significado
IO_FORCE_ACCESS_CHECK	Indica que el administrador de E/S debe comprobar la solicitud de creación en el descriptor de seguridad del archivo.
IO_IGNORE_SHARE_ACCESS_CHECK	Indica que 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.

[in, optional] DeviceObject

Puntero al objeto de dispositivo al que se va a enviar la solicitud de creación. El objeto de dispositivo debe ser un objeto de dispositivo de sistema de archivos o filtro en la pila del controlador del sistema de archivos para el volumen en el que reside el archivo o directorio. Este parámetro es opcional y puede ser NULL. Si este parámetro es NULL, la solicitud se enviará al objeto de dispositivo en la parte superior de la pila de controladores.

Valor devuelto

IoCreateFileSpecifyDeviceObjectHint devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:

Código devuelto	Descripción
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	El DeviceObject especificado no está asociado a la pila de controladores del sistema de archivos para el volumen especificado en el nombre de archivo o directorio. Este error también puede producirse si el nombre contiene un punto de reanálisis distinto de un punto de montaje.
STATUS_MOUNT_POINT_NOT_RESOLVED	El nombre de archivo o directorio contiene un punto de montaje que se resuelve en un volumen distinto del al que está asociado el DeviceObject especificado.
STATUS_OBJECT_PATH_SYNTAX_BAD

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

Comentarios

Los controladores de filtro del sistema de archivos usan esta rutina para enviar una solicitud de creación solo a los filtros debajo de un objeto de dispositivo especificado y al sistema de archivos. Los filtros que están conectados encima del objeto de dispositivo especificado en la pila de controladores no reciben la solicitud de creación.

La rutina IoCreateFileEx de Windows Vista es similar a la rutina IoCreateFileSpecifyDeviceObjectHint , pero proporciona una mayor funcionalidad que la rutina IoCreateFileSpecifyDeviceObjectHint , incluido el acceso a parámetros de creación adicionales (ECP) e información de transacción.

Si usa la rutina IoCreateFileEx en lugar de la rutina IoCreateFileSpecifyDeviceObjectHint , tenga en cuenta que el parámetro DriverContext de la rutina IoCreateFileSpecifyDeviceObjectHint se ha movido al miembro DeviceObjectHint de la estructura IO_DRIVER_CREATE_CONTEXT . La estructura IO_DRIVER_CREATE_CONTEXT se pasa a la rutina IoCreateFileEx a través de su parámetro DriverContext .

Los controladores de filtro del sistema de archivos llaman a IoCreateFileSpecifyDeviceObjectHint 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. Lo mismo sucede con las solicitudes de limpieza o cierre en el objeto de archivo creado por IoCreateFileSpecifyDeviceObjectHint.

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

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 identificador que se obtenga de IoCreateFileSpecifyDeviceObjectHint debe liberarse al llamar a ZwClose.

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 IoCreateFileSpecifyDeviceObjectHint. Esto restringe el uso del identificador devuelto por IoCreateFileSpecifyDeviceObjectHint 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.

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

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 IoCreateFileSpecifyDeviceObjectHint 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 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 ZwClose. Es decir, el desiredAccess especificado en IoCreateFileSpecifyDeviceObjectHint para un archivo determinado no debe entrar en conflicto con los accesos a los que otros openers 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 IoCreateFileSpecifyDeviceObjectHint 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 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 De disposición FILE_OVERWRITE_IF y FILE_SUPERSEDE son similares. Si se llama a IoCreateFileSpecifyDeviceObjectHint 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 IoCreateFileSpecifyDeviceObjectHint no puede deshabilitar las marcas fileAttributes existentes, pero puede habilitar marcas adicionales para el mismo archivo.

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

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

Cualquier valor de desplazamiento de bytes que se pasa a ZwReadFile o ZwWriteFile debe ser un múltiplo del tamaño del sector del dispositivo subyacente.
La longitud que se pasa 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 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 IoCreateFileSpecifyDeviceObjectHint para obtener un identificador para el objeto de archivo que representa el dispositivo físico y, a continuación, llamar 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 que sea un múltiplo del tamaño del sector.

La propiedad CreateOptions, FILE_SYNCHRONOUS_IO_ALERT y FILE_SYNCHRONOUS_IO_NONALERT mutuamente excluyentes, especifique 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 estas opciones 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 conjuntos CreateOptions , el Administrador de E/S mantiene el "contexto de posición del 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 IoCreateFileSpecifyDeviceObjectHint intenta abrir un archivo con un punto de reanálisis, se produce un 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 IoCreateFileSpecifyDeviceObjectHint intenta abrir directamente el archivo de punto de reanálisis. En cualquier caso, si la operación de apertura se realizó correctamente, IoCreateFileSpecifyDeviceObjectHint devuelve STATUS_SUCCESS; de lo contrario, la rutina devuelve un código de error NTSTATUS. IoCreateFileSpecifyDeviceObjectHint 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 IoCreateFileSpecifyDeviceObjectHint 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 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 create 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 producirá un error en la solicitud de creación con STATUS_OPLOCK_NOT_GRANTED y también se producirá 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.

IoCreateFileSpecifyDeviceObjectHint no se puede usar para obtener un identificador para un volumen.

Si la ruta de acceso del nombre de archivo que se pasa a IoCreateFileSpecifyDeviceObjectHint contiene un punto de reanálisis, el punto de reanálisis debe resolverse en el mismo volumen donde reside el archivo o directorio. Si no es así, se devuelve el error STATUS_INVALID_DEVICE_OBJECT_PARAMETER o STATUS_MOUNT_POINT_NOT_RESOLVED.

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