Función NtCreateFile (ntifs.h)

Artículo
03/08/2023

La rutina NtCreateFile crea un nuevo archivo o abre un archivo existente.

Sintaxis

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [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
);

Parámetros

[out] FileHandle

Puntero a una variable HANDLE que recibe un identificador para el archivo.

[in] DesiredAccess

Especifica un valor de ACCESS_MASK que determina el acceso solicitado al objeto .

Además de los derechos de acceso estándar definidos para todos los tipos de objetos, el autor de la llamada puede especificar cualquiera de los siguientes derechos de acceso específicos ; es decir, derechos específicos de los archivos.

marca de ACCESS_MASK	Permite al autor de la llamada hacer esto
FILE_READ_DATA	Lee datos del archivo.
FILE_READ_ATTRIBUTES	Lea los atributos del archivo. Para obtener más información, vea la descripción del parámetro FileAttributes .
FILE_READ_EA	Lea los atributos extendidos (EAs) del archivo. Esta marca es irrelevante para los controladores intermedios y del dispositivo.
FILE_WRITE_DATA	Escriba datos en el archivo.
FILE_WRITE_ATTRIBUTES	Escriba los atributos del archivo. Para obtener más información, vea la descripción del parámetro FileAttributes .
FILE_WRITE_EA	Cambie los atributos extendidos (EAs) del archivo. Esta marca es irrelevante para los controladores intermedios y del dispositivo.
FILE_APPEND_DATA	Anexe datos al archivo.
FILE_EXECUTE	Use la E/S de paginación del sistema para leer datos del archivo en memoria. Esta marca es irrelevante para los controladores intermedios y del dispositivo.

Nota

No especifique FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA ni FILE_EXECUTE al crear o abrir un directorio.

El autor de la llamada también puede especificar los siguientes derechos de acceso genéricos (derechos que se aplican a todos los tipos de objetos, donde el significado de cada derecho de acceso genérico es específico del tipo de objeto). Los derechos de acceso genéricos para los objetos de archivo corresponden a derechos de acceso específicos, como se muestra en la tabla siguiente. (Tenga en cuenta que "corresponde" significa "se asigna a" y no significa que el valor del derecho genérico sea "igual a" el valor del OR bit a bit de su asignación de derechos específica). El administrador de E/S define la asignación real.

Derecho de acceso genérico	Se asigna a estos derechos de acceso específicos
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, FILE_EXECUTE, FILE_READ_ATTRIBUTES y SYNCHRONIZE. Este valor es irrelevante para los controladores intermedios y del dispositivo.
GENERIC_ALL	FILE_ALL_ACCESS

Nota

Los derechos de acceso genéricos solo se pueden especificar para un archivo; no se pueden especificar para un directorio.

Algunas marcas CreateOptions requieren que se establezcan determinadas marcas de acceso en DesiredAccess cuando se llama a NtCreateFile . Consulte el parámetro CreateOptions para obtener estos detalles.

Por ejemplo, si especifica GENERIC_READ para un objeto de archivo, la rutina asigna este valor al FILE_GENERIC_READ máscara de bits de derechos de acceso específicos. En la tabla anterior, los derechos de acceso específicos que se enumeran para GENERIC_READ corresponden a (pero no son iguales a) las marcas de acceso contenidas en la máscara de bits de FILE_GENERIC_READ.

Si el archivo es realmente un directorio, el autor de la llamada también puede especificar los siguientes derechos de acceso genéricos.

Marca DesiredAccess	Permite al autor de la llamada hacer esto
FILE_LIST_DIRECTORY	Enumere los archivos del directorio.
FILE_TRAVERSE	Recorrer el directorio, es decir, incluir el directorio en la ruta de acceso de un archivo.

Para obtener más información sobre los derechos de acceso, consulte ACCESS_MASK y Derechos de acceso.

[in] ObjectAttributes

Puntero a una estructura OBJECT_ATTRIBUTES que especifica el nombre del objeto y otros atributos. Use InitializeObjectAttributes para inicializar esta estructura. Si el autor de la llamada no se ejecuta en un contexto de subproceso del sistema, debe establecer el atributo OBJ_KERNEL_HANDLE cuando llama a InitializeObjectAttributes.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final y otra información sobre la operación solicitada. En concreto, el miembro Information recibe uno de los siguientes valores:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Puntero a un LARGE_INTEGER que contiene el tamaño de asignación inicial, en bytes, para un archivo creado o sobrescrito. Si AllocationSize es NULL, no se especifica ningún tamaño de asignación. Si no se crea ni se sobrescribe ningún archivo, se omite AllocationSize .

[in] FileAttributes

Especifica una o varias marcas FILE_ATTRIBUTE_XXX , que representan los atributos de archivo que se van a establecer si crea o sobrescribe un archivo. Normalmente, el autor de la llamada especifica FILE_ATTRIBUTE_NORMAL, que establece los atributos predeterminados. Para obtener una lista de las marcas FILE_ATTRIBUTE_XXX válidas, consulte la rutina CreateFile en la documentación de Microsoft Windows SDK. Si no se crea ni se sobrescribe ningún archivo, se omite FileAttributes .

[in] ShareAccess

Tipo de acceso a recursos compartidos, que se especifica como cero o cualquier combinación de las marcas siguientes.

Marca de ShareAccess	Permite que otros subprocesos lo hagan
FILE_SHARE_READ	Leer el archivo
FILE_SHARE_WRITE	Escribir el archivo
FILE_SHARE_DELETE	Eliminar el archivo

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

[in] CreateDisposition

Especifica la acción que se va a realizar si el archivo no existe o no. CreateDisposition puede ser uno de los valores de la tabla siguiente.

Valor CreateDisposition	Acción si el archivo existe	Acción si el archivo no existe
FILE_SUPERSEDE	Reemplace el archivo.	Cree el archivo.
FILE_CREATE	Devuelve un error.	Cree el archivo.
FILE_OPEN	Abra el archivo.	Devuelve un error.
FILE_OPEN_IF	Abra el archivo.	Cree el archivo.
FILE_OVERWRITE	Abra el archivo y sobrescriba.	Devuelve un error.
FILE_OVERWRITE_IF	Abra el archivo y sobrescriba.	Cree el archivo.

[in] CreateOptions

Especifica las opciones que se deben aplicar cuando el controlador crea o abre el archivo. Use una o varias de las marcas de la tabla siguiente.

Marca CreateOptions	Significado
FILE_DIRECTORY_FILE (0x00000001)	El archivo es un directorio. Las marcas CreateOptions compatibles se FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT y FILE_OPEN_BY_FILE_ID. El parámetro CreateDisposition debe establecerse en FILE_CREATE, FILE_OPEN o FILE_OPEN_IF.
FILE_WRITE_THROUGH (0x00000002)	Los servicios del sistema, los controladores del sistema 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)	Todo el acceso al archivo será secuencial.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	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 de FILE_APPEND_DATA del parámetro DesiredAccess .
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 terminación prematura de las alertas. Esta marca también hace que el sistema de E/S mantenga el puntero de posición de archivo. Si se establece esta marca, la marca SYNCHRONIZE debe establecerse en el parámetro DesiredAccess .
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Todas las operaciones del archivo se realizan de forma sincrónica. Las esperas en el sistema que sincronizan 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, la marca SYNCHRONIZE debe establecerse en el parámetro DesiredAccess .
FILE_NON_DIRECTORY_FILE (0x00000040)	El archivo no es un directorio. El objeto de archivo que se va a abrir 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 para abrirlo a través de la red. Este indicador no lo usan los controladores intermedios y del dispositivo.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Complete esta operación inmediatamente con un código correcto alternativo de STATUS_OPLOCK_BREAK_IN_PROGRESS 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. Este indicador no lo usan los controladores intermedios y del dispositivo.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Si los atributos extendidos (CA) 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, NtCreateFile debe devolver un error. Esta marca es irrelevante para los controladores intermedios y del dispositivo.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Reservado para uso del sistema; no use.
FILE_RANDOM_ACCESS (0x00000800)	El acceso al archivo puede ser aleatorio, por lo que los controladores del sistema de archivos o el sistema no deben realizar operaciones de lectura anticipada secuenciales.
FILE_DELETE_ON_CLOSE (0x00001000)	El sistema elimina el archivo cuando el último identificador del archivo se pasa a NtClose. Si se establece esta marca, la marca DELETE debe establecerse en el parámetro DesiredAccess .
FILE_OPEN_BY_FILE_ID (0x00002000)	El nombre de archivo especificado por el parámetro ObjectAttributes incluye un número de referencia de archivo binario de 8 bytes o un número de referencia de 16 bytes para el archivo, en función del sistema de archivos. Opcionalmente, un nombre de dispositivo seguido de un carácter de barra diagonal inversa puede continuar con estos valores binarios. Vea Comentarios para obtener más detalles y un ejemplo.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	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 el acceso adecuado al archivo, antes de comprobar el parámetro DesiredAccess en el descriptor de seguridad del archivo. Esta marca no la usan los controladores intermedios y del dispositivo.
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 producirá un error en la creación con un código de retorno de STATUS_CANNOT_BREAK_OPLOCK si el resultado sería interrumpir un interbloqueo existente. Esta marca está disponible a partir de Windows 7 y Windows Server 2008 R2.
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. Esta marca está disponible a partir de Windows 7 y Windows Server 2008 R2.
FILE_SESSION_AWARE (0x00040000)	El cliente que abre el archivo o el dispositivo es compatible con la sesión y el acceso por sesión se valida si es necesario. Esta marca está disponible a partir de Windows 8.
FILE_RESERVE_OPFILTER (0x00100000)	Esta marca permite a una aplicación solicitar un bloqueo oportunista filter (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.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000)	Interprete el parámetro EaBuffer como una instancia de EXTENDED_CREATE_INFORMATION. Esta marca está disponible a partir de Windows 11, versión 22H2.

[in, optional] EaBuffer

Para los controladores intermedios y del dispositivo, este parámetro debe ser un puntero NULL .

[in] EaLength

En el caso de los controladores intermedios y del dispositivo, este parámetro debe ser cero.

Valor devuelto

NtCreateFile devuelve STATUS_SUCCESS si se ejecuta correctamente o un código de error NTSTATUS adecuado en caso de error. En este último caso, el autor de la llamada puede determinar la causa del error comprobando el parámetro IoStatusBlock .

Nota

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

Comentarios

NtCreateFile proporciona un identificador que el autor de la llamada puede usar para manipular los datos de un archivo o el estado y los atributos del objeto de archivo. Para obtener más información, vea Usar archivos en un controlador.

Una vez que el identificador al que apunta FileHandle ya no está en uso, el controlador debe llamar a NtClose para cerrarlo.

Si el autor de la llamada no se ejecuta en un contexto de subproceso del sistema, debe asegurarse de que los identificadores que cree sean identificadores privados. De lo contrario, el proceso puede acceder al identificador en cuyo contexto se ejecuta el controlador. Para obtener más información, vea Identificadores de objeto.

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

Como pathname completo, proporcionado en el miembro ObjectName de la entrada ObjectAttributes.
Como pathname relativo al archivo de directorio representado por el identificador en el miembro RootDirectory de la entrada ObjectAttributes.

Establecer determinadas marcas en el parámetro DesiredAccess da como resultado los siguientes efectos:

Para que un autor de llamada sincronice una finalización de E/S esperando a que se devuelva FileHandle, se debe establecer la marca SYNCHRONIZE. De lo contrario, un autor de llamada que sea un dispositivo o controlador intermedio debe sincronizar una finalización de E/S mediante un objeto de evento.
Si el autor de la llamada establece solo las marcas FILE_APPEND_DATA y SYNCHRONIZE, solo puede escribir al final del archivo y se omite cualquier información de desplazamiento sobre las operaciones de escritura en el archivo. El archivo se extenderá automáticamente según sea necesario para este tipo de operación.
Establecer la marca FILE_WRITE_DATA para un archivo también permite que el autor de la llamada escriba más allá del final del archivo. De nuevo, el archivo se extiende automáticamente según sea necesario.
Si el autor de la llamada establece solo las marcas FILE_EXECUTE y SYNCHRONIZE, no puede leer ni escribir directamente ningún dato en el archivo mediante el fileHandle devuelto. Es decir, todas las operaciones del archivo se producen a través del buscapersonas del sistema en respuesta a las operaciones de instrucción y acceso a datos. Los controladores intermedios y de dispositivo no deben establecer la marca FILE_EXECUTE.

El parámetro ShareAccess determina si los subprocesos independientes pueden tener acceso al mismo archivo, posiblemente simultáneamente. Siempre que ambos autores de llamada tengan los privilegios de acceso adecuados, el archivo se puede abrir y compartir correctamente. Si el autor de la llamada original de NtCreateFile no especifica FILE_SHARE_READ, FILE_SHARE_WRITE o FILE_SHARE_DELETE, ningún otro autor de llamada puede abrir el archivo, es decir, se concede acceso exclusivo al autor de la llamada original.

Para abrir correctamente un archivo compartido, las marcas DesiredAccess deben ser compatibles con las marcas DesiredAccess y ShareAccess de todas las operaciones abiertas anteriores que aún no se han publicado a través de . Es decir, el DesiredAccess especificado en NtCreateFile para un archivo determinado no debe entrar en conflicto con los accesos a los que otros abiertores del archivo no se han permitido.

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 NtCreateFile 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 NtCreateFile con un archivo existente y cualquiera de estos valores CreateDisposition , el archivo se reemplazará.

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 NtCreateFile 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, Microsoft Windows 3.1 y OS/2.

El valor de FILE_DIRECTORY_FILE CreateOptions especifica que el archivo que se va a crear o abrir es un 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 producirá un error en la llamada a NtCreateFile .

La marca CreateOptions de FILE_NO_INTERMEDIATE_BUFFERING impide que el sistema de archivos realice cualquier almacenamiento en búfer intermedio en nombre del autor de la llamada. Al especificar esta marca, se aplican las restricciones siguientes a los parámetros del autor de la llamada a otras rutinas zwxxxFile .

Cualquier ByteOffset opcional pasado a NtReadFile o NtWriteFile debe ser un múltiplo del tamaño del sector.
La longitud pasada a NtReadFile o NtWriteFile debe ser una parte integral 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. Para obtener esta información, llame a NtCreateFile para obtener un identificador para el objeto de archivo que representa el dispositivo físico y pase ese identificador a NtQueryInformationFile. Para obtener una lista de los valores FILE_XXX_ALIGNMENT del sistema, consulte DEVICE_OBJECT.
Las llamadas a NtSetInformationFile 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 marcas CreateOptions (que son mutuamente excluyentes) especifican que todas las operaciones de E/S del archivo serán sincrónicas, siempre y cuando las operaciones se produzcan a través del objeto de archivo al que hace referencia el FileHandle devuelto. Todas las E/S de este tipo de archivo se serializan en todos los subprocesos mediante el identificador devuelto. Si se establece alguna de estas marcas CreateOptions , la marca SYNCHRONIZE DesiredAccess también debe establecerse para obligar al administrador de E/S a usar el objeto de archivo como un objeto de sincronización. En estos casos, el administrador de E/S realiza un seguimiento del desplazamiento de posición de archivo actual, que puede pasar a NtReadFile y NtWriteFile. Llame a NtQueryInformationFile o NtSetInformationFile para obtener o establecer esta posición.

Si no se especifica la marca CreateOptions FILE_OPEN_REPARSE_POINT y NtCreateFile intenta abrir un archivo con un punto de reanálisis, se produce el procesamiento normal del punto de reanálisis para el archivo. Si, por otro lado, se especifica la marca FILE_OPEN_REPARSE_POINT, no se produce el procesamiento de reanálisis normal y NtCreateFile intenta abrir directamente el archivo de punto de reanálisis. En cualquier caso, si la operación de apertura se realizó correctamente, NtCreateFile devuelve STATUS_SUCCESS; de lo contrario, la rutina devuelve un código de error NTSTATUS. NtCreateFile nunca devuelve STATUS_REPARSE.

La marca CreateOptions FILE_OPEN_REQUIRING_OPLOCK elimina el tiempo entre abrir el archivo y solicitar un interbloqueo que podría permitir que un tercero abra el archivo y obtenga una infracción de uso compartido. Una aplicación puede usar la marca FILE_OPEN_REQUIRING_OPLOCK en NtCreateFile y, a continuación, solicitar cualquier interbloqueo. Esto garantiza que se notificará a un propietario de oplock cualquier solicitud abierta posterior que provoque una infracción de uso compartido.

En Windows 7, si existen otros identificadores en el archivo cuando una aplicación usa la marca FILE_OPEN_REQUIRING_OPLOCK, se producirá un error en la operación de creación con STATUS_OPLOCK_NOT_GRANTED. Esta restricción ya no existe a partir de Windows 8.

Si esta operación de creación interrumpiría un interbloqueo que ya existe en el archivo, al establecer la marca FILE_OPEN_REQUIRING_OPLOCK se producirá un error en la operación de creación con STATUS_CANNOT_BREAK_OPLOCK. Esta operación de creación no romperá el interbloqueo existente.

Una aplicación que use la marca FILE_OPEN_REQUIRING_OPLOCK 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 normal del bloqueo de operación. Del mismo modo, si esta llamada se realiza correctamente, pero se produce un error en la solicitud de interbloqueo posterior, una aplicación que usa esta marca debe cerrar su identificador después de detectar que se ha producido un error en la solicitud de interbloqueo.

Nota

La marca FILE_OPEN_REQUIRING_OPLOCK está disponible en Los sistemas operativos Windows 7, Windows Server 2008 R2 y versiones posteriores. Los sistemas de archivos de Microsoft que implementan esta marca en Windows 7 son NTFS, FAT y exFAT.

La marca CreateOptions FILE_RESERVE_OPFILTER permite a una aplicación solicitar un oplock de nivel 1, lote o filtro para evitar que otras aplicaciones obtengan infracciones de recursos compartidos. Sin embargo, FILE_RESERVE_OPFILTER solo resulta prácticamente útil para los interbloqueos de filtro. Para usarlo, debe completar los pasos siguientes:

Emita una solicitud de creación con CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess de exactamente FILE_READ_ATTRIBUTES y ShareAccess de exactamente FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Si ya hay identificadores abiertos, se produce un error en la solicitud de creación con STATUS_OPLOCK_NOT_GRANTED y también se produce un error en el siguiente bloqueo de operación solicitado.
- Si abre con más acceso o menos uso compartido también provocará un error de STATUS_OPLOCK_NOT_GRANTED.
Si la solicitud de creación se realiza correctamente, solicite un interbloqueo.
Abra otro identificador en el archivo para realizar E/S.

El paso 3 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 todavía 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 batch 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.

Para la marca de FILE_OPEN_BY_FILE_ID CreateOptions , un nombre de dispositivo de ejemplo tendrá el formato:

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

donde FileID es de 8 bytes y ObjectID es de 16 bytes:

En NTFS, puede ser un número de referencia de 8 bytes o un número de referencia de 16 bytes o un identificador de objeto. Un número de referencia de 16 bytes es el mismo que un número de 8 bytes rellenado con ceros.
En ReFS, puede ser un número de referencia de 8 bytes o de 16 bytes. Un número de 16 bytes no está relacionado con un número de 8 bytes. No se admiten identificadores de objeto.
Los sistemas de archivos FAT, ExFAT, UDFS y CDFS no admiten la marca FILE_OPEN_BY_FILE_ID.

Este número lo asigna y es específico del sistema de archivos en particular. Dado que el campo de nombre de archivo contendrá en parte un blob binario, es incorrecto suponer que se trata de una cadena Unicode válida y, lo que es más importante, no puede ser una cadena terminada en null.

Los autores de llamadas de NtCreateFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con las API de kernel especiales habilitadas.

Nota

Si la llamada a esta función se produce en modo de usuario, debe usar el nombre "NtCreateFile" en lugar de "ZwCreateFile".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Servicios del sistema nativo de Windows se pueden comportar de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000
Plataforma de destino	Universal
Encabezado	ntifs.h (incluye Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs, PowerIrpDDis