Compartir a través de

Función NtCreateFile (ntifs.h)

  • Artículo

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

[in] DesiredAccess

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

Además del estándar derechos de acceso 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 (EA) 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 (CA) 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 "asignar a" y no significa que el valor del derecho genérico sea "igual a" el valor de 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.

Algunos marcas de 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 a la 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 de DesiredAccess Permite al autor de la llamada hacer esto
FILE_LIST_DIRECTORY Enumere los archivos del directorio.
FILE_TRAVERSE Recorra el directorio, es decir, incluya 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 que se crea o sobrescribe. 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 de 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 marcas de XXX válidas FILE_ATTRIBUTE_, consulte la rutina CreateFile en la documentación del SDK de Microsoft Windows. 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 de CreateDisposition Acción si existe un archivo 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 aplicarán 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 de CreateOptions compatibles son 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 una 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 puesta en cola y la finalización de E/S 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 se 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. A partir de Windows 11, versión 24H2, NTFS ahora respeta esta marca al abrir un atributo $INDEX_ALLOCATION.
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á bloqueado, 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 (EA) 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 se pasa el último identificador al archivo 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 de 8 bytes o de 16 bytes binarios o un identificador de objeto 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. Consulte 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 abre y se solicita un bloqueo oportunista (oplock) en el archivo como una sola 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 devuelto 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, produzca un error al abrirlo 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 siguiente sección Comentarios.
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 siguiente sección Comentarios.
FILE_OPEN_NO_RECALL (0x00400000) Indica a los filtros que realicen almacenamiento sin conexión o virtualización que no recuperen 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. Cualquier llamada posterior a FltQueryVolumeInformation o ZwQueryVolumeInformationFile mediante el identificador devuelto asume 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

En el caso de 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 correcto 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 de 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.

Observaciones

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 Using Files in a Driver.

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 está ejecutando 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 está ejecutando 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 nombre de ruta de acceso completo, proporcionado en el ObjectName miembro de la entrada ObjectAttributes.
  • Como pathname relativo al archivo de directorio representado por el identificador del rootDirectory miembro de la entrada ObjectAttributes.

Al establecer ciertas marcas en el parámetro DesiredAccess se muestran los siguientes efectos:

  • Para que un autor de llamada sincronice una finalización de E/S esperando el FileHandle devuelto, se debe establecer la marca SYNCHRONIZE. De lo contrario, un autor de llamada que sea un dispositivo o un 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 al autor de la llamada escribir 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 de de DesiredAccess deben ser compatibles con el DesiredAccess y ShareAccess marcas de todas las operaciones abiertas anteriores que aún no se han publicado a través de . Es decir, el DesiredAccess especificado para 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 FILE_SUPERSEDE 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 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 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 CreateDisposition FILE_OVERWRITE_IF y FILE_SUPERSEDE son similares. Si se llama NtCreateFile con un archivo existente y cualquiera de estos valores CreateDisposition, se reemplazará el archivo.

Sobrescribir 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 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 existentes FileAttributes, 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 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 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 CreateOptions o valor de CreateDisposition, se producirá un error en la llamada a NtCreateFile.

La marca FILE_NO_INTERMEDIATE_BUFFERING CreateOptions impide que el sistema de archivos realice un 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 de ZwXxxFile.

  • Cualquier byteOff set opcional que se pase a NtReadFile o NtWriteFile debe ser un múltiplo del tamaño del sector.
  • El length de pasado a NtReadFile o ntWriteFile debe ser un entero 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 de_ALIGNMENT XXX de FILE_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 de 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. Toda la E/S de este tipo de archivo se serializa en todos los subprocesos mediante el identificador devuelto. Si se establece cualquiera 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 actual de la posición del archivo, que puede pasar a NtReadFile y NtWriteFile. Llame a NtQueryInformationFile o NtSetInformationFile para obtener o establecer esta posición.

Si la marca FILE_OPEN_REPARSE_POINT CreateOptions no está especificada y ntCreateFile intenta abrir un archivo con un punto de reanálisis, el procesamiento normal de puntos de reanálisis se produce para el archivo. Si, por otro lado, se especifica la marca FILE_OPEN_REPARSE_POINT, el procesamiento normal de reanálisis no se produce 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.

El 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 de FILE_OPEN_REQUIRING_OPLOCK en NtCreateFile 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 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 de interbloqueos. Del mismo modo, si esta llamada se realiza correctamente, pero se produce un error en la solicitud de interbloqueo posterior, una aplicación que use esta marca debe cerrar su identificador después de detectar que se ha producido un error en la solicitud de interbloqueo. La aplicación no debe realizar ninguna otra operación del sistema de archivos en el archivo antes de solicitar el interbloqueo (además de cerrar el identificador de archivo), de lo contrario, puede producirse un interbloqueo.

Nota

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

El marca CreateOptions FILE_RESERVE_OPFILTER permite a una aplicación solicitar un interbloqueo de nivel 1, lote o filtro 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:

  1. Emita una solicitud de creación con createOptions de FILE_RESERVE_OPFILTER, DesiredAccess de exactamente FILE_READ_ATTRIBUTES y de ShareAccess 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 interbloqueo 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 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 FILE_OPEN_BY_FILE_ID createOptions de , 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 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 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 se asigna por y es específico del sistema de archivos en particular. Dado que el campo de nombre de archivo contendrá parcialmente 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 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 NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows pueden comportarse 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 de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito Valor
cliente mínimo admitido Windows 2000
de la plataforma de destino de Universal
encabezado de ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca de NtosKrnl.lib
DLL de NtosKrnl.exe
irQL PASSIVE_LEVEL (consulte la sección Comentarios)
reglas de cumplimiento de DDI HwStorPortProhibitedDIs, PowerIrpDDis

Consulte también

ACCESS_MASK

DEVICE_OBJECT

EXTENDED_CREATE_INFORMATION

IO_STATUS_BLOCK

initializeObjectAttributes

NtClose

NtOpenFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile

NtWriteFile