estructura USN_RECORD_V4 (winioctl.h)

Artículo
03/08/2023

Contiene la información de un registro de la versión 4.0 del diario de cambios de números de secuencias actualizadas (USN). Los registros de la versión 2.0 y 3.0 se definen mediante las estructuras de USN_RECORD_V2 (también denominado USN_RECORD) y de USN_RECORD_V3 respectivamente.

Sintaxis

typedef struct {
  USN_RECORD_COMMON_HEADER Header;
  FILE_ID_128              FileReferenceNumber;
  FILE_ID_128              ParentFileReferenceNumber;
  USN                      Usn;
  DWORD                    Reason;
  DWORD                    SourceInfo;
  DWORD                    RemainingExtents;
  WORD                     NumberOfExtents;
  WORD                     ExtentSize;
  USN_RECORD_EXTENT        Extents[1];
} USN_RECORD_V4, *PUSN_RECORD_V4;

Miembros

Header

Estructura USN_RECORD_COMMON_HEADER que describe la longitud del registro, la versión principal y la versión secundaria del registro.

FileReferenceNumber

Número ordinal de 128 bits del archivo o directorio para el que cambia este registro.

Este valor es un valor asignado arbitrariamente que asocia un registro de diario a un archivo.

ParentFileReferenceNumber

Número ordinal de 128 bits del directorio donde se encuentra el archivo o directorio asociado a este registro.

Este valor es un valor asignado arbitrariamente que asocia un registro de diario a un directorio primario.

Usn

USN de este registro.

Reason

Marcas que identifican los motivos de los cambios que se han acumulado en este registro de diario de archivos o directorios desde que se abrió el archivo o directorio.

Cuando se cierra un archivo o directorio, se genera un registro USN final con la marca USN_REASON_CLOSE establecida. El siguiente cambio (por ejemplo, después de la siguiente operación de apertura o eliminación) inicia un nuevo registro con un nuevo conjunto de marcas de motivo.

Una operación de cambio de nombre o movimiento genera dos registros USN, uno que registra el directorio primario anterior para el elemento y otro que registra un nuevo elemento primario.

En la tabla siguiente se identifican las marcas posibles.

Nota Los bits sin usar están reservados.

Valor	Significado
USN_REASON_BASIC_INFO_CHANGE 0x00008000	Un usuario ha cambiado uno o varios atributos de archivo o directorio (por ejemplo, el atributo de solo lectura, oculto, sistema, archivo o disperso) o una o varias marcas de tiempo.
USN_REASON_CLOSE 0x80000000	Se cierra el archivo o directorio.
USN_REASON_COMPRESSION_CHANGE 0x00020000	El estado de compresión del archivo o directorio se cambia de o a comprimido.
USN_REASON_DATA_EXTEND 0x00000002	El archivo o directorio se extiende (se agrega a).
USN_REASON_DATA_OVERWRITE 0x00000001	Los datos del archivo o directorio se sobrescriben.
USN_REASON_DATA_TRUNCATION 0x00000004	El archivo o directorio se trunca.
USN_REASON_EA_CHANGE 0x00000400	El usuario realizó un cambio en los atributos extendidos de un archivo o directorio. Estos atributos del sistema de archivos NTFS no son accesibles para las aplicaciones basadas en Windows.
USN_REASON_ENCRYPTION_CHANGE 0x00040000	El archivo o directorio está cifrado o descifrado.
USN_REASON_FILE_CREATE 0x00000100	El archivo o directorio se crea por primera vez.
USN_REASON_FILE_DELETE 0x00000200	Se elimina el archivo o directorio.
USN_REASON_HARD_LINK_CHANGE 0x00010000	Se agrega o quita un vínculo físico del sistema de archivos NTFS al archivo o directorio. Un vínculo físico del sistema de archivos NTFS, similar a un vínculo físico POSIX, es una de varias entradas de directorio que ven el mismo archivo o directorio.
USN_REASON_INDEXABLE_CHANGE 0x00004000	Un usuario cambia el atributo FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Es decir, el usuario cambia el archivo o directorio de uno donde el contenido se puede indexar a uno donde no se puede indexar el contenido o viceversa. La indexación de contenido permite la búsqueda rápida de datos mediante la creación de una base de datos de contenido seleccionado.
USN_REASON_INTEGRITY_CHANGE 0x00800000	Un usuario cambió el estado del atributo FILE_ATTRIBUTE_INTEGRITY_STREAM para la secuencia especificada. En el sistema de archivos ReFS, las secuencias de integridad mantienen una suma de comprobación de todos los datos de esa secuencia, de modo que el contenido del archivo se pueda validar durante las operaciones de lectura o escritura.
USN_REASON_NAMED_DATA_EXTEND 0x00000020	Uno o varios flujos de datos con nombre para un archivo se extienden (se agregan a).
USN_REASON_NAMED_DATA_OVERWRITE 0x00000010	Los datos de uno o varios flujos de datos con nombre para un archivo se sobrescriben.
USN_REASON_NAMED_DATA_TRUNCATION 0x00000040	Se truncan uno o varios flujos de datos con nombre para un archivo.
USN_REASON_OBJECT_ID_CHANGE 0x00080000	Se cambia el identificador de objeto de un archivo o directorio.
USN_REASON_RENAME_NEW_NAME 0x00002000	Se cambia el nombre de un archivo o directorio y el nombre de archivo de la estructura USN_RECORD_V4 es el nuevo nombre.
USN_REASON_RENAME_OLD_NAME 0x00001000	Se cambia el nombre del archivo o directorio y el nombre de archivo de la estructura USN_RECORD_V4 es el nombre anterior.
USN_REASON_REPARSE_POINT_CHANGE 0x00100000	Se cambia el punto de reanálisis contenido en un archivo o directorio, o se agrega o elimina un punto de reanálisis de un archivo o directorio.
USN_REASON_SECURITY_CHANGE 0x00000800	Se realiza un cambio en los derechos de acceso a un archivo o directorio.
USN_REASON_STREAM_CHANGE 0x00200000	Se agrega o quita una secuencia con nombre de un archivo o se cambia el nombre de una secuencia con nombre.
USN_REASON_TRANSACTED_CHANGE 0x00400000	La secuencia especificada se modifica a través de una transacción TxF confirmada.

SourceInfo

Información adicional sobre el origen del cambio, establecido por el FSCTL_MARK_HANDLE de la operación DeviceIoControl .

Cuando un subproceso escribe un nuevo registro USN, las marcas de información de origen del registro anterior siguen estando presentes solo si el subproceso también establece esas marcas. Por lo tanto, la estructura de información de origen permite que las aplicaciones filtren los registros USN establecidos solo por un origen conocido, por ejemplo, un filtro antivirus.

Se puede establecer uno de los siguientes valores.

Valor	Significado
USN_SOURCE_AUXILIARY_DATA 0x00000002	La operación agrega un flujo de datos privado a un archivo o directorio. Un ejemplo es un detector de virus que agrega información de suma de comprobación. A medida que el detector de virus modifica el elemento, el sistema genera registros USN. USN_SOURCE_AUXILIARY_DATA indica que las modificaciones no cambiaron los datos de la aplicación.
USN_SOURCE_DATA_MANAGEMENT 0x00000001	La operación proporciona información sobre un cambio en el archivo o directorio realizado por el sistema operativo. Un uso típico es cuando el sistema de almacenamiento remoto mueve los datos del almacenamiento externo al local. Almacenamiento remoto es el software de administración jerárquica de almacenamiento. Este movimiento suele agregar como mínimo la marca USN_REASON_DATA_OVERWRITE a un registro USN. Sin embargo, los datos no han cambiado desde el punto de vista del usuario. Al anotar USN_SOURCE_DATA_MANAGEMENT en el miembro SourceInfo , puede determinar que, aunque se realiza una operación de escritura en el elemento, los datos no han cambiado.
USN_SOURCE_REPLICATION_MANAGEMENT 0x00000004	La operación modifica un archivo para que coincida con el contenido del mismo archivo que existe en otro miembro del conjunto de réplicas.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT 0x00000008	La operación modifica un archivo en los sistemas cliente para que coincida con el contenido del mismo archivo que existe en la nube.

RemainingExtents

Número de extensiones que permanecen después del registro de USN_RECORD_V4 actual. Es posible que se necesiten varios registros de la versión 4.0 para describir todas las extensiones modificadas de un archivo determinado. Cuando el miembro RemainingExtents es 0, el registro de USN_RECORD_V4 actual es el último registro USN_RECORD_V4 para el archivo. La última entrada USN_RECORD_V4 para un archivo determinado siempre va seguida de un registro de USN_RECORD_V3 con al menos la marca USN_REASON_CLOSE establecida.

NumberOfExtents

Número de extensiones en la entrada actual USN_RECORD_V4 .

ExtentSize

Tamaño de cada estructura de USN_RECORD_EXTENT en el miembro Extents , en bytes.

Extents[1]

Matriz de estructuras de USN_RECORD_EXTENT que representan las extensiones de la entrada USN_RECORD_V4 .

Comentarios

Un registro de USN_RECORD_V4 solo se genera cuando se activa el seguimiento de intervalos y el tamaño del archivo es igual o mayor que el valor del miembro RangeTrackFileSizeThreshold . El usuario siempre recibe uno o varios registros USN_RECORD_V4 seguidos de un registro USN_RECORD_V3 .

Para proporcionar una ruta de acceso de compatibilidad hacia delante en los clientes de diario de cambios, Microsoft proporciona un número de versión principal y secundaria del software de diario de cambios en la estructura de USN_RECORD_V4 . El código debe examinar estos valores, examinar su propia compatibilidad con el software de diario de cambios y controlar correctamente cualquier incompatibilidad si es necesario.

Un cambio en el número de versión secundaria indica que los miembros de estructura de USN_RECORD_V4 existentes siguen siendo válidos, pero es posible que se hayan agregado nuevos miembros entre el miembro penúltimo y el último, que es una cadena de longitud variable.

Para controlar este cambio correctamente, el código no debe realizar ninguna aritmética de puntero de tiempo de compilación que se base en la ubicación del último miembro. Por ejemplo, un cambio en el número de versión secundaria hace que la sizeof(USN_RECORD) llamada no sea confiable. En su lugar, confíe en cálculos en tiempo de ejecución que usen el miembro RecordLength .

Un aumento en el número de versión principal del software de diario de cambios indica que la estructura de USN_RECORD_V4 puede haber sufrido cambios importantes y que la definición actual puede no ser confiable. Si el código detecta un cambio en el número de versión principal del software de diario de cambios, el código no debe funcionar con el diario de cambios.

Para obtener más información, vea Crear, modificar y eliminar un Journal de cambios.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 R2 [solo aplicaciones de escritorio]
Encabezado	winioctl.h (incluya Windows.h)