estructura USN_RECORD_V2 (winioctl.h)

Artículo
03/08/2023

Contiene la información de un registro de la versión 2.0 del diario de cambios de números de secuencias actualizadas (USN). Las aplicaciones no deben intentar trabajar con versiones de diario de cambios anteriores a la 2.0. Antes de Windows 8 y Windows Server 2012 esta estructura se denominaba USN_RECORD. Use ese nombre para compilar con sdk y compiladores anteriores.

Sintaxis

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  DWORDLONG     FileReferenceNumber;
  DWORDLONG     ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V2, *PUSN_RECORD_V2;

Miembros

RecordLength

Longitud total de un registro, en bytes.

Dado que USN_RECORD_V2 es un tamaño variable, se debe usar el miembro RecordLength al calcular la dirección del siguiente registro en un búfer de salida, por ejemplo, un búfer que se devuelve de las operaciones para la función DeviceIoControl que funciona con USN_RECORD_V2.

El tamaño en bytes de cualquier registro de diario de cambios es como máximo el tamaño de la estructura de USN_RECORD_V2 , más los caracteres MaximumComponentLength menos 1 (para el carácter declarado en la estructura) el tamaño de un carácter ancho. El valor de MaximumComponentLength se puede determinar llamando a
Función GetVolumeInformation . En C, puede determinar un tamaño de registro mediante el ejemplo de código siguiente.

C++
MaximumChangeJournalRecordSize = ( MaximumComponentLength * sizeof(WCHAR) + sizeof(USN_RECORD) + sizeof(WCHAR) );

Para mantener la compatibilidad entre los cambios de versión del software de diario de cambios, use un cálculo en tiempo de ejecución para determinar el tamaño de la estructura de USN_RECORD_V2 . Para obtener más información sobre la compatibilidad entre los cambios de versión, vea la sección Comentarios de este tema.

MajorVersion

Número de versión principal del software de diario de cambios para este registro.

Por ejemplo, si el software de diario de cambios es la versión 2.0, el número de versión principal es 2.

Valor	Significado
2	La estructura es una estructura USN_RECORD_V2 y el resto de la estructura se debe analizar con ese diseño.
3	La estructura es una estructura USN_RECORD_V3 y el resto de la estructura se debe analizar con ese diseño.
4	La estructura es una [estructura USN_RECORD_V4](ns-winioctl-usn_record_v4.md) y el resto de la estructura se debe analizar con ese diseño.

MinorVersion

Número de versión secundaria del software de diario de cambios para este registro. Por ejemplo, si el software de diario de cambios es la versión 2.0, el número de versión secundaria es cero.

FileReferenceNumber

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

Se trata de un valor asignado arbitrariamente que asocia un registro de diario a un archivo.

ParentFileReferenceNumber

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

Se trata de un valor asignado arbitrariamente que asocia un registro de diario a un directorio primario.

Usn

USN de este registro.

TimeStamp

Marca de tiempo UTC estándar (FILETIME) de este registro, en formato de 64 bits.

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

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 dos valores siguientes.

Valor	Significado
USN_SOURCE_AUXILIARY_DATA 0x00000002	La operación agrega un flujo de datos privado a un archivo o directorio. Un ejemplo podría ser 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 almacenamiento local. El almacenamiento remoto es el software de administración de almacenamiento jerárquico. 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 está modificando 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 está modificando un archivo en los sistemas cliente para que coincida con el contenido del mismo archivo que existe en la nube.

SecurityId

Identificador de seguridad único asignado al archivo o directorio asociado a este registro.

FileAttributes

Los atributos del archivo o directorio asociados a este registro, tal como lo devuelve la función GetFileAttributes . Se excluyen los atributos de las secuencias asociadas al archivo o directorio.

FileNameLength

Longitud del nombre del archivo o directorio asociado a este registro, en bytes. El miembro FileName contiene este nombre. Use este miembro para determinar la longitud del nombre de archivo, en lugar de depender de un final '\0' para delimitar el nombre de archivo en FileName.

FileNameOffset

Desplazamiento del miembro FileName desde el principio de la estructura.

FileName[1]

Nombre del archivo o directorio asociado a este registro en formato Unicode. Este nombre de archivo o directorio es de longitud variable.

Al trabajar con FileName, no cuente el nombre de archivo que contiene un delimitador "\0" final, sino que determine la longitud del nombre de archivo mediante FileNameLength.

No realice ninguna aritmética de puntero en tiempo de compilación mediante FileName. En su lugar, realice los cálculos necesarios en tiempo de ejecución mediante el valor del miembro FileNameOffset . Esto ayuda a hacer que el código sea compatible con cualquier versión futura de USN_RECORD_V2.

Comentarios

En los búferes de salida devueltos por las operaciones DeviceIoControl que funcionan con USN_RECORD_V2, todos los registros se alinean en límites de 64 bits desde el inicio del búfer.

Para proporcionar una ruta de compatibilidad ascendente en los clientes del 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_V2 . El código debe examinar estos valores, detectar su propia compatibilidad con el software de diario de cambios y, si es necesario, controlar correctamente cualquier incompatibilidad.

Un cambio en el número de versión secundaria indica que los miembros de la estructura USN_RECORD_V2 existentes siguen siendo válidos, pero que se pueden haber 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 en tiempo de compilación que se base en la ubicación del último miembro. Por ejemplo, esto hace que el código sizeof(USN_RECORD) de C no sea confiable. En su lugar, confíe en cálculos en tiempo de ejecución mediante el miembro RecordLength .

Un aumento en el número de versión principal del software de diario de cambios indica que la estructura del USN_RECORD_V2 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, 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 XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Encabezado	winioctl.h (incluye Windows.h)