estructura USN_RECORD_V2 (winioctl.h)
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) );
|
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 |
|---|---|
|
La estructura es una estructura USN_RECORD_V2 y el resto de la estructura se debe analizar con ese diseño. |
|
La estructura es una estructura USN_RECORD_V3 y el resto de la estructura se debe analizar con ese diseño. |
|
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.
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.
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) |