estructura READ_USN_JOURNAL_DATA_V1 (winioctl.h)

Contiene información que define un conjunto de registros del diario de cambios de números de secuencias actualizadas (USN) para volver al proceso de llamada. Lo usan los códigos de control FSCTL_QUERY_USN_JOURNAL y FSCTL_READ_USN_JOURNAL . Antes de Windows 8 y Windows Server 2012 esta estructura se denominaba READ_USN_JOURNAL_DATA. Use ese nombre para compilar con sdk y compiladores anteriores. Windows Server 2012 introdujo READ_USN_JOURNAL_DATA_V1 para admitir identificadores de archivo de 128 bits usados por ReFS.

Sintaxis

typedef struct {
  USN       StartUsn;
  DWORD     ReasonMask;
  DWORD     ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
  WORD      MinMajorVersion;
  WORD      MaxMajorVersion;
} READ_USN_JOURNAL_DATA_V1, *PREAD_USN_JOURNAL_DATA_V1;

Miembros

StartUsn

USN en el que se va a empezar a leer el diario de cambios.

Para iniciar la operación de lectura en el primer registro del diario, establezca el miembro StartUsn en cero. Dado que un USN está contenido en cada registro del diario, el búfer de salida indica en qué registro se inició realmente la operación de lectura.

Para iniciar la operación de lectura en un registro específico, establezca StartUsn en ese registro USN.

Si se especifica un USN distinto de cero que es menor que el primer USN del diario de cambios, se produce un error y se devuelve el código de error ERROR_JOURNAL_ENTRY_DELETED . Este código puede indicar un caso en el que el USN especificado es válido a la vez, pero se ha eliminado.

Para obtener más información sobre cómo navegar por el búfer de diario de cambios devuelto en READ_USN_JOURNAL_DATA_V0, vea Walking a Buffer of Change Journal Records.

ReasonMask

Máscara de marcas, cada marca que observa un cambio para el que el archivo o directorio tiene un registro en el diario de cambios. Para devolverse en una operación de FSCTL_READ_USN_JOURNAL , un registro de diario de cambios debe tener al menos una de estas marcas establecidas.

La lista de marcas válidas es la siguiente. 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 (como 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 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 realiza un cambio en los atributos extendidos de 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 cambió el atributo FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Es decir, el usuario cambió el archivo o directorio de uno que puede ser contenido indexado a uno que no puede, o viceversa. (La indexación de contenido permite una búsqueda rápida de datos mediante la creación de una base de datos de contenido seleccionado).
USN_REASON_NAMED_DATA_EXTEND
0x00000020
Se agregaron uno o varios flujos de datos con nombre para el archivo.
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
Los datos de uno o varios flujos de datos con nombre para el archivo se sobrescriben.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
Se truncan uno o varios flujos de datos con nombre para el archivo.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
Se cambia el identificador de objeto del archivo o directorio.
USN_REASON_RENAME_NEW_NAME
0x00002000
Se cambia el nombre del archivo o directorio y el nombre de archivo de la estructura USN_RECORD_V2 o USN_RECORD_V3 que contiene este registro de diario 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 o USN_RECORD_V3 que contiene este registro de diario es el nombre anterior.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
Se cambia el punto de reanálisis contenido en el archivo o directorio, o se agrega o elimina un punto de reanálisis del archivo o directorio.
USN_REASON_SECURITY_CHANGE
0x00000800
Se realiza un cambio en los permisos de acceso al archivo o directorio.
USN_REASON_STREAM_CHANGE
0x00200000
Se agrega o quita una secuencia con nombre del archivo o directorio, o se cambia el nombre de una secuencia con nombre.

ReturnOnlyOnClose

Valor que especifica cuándo se devuelven los registros del diario de cambios.

Para recibir una notificación cuando se cierra el identificador final del archivo o directorio modificados, en lugar de en el momento en que se produce un cambio, establezca ReturnOnlyOnClose en cualquier valor distinto de cero y especifique la marca USN_REASON_CLOSE en el miembro ReasonMask .

Todos los cambios indicados por las marcas ReasonMask generan finalmente una llamada al software de diario de cambios cuando se cierra el archivo. Si la llamada a DeviceIoControl está esperando a que se cierre el archivo, esa llamada a su vez permitirá que se devuelva la llamada DeviceIoControl . En caso de que un archivo o directorio no se cierre antes de un error de volumen, un error del sistema operativo o un apagado, se produce una llamada de limpieza al software del diario de cambios la próxima vez que se monte el volumen. La llamada se produce incluso si hay un reinicio del sistema intermedio.

Para recibir la notificación la primera vez que se registra cada cambio, así como en la limpieza, establezca ReturnOnlyOnClose en cero.

Tanto si ReturnOnlyOnClose es cero como distinto de cero, los registros generados en el registro de limpieza dentro del diario de cambios son todos los motivos de los cambios de USN que se produjeron en el archivo o directorio. Cada vez que se produce una operación de cierre final para un elemento, se escribe un registro de cierre de USN en el diario de cambios y se restablecen todas las marcas ReasonMask del elemento.

Para un archivo o directorio para el que no existe ningún dato de usuario (por ejemplo, una carpeta montada), la operación de cierre final se produce cuando se llama a la función CloseHandle en el último identificador de usuario para el elemento.

Timeout

El valor de tiempo de espera, en segundos, se usa con el miembro BytesToWaitFor para indicar al sistema operativo qué hacer si la operación de FSCTL_READ_USN_JOURNAL solicita más datos de los que existe en el diario de cambios.

Si Timeout es cero y BytesToWaitFor es distinto de cero, y la llamada a la operación de FSCTL_READ_USN_JOURNAL llega al final del diario de cambios sin encontrar los datos que se van a devolver, FSCTL_READ_USN_JOURNAL espera hasta que se hayan agregado bytes de bytes de datos sin filtrar al diario de cambios y, a continuación, recupera los registros especificados.

Si Timeout es distinto de cero y BytesToWaitFor es distinto de cero, y la llamada a la operación de FSCTL_READ_USN_JOURNAL llega al final del diario de cambios sin encontrar datos para devolver, FSCTL_READ_USN_JOURNAL espera segundos de tiempo de espera y, a continuación, intenta devolver los registros especificados. Después de los segundos de tiempo de espera , FSCTL_READ_USN_JOURNAL recupera los registros disponibles dentro del intervalo especificado.

En cualquier caso, después del período de tiempo de espera, se procesan los datos nuevos anexados al diario de cambios. Si todavía no hay registros que devolver del conjunto especificado, se repite el período de tiempo de espera. En este modo, FSCTL_READ_USN_JOURNAL permanece pendiente hasta que se devuelva al menos un registro o se cancele la E/S.

Si BytesToWaitFor es cero, se omite Timeout . El tiempo de espera también se omite para los identificadores abiertos de forma asincrónica.

BytesToWaitFor

Número de bytes de datos sin filtrar agregados al diario de cambios. Use este valor con Timeout para indicar al sistema operativo qué hacer si la operación de FSCTL_READ_USN_JOURNAL solicita más datos de los que existen en el diario de cambios.

Si BytesToWaitFor es cero, se omite Timeout . En este caso, la operación FSCTL_READ_USN_JOURNAL siempre devuelve correctamente cuando se encuentra el final del archivo de diario de cambios. También recupera el USN que se debe usar para la siguiente operación de FSCTL_READ_USN_JOURNAL . Cuando el USN devuelto es el mismo que el proporcionado por StartUsn , no hay registros disponibles. El proceso de llamada no debe volver a usar FSCTL_READ_USN_JOURNAL inmediatamente.

Dado que la cantidad de datos devueltos no se puede predecir cuando BytesToWaitFor es cero, se corre el riesgo de desbordar el búfer de salida. Para reducir este riesgo, especifique un valor distinto de BytesToWaitFor en operaciones repetidas de FSCTL_READ_USN_JOURNAL hasta que se agoten todos los registros del diario de cambios. A continuación, especifique cero para esperar nuevos registros.

Como alternativa, use el parámetro lpBytesReturned de DeviceIoControl en la llamada a la operación de FSCTL_READ_USN_JOURNAL para determinar la cantidad de datos disponibles, reasignar el búfer de salida (con espacio para ahorrar para registros nuevos) y volver a llamar a DeviceIoControl .

UsnJournalID

Identificador de la instancia del diario actual para el volumen.

El sistema de archivos NTFS puede perder la colocación de eventos en el diario de cambios si el diario de cambios se detiene y se reinicia o se elimina y se vuelve a crear. Si se produce alguno de estos eventos, el sistema de archivos NTFS proporciona al diario un nuevo identificador. Si el identificador del diario no está de acuerdo con el identificador del diario actual, se produce un error en la llamada a DeviceIoControl y devuelve un código de error adecuado. Para recuperar el nuevo identificador de diario, llame a DeviceIoControl con la operación FSCTL_QUERY_USN_JOURNAL .

MinMajorVersion

MaxMajorVersion

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 (incluya Windows.h)

Consulte también

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD