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.

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

Consulte también

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD