estructura READ_USN_JOURNAL_DATA_V0 (winioctl.h)
Contiene información que define un conjunto de registros de diario de cambios de número de secuencia de actualización (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;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;
Members
StartUsn
USN en el que 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á incluido en cada registro de 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 al mismo tiempo, 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 señala 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 no usados están reservados.
| Value | Significado |
|---|---|
|
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. |
|
El archivo o directorio está cerrado. |
|
El estado de compresión del archivo o directorio se cambia de o a comprimido. |
|
El archivo o directorio se agrega a. |
|
Los datos del archivo o directorio se sobrescriben. |
|
El archivo o directorio se trunca. |
|
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. |
|
El archivo o directorio está cifrado o descifrado. |
|
El archivo o directorio se crea por primera vez. |
|
Se elimina el archivo o directorio. |
|
Un vínculo duro del sistema de archivos NTFS se agrega o quita del archivo o directorio. Un vínculo duro del sistema de archivos NTFS, similar a un vínculo duro POSIX, es una de varias entradas de directorio que ven el mismo archivo o directorio. |
|
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 la búsqueda rápida de datos mediante la creación de una base de datos de contenido seleccionado). |
|
Se agregaron uno o más flujos de datos con nombre para el archivo. |
|
Los datos de uno o varios flujos de datos con nombre para el archivo se sobrescriben. |
|
Se truncan uno o varios flujos de datos con nombre para el archivo. |
|
Se cambia el identificador de objeto del archivo o directorio. |
|
Se cambia el nombre del archivo o directorio y el nombre del archivo en el USN_RECORD_V2 o USN_RECORD_V3 estructura que contiene este registro de diario es el nuevo nombre. |
|
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. |
|
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. |
|
Se realiza un cambio en los permisos de acceso al archivo o directorio. |
|
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 devolver registros de 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 a 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 de 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 una 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 .
Requisitos
| 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) |