Compartilhar via


estrutura READ_USN_JOURNAL_DATA_V1 (winioctl.h)

Contém informações que definem um conjunto de registros do diário de alterações de USN (números de sequência de atualização) para retornar ao processo de chamada. Ele é usado pelos códigos de controle FSCTL_QUERY_USN_JOURNAL e FSCTL_READ_USN_JOURNAL . Antes de Windows 8 e Windows Server 2012 essa estrutura era nomeada READ_USN_JOURNAL_DATA. Use esse nome para compilar com compiladores e SDKs mais antigos. Windows Server 2012 introduziu READ_USN_JOURNAL_DATA_V1 para dar suporte a identificadores de arquivo de 128 bits usados pelo ReFS.

Sintaxe

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;

Membros

StartUsn

A USN na qual começar a ler o diário de alterações.

Para iniciar a operação de leitura no primeiro registro no diário, defina o membro StartUsn como zero. Como um USN está contido em cada registro de diário, o buffer de saída informa em qual registro a operação de leitura realmente foi iniciada.

Para iniciar a operação de leitura em um registro específico, defina StartUsn para esse registro USN.

Se um USN diferente de zero for especificado que seja menor que o primeiro USN no diário de alteração, ocorrerá um erro e o código de erro ERROR_JOURNAL_ENTRY_DELETED será retornado. Esse código pode indicar um caso em que o USN especificado é válido ao mesmo tempo, mas foi excluído desde então.

Para obter mais informações sobre como navegar no buffer de diário de alterações retornado no READ_USN_JOURNAL_DATA_V0, consulte Walking a Buffer of Change Diário Records.

ReasonMask

Uma máscara de sinalizadores, cada sinalizador observando uma alteração para a qual o arquivo ou diretório tem um registro no diário de alteração. Para ser retornado em uma operação de FSCTL_READ_USN_JOURNAL , um registro de diário de alteração deve ter pelo menos um desses sinalizadores definidos.

A lista de sinalizadores válidos é a seguinte. Os bits não utilizados são reservados.

Valor Significado
USN_REASON_BASIC_INFO_CHANGE
0x00008000
Um usuário alterou um ou mais atributos de arquivo ou diretório (como somente leitura, oculto, sistema, arquivo morto ou atributo esparso) ou um ou mais carimbos de data/hora.
USN_REASON_CLOSE
0x80000000
O arquivo ou diretório está fechado.
USN_REASON_COMPRESSION_CHANGE
0x00020000
O estado de compactação do arquivo ou diretório é alterado de ou para compactado.
USN_REASON_DATA_EXTEND
0x00000002
O arquivo ou diretório é adicionado a.
USN_REASON_DATA_OVERWRITE
0x00000001
Os dados no arquivo ou diretório são substituídos.
USN_REASON_DATA_TRUNCATION
0x00000004
O arquivo ou diretório está truncado.
USN_REASON_EA_CHANGE
0x00000400
O usuário faz uma alteração nos atributos estendidos de arquivo ou diretório. Esses atributos do sistema de arquivos NTFS não são acessíveis para aplicativos baseados no Windows.
USN_REASON_ENCRYPTION_CHANGE
0x00040000
O arquivo ou diretório é criptografado ou descriptografado.
USN_REASON_FILE_CREATE
0x00000100
O arquivo ou diretório é criado pela primeira vez.
USN_REASON_FILE_DELETE
0x00000200
O arquivo ou diretório é excluído.
USN_REASON_HARD_LINK_CHANGE
0x00010000
Um link rígido do sistema de arquivos NTFS é adicionado ou removido do arquivo ou diretório. Um link rígido do sistema de arquivos NTFS, semelhante a um link rígido POSIX, é uma das várias entradas de diretório que veem o mesmo arquivo ou diretório.
USN_REASON_INDEXABLE_CHANGE
0x00004000
Um usuário alterou o atributo FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Ou seja, o usuário alterou o arquivo ou diretório de um que pode ser indexado para um que não pode ou vice-versa. (A indexação de conteúdo permite a pesquisa rápida de dados criando um banco de dados de conteúdo selecionado.)
USN_REASON_NAMED_DATA_EXTEND
0x00000020
Um ou mais fluxos de dados nomeados para o arquivo foram adicionados.
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
Os dados em um ou mais fluxos de dados nomeados para o arquivo são substituídos.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
Um ou mais fluxos de dados nomeados para o arquivo são truncados.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
O identificador de objeto do arquivo ou diretório é alterado.
USN_REASON_RENAME_NEW_NAME
0x00002000
O arquivo ou diretório é renomeado e o nome do arquivo na estrutura USN_RECORD_V2 ou USN_RECORD_V3 que contém esse registro de diário é o novo nome.
USN_REASON_RENAME_OLD_NAME
0x00001000
O arquivo ou diretório é renomeado e o nome do arquivo na estrutura USN_RECORD_V2 ou USN_RECORD_V3 que contém esse registro de diário é o nome anterior.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
O ponto de nova análise contido no arquivo ou diretório é alterado ou um ponto de nova análise é adicionado ou excluído do arquivo ou diretório.
USN_REASON_SECURITY_CHANGE
0x00000800
Uma alteração é feita nas permissões de acesso para o arquivo ou diretório.
USN_REASON_STREAM_CHANGE
0x00200000
Um fluxo nomeado é adicionado ou removido do arquivo ou diretório ou um fluxo nomeado é renomeado.

ReturnOnlyOnClose

Um valor que especifica quando retornar registros de diário de alteração.

Para receber notificação quando o identificador final do arquivo ou diretório alterado for fechado, em vez de no momento em que ocorrer uma alteração, defina ReturnOnlyOnClose como qualquer valor diferente de zero e especifique o sinalizador USN_REASON_CLOSE no membro ReasonMask .

Todas as alterações indicadas pelos sinalizadores ReasonMask eventualmente geram uma chamada para o software de diário de alteração quando o arquivo é fechado. Se a chamada deviceIoControl estiver aguardando o arquivo ser fechado, essa chamada, por sua vez, permitirá que sua chamada DeviceIoControl retorne. Caso um arquivo ou diretório não seja fechado antes de uma falha de volume, falha do sistema operacional ou desligamento, uma chamada de limpeza para o software de diário de alteração ocorrerá na próxima vez que o volume for montado. A chamada ocorre mesmo se houver uma reinicialização intermediária do sistema.

Para receber notificação na primeira vez em que cada alteração for registrada, bem como na limpeza, defina ReturnOnlyOnClose como zero.

Se ReturnOnlyOnClose for zero ou diferente de zero, os registros gerados no log de limpeza no diário de alterações todos os motivos para alterações de USN que ocorreram no arquivo ou diretório. Sempre que ocorre uma operação de fechamento final para um item, um registro de fechamento de USN é gravado no diário de alteração e os sinalizadores ReasonMask para o item são todos redefinidos.

Para um arquivo ou diretório para o qual não existem dados de usuário (por exemplo, uma pasta montada), a operação final de fechamento ocorre quando a função CloseHandle é chamada no último identificador de usuário para o item.

Timeout

O valor de tempo limite, em segundos, usado com o membro BytesToWaitFor para informar ao sistema operacional o que fazer se a operação FSCTL_READ_USN_JOURNAL solicitar mais dados do que existe no diário de alterações.

Se Timeout for zero e BytesToWaitFor for diferente de zero e a chamada de operação FSCTL_READ_USN_JOURNAL atingir o final do diário de alteração sem encontrar dados a serem retornados, FSCTL_READ_USN_JOURNAL aguardará até que bytes BytesToWaitFor de dados não filtrados sejam adicionados ao diário de alterações e recupere os registros especificados.

Se Timeout for diferente de zero e BytesToWaitFor for diferente de zero e a chamada de operação FSCTL_READ_USN_JOURNAL atingir o final do diário de alterações sem encontrar dados a serem retornados, FSCTL_READ_USN_JOURNAL aguardará o Tempo Limite segundos e tentará retornar os registros especificados. Após os segundos de tempo limite , FSCTL_READ_USN_JOURNAL recupera todos os registros disponíveis dentro do intervalo especificado.

Em ambos os casos, após o período de tempo limite, todos os novos dados acrescentados ao diário de alteração são processados. Se ainda não houver registros a serem retornados do conjunto especificado, o período de tempo limite será repetido. Nesse modo, FSCTL_READ_USN_JOURNAL permanece pendente até que pelo menos um registro seja retornado ou a E/S seja cancelada.

Se BytesToWaitFor for zero, o Tempo Limite será ignorado. O tempo limite também é ignorado para identificadores abertos de forma assíncrona.

BytesToWaitFor

O número de bytes de dados não filtrados adicionados ao diário de alterações. Use esse valor com Timeout para informar ao sistema operacional o que fazer se a operação de FSCTL_READ_USN_JOURNAL solicitar mais dados do que existe no diário de alterações.

Se BytesToWaitFor for zero, o Tempo Limite será ignorado. Nesse caso, a operação FSCTL_READ_USN_JOURNAL sempre retorna com êxito quando o final do arquivo de diário de alteração é encontrado. Ele também recupera o USN que deve ser usado para a próxima operação de FSCTL_READ_USN_JOURNAL . Quando o próximo USN retornado é o mesmo que o StartUsn fornecido, não há registros disponíveis. O processo de chamada não deve usar FSCTL_READ_USN_JOURNAL novamente imediatamente.

Como a quantidade de dados retornados não pode ser prevista quando BytesToWaitFor é zero, você corre o risco de estourar o buffer de saída. Para reduzir esse risco, especifique um valor BytesToWaitFor diferente de zero em operações de FSCTL_READ_USN_JOURNAL repetidas até que todos os registros no diário de alteração sejam esgotados. Em seguida, especifique zero para aguardar novos registros.

Como alternativa, use o parâmetro lpBytesReturned de DeviceIoControl na chamada de operação FSCTL_READ_USN_JOURNAL para determinar a quantidade de dados disponíveis, realocar o buffer de saída (com espaço de sobra para novos registros) e chamar DeviceIoControl novamente.

UsnJournalID

O identificador da instância do diário que é atual para o volume.

O sistema de arquivos NTFS poderá perder a colocação de eventos no diário de alterações se o diário de alterações for interrompido e reiniciado ou excluído e recriado. Se qualquer um desses eventos ocorrer, o sistema de arquivos NTFS fornecerá ao diário um novo identificador. Se o identificador de diário não concordar com o identificador de diário atual, a chamada para DeviceIoControl falhará e retornará um código de erro apropriado. Para recuperar o novo identificador de diário, chame DeviceIoControl com a operação FSCTL_QUERY_USN_JOURNAL .

MinMajorVersion

MaxMajorVersion

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Cabeçalho winioctl.h (inclua Windows.h)

Confira também

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD