estrutura READ_USN_JOURNAL_DATA_V0 (winioctl.h)

Contém informações que definem um conjunto de registros de diário de alteração de número de sequência de atualização (USN) 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 SDKs e compiladores 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;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;

Membros

StartUsn

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

Para iniciar a operação de leitura no primeiro registro no diário, defina o membro StartUsn como zero. Como uma USN está contida em todos os registros 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ções, 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 Journal Records.

ReasonMask

Uma máscara de sinalizadores, cada sinalizador notando uma alteração para a qual o arquivo ou diretório tem um registro no diário de alterações. 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.

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 do diário de alterações ocorrerá na próxima vez que o volume for montado. A chamada ocorre mesmo se houver uma reinicialização intervindo do sistema.

Para receber notificação na primeira vez 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 são todos os motivos para alterações de USN que ocorreram no arquivo ou diretório. Sempre que ocorre uma operação final de fechamento para um item, um registro de fechamento da 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 nenhum dado de usuário existe (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 não for 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á até que 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 não for 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 e tentará retornar os registros especificados. Após os segundos de tempo limite , FSCTL_READ_USN_JOURNAL recupera todos os registros disponíveis no intervalo especificado.

Em ambos os casos, após o período de tempo limite, todos os novos dados acrescentados ao diário de alterações 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 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 a USN que deve ser usada para a próxima operação de FSCTL_READ_USN_JOURNAL . Quando o usn seguinte retornado é o mesmo que a StartUsn fornecida, 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 .

Requisitos

Confira também

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD