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 |
|---|---|
|
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. |
|
O arquivo ou diretório está fechado. |
|
O estado de compactação do arquivo ou diretório é alterado de ou para compactado. |
|
O arquivo ou diretório é adicionado a. |
|
Os dados no arquivo ou diretório são substituídos. |
|
O arquivo ou diretório está truncado. |
|
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. |
|
O arquivo ou diretório é criptografado ou descriptografado. |
|
O arquivo ou diretório é criado pela primeira vez. |
|
O arquivo ou diretório é excluído. |
|
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. |
|
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.) |
|
Um ou mais fluxos de dados nomeados para o arquivo foram adicionados. |
|
Os dados em um ou mais fluxos de dados nomeados para o arquivo são substituídos. |
|
Um ou mais fluxos de dados nomeados para o arquivo são truncados. |
|
O identificador de objeto do arquivo ou diretório é alterado. |
|
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. |
|
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. |
|
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. |
|
Uma alteração é feita nas permissões de acesso para o arquivo ou diretório. |
|
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) |