estrutura USN_RECORD_V2 (winioctl.h)

Artigo
03/08/2023

Contém as informações de um registro do diário de alterações USN (números de sequência de atualização) versão 2.0. Os aplicativos não devem tentar trabalhar com versões de diário de alteração anteriores à 2.0. Antes de Windows 8 e Windows Server 2012 essa estrutura era nomeada USN_RECORD. Use esse nome para compilar com compiladores e SDKs mais antigos.

Sintaxe

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  DWORDLONG     FileReferenceNumber;
  DWORDLONG     ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V2, *PUSN_RECORD_V2;

Membros

RecordLength

O comprimento total de um registro, em bytes.

Como USN_RECORD_V2 é um tamanho variável, o membro RecordLength deve ser usado ao calcular o endereço do próximo registro em um buffer de saída, por exemplo, um buffer retornado de operações para a função DeviceIoControl que funcionam com USN_RECORD_V2.

O tamanho em bytes de qualquer registro de diário de alteração é, no máximo, o tamanho da estrutura USN_RECORD_V2 , mais os caracteres MaximumComponentLength menos 1 (para o caractere declarado na estrutura) vezes o tamanho de um caractere largo. O valor de MaximumComponentLength pode ser determinado chamando o
Função GetVolumeInformation . Em C, você pode determinar um tamanho de registro usando o exemplo de código a seguir.

C++
MaximumChangeJournalRecordSize = ( MaximumComponentLength * sizeof(WCHAR) + sizeof(USN_RECORD) + sizeof(WCHAR) );

Para manter a compatibilidade entre as alterações de versão do software de diário de alterações, use um cálculo em tempo de execução para determinar o tamanho da estrutura de USN_RECORD_V2 . Para obter mais informações sobre a compatibilidade entre as alterações de versão, consulte a seção Comentários neste tópico.

MajorVersion

O número de versão principal do software de diário de alteração para esse registro.

Por exemplo, se o software de diário de alteração for a versão 2.0, o número da versão principal será 2.

Valor	Significado
2	A estrutura é uma estrutura USN_RECORD_V2 e o restante da estrutura deve ser analisado usando esse layout.
3	A estrutura é uma estrutura USN_RECORD_V3 e o restante da estrutura deve ser analisado usando esse layout.
4	A estrutura é uma [estrutura USN_RECORD_V4](ns-winioctl-usn_record_v4.md) e o restante da estrutura deve ser analisado usando esse layout.

MinorVersion

O número de versão secundária do software de diário de alteração para este registro. Por exemplo, se o software de diário de alteração for a versão 2.0, o número de versão secundária será zero.

FileReferenceNumber

O número ordinal do arquivo ou diretório para o qual esta anotação de registro é alterada.

Esse é um valor atribuído arbitrariamente que associa um registro de diário a um arquivo.

ParentFileReferenceNumber

O número ordinal do diretório em que o arquivo ou diretório associado a esse registro está localizado.

Esse é um valor atribuído arbitrariamente que associa um registro de diário a um diretório pai.

Usn

A USN deste registro.

TimeStamp

O carimbo de data/hora UTC padrão (FILETIME) desse registro, no formato de 64 bits.

Reason

Os sinalizadores que identificam os motivos das alterações acumuladas neste arquivo ou registro de diário de diretório desde que o arquivo ou diretório foi aberto.

Quando um arquivo ou diretório é fechado, um registro usn final é gerado com o sinalizador USN_REASON_CLOSE definido. A próxima alteração (por exemplo, após a próxima operação ou exclusão aberta) inicia um novo registro com um novo conjunto de sinalizadores de motivo.

Uma operação de renomeação ou movimentação gera dois registros USN, um que registra o diretório pai antigo para o item e outro que registra um novo pai.

A tabela a seguir identifica os possíveis sinalizadores.

Nota 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 (por exemplo, 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 é estendido (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 fez uma alteração nos atributos estendidos de um 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 altera o atributo FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Ou seja, o usuário altera o arquivo ou diretório de um em que o conteúdo pode ser indexado para um em que o conteúdo não pode ser indexado 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_INTEGRITY_CHANGE 0x00800000	Um usuário alterou o estado do atributo FILE_ATTRIBUTE_INTEGRITY_STREAM para o fluxo fornecido. No sistema de arquivos ReFS, os fluxos de integridade mantêm uma soma de verificação de todos os dados desse fluxo, para que o conteúdo do arquivo possa ser validado durante operações de leitura ou gravação.
USN_REASON_NAMED_DATA_EXTEND 0x00000020	Um ou mais fluxos de dados nomeados para um arquivo são estendidos (adicionados a).
USN_REASON_NAMED_DATA_OVERWRITE 0x00000010	Os dados em um ou mais fluxos de dados nomeados para um arquivo são substituídos.
USN_REASON_NAMED_DATA_TRUNCATION 0x00000040	Um ou mais fluxos de dados nomeados para um arquivo é truncado.
USN_REASON_OBJECT_ID_CHANGE 0x00080000	O identificador de objeto de um arquivo ou diretório é alterado.
USN_REASON_RENAME_NEW_NAME 0x00002000	Um arquivo ou diretório é renomeado e o nome do arquivo na estrutura USN_RECORD_V2 é 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 é o nome anterior.
USN_REASON_REPARSE_POINT_CHANGE 0x00100000	O ponto de nova análise contido em um arquivo ou diretório é alterado ou um ponto de nova análise é adicionado ou excluído de um arquivo ou diretório.
USN_REASON_SECURITY_CHANGE 0x00000800	Uma alteração é feita nos direitos de acesso a um arquivo ou diretório.
USN_REASON_STREAM_CHANGE 0x00200000	Um fluxo nomeado é adicionado ou removido de um arquivo ou um fluxo nomeado é renomeado.
USN_REASON_TRANSACTED_CHANGE 0x00400000	O fluxo fornecido é modificado por meio de uma transação TxF.

SourceInfo

Informações adicionais sobre a origem da alteração, definidas pelo FSCTL_MARK_HANDLE da operação DeviceIoControl .

Quando um thread grava um novo registro USN, os sinalizadores de informações de origem no registro anterior só estarão presentes se o thread também definir esses sinalizadores. Portanto, a estrutura de informações de origem permite que os aplicativos filtrem registros USN definidos apenas por uma fonte conhecida, por exemplo, um filtro antivírus.

Um dos dois valores a seguir pode ser definido.

Valor	Significado
USN_SOURCE_AUXILIARY_DATA 0x00000002	A operação adiciona um fluxo de dados privado a um arquivo ou diretório. Um exemplo pode ser um detector de vírus adicionando informações de soma de verificação. À medida que o detector de vírus modifica o item, o sistema gera registros USN. USN_SOURCE_AUXILIARY_DATA indica que as modificações não alteraram os dados do aplicativo.
USN_SOURCE_DATA_MANAGEMENT 0x00000001	A operação fornece informações sobre uma alteração no arquivo ou diretório feito pelo sistema operacional. Um uso típico é quando o sistema de Armazenamento Remoto move dados do armazenamento externo para o local. O Armazenamento Remoto é o software de gerenciamento de armazenamento hierárquico. Essa movimentação geralmente, no mínimo, adiciona o sinalizador USN_REASON_DATA_OVERWRITE a um registro USN. No entanto, os dados não foram alterados do ponto de vista do usuário. Observando USN_SOURCE_DATA_MANAGEMENT no membro SourceInfo , você pode determinar que, embora uma operação de gravação seja executada no item, os dados não foram alterados.
USN_SOURCE_REPLICATION_MANAGEMENT 0x00000004	A operação está modificando um arquivo para corresponder ao conteúdo do mesmo arquivo que existe em outro membro do conjunto de réplica.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT 0x00000008	A operação está modificando um arquivo em sistemas cliente para corresponder ao conteúdo do mesmo arquivo que existe na nuvem.

SecurityId

O identificador de segurança exclusivo atribuído ao arquivo ou diretório associado a esse registro.

FileAttributes

Os atributos para o arquivo ou diretório associado a esse registro, conforme retornado pela função GetFileAttributes . Atributos de fluxos associados ao arquivo ou diretório são excluídos.

FileNameLength

O comprimento do nome do arquivo ou diretório associado a esse registro, em bytes. O membro FileName contém esse nome. Use esse membro para determinar o comprimento do nome do arquivo, em vez de depender de um '\0' à direita para delimitar o nome do arquivo em FileName.

FileNameOffset

O deslocamento do membro FileName desde o início da estrutura.

FileName[1]

O nome do arquivo ou diretório associado a esse registro no formato Unicode. Esse nome de arquivo ou diretório é de comprimento variável.

Ao trabalhar com FileName, não conte com o nome do arquivo que contém um delimitador '\0' à direita, mas determine o comprimento do nome do arquivo usando FileNameLength.

Não execute nenhuma aritmética de ponteiro de tempo de compilação usando FileName. Em vez disso, faça os cálculos necessários em tempo de execução usando o valor do membro FileNameOffset . Isso ajuda a tornar seu código compatível com versões futuras do USN_RECORD_V2.

Comentários

Em buffers de saída retornados das operações DeviceIoControl que funcionam com USN_RECORD_V2, todos os registros são alinhados em limites de 64 bits desde o início do buffer.

Para fornecer um caminho para compatibilidade ascendente em clientes de diário de alterações, a Microsoft fornece um número de versão principal e secundário do software de diário de alterações na estrutura USN_RECORD_V2 . Seu código deve examinar esses valores, detectar sua própria compatibilidade com o software de diário de alterações e, se necessário, lidar normalmente com qualquer incompatibilidade.

Uma alteração no número de versão secundária indica que os membros existentes da estrutura USN_RECORD_V2 ainda são válidos, mas que novos membros podem ter sido adicionados entre o penúltimo membro e o último, que é uma cadeia de caracteres de comprimento variável.

Para lidar com essa alteração normalmente, seu código não deve fazer nenhuma aritmética de ponteiro em tempo de compilação que dependa da localização do último membro. Por exemplo, isso torna o código sizeof(USN_RECORD) C não confiável. Em vez disso, conte com cálculos em tempo de execução usando o membro RecordLength .

Um aumento no número de versão principal do software de diário de alteração indica que a estrutura USN_RECORD_V2 pode ter passado por grandes alterações e que a definição atual pode não ser confiável. Se o código detectar uma alteração no número de versão principal do software de diário de alteração, ele não deverá funcionar com o diário de alterações.

Para obter mais informações, consulte Criando, modificando e excluindo uma Diário de alteração.

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)