estrutura USN_RECORD_V3 (winioctl.h)
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 3.0. O registro da versão 2.0 é definido pela estrutura USN_RECORD_V2 (também chamada de estrutura USN_RECORD ).
Sintaxe
typedef struct {
DWORD RecordLength;
WORD MajorVersion;
WORD MinorVersion;
FILE_ID_128 FileReferenceNumber;
FILE_ID_128 ParentFileReferenceNumber;
USN Usn;
LARGE_INTEGER TimeStamp;
DWORD Reason;
DWORD SourceInfo;
DWORD SecurityId;
DWORD FileAttributes;
WORD FileNameLength;
WORD FileNameOffset;
WCHAR FileName[1];
} USN_RECORD_V3, *PUSN_RECORD_V3;
Membros
RecordLength
O comprimento total de um registro, em bytes.
Como USN_RECORD_V3 é 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_V3.
O tamanho em bytes de qualquer registro de diário de alteração é, no máximo, o tamanho da estrutura USN_RECORD_V3 , 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 =
QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR)
+ sizeof(USN_RECORD_V3) );
|
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 3.0, o número da versão principal será 3.
| Valor | Significado |
|---|---|
|
A estrutura é uma estrutura USN_RECORD_V2 e o restante da estrutura deve ser analisado usando esse layout. |
|
A estrutura é uma estrutura USN_RECORD_V3 e o restante da estrutura deve ser analisado usando esse layout. |
|
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 3.0, o número de versão secundária será zero.
FileReferenceNumber
O número ordinal de 128 bits 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 de 128 bits 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.
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.
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 tamanho 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 tem 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_V3.
Comentários
Em buffers de saída retornados de operações DeviceIoControl que funcionam com USN_RECORD_V3, todos os registros são alinhados em limites de 64 bits desde o início do buffer.
Quando o rastreamento de intervalo é ativado, o NTFS alterna para produzir apenas USN_RECORD_V3 registros como saída.
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_V3 . 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_V3 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 do local do último membro. Por exemplo, isso torna o código sizeof(USN_RECORD) C não confiável. Em vez disso, dependa de 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ções indica que a estrutura de USN_RECORD_V3 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ções, ele não deverá funcionar com o diário de alterações.
Para obter mais informações, consulte Criando, modificando e excluindo um Diário de alteração.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 8 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2012 [somente aplicativos da área de trabalho] |
| Cabeçalho | winioctl.h (inclua Windows.h) |