estrutura USN_RECORD_V2 (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 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) );
|
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 |
|---|---|
|
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 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.
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 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) |