Compartilhar via


Anotações de cabeçalho

[Este tópico descreve as anotações com suporte nos cabeçalhos do Windows por meio do Windows 7. Se você estiver desenvolvendo para o Windows 8, deverá usar as anotações descritas em anotações SAL.]

Anotações de cabeçalho descrevem como uma função usa seus parâmetros e valor retornado. Essas anotações foram adicionadas a muitos dos arquivos de cabeçalho do Windows para ajudá-lo a garantir que você esteja chamando a API do Windows corretamente. Se você habilitar a análise de código, que está disponível a partir do Visual Studio 2005, o compilador produzirá avisos de nível 6000 se você não estiver chamando essas funções de acordo com o uso descrito por meio das anotações. Você também pode adicionar essas anotações em seu próprio código para garantir que elas sejam chamadas corretamente. Para habilitar a análise de código no Visual Studio, consulte a documentação da sua versão do Visual Studio.

Essas anotações são definidas em Specstrings.h. Eles são criados sobre primitivos que fazem parte da SAL (Linguagem de Anotação Padrão) e implementados usando _declspec("SAL_*").

Há duas classes de anotações: anotações de buffer e anotações avançadas.

Anotações de buffer

Anotações de buffer descrevem como as funções usam seus ponteiros e podem ser usadas para detectar excessos de buffer. Cada parâmetro pode usar anotação de buffer zero ou um. Uma anotação de buffer é construída com um sublinhado à esquerda e os componentes descritos nas seções a seguir.

Tamanho do buffer Descrição
(de tamanho de)
Especifica o tamanho total do buffer. Usar com _bcount e _ecount; não use com _part. Esse valor é o espaço acessível; pode ser menor que o espaço alocado.
( tamanho,comprimento)
Especifica o tamanho total e o tamanho inicializado do buffer. Use com _bcount_part e _ecount_part. O tamanho total pode ser menor que o espaço alocado.
Unidades de tamanho de buffer Descrição
_bcount
O tamanho do buffer está em bytes.
_ecount
O tamanho do buffer está em elementos.
Direção Descrição
_in
A função lê do buffer. O chamador fornece o buffer e o inicializa.
_inout
A função lê e grava em buffer. O chamador fornece o buffer e o inicializa. Se usado com _deref, o buffer poderá ser realocado pela função.
_out
A função grava no buffer. Se usado no valor retornado ou com _deref, a função fornece o buffer e o inicializa. Caso contrário, o chamador fornecerá o buffer e a função o inicializará.
Indireção Descrição
_deref
Desreferenciar o parâmetro para obter o ponteiro de buffer. Esse parâmetro pode não ser NULL.
_deref_opt
Desreferenciar o parâmetro para obter o ponteiro de buffer. Esse parâmetro pode ser NULL.
Inicialização Descrição
_full
A função inicializa todo o buffer. Use somente com buffers de saída.
_part
A função inicializa parte do buffer e indica explicitamente quanto. Use somente com buffers de saída.
Buffer obrigatório ou opcional Descrição
_opt
Esse parâmetro pode ser NULL.

O exemplo a seguir mostra as anotações da função GetModuleFileName. O parâmetro hModule é um parâmetro de entrada opcional. O parâmetro lpFilename é um parâmetro de saída; seu tamanho em caracteres é especificado pelo parâmetro nSize e seu comprimento inclui o caractere nulo-terminating. O parâmetro nSize é um parâmetro de entrada.

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

Veja a seguir as anotações definidas em Specstrings.h. Use as informações nas tabelas acima para interpretar seu significado.

__bcount( tamanho)
__bcount_opt( tamanho)
__deref_bcount(de tamanho de)
__deref_bcount_opt( tamanho)
__deref_ecount( tamanho)
__deref_ecount_opt( tamanho)
__deref_in
__deref_in_bcount(de tamanho de)
__deref_in_bcount_opt( tamanho)
__deref_in_ecount( tamanho)
__deref_in_ecount_opt( tamanho)
__deref_in_opt
__deref_inout
__deref_inout_bcount( tamanho)
__deref_inout_bcount_full( tamanho)
__deref_inout_bcount_full_opt( tamanho)
__deref_inout_bcount_opt( tamanho)
__deref_inout_bcount_part(de tamanho de,comprimento)
__deref_inout_bcount_part_opt(de tamanho,comprimento)
__deref_inout_ecount(de tamanho de)
__deref_inout_ecount_full( tamanho)
__deref_inout_ecount_full_opt( tamanho)
__deref_inout_ecount_opt( tamanho)
__deref_inout_ecount_part(de tamanho de,de comprimento)
__deref_inout_ecount_part_opt(de tamanho,de comprimento)
__deref_inout_opt
__deref_opt_bcount(tamanho)
__deref_opt_bcount_opt(de tamanho de)
__deref_opt_ecount(de tamanho)
__deref_opt_ecount_opt(de tamanho de)
__deref_opt_in
__deref_opt_in_bcount( tamanho)
__deref_opt_in_bcount_opt(de tamanho de)
__deref_opt_in_ecount( tamanho)
__deref_opt_in_ecount_opt( tamanho)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(de tamanho de)
__deref_opt_inout_bcount_full( tamanho)
__deref_opt_inout_bcount_full_opt(de tamanho de)
__deref_opt_inout_bcount_opt( tamanho)
__deref_opt_inout_bcount_part(de tamanho,de comprimento)
__deref_opt_inout_bcount_part_opt(de tamanho,de comprimento)
__deref_opt_inout_ecount( tamanho)
__deref_opt_inout_ecount_full( tamanho)
__deref_opt_inout_ecount_full_opt( tamanho)
__deref_opt_inout_ecount_opt( tamanho)
__deref_opt_inout_ecount_part(de tamanho de,comprimento)
__deref_opt_inout_ecount_part_opt(de tamanho de,comprimento)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount( tamanho)
__deref_opt_out_bcount_full( tamanho)
__deref_opt_out_bcount_full_opt(de tamanho de)
__deref_opt_out_bcount_opt( tamanho)
__deref_opt_out_bcount_part(de tamanho,de comprimento)
__deref_opt_out_bcount_part_opt(de tamanho,comprimento)
__deref_opt_out_ecount( tamanho)
__deref_opt_out_ecount_full( tamanho)
__deref_opt_out_ecount_full_opt(tamanho)
__deref_opt_out_ecount_opt( tamanho)
__deref_opt_out_ecount_part(de tamanho de,de comprimento)
__deref_opt_out_ecount_part_opt(de tamanho,de comprimento)
__deref_opt_out_opt
__deref_out
__deref_out_bcount( tamanho)
__deref_out_bcount_full( tamanho)
__deref_out_bcount_full_opt( tamanho)
__deref_out_bcount_opt( tamanho)
__deref_out_bcount_part(de tamanho de,de comprimento)
__deref_out_bcount_part_opt(de tamanho de,comprimento)
__deref_out_ecount(de tamanho de)
__deref_out_ecount_full(tamanho)
__deref_out_ecount_full_opt( tamanho)
__deref_out_ecount_opt( tamanho)
__deref_out_ecount_part(de tamanho de,comprimento)
__deref_out_ecount_part_opt( tamanho,de comprimento)
__deref_out_opt
__ecount( tamanho)
__ecount_opt( tamanho)
__em
__in_bcount( tamanho)
__in_bcount_opt(de tamanho de)
__in_ecount( tamanho)
__in_ecount_opt(de tamanho de)
__in_opt
__inout
__inout_bcount( tamanho)
__inout_bcount_full( tamanho)
__inout_bcount_full_opt( tamanho)
__inout_bcount_opt( tamanho)
__inout_bcount_part(de tamanho de,de comprimento)
__inout_bcount_part_opt(de tamanho de,comprimento)
__inout_ecount(de tamanho)
__inout_ecount_full( tamanho)
__inout_ecount_full_opt( tamanho)
__inout_ecount_opt( tamanho)
__inout_ecount_part(de tamanho,de comprimento)
__inout_ecount_part_opt(de tamanho de,comprimento)
__inout_opt
__fora
__out_bcount(de tamanho de)
__out_bcount_full( tamanho)
__out_bcount_full_opt( tamanho)
__out_bcount_opt( tamanho)
__out_bcount_part(de tamanho de,de comprimento)
__out_bcount_part_opt(de tamanho de,de comprimento)
__out_ecount( tamanho)
__out_ecount_full( tamanho)
__out_ecount_full_opt( tamanho)
__out_ecount_opt( tamanho)
__out_ecount_part(de tamanho de,comprimento)
__out_ecount_part_opt(de tamanho de,de comprimento)
__out_opt

Anotações Avançadas

Anotações avançadas fornecem informações adicionais sobre o parâmetro ou o valor retornado. Cada parâmetro ou valor retornado pode usar zero ou uma anotação avançada.

Anotação Descrição
__blocksOn(de recursos )
As funções bloqueiam o recurso especificado.
__callback
A função pode ser usada como um ponteiro de função.
__checkReturn
Os chamadores devem verificar o valor retornado.
__format_string
O parâmetro é uma cadeia de caracteres que contém marcadores de % no estilo printf.
__in_awcount(expr,tamanho)
Se a expressão for verdadeira na saída, o tamanho do buffer de entrada será especificado em bytes. Se a expressão for false, o tamanho será especificado em elementos.
__nullnullterminated
O buffer pode ser acessado até e incluindo a primeira sequência de dois caracteres ou ponteiros nulos.
__nullterminated
O buffer pode ser acessado até e incluindo o primeiro caractere de nulo ou ponteiro.
__out_awcount(expr, tamanho)
Se a expressão for verdadeira na saída, o tamanho do buffer de saída será especificado em bytes. Se a expressão for false, o tamanho será especificado em elementos.
__override
Especifica o comportamento de substituição de estilo C#para métodos virtuais.
__reserved
O parâmetro é reservado para uso futuro e deve ser zero ou NULL.
__success(expr)
Se a expressão for verdadeira na saída, o chamador poderá contar com todas as garantias especificadas por outras anotações. Se a expressão for falsa, o chamador não poderá confiar nas garantias. Essa anotação é adicionada automaticamente a funções que retornam um valor HRESULT.
__typefix(ctype)
Trate o parâmetro como o tipo especificado em vez de seu tipo declarado.

Os exemplos a seguir mostram o buffer e as anotações avançadas das funções DeleteTimerQueueTimer, FreeEnvironmentStringse UnhandledExceptionFilter.

__checkReturn
BOOL
WINAPI
DeleteTimerQueueTimer(
    __in_opt HANDLE TimerQueue,
    __in     HANDLE Timer,
    __in_opt HANDLE CompletionEvent
    );

BOOL
WINAPI
FreeEnvironmentStrings(
    __in __nullnullterminated LPTCH
    );

__callback
LONG
WINAPI
UnhandledExceptionFilter(
    __in struct _EXCEPTION_POINTERS *ExceptionInfo
    );

anotações de SAL

passo a passo: analisando o código C/C++ para defeitos