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 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 em 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 estouros de buffer. Cada parâmetro pode usar zero ou uma anotação de buffer. 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
(tamanho)	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 comprimento inicializado do buffer. Use com _bcount_part e _ecount_part. O tamanho total pode ser menor que o espaço alocado.

Unidades de tamanho do buffer	Descrição
_bcount	O tamanho do buffer está em bytes.
_ecount	O tamanho do buffer está em elementos .

Direção	Descrição
_Em	A função lê do buffer. O chamador fornece o buffer e o inicializa.
_Inout	A função lê de 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 do buffer. Esse parâmetro pode não ser NULL.
_deref_opt	Desreferenciar o parâmetro para obter o ponteiro do buffer. Este parâmetro pode ser NULL.

Inicialização	Descrição
_Cheio	A função inicializa todo o buffer. Use somente com buffers de saída.
_Parte	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
_Optar	Este parâmetro pode ser NULL.

O exemplo a seguir mostra as anotações para a 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 de terminação nula. 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(size)
__bcount_opt(size)
__deref_bcount(size)
__deref_bcount_opt(size)
__deref_ecount(size)
__deref_ecount_opt(size)
__deref_in
__deref_in_bcount(size)
__deref_in_bcount_opt(size)
__deref_in_ecount(size)
__deref_in_ecount_opt(size)
__deref_in_opt
__deref_inout
__deref_inout_bcount(size)
__deref_inout_bcount_full(size)
__deref_inout_bcount_full_opt(size)
__deref_inout_bcount_opt(size)
__deref_inout_bcount_part(size,length)
__deref_inout_bcount_part_opt(size,length)
__deref_inout_ecount(size)
__deref_inout_ecount_full(size)
__deref_inout_ecount_full_opt(size)
__deref_inout_ecount_opt(size)
__deref_inout_ecount_part(size,length)
__deref_inout_ecount_part_opt(size,length)
__deref_inout_opt
__deref_opt_bcount(size)
__deref_opt_bcount_opt(size)
__deref_opt_ecount(size)
__deref_opt_ecount_opt(size)
__deref_opt_in
__deref_opt_in_bcount(size)
__deref_opt_in_bcount_opt(size)
__deref_opt_in_ecount(size)
__deref_opt_in_ecount_opt(size)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(size)
__deref_opt_inout_bcount_full(size)
__deref_opt_inout_bcount_full_opt(size)
__deref_opt_inout_bcount_opt(size)
__deref_opt_inout_bcount_part(size,length)
__deref_opt_inout_bcount_part_opt(size,length)
__deref_opt_inout_ecount(size)
__deref_opt_inout_ecount_full(size)
__deref_opt_inout_ecount_full_opt(size)
__deref_opt_inout_ecount_opt(size)
__deref_opt_inout_ecount_part(size,length)
__deref_opt_inout_ecount_part_opt(size,length)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(size)
__deref_opt_out_bcount_full(size)
__deref_opt_out_bcount_full_opt(size)
__deref_opt_out_bcount_opt(size)
__deref_opt_out_bcount_part(size,length)
__deref_opt_out_bcount_part_opt(size,length)
__deref_opt_out_ecount(size)
__deref_opt_out_ecount_full(size)
__deref_opt_out_ecount_full_opt(size)
__deref_opt_out_ecount_opt(size)
__deref_opt_out_ecount_part(size,length)
__deref_opt_out_ecount_part_opt(size,length)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(size)
__deref_out_bcount_full(size)
__deref_out_bcount_full_opt(size)
__deref_out_bcount_opt(size)
__deref_out_bcount_part(size,length)
__deref_out_bcount_part_opt(size,length)
__deref_out_ecount(size)
__deref_out_ecount_full(size)
__deref_out_ecount_full_opt(size)
__deref_out_ecount_opt(size)
__deref_out_ecount_part(size,length)
__deref_out_ecount_part_opt(size,length)
__deref_out_opt
__ecount(size)
__ecount_opt(size)
__Em
__in_bcount(size)
__in_bcount_opt(size)
__in_ecount(size)
__in_ecount_opt(size)
__in_opt
__Inout
__inout_bcount(size)
__inout_bcount_full(size)
__inout_bcount_full_opt(size)
__inout_bcount_opt(size)
__inout_bcount_part(size,length)
__inout_bcount_part_opt(size,length)
__inout_ecount(size)
__inout_ecount_full(size)
__inout_ecount_full_opt(size)
__inout_ecount_opt(size)
__inout_ecount_part(size,length)
__inout_ecount_part_opt(size,length)
__inout_opt
__out
__out_bcount(size)
__out_bcount_full(size)
__out_bcount_full_opt(size)
__out_bcount_opt(size)
__out_bcount_part(size,length)
__out_bcount_part_opt(size,length)
__out_ecount(size)
__out_ecount_full(size)
__out_ecount_full_opt(size)
__out_ecount_opt(size)
__out_ecount_part(size,length)
__out_ecount_part_opt(size,length)
__out_opt

Anotações Avançadas

As 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.

Annotation	Descrição
__blocksOn(resource)	As funções são bloqueadas no recurso especificado.
__Callback	A função pode ser usada como um ponteiro de função.
__checkReturn	Os chamadores devem marcar o valor retornado.
__Format_string	O parâmetro é uma cadeia de caracteres que contém marcadores % de estilo printf.
__in_awcount(expr,size)	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 nulos ou ponteiros.
__nullterminated	O buffer pode ser acessado até e incluindo o primeiro caractere ou ponteiro nulo .
__out_awcount(expr,size)	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 .
__Substituir	Especifica o comportamento de substituição de estilo C#para métodos virtuais.
__Reservados	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 para as funções DeleteTimerQueueTimer, FreeEnvironmentStrings e 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
    );

Tópicos relacionados

Anotações de SAL

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