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
);