Anotações de cabeçalho
[Este tópico descreve as anotações suportadas nos cabeçalhos do Windows através do Windows 7. Se você estiver desenvolvendo para o Windows 8, deverá usar as anotações descritas em Anotações SAL.]
As anotações de cabeçalho descrevem como uma função usa seus parâmetros e valor de retorno. Essas anotações foram adicionadas a muitos dos arquivos de cabeçalho do Windows para ajudá-lo a garantir que você está 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 ele esteja sendo chamado 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 construídos em primitivos que fazem parte da Standard Annotation Language (SAL) e implementados usando _declspec("SAL_*").
Existem duas classes de anotações: anotações buffer e anotações avançadas.
Anotações de buffer
As anotações de buffer descrevem como as funções usam seus ponteiros e podem ser usadas para detetar saturações de buffer. Cada parâmetro pode usar zero ou uma anotação de buffer. Uma anotação de buffer é construída com um sublinhado principal e os componentes descritos nas seções a seguir.
| Tamanho do buffer | Descrição |
|---|---|
|
( tamanho) |
Especifica o tamanho total do buffer. Use com _bcount e _ecount; Não utilizar com _part. Este valor é o espaço acessível; pode ser inferior ao espaço atribuído. |
|
(tamanho,comprimento) |
Especifica o tamanho total e o comprimento inicializado do buffer. Use com _bcount_part e _ecount_part. O tamanho total pode ser inferior ao espaço atribuído. |
| Unidades de tamanho de buffer | Descrição |
|---|---|
|
_bcount |
O tamanho do buffer é em bytes. |
|
_ecount |
O tamanho do buffer está em elementos. |
| Direção | Descrição |
|---|---|
|
_in |
A função lê a partir do buffer. O chamador fornece o buffer e o inicializa. |
|
_inout |
A função lê e grava no buffer. O chamador fornece o buffer e o inicializa. Se usado com _deref, o buffer pode ser realocado pela função. |
|
_out |
A função grava no buffer. Se usada no valor de retorno ou com _deref, a função fornece o buffer e o inicializa. Caso contrário, o chamador fornece o buffer e a função o inicializa. |
| Indireção | Descrição |
|---|---|
|
_deref |
Cancele a referência do parâmetro para obter o ponteiro do buffer. Este parâmetro pode não ser NULL. |
|
_deref_opt |
Cancele a referência do parâmetro para obter o ponteiro do buffer. Este parâmetro pode ser NULL. |
| Inicialização | Descrição |
|---|---|
|
_full |
A função inicializa todo o buffer. Use apenas com buffers de saída. |
|
_part |
A função inicializa parte do buffer e indica explicitamente quanto. Use apenas com buffers de saída. |
| Buffer obrigatório ou opcional | Descrição |
|---|---|
|
_opt |
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 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
);
A seguir estão 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(tamanho)
__deref_bcount_opt(tamanho)
__deref_ecount(tamanho)
__deref_ecount_opt(tamanho)
__deref_in
__deref_in_bcount(tamanho)
__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(tamanho,comprimento)
__deref_inout_bcount_part_opt(tamanho,comprimento)
__deref_inout_ecount(tamanho)
__deref_inout_ecount_full(tamanho)
__deref_inout_ecount_full_opt(tamanho)
__deref_inout_ecount_opt(tamanho)
__deref_inout_ecount_part(tamanho,comprimento)
__deref_inout_ecount_part_opt(tamanho,comprimento)
__deref_inout_opt
__deref_opt_bcount(tamanho)
__deref_opt_bcount_opt(tamanho)
__deref_opt_ecount(tamanho)
__deref_opt_ecount_opt(tamanho)
__deref_opt_in
__deref_opt_in_bcount(tamanho)
__deref_opt_in_bcount_opt(tamanho)
__deref_opt_in_ecount(tamanho)
__deref_opt_in_ecount_opt(tamanho)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(tamanho)
__deref_opt_inout_bcount_full( tamanho)
__deref_opt_inout_bcount_full_opt(tamanho)
__deref_opt_inout_bcount_opt(tamanho)
__deref_opt_inout_bcount_part(tamanho,comprimento)
__deref_opt_inout_bcount_part_opt(tamanho,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(tamanho,comprimento)
__deref_opt_inout_ecount_part_opt(tamanho,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(tamanho)
__deref_opt_out_bcount_opt(tamanho)
__deref_opt_out_bcount_part(tamanho,comprimento)
__deref_opt_out_bcount_part_opt(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(tamanho,comprimento)
__deref_opt_out_ecount_part_opt(tamanho,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(tamanho,comprimento)
__deref_out_bcount_part_opt(tamanho,comprimento)
__deref_out_ecount(tamanho)
__deref_out_ecount_full(tamanho)
__deref_out_ecount_full_opt(tamanho)
__deref_out_ecount_opt(tamanho)
__deref_out_ecount_part(tamanho,comprimento)
__deref_out_ecount_part_opt(tamanho,comprimento)
__deref_out_opt
__ecount(tamanho)
__ecount_opt(tamanho)
__in
__in_bcount(tamanho)
__in_bcount_opt(tamanho)
__in_ecount(tamanho)
__in_ecount_opt(tamanho)
__in_opt
__inout
__inout_bcount(tamanho)
__inout_bcount_full(tamanho)
__inout_bcount_full_opt(tamanho)
__inout_bcount_opt(tamanho)
__inout_bcount_part(tamanho,comprimento)
__inout_bcount_part_opt(tamanho,comprimento)
__inout_ecount(tamanho)
__inout_ecount_full(tamanho)
__inout_ecount_full_opt(tamanho)
__inout_ecount_opt(tamanho)
__inout_ecount_part(tamanho,comprimento)
__inout_ecount_part_opt(tamanho,comprimento)
__inout_opt
__out
__out_bcount(tamanho)
__out_bcount_full(tamanho)
__out_bcount_full_opt(tamanho)
__out_bcount_opt(tamanho)
__out_bcount_part(tamanho,comprimento)
__out_bcount_part_opt(tamanho,comprimento)
__out_ecount(tamanho)
__out_ecount_full(tamanho)
__out_ecount_full_opt(tamanho)
__out_ecount_opt(tamanho)
__out_ecount_part(tamanho,comprimento)
__out_ecount_part_opt(tamanho,comprimento)
__out_opt
Anotações avançadas
As anotações avançadas fornecem informações adicionais sobre o parâmetro ou o valor de retorno. Cada parâmetro ou valor de retorno pode usar zero ou uma anotação avançada.
| Anotação | Descrição |
|---|---|
|
__blocksOn(de recursos ) |
Os blocos de funções no recurso especificado. |
|
__callback |
A função pode ser usada como um ponteiro de função. |
|
__checkReturn |
Os chamadores devem verificar o valor de retorno. |
|
__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 true 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 nulos caracteres ou ponteiros. |
|
__nullterminated |
O buffer pode ser acessado até e incluindo o primeiro nulo caractere 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 no 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 pode confiar em todas as garantias especificadas por outras anotações. Se a expressão for falsa, o chamador não pode confiar nas garantias. Essa anotação é adicionada automaticamente às funções que retornam um valor de 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 o DeleteTimerQueueTimer, FreeEnvironmentStringse UnhandledExceptionFilter funções.
__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
);