Partilhar via

Anotando parâmetros de função e valores de retorno

  • Artigo

Este artigo descreve os usos mais comuns de anotações para parâmetro- escalares de função simples, e ponteiros para estruturas e classes - e a maioria dos tipos de buffers.Este artigo também mostra padrões comuns de uso para anotações.Para anotações adicionais que são relacionadas a funções, consulte Anotando o comportamento da função

Parâmetros de ponteiro

Para anotações na tabela a seguir, quando um parâmetro do ponteiro está sendo anotado, o analisador relata um erro se o ponteiro é nulo.Isso se aplica a ponteiros e qualquer item de dados que é apontado.

Anotação

Descrição

_In_

Annotates os parâmetros de entrada que são escalares, estruturas, ponteiros para estruturas e iguais.Explicitamente pode ser usado em escalares simples.O parâmetro deve ser válido no estado pré-compilação e não será alterado.

_Out_

Annotates parâmetros de saída que são escalares, estruturas, ponteiros para estruturas e iguais.Isso não aplicar a um objeto que não pode retornar a - por exemplo, um único que é passado por valor.O parâmetro não tem que ser válido no estado pré-compilação mas deve ser válido no estado posteriores.

_Inout_

Annotates um parâmetro que é modificado pela função.Deve ser válido no estado passos pré e o estado, mas é suposot diferentes valores antes e depois de chamada.Deve ser aplicados a um valor modificável.

_In_z_

Um ponteiro para uma cadeia de caracteres NULL- finalizada que é usada como entrada.A cadeia de caracteres deve ser válido em passos estado.Variantes de PSTR, já que têm as anotações corretas, são preferenciais.

_Inout_z_

Um ponteiro para uma matriz de caracteres NULL- finalizada que é modificada.Deve ser válido antes e após a chamada, mas o valor é assumido ter sido alterado.Terminador o zero pode ser movido, mas somente os elementos até o terminador nulo original podem ser acessados.

_In_reads_(s)

_In_reads_bytes_(s)

Um ponteiro para uma matriz, que é lido pela função.A matriz é de elementos de s de tamanho, que deve ser válido.

A variante de _bytes_ fornece o tamanho em bytes em vez de elementos.Use isso somente quando o tamanho não pode ser expresso como elementos.Por exemplo, cadeias de caracteres de char usariam a variante de _bytes_ somente se uma função semelhante que usa wchar_t .

_In_reads_z_(s)

Um ponteiro para uma matriz que NULL- é finalizada e tem um tamanho conhecido.Os elementos até o terminador- zero ou s se não houver nenhum zero terminador- deve ser válido em passos estado.Se o tamanho é conhecido em bytes, escala s pelo tamanho do elemento.

_In_reads_or_z_(s)

Um ponteiro para uma matriz que NULL- é finalizada ou tem um tamanho conhecido, ou ambos.Os elementos até o terminador- zero ou s se não houver nenhum zero terminador- deve ser válido em passos estado.Se o tamanho é conhecido em bytes, escala s pelo tamanho do elemento.(Usado para a família de strn .)

_Out_writes_(s)

_Out_writes_bytes_(s)

Um ponteiro para uma matriz de elementos s (resp.bytes) que será escrito pela função.Os elementos da matriz não precisam ser válido em passos estado, e o número de elementos que são válidos em após estado não é especificado.Se houver anotações no tipo de parâmetro, são aplicados em após estado.Por exemplo, considere o seguinte código.

typedef _Null_terminated_ wchar_t *PWSTR;
void MyStringCopy(_Out_writes_ (size) PWSTR p1,
   _In_ size_t size,
   _In_ PWSTR p2);

Nesse exemplo, o chamador fornece um buffer de elementos de size para p1.MyStringCopy faz parte desses elementos válido.Mais importante, a anotação de _Null_terminated_ em PWSTR significa que p1 NULL- é encerrado no estado posteriores.Dessa forma, o número de elementos válidos ainda é bem definido, mas uma contagem específica de elemento não é necessária.

A variante de _bytes_ fornece o tamanho em bytes em vez de elementos.Use isso somente quando o tamanho não pode ser expresso como elementos.Por exemplo, cadeias de caracteres de char usariam a variante de _bytes_ somente se uma função semelhante que usa wchar_t .

_Out_writes_z_(s)

Um ponteiro para uma matriz de elementos s .Elementos não têm que ser válido em passos estado.Após no estado, os elementos anterior com o zero terminador- que deve ser atual- deve ser válido.Se o tamanho é conhecido em bytes, escala s pelo tamanho do elemento.

_Inout_updates_(s)

_Inout_updates_bytes_(s)

Um ponteiro para uma matriz, que é ler e gravar na função.É de elementos de s de tamanho, e válido no estado passos pré e o estado.

A variante de _bytes_ fornece o tamanho em bytes em vez de elementos.Use isso somente quando o tamanho não pode ser expresso como elementos.Por exemplo, cadeias de caracteres de char usariam a variante de _bytes_ somente se uma função semelhante que usa wchar_t .

_Inout_updates_z_(s)

Um ponteiro para uma matriz que NULL- é finalizada e tem um tamanho conhecido.Os elementos anterior com o zero terminador- que deve ser atual- deve ser válido no estado passos pré e o estado.Após o valor no estado é presumido ser diferente do valor no estado; pré-compilação isso inclui o local terminador de zero.Se o tamanho é conhecido em bytes, escala s pelo tamanho do elemento.

_Out_writes_to_(s,c)

_Out_writes_bytes_to_(s,c)

_Out_writes_all_(s)

_Out_writes_bytes_all_(s)

Um ponteiro para uma matriz de elementos s .Elementos não têm que ser válido em passos estado.Após no estado, os elementos até c- o elemento de th deve ser válido.Se o tamanho é conhecido em bytes, a escala s e c pelo tamanho do elemento ou usa a variante de _bytes_ , que é definido como:

   _Out_writes_to_(_Old_(s), _Old_(s))
   _Out_writes_bytes_to_(_Old_(s), _Old_(s))

Ou seja cada elemento que existe em buffer até s pré-compilação no estado é válido no estado posteriores.Por exemplo:

void *memcpy(_Out_writes_bytes_all_(s) char *p1,
   _In_reads_bytes_(s) char *p2,
   _In_ int s);
void * wordcpy(_Out_writes_all_(s) DWORD *p1, 
   _In_reads_(s) DWORD *p2,
   _In_ int s);

_Inout_updates_to_(s,c)

_Inout_updates_bytes_to_(s,c)

Um ponteiro para uma matriz, que é ler e gravar função.É de elementos de s de tamanho, que deve ser válido em passos estado, e os elementos de c deve ser válido no estado posteriores.

A variante de _bytes_ fornece o tamanho em bytes em vez de elementos.Use isso somente quando o tamanho não pode ser expresso como elementos.Por exemplo, cadeias de caracteres de char usariam a variante de _bytes_ somente se uma função semelhante que usa wchar_t .

_Inout_updates_all_(s)

_Inout_updates_bytes_all_(s)

Um ponteiro para uma matriz, que é ler e gravar pela função dos elementos de s de tamanho.Definido como equivalente a:

   _Inout_updates_to_(_Old_(s), _Old_(s))
   _Inout_updates_bytes_to_(_Old_(s), _Old_(s))

Ou seja cada elemento que existe em buffer até s pré-compilação no estado é válido no estado passos pré e o estado.

A variante de _bytes_ fornece o tamanho em bytes em vez de elementos.Use isso somente quando o tamanho não pode ser expresso como elementos.Por exemplo, cadeias de caracteres de char usariam a variante de _bytes_ somente se uma função semelhante que usa wchar_t .

_In_reads_to_ptr_(p)

Um ponteiro para uma matriz para que a expressão p – _Curr_ (isto é, p menos _Curr_) é definido por padrão de idioma apropriado.Os elementos antes de p deve ser válido em passos estado.

_In_reads_to_ptr_z_(p)

Um ponteiro para uma matriz NULL- finalizada para que a expressão p – _Curr_ (isto é, p menos _Curr_) é definido por padrão de idioma apropriado.Os elementos antes de p deve ser válido em passos estado.

_Out_writes_to_ptr_(p)

Um ponteiro para uma matriz para que a expressão p – _Curr_ (isto é, p menos _Curr_) é definido por padrão de idioma apropriado.Os elementos antes de p não têm que ser válido em passos estado e deve ser válido no estado posteriores.

_Out_writes_to_ptr_z_(p)

Um ponteiro para uma matriz NULL- finalizada para que a expressão p – _Curr_ (isto é, p menos _Curr_) é definido por padrão de idioma apropriado.Os elementos antes de p não têm que ser válido em passos estado e deve ser válido no estado posteriores.

Parâmetros opcionais do ponteiro

Quando uma anotação do ponteiro inclui _opt_, indica que o parâmetro pode ser nulo.Caso contrário, a anotação executa o mesmo que a versão que não inclui _opt_.Aqui está uma lista de variantes de _opt_ de anotações do ponteiro:

_In_opt_

_Out_opt_

_Inout_opt_

_In_opt_z_

_Inout_opt_z_

_In_reads_opt_

_In_reads_bytes_opt_

_In_reads_opt_z_

_Out_writes_opt_

_Out_writes_opt_z_

_Inout_updates_opt_

_Inout_updates_bytes_opt_

_Inout_updates_opt_z_

_Out_writes_to_opt_

_Out_writes_bytes_to_opt_

_Out_writes_all_opt_

_Out_writes_bytes_all_opt_

_Inout_updates_to_opt_

_Inout_updates_bytes_to_opt_

_Inout_updates_all_opt_

_Inout_updates_bytes_all_opt_

_In_reads_to_ptr_opt_

_In_reads_to_ptr_opt_z_

_Out_writes_to_ptr_opt_

_Out_writes_to_ptr_opt_z_

Parâmetros do ponteiro de saída

Os parâmetros do ponteiro de saída requerem a notação especial torne o NULL- Ness no parâmetro e apontar- para o local.

Anotação

Descrição

_Outptr_

O parâmetro não pode ser nulo, e posteriores no estado apontar- para o local não pode ser o zero e deve ser válido.

_Outptr_opt_

O parâmetro pode ser nulo, mas após no estado apontar- para o local não pode ser o zero e deve ser válido.

_Outptr_result_maybenull_

O parâmetro não pode ser nulo, e posteriores no estado apontar- para o local pode ser nulo.

_Outptr_opt_result_maybenull_

O parâmetro pode ser nulo, e posteriores no estado apontar- para o local pode ser nulo.

Na tabela a seguir, as subcadeias de caracteres adicionais são inseridas no nome de anotação para qualificar mais significado de anotação.Várias subcadeias de caracteres são _z, _COM_, _buffer_, _bytebuffer_, e _to_.

Observação importanteImportante

Se a interface que você está anotando é COM, use o formulário COM dessas anotações.Não use as anotações COM com nenhuma outra interface de tipo.

Anotação

Descrição

_Outptr_result_z_

_Outptr_opt_result_z_

_Outptr_result_maybenull_z_

_Ouptr_opt_result_maybenull_z_

O ponteiro retornado tem a anotação de _Null_terminated_ .

_COM_Outptr_

_COM_Outptr_opt_

_COM_Outptr_result_maybenull_

_COM_Outptr_opt_result_maybenull_

O ponteiro retornado tem a semântica COM, e portanto após leva uma condição de _On_failure_ que o ponteiro retornado é nulo.

_Outptr_result_buffer_(s)

_Outptr_result_bytebuffer_(s)

_Outptr_opt_result_buffer_(s)

_Outptr_opt_result_bytebuffer_(s)

Os pontos retornados de ponteiro para um buffer válido de elementos ou de bytes de s de tamanho.

_Outptr_result_buffer_to_(s, c)

_Outptr_result_bytebuffer_to_(s, c)

_Outptr_opt_result_buffer_to_(s,c)

_Outptr_opt_result_bytebuffer_to_(s,c)

Os pontos retornados de ponteiro para um buffer de elementos ou de bytes de s de tamanho, que primeiro c é válido.

Determinadas convenções de interface presumem que os parâmetros de saída são anulados em caso de falha.A exceção explicitamente de código COM, formulários na tabela a seguir são preferenciais.Para o código COM, use os formulários correspondentes COM que são listados na seção anterior.

Anotação

Descrição

_Result_nullonfailure_

Altera outras anotações.O resultado é definido como nulo se a função falhar.

_Result_zeroonfailure_

Altera outras anotações.O resultado é definido como zero se a função falhar.

_Outptr_result_nullonfailure_

Os pontos retornados de ponteiro para um buffer válido se a função tiver êxito, ou zero se a função falhar.Esta anotação é para um parâmetro não opcional.

_Outptr_opt_result_nullonfailure_

Os pontos retornados de ponteiro para um buffer válido se a função tiver êxito, ou zero se a função falhar.Esta anotação é para um parâmetro opcional.

_Outref_result_nullonfailure_

Os pontos retornados de ponteiro para um buffer válido se a função tiver êxito, ou zero se a função falhar.Esta anotação é para um parâmetro de referência.

Parâmetros de referência de saída

Um uso comum de parâmetro de referência é para parâmetros de saída.Para referência simples de saída parâmetro- por exemplo, int&—_Out_ fornece semântica correta.No entanto, quando o valor de saída for ao tipo para o exemplo int *&— anotações equivalentes do ponteiro como _Outptr_ int ** não fornece semântica correta.Para expressar concisa a semântica de parâmetros de referência de saída para tipos ponteiro, use essas anotações compostas:

Anotação

Descrição

_Outref_

O resultado deve ser válido no estado pré e não pode ser nulo.

_Outref_result_maybenull_

O resultado deve ser válido no estado posteriores, mas pode ser nulo no estado posteriores.

_Outref_result_buffer_(s)

O resultado deve ser válido no estado pré e não pode ser nulo.Pontos ao buffer válido de elementos de s de tamanho.

_Outref_result_bytebuffer_(s)

O resultado deve ser válido no estado pré e não pode ser nulo.Pontos ao buffer válido de bytes de s de tamanho.

_Outref_result_buffer_to_(s, c)

O resultado deve ser válido no estado pré e não pode ser nulo.Pontos ao buffer de elementos de s , que primeiro c é válido.

_Outref_result_bytebuffer_to_(s, c)

O resultado deve ser válido no estado pré e não pode ser nulo.Pontos ao buffer de bytes de s da primeira c é válido.

_Outref_result_buffer_all_(s)

O resultado deve ser válido no estado pré e não pode ser nulo.Pontos ao buffer válido de elementos válidos de s de tamanho.

_Outref_result_bytebuffer_all_(s)

O resultado deve ser válido no estado pré e não pode ser nulo.Pontos ao buffer válido de bytes de s de elementos válidos.

_Outref_result_buffer_maybenull_(s)

O resultado deve ser válido no estado posteriores, mas pode ser nulo no estado posteriores.Pontos ao buffer válido de elementos de s de tamanho.

_Outref_result_bytebuffer_maybenull_(s)

O resultado deve ser válido no estado posteriores, mas pode ser nulo no estado posteriores.Pontos ao buffer válido de bytes de s de tamanho.

_Outref_result_buffer_to_maybenull_(s, c)

O resultado deve ser válido no estado posteriores, mas pode ser nulo no estado posteriores.Pontos ao buffer de elementos de s , que primeiro c é válido.

_Outref_result_bytebuffer_to_maybenull_(s,c)

O resultado deve ser válido no estado posteriores, mas pode ser nulo no estado de postagem.Pontos ao buffer de bytes de s da primeira c é válido.

_Outref_result_buffer_all_maybenull_(s)

O resultado deve ser válido no estado posteriores, mas pode ser nulo no estado de postagem.Pontos ao buffer válido de elementos válidos de s de tamanho.

_Outref_result_bytebuffer_all_maybenull_(s)

O resultado deve ser válido no estado posteriores, mas pode ser nulo no estado de postagem.Pontos ao buffer válido de bytes de s de elementos válidos.

Valores de retorno

O valor de retorno de uma função é semelhante a um parâmetro de _Out_ mas está-se a nível diferente de- referência, e você não precisa considerar o conceito de ponteiro ao resultado.Para as anotações, o valor de retorno é o objeto - um anotado escalar, um ponteiro para um estrutura, ou um ponteiro para um buffer.Essas anotações têm a mesma semântica que a anotação correspondente de _Out_ .

_Ret_z_

_Ret_writes_(s)

_Ret_writes_bytes_(s)

_Ret_writes_z_(s)

_Ret_writes_to_(s,c)

_Ret_writes_maybenull_(s)

_Ret_writes_to_maybenull_(s)

_Ret_writes_maybenull_z_(s)

_Ret_maybenull_

_Ret_maybenull_z_

_Ret_null_

_Ret_notnull_

_Ret_writes_bytes_to_

_Ret_writes_bytes_maybenull_

_Ret_writes_bytes_to_maybenull_

Outras anotações comuns

Anotação

Descrição

_In_range_(low, hi)

_Out_range_(low, hi)

_Ret_range_(low, hi)

_Deref_in_range_(low, hi)

_Deref_out_range_(low, hi)

_Deref_inout_range_(low, hi)

_Field_range_(low, hi)

O parâmetro, o campo, ou o resultado está no intervalo (-) de low a hi.Equivalente a _Satisfies_(_Curr_ >= low && _Curr_ <= hi) que é aplicada ao objeto anotado junto com as condições apropriadas de estado ou passos pré de estado.

Observação importanteImportante
Embora os nomes contém “e” em “para fora”, a semântica de _In_ e _Out_not se aplicam a essas anotações.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

O valor anotado é exatamente expr.Equivalente a _Satisfies_(_Curr_ == expr) que é aplicada ao objeto anotado junto com as condições apropriadas de estado ou passos pré de estado.

_Struct_size_bytes_(size)

Se aplica a uma declaração de estrutura ou classe.Indica que um objeto válido desse tipo pode ser maior do que o tipo declarado, com o número de bytes que estão sendo dados por size.Por exemplo:

typedef _Struct_size_bytes_(nSize)
struct MyStruct {
   size_t nSize;
   ...
};

O tamanho do buffer em bytes de pM um parâmetro de tipo MyStruct * é então ser colocada:

   min(pM->nSize, sizeof(MyStruct))

Recursos relacionados

Blog da Equipe de Análise de Código

Consulte também

Referência

Anotando o comportamento da função

Anotando estruturas e classes

Anotando o comportamento de bloqueio

Especificando quando e onde uma anotação se aplica

Funções intrínsecas

Práticas recomendadas e exemplos (SAL)

Conceitos

Noções básicas sobre SAL

Outros recursos

Usando o SAL anotações para reduzir os defeitos no código C/C++