Partilhar via

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

  • Artigo

Este artigo descreve os usos típicos de anotações para parâmetros escalares da função simples, e ponteiros para as estruturas classe e e a maioria dos tipos de buffers. Este artigo também mostra padrões de uso comum para anotações.Para as anotações adicionais que estão relacionadas às funções, consulte Anotando o comportamento da função

Parâmetros do ponteiro

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

Anotação

Descrição

_In_

Anota os parâmetros de entrada que são escalares, estruturas, ponteiros para as estruturas e LIKE. Explicitamente pode ser usado em escalares simples. O parâmetro deve ser válido no estado e não será alterado.

_Out_

Anota os parâmetros de saída que são escalares, estruturas, ponteiros para as estruturas e LIKE. Não aplicá-la a um objeto que não pode retornar a - por exemplo, um escalar que é passado pelo valor. O parâmetro não precisa ser válido no estado mas deve ser válido em após o estado.

_Inout_

Anota um parâmetro que foi modificado pela função. Deve ser válido no e no estado após estado, mas tem valores diferentes antes e depois da chamada.Deve ser aplicada a um valor modificável.

_In_z_

Um ponteiro para uma cadeia de caracteres com terminação nula que é usada como entrada. A cadeia de caracteres deve ser válido no estado. As variantes de PSTR, que já estão corretas, as anotações são preferenciais.

_Inout_z_

Um ponteiro para uma matriz de caracteres com terminação nula que foi modificada. Deve ser válido antes e depois da chamada, mas o valor será assumido para ter modificado. O terminador nulo pode ser movido, mas somente elementos até o terminador nulo original podem ser acessados.

_In_reads_(s)

_In_reads_bytes_(s)

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

A variante de _bytes_ do tamanho em bytes em vez de elementos.Use essa opção apenas quando o tamanho não pode ser expresso como elementos. Por exemplo, as cadeias de caracteres de char usariam a variante de _bytes_ apenas se uma função similar que usa wchar_t .

_In_reads_z_(s)

Um ponteiro para uma matriz que o valor nulo é encerrada e tem um tamanho válido.Os elementos até o terminador- zero ou s se não houver nenhum zero terminador- devem ser válidas no estado anterior. Se o tamanho é conhecido em bytes, escala s pelo tamanho do elemento.

_In_reads_or_z_(s)

Um ponteiro para uma matriz com que seja encerrada ou tem um tamanho conhecido, ou ambos.Os elementos até o terminador- zero ou s se não houver nenhum zero terminador- devem ser válidas no estado anterior. 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 de s (resp. bytes) que será gravado pela função. Os elementos da matriz não precisam ser válidas no estado anterior, e o número de elementos que são válidos no estado após não é especificado. Se houver anotações no tipo de parâmetro, são aplicados após no 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);

Neste exemplo, o chamador fornece um buffer de elementos de size para p1. MyStringCopy torna alguns dos elementos válido.Mais importante, a anotação de _Null_terminated_ em PWSTR significa que p1 nulo é encerrado após no estado. Desse modo, o número de elementos válidos ainda é bem definido, mas uma contagem específica do elemento não é necessária.

A variante de _bytes_ do tamanho em bytes em vez de elementos.Use essa opção apenas quando o tamanho não pode ser expresso como elementos. Por exemplo, as cadeias de caracteres de char usariam a variante de _bytes_ apenas se uma função similar que usa wchar_t .

_Out_writes_z_(s)

Um ponteiro para uma matriz de elementos de s . Os elementos não têm que ser válidas no estado anterior. Após no estado, os elementos acima por um nulo terminador- que deve ser atualmente devem ser válidas. 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 é leitura e gravação na função. É dos elementos de s de tamanho válido, e no estado anterior e pós-atualização no estado.

A variante de _bytes_ do tamanho em bytes em vez de elementos.Use essa opção apenas quando o tamanho não pode ser expresso como elementos. Por exemplo, as cadeias de caracteres de char usariam a variante de _bytes_ apenas se uma função similar que usa wchar_t .

_Inout_updates_z_(s)

Um ponteiro para uma matriz que o valor nulo é encerrada e tem um tamanho válido.Os elementos acima por um nulo terminador- que deve ser atualmente devem ser válidas no estado anterior e pós-atualização no estado. O valor no estado após deve ser diferente do valor no estado anterior; isso inclui o local de terminador nulo.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 de s . Os elementos não têm que ser válidas no estado anterior. Após no estado, os elementos até c- o elemento do º deve ser válida. Se o tamanho é conhecido em bytes, a escala s e c pelo tamanho do elemento ou usa a variante de _bytes_ , definido como:

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

Ou seja cada elemento que existe no buffer até s no estado é válido no estado após. 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 é leitura e gravação pela função. É dos elementos de s de tamanho, que devem ser válidas no estado anterior à, e os elementos de c devem ser válidas no estado após.

A variante de _bytes_ do tamanho em bytes em vez de elementos.Use essa opção apenas quando o tamanho não pode ser expresso como elementos. Por exemplo, as cadeias de caracteres de char usariam a variante de _bytes_ apenas se uma função similar que usa wchar_t .

_Inout_updates_all_(s)

_Inout_updates_bytes_all_(s)

Um ponteiro para uma matriz, que é leitura e gravação pela função dos elementos de s do 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 no buffer até s no estado é válido no estado anterior e pós-atualização no estado.

A variante de _bytes_ do tamanho em bytes em vez de elementos.Use essa opção apenas quando o tamanho não pode ser expresso como elementos. Por exemplo, as cadeias de caracteres de char usariam a variante de _bytes_ apenas se uma função similar 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 devem ser válidas no estado anterior.

_In_reads_to_ptr_z_(p)

Um ponteiro para uma matriz com terminação nula para que a expressão p – _Curr_ (isto é, p menos _Curr_) é definido por padrão de idioma apropriado. Os elementos antes de p devem ser válidas no estado anterior.

_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 precisam ser válidas no estado anterior e devem ser válidas no estado após.

_Out_writes_to_ptr_z_(p)

Um ponteiro para uma matriz com terminação nula 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 precisam ser válidas no estado anterior e devem ser válidas no estado após.

Parâmetros opcionais do ponteiro

Quando uma anotação de parâmetro do ponteiro inclui _opt_, indica que o parâmetro pode ser nulo.Caso contrário, a anotação é o mesmo que a versão que não inclui _opt_.Esta é uma lista das variantes de _opt_ de anotações de parâmetro 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 requer a notação especial resolver a ambiguidade do com Ness no parâmetro e apontar- para o local.

Anotação

Descrição

_Outptr_

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

_Outptr_opt_

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

_Outptr_result_maybenull_

O parâmetro não pode ser nulo, e no estado após apontar- no local pode ser nulo.

_Outptr_opt_result_maybenull_

O parâmetro pode ser nulo, e no estado após apontar- no local pode ser nulo.

Na tabela a seguir, a subcadeia de caracteres adicionais são inseridas no nome da anotação para qualificar mais o significado da anotação. Várias subcadeia 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 de COM essas anotações.Não use anotações COM com nenhuma outra interface do tipo.

Anotação

Descrição

_Outptr_result_z_

_Outptr_opt_result_z_

_Outptr_result_maybenull_z_

_Ouptr_opt_result_maybenull_z_

O ponteiro retornada possui a anotação de _Null_terminated_ .

_COM_Outptr_

_COM_Outptr_opt_

_COM_Outptr_result_maybenull_

_COM_Outptr_opt_result_maybenull_

O ponteiro retornada possui a semântica do, e leva em virtude disso após uma condição de _On_failure_ que o ponteiro nulo será retornado.

_Outptr_result_buffer_(s)

_Outptr_result_bytebuffer_(s)

_Outptr_opt_result_buffer_(s)

_Outptr_opt_result_bytebuffer_(s)

Os pontos retornados do ponteiro para um buffer válido de elementos ou de bytes de s do 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 do ponteiro para um buffer de elementos ou de bytes de s de tamanho, que primeiro c é válido.

Certas convenções de interface presumem que os parâmetros de saída são cancelada a falha. Exceto explicitamente o código clr COM, formas na tabela a seguir são preferencial. Para o código do, use os formulários correspondentes de COM que são listados na seção anterior.

Anotação

Descrição

_Result_nullonfailure_

Alterar outras anotações.O resultado será definido como nulo se a função falhará.

_Result_zeroonfailure_

Alterar outras anotações.O resultado é definido como zero se houver falha na função.

_Outptr_result_nullonfailure_

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

_Outptr_opt_result_nullonfailure_

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

_Outref_result_nullonfailure_

Os pontos retornados do ponteiro para um buffer válido se a função tiver êxito, ou nulo se a função falhará.Essa 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 de parâmetros para o exemplo, int&—_Out_ oferece semântica correta. No entanto, quando o valor de saída é a ponteiro- para o exemplo int *&— as anotações equivalentes do ponteiro como _Outptr_ int ** não oferece semântica correta. Para expressar concisa a semântica de parâmetros de referência de saída para tipos do ponteiro, use estas anotações compostas:

Anotação

Descrição

_Outref_

O resultado deve ser válido em pós-instalação estado e não pode ser nulo.

_Outref_result_maybenull_

O resultado deve ser válido em pós-instalação estado, mas pode ser nulo no estado após.

_Outref_result_buffer_(s)

O resultado deve ser válido em pós-instalação estado e não pode ser nulo.Aponte para o buffer válido dos elementos de s do tamanho.

_Outref_result_bytebuffer_(s)

O resultado deve ser válido em pós-instalação estado e não pode ser nulo.Aponte para o buffer válido de bytes de s do tamanho.

_Outref_result_buffer_to_(s, c)

O resultado deve ser válido em pós-instalação estado e não pode ser nulo.Aponte para o buffer dos elementos de s , que primeiro c é válido.

_Outref_result_bytebuffer_to_(s, c)

O resultado deve ser válido em pós-instalação estado e não pode ser nulo.Aponte para o buffer de bytes de s de que primeiro c é válido.

_Outref_result_buffer_all_(s)

O resultado deve ser válido em pós-instalação estado e não pode ser nulo.Aponte para o buffer válido de elementos válidos de s do tamanho.

_Outref_result_bytebuffer_all_(s)

O resultado deve ser válido em pós-instalação estado e não pode ser nulo.Aponte para o buffer válido de bytes de s de elementos válidos.

_Outref_result_buffer_maybenull_(s)

O resultado deve ser válido em pós-instalação estado, mas pode ser nulo no estado após.Aponte para o buffer válido dos elementos de s do tamanho.

_Outref_result_bytebuffer_maybenull_(s)

O resultado deve ser válido em pós-instalação estado, mas pode ser nulo no estado após.Aponte para o buffer válido de bytes de s do tamanho.

_Outref_result_buffer_to_maybenull_(s, c)

O resultado deve ser válido em pós-instalação estado, mas pode ser nulo no estado após.Aponte para o buffer dos elementos de s , que primeiro c é válido.

_Outref_result_bytebuffer_to_maybenull_(s,c)

O resultado deve ser válido em pós-instalação estado, mas pode ser nulo no estado da postagem.Aponte para o buffer de bytes de s de que primeiro c é válido.

_Outref_result_buffer_all_maybenull_(s)

O resultado deve ser válido em pós-instalação estado, mas pode ser nulo no estado da postagem.Aponte para o buffer válido de elementos válidos de s do tamanho.

_Outref_result_bytebuffer_all_maybenull_(s)

O resultado deve ser válido em pós-instalação estado, mas pode ser nulo no estado da postagem.Aponte para o 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 no nível diferente eliminação de referência, e você não deve considerar o conceito do ponteiro ao resultado. Para as anotações a seguir, o valor de retorno é o objeto - anotado um escalar, um ponteiro para uma 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ão no intervalo (inclusivo) de low a hi. Equivalente a _Satisfies_(_Curr_ >= low && _Curr_ <= hi) que é aplicado ao objeto anotado junto com as condições apropriados ao estado anterior ou após o estado.

Observação importanteImportante

Embora os nomes contêm “” e “out”, a semântica de _In_ e _Out_not se aplicam a essas anotações.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

O valor XSD anotado é exatamente expr. Equivalente a _Satisfies_(_Curr_ == expr) que é aplicado ao objeto anotado junto com as condições apropriados ao estado anterior ou após o estado.

_Struct_size_bytes_(size)

Se aplica a uma declaração da estrutura ou da classe. Indica que um objeto válida desse tipo pode ser maior 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 um parâmetro pM do tipo MyStruct * é então ser efetuado:

   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 de SAL

Outros recursos

Usando anotações de SAL para reduzir defeitos de código do C/C++