Partilhar via

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

Este artigo descreve usos típicos de anotações para parâmetros de função simples — escalares e ponteiros para estruturas e classes — e a maioria dos tipos de buffers. Este artigo também mostra padrões de uso comuns para anotações. Para obter anotações adicionais relacionadas a 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 de ponteiro é anotado, o analisador relata um erro se o ponteiro for nulo. Esta anotação aplica-se a ponteiros e a qualquer item de dados apontado.

Anotações e descrições

  • _In_

    Anota parâmetros de entrada que são escalares, estruturas, ponteiros para estruturas e similares. Explicitamente pode ser usado em escalares simples. O parâmetro deve ser válido em pré-estado e não será modificado.

  • _Out_

    Anota parâmetros de saída que são escalares, estruturas, ponteiros para estruturas e similares. Não aplique essa anotação a um objeto que não pode retornar um valor, por exemplo, um escalar que é passado por valor. O parâmetro não precisa ser válido em pré-estado, mas deve ser válido em pós-estado.

  • _Inout_

    Anota um parâmetro que será alterado pela função. Ele deve ser válido tanto no pré-estado quanto no pós-estado, mas presume-se que tenha valores diferentes antes e depois da chamada. Deve aplicar-se a um valor modificável.

  • _In_z_

    Um ponteiro para uma cadeia de caracteres terminada em nulo que é usada como entrada. A cadeia de caracteres deve ser válida no estado inicial. As variantes de PSTR, que já têm as anotações corretas, são preferidas.

  • _Inout_z_

    Um ponteiro para uma matriz de caracteres terminada em nulo que será modificada. Deve ser válido antes e depois da chamada, mas presume-se que o valor foi alterado. O terminador nulo pode ser movido, mas apenas os elementos até o terminador nulo original podem ser acessados.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    Um ponteiro para uma matriz, cujo conteúdo é lido pela função. A matriz é de elementos de tamanho s , todos os quais devem ser válidos.

    A _bytes_ variante dá o tamanho em bytes em vez de elementos. Use esta variante somente quando o tamanho não puder ser expresso como elementos. Por exemplo, char cadeias de caracteres usariam uma _bytes_ variante somente se uma função semelhante que usa wchar_t também a usasse.

  • _In_reads_z_(s)

    Um ponteiro para uma matriz que é terminada em nulo e tem um tamanho conhecido. Os elementos até o terminador nulo — ou s se não houver um terminador nulo — devem ser válidos no pré-estado. Se o tamanho for conhecido em bytes, dimensione s pelo tamanho do elemento.

  • _In_reads_or_z_(s)

    Um ponteiro para uma matriz que é terminada nula ou tem um tamanho conhecido, ou ambos. Os elementos até o terminador nulo — ou s se não houver um terminador nulo — devem ser válidos no pré-estado. Se o tamanho for conhecido em bytes, dimensione s pelo tamanho do elemento. (Usado para a família strn.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    Um ponteiro para uma matriz de s elementos (resp. bytes) que serão escritos pela função. Os elementos de matriz não precisam ser válidos em pré-estado, e o número de elementos que são válidos em pós-estado não é especificado. Se houver anotações no tipo de parâmetro, elas são aplicadas no estado posterior. Por exemplo, considere o código a seguir.

    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 size elementos para p1. MyStringCopy torna válidos alguns desses elementos. Mais importante ainda, a _Null_terminated_ anotação em PWSTR significa que p1 é terminada por um nulo no estado posterior. Desta forma, o número de elementos válidos ainda está bem definido, mas uma contagem de elementos específicos não é necessária.

    A _bytes_ variante dá o tamanho em bytes em vez de elementos. Use esta variante somente quando o tamanho não puder ser expresso como elementos. Por exemplo, char cadeias de caracteres usariam uma _bytes_ variante somente se uma função semelhante que usa wchar_t também a usasse.

  • _Out_writes_z_(s)

    Um ponteiro para uma matriz de s elementos. Os elementos não precisam ser válidos no estado anterior. No pós-estado, os elementos até ao terminador nulo — que deve estar presente — devem ser válidos. Se o tamanho for conhecido em bytes, dimensione s pelo tamanho do elemento.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    Um ponteiro para uma matriz, que é lido e gravado na função. É de elementos de tamanho s e válido em pré-estado e pós-estado.

    A _bytes_ variante dá o tamanho em bytes em vez de elementos. Use esta variante somente quando o tamanho não puder ser expresso como elementos. Por exemplo, char cadeias de caracteres usariam uma _bytes_ variante somente se uma função semelhante que usa wchar_t também a usasse.

  • _Inout_updates_z_(s)

    Um ponteiro para uma matriz que é terminada em nulo e tem um tamanho conhecido. Os elementos até ao terminador nulo — que deve estar presente — devem ser válidos tanto no estado anterior quanto no estado posterior. Presume-se que o valor no pós-estado seja diferente do valor no pré-estado; isso inclui a posição do terminador nulo. Se o tamanho for conhecido em bytes, dimensione 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 s elementos. Os elementos não precisam ser válidos no estado anterior. No pós-estado, os elementos até ao -ésimo c elemento devem ser válidos. A _bytes_ variante pode ser usada se o tamanho for conhecido em bytes em vez de número de elementos.

    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 é lida e escrita pela função. É de elementos de tamanho s , todos os quais devem ser válidos em pré-estado, e c elementos devem ser válidos em pós-estado.

    A _bytes_ variante dá o tamanho em bytes em vez de elementos. Use esta variante somente quando o tamanho não puder ser expresso como elementos. Por exemplo, char cadeias de caracteres usariam uma _bytes_ variante somente se uma função semelhante que usa wchar_t também a usasse.

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

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

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

    Em outras palavras, todos os elementos que existem no buffer até s no pré-estado são válidos no pré-estado e pós-estado.

    A _bytes_ variante dá o tamanho em bytes em vez de elementos. Use esta variante somente quando o tamanho não puder ser expresso como elementos. Por exemplo, char cadeias de caracteres usariam uma _bytes_ variante somente se uma função semelhante que usa wchar_t também a usasse.

  • _In_reads_to_ptr_(p)

    Um ponteiro para uma matriz para a qual p - _Curr_ (isto é, p menos _Curr_) é uma expressão válida. Os elementos anteriores a p devem ser válidos no estado anterior.

    Por exemplo:

    int ReadAllElements(_In_reads_to_ptr_(EndOfArray) const int *Array, const int *EndOfArray);

  • _In_reads_to_ptr_z_(p)

    Um ponteiro para uma matriz terminada em nulo para a qual a expressão p - _Curr_ (isto é, p menos _Curr_) é uma expressão válida. Os elementos anteriores a p devem ser válidos no estado anterior.

  • _Out_writes_to_ptr_(p)

    Um ponteiro para uma matriz para a qual p - _Curr_ (isto é, p menos _Curr_) é uma expressão válida. Os elementos anteriores a p não precisam ser válidos no estado anterior, mas devem ser válidos no estado posterior.

  • _Out_writes_to_ptr_z_(p)

    Um ponteiro para uma matriz terminada em nulo para a qual p - _Curr_ (isto é, p menos _Curr_) é uma expressão válida. Os elementos anteriores a p não precisam ser válidos no estado anterior, mas devem ser válidos no estado posterior.

Parâmetros de ponteiro opcionais

Quando uma anotação de parâmetro de ponteiro inclui _opt_, indica que o parâmetro pode ser nulo. Caso contrário, a anotação se comportará da mesma forma que a versão que não inclui _opt_. Aqui está uma lista das _opt_ variantes das anotações de parâmetro de 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 de ponteiro de saída exigem notação especial para desambiguar a nulidade do parâmetro e do local apontado.

Anotações e descrições

  • _Outptr_

    O parâmetro não pode ser nulo e, no pós-estado, o local para o qual se aponta não pode ser nulo e deve ser válido.

  • _Outptr_opt_

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

  • _Outptr_result_maybenull_

    O parâmetro não pode ser nulo e, no estado posterior, o local apontado pode ser nulo.

  • _Outptr_opt_result_maybenull_

    O parâmetro pode ser nulo e, no pós-estado, o local para o qual se aponta pode ser nulo.

    Na tabela a seguir, substrings adicionais são inseridas no nome da anotação para qualificar ainda mais o significado da anotação. As várias substrings são _z, _COM_, _buffer_, _bytebuffer_ e _to_.

Importante

Se a interface que você está anotando for COM, use a forma COM dessas anotações. Não use as anotações COM com qualquer interface de outro tipo.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    O ponteiro retornado tem a _Null_terminated_ anotação.

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    O ponteiro retornado tem semântica COM, e é por isso que ele carrega uma _On_failure_ pós-condição de que o ponteiro retornado é nulo.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    O ponteiro retornado aponta para um buffer válido de elementos de tamanho s ou bytes.

  • _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)

    O ponteiro retornado aponta para um buffer de elementos de tamanho s ou bytes, dos quais os primeiros c são válidos.

Certas convenções de interface presumem que os parâmetros de saída são anulados em caso de falha. Exceto para o código COM explícito, os formulários na tabela a seguir são preferidos. Para código COM, use os formulários COM correspondentes listados na seção anterior.

  • _Result_nullonfailure_

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

  • _Result_zeroonfailure_

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

  • _Outptr_result_nullonfailure_

    O ponteiro retornado aponta para um buffer válido se a função for bem-sucedida, ou nulo se a função falhar. Esta anotação é para um parâmetro não opcional.

  • _Outptr_opt_result_nullonfailure_

    O ponteiro retornado aponta para um buffer válido se a função for bem-sucedida, ou nulo se a função falhar. Esta anotação é para um parâmetro opcional.

  • _Outref_result_nullonfailure_

    O ponteiro retornado aponta para um buffer válido se a função for bem-sucedida, ou nulo 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 do parâmetro de referência é para parâmetros de saída. Para parâmetros de referência de saída simples, como int&, _Out_ fornece a semântica correta. No entanto, quando o valor de saída é um ponteiro como int *&, as anotações de ponteiro equivalentes como _Outptr_ int ** não fornecem a semântica correta. Para expressar de forma concisa a semântica dos parâmetros de referência de saída para tipos de ponteiro, use estas anotações compostas:

Anotações e descrições

  • _Outref_

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

  • _Outref_result_maybenull_

    O resultado deve ser válido em pós-estado, mas pode ser nulo em pós-estado.

  • _Outref_result_buffer_(s)

    O resultado deve ser válido no estado posterior e não pode ser nulo. Aponta para um buffer válido com s elementos.

  • _Outref_result_bytebuffer_(s)

    O resultado deve ser válido no estado posterior e não pode ser nulo. Aponta para um buffer válido de tamanho s bytes.

  • _Outref_result_buffer_to_(s, c)

    O resultado deve ser válido no estado posterior e não pode ser nulo. Aponta para um buffer de s elementos, dos quais os primeiros c são válidos.

  • _Outref_result_bytebuffer_to_(s, c)

    O resultado deve ser válido no estado posterior e não pode ser nulo. Aponta para buffer de s bytes dos quais os primeiros c são válidos.

  • _Outref_result_buffer_all_(s)

    O resultado deve ser válido no estado posterior e não pode ser nulo. Aponta para um buffer válido de tamanho s de elementos válidos.

  • _Outref_result_bytebuffer_all_(s)

    O resultado deve ser válido no estado posterior e não pode ser nulo. Aponta para um buffer válido de s bytes de elementos válidos.

  • _Outref_result_buffer_maybenull_(s)

    O resultado deve ser válido em pós-estado, mas pode ser nulo em pós-estado. Aponta para um buffer válido com s elementos.

  • _Outref_result_bytebuffer_maybenull_(s)

    O resultado deve ser válido em pós-estado, mas pode ser nulo em pós-estado. Aponta para um buffer válido de tamanho s bytes.

  • _Outref_result_buffer_to_maybenull_(s, c)

    O resultado deve ser válido em pós-estado, mas pode ser nulo em pós-estado. Aponta para um buffer de s elementos, dos quais os primeiros c são válidos.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    O resultado deve ser válido no pós-estado, mas pode ser nulo no pós-estado. Aponta para buffer de s bytes dos quais os primeiros c são válidos.

  • _Outref_result_buffer_all_maybenull_(s)

    O resultado deve ser válido no pós-estado, mas pode ser nulo no pós-estado. Aponta para um buffer válido de tamanho s de elementos válidos.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    O resultado deve ser válido no pós-estado, mas pode ser nulo no pós-estado. Aponta para um buffer válido de s bytes de elementos válidos.

Valores de retorno

O valor de retorno de uma função assemelha-se a um _Out_ parâmetro, mas está num nível diferente de desreferenciação, e você não precisa considerar o conceito de ponteiro para o 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. Estas anotações têm a mesma semântica que a anotação correspondente _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_

Formatar parâmetros de cadeia de caracteres

  • _Printf_format_string_ Indica que o parâmetro é uma cadeia de caracteres de formato para uso em uma printf expressão.

    Exemplo

    int MyPrintF(_Printf_format_string_ const wchar_t* format, ...)
{
       va_list args;
       va_start(args, format);
       int ret = vwprintf(format, args);
       va_end(args);
       return ret;
}

  • _Scanf_format_string_ Indica que o parâmetro é uma cadeia de caracteres de formato para uso em uma scanf expressão.

    Exemplo

    int MyScanF(_Scanf_format_string_ const wchar_t* format, ...)
{
       va_list args;
       va_start(args, format);
       int ret = vwscanf(format, args);
       va_end(args);
       return ret;
}

  • _Scanf_s_format_string_ Indica que o parâmetro é uma cadeia de caracteres de formato para uso em uma scanf_s expressão.

    Exemplo

    int MyScanF_s(_Scanf_s_format_string_ const wchar_t* format, ...)
{
       va_list args;
       va_start(args, format);
       int ret = vwscanf_s(format, args);
       va_end(args);
       return ret;
}

Outras anotações comuns

Anotações e descrições

  • _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, campo ou resultado está no intervalo (inclusive) de low até hi. Equivalente a _Satisfies_(_Curr_ >= low && _Curr_ <= hi) que é aplicado ao objeto anotado juntamente com as condições de pré-estado ou de pós-estado apropriadas.

    Importante

    Embora os nomes contenham "in" e "out", as semânticas de _In_ e _Out_não se aplicam a estas anotações.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    O valor anotado é exatamente expr. Equivalente a _Satisfies_(_Curr_ == expr) que é aplicado ao objeto anotado juntamente com as condições de pré-estado ou de pós-estado apropriadas.

  • _Struct_size_bytes_(size)

    Aplica-se a uma declaração struct ou class. Indica que um objeto válido desse tipo pode ser maior do que o tipo declarado, com o número de bytes sendo dado 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 considerado como:

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

Ver também

  • Last updated on