Anotando parâmetros de função e valores de retorno
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.
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:
Ou seja cada elemento que existe no buffer até s no estado é válido no estado após. Por exemplo:
|
_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:
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_.
Importante |
---|
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.
|
||
_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:
O tamanho do buffer em bytes de um parâmetro pM do tipo MyStruct * é então ser efetuado:
|
Recursos relacionados
Blog da equipe de análise de código
Consulte também
Referência
Anotando o comportamento da função
Anotando o comportamento de bloqueio
Especificando quando e onde uma anotação se aplica
Práticas recomendadas e exemplos (SAL)
Conceitos
Outros recursos
Usando anotações de SAL para reduzir defeitos de código do C/C++