Anotación de parámetros de función y valores devueltos

  • Artículo
  • 13 minutos para leer

En este artículo se describen los usos típicos de anotaciones para parámetros de función simples (escalares y punteros a estructuras y clases) y la mayoría de los tipos de búferes. En este artículo también se muestran los patrones de uso comunes para las anotaciones. Para obtener anotaciones adicionales relacionadas con las funciones, vea Anotación del comportamiento de la función.

Parámetros de puntero

Para las anotaciones de la tabla siguiente, cuando se anota un parámetro de puntero, el analizador notifica un error si el puntero es NULL. Esta anotación se aplica a los punteros y a cualquier elemento de datos al que se apunte.

Anotaciones y descripciones

  • _In_

    Anota los parámetros de entrada que son escalares, estructuras, punteros a estructuras y similares. Se puede usar explícitamente en escalares simples. El parámetro debe ser válido en estado previo y no se modificará.

  • _Out_

    Anota los parámetros de salida que son escalares, estructuras, punteros a estructuras y similares. No aplique esta anotación a un objeto que no pueda devolver un valor, por ejemplo, un valor escalar que se pasa por valor. El parámetro no tiene que ser válido en estado previo, pero debe ser válido en estado posterior.

  • _Inout_

    Anota un parámetro que cambiará la función. Debe ser válido tanto en el estado anterior como en el posterior, pero se supone que tiene valores diferentes antes y después de la llamada. Debe aplicarse a un valor modificable.

  • _In_z_

    Puntero a una cadena terminada en NULL que se usa como entrada. La cadena debe ser válida en estado previo. Se prefieren PSTR variantes de , que ya tienen las anotaciones correctas.

  • _Inout_z_

    Puntero a una matriz de caracteres terminada en NULL que se modificará. Debe ser válido antes y después de la llamada, pero se supone que el valor ha cambiado. Se puede mover el terminador null, pero solo se puede acceder a los elementos hasta el terminador null original.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    Puntero a una matriz, que lee la función . La matriz es de elementos s de tamaño, todos los cuales deben ser válidos.

    La _bytes_ variante proporciona el tamaño en bytes en lugar de elementos. Use esta variante solo cuando el tamaño no se pueda expresar como elementos. Por ejemplo, char las cadenas usarían la variante solo si lo haría _bytes_ una función similar que use wchar_t .

  • _In_reads_z_(s)

    Puntero a una matriz terminada en NULL y con un tamaño conocido. Los elementos hasta el terminador nulo, o si no hay un terminador null, deben ser válidos s en estado previo. Si el tamaño se conoce en bytes, escale s según el tamaño del elemento.

  • _In_reads_or_z_(s)

    Puntero a una matriz terminada en NULL o con un tamaño conocido, o ambos. Los elementos hasta el terminador nulo, o si no hay un terminador null, deben ser válidos s en estado previo. Si el tamaño se conoce en bytes, escale s según el tamaño del elemento. (Se usa para la strn familia).

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    Puntero a una matriz s de elementos (bytes resp. ) que escribirá la función. Los elementos de la matriz no tienen que ser válidos en estado previo y el número de elementos que son válidos en estado posterior no se especifica. Si hay anotaciones en el tipo de parámetro, se aplican en estado posterior. Por ejemplo, considere el fragmento de código siguiente:

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

    En este ejemplo, el autor de la llamada proporciona un búfer de size elementos para p1 . MyStringCopy hace que algunos de esos elementos sea válido. Lo que es más importante, _Null_terminated_ la PWSTR anotación en significa p1 que termina en NULL en estado posterior. De este modo, el número de elementos válidos sigue estando bien definido, pero no se requiere un recuento de elementos específico.

    La _bytes_ variante proporciona el tamaño en bytes en lugar de elementos. Use esta variante solo cuando el tamaño no se pueda expresar como elementos. Por ejemplo, char las cadenas usarían la variante solo si lo haría _bytes_ una función similar que use wchar_t .

  • _Out_writes_z_(s)

    Puntero a una matriz de s elementos. Los elementos no tienen que ser válidos en estado previo. En el estado posterior, los elementos hasta el terminador null ,que deben estar presentes, deben ser válidos. Si el tamaño se conoce en bytes, escale s según el tamaño del elemento.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    Puntero a una matriz, que se lee y se escribe en en la función . Es de elementos de s tamaño y es válido en estado previo y posterior.

    La _bytes_ variante proporciona el tamaño en bytes en lugar de elementos. Use esta variante solo cuando el tamaño no se pueda expresar como elementos. Por ejemplo, char las cadenas usarían la variante solo si lo haría _bytes_ una función similar que use wchar_t .

  • _Inout_updates_z_(s)

    Puntero a una matriz terminada en NULL y con un tamaño conocido. Los elementos hasta el terminador null , que deben estar presentes, deben ser válidos tanto en el estado anterior como en el posterior. Se supone que el valor del estado posterior es diferente del valor del estado anterior; que incluye la ubicación del terminador nulo. Si el tamaño se conoce en bytes, escale s según el tamaño del elemento.

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    Puntero a una matriz de s elementos. Los elementos no tienen que ser válidos en estado previo. En estado posterior, los elementos hasta c el elemento -th deben ser válidos. La _bytes_ variante se puede usar si el tamaño se conoce en bytes en lugar de en el número de elementos.

    Por ejemplo:

    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)

    Puntero a una matriz, que la función lee y escribe. Es de elementos de tamaño, todos los cuales deben ser válidos en estado previo y los elementos deben ser válidos sc en estado posterior.

    La _bytes_ variante proporciona el tamaño en bytes en lugar de elementos. Use esta variante solo cuando el tamaño no se pueda expresar como elementos. Por ejemplo, char las cadenas usarían la variante solo si lo haría _bytes_ una función similar que use wchar_t .

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    Puntero a una matriz, que la función de elementos de tamaño lee y s escribe. Se define como equivalente a:

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

    En otras palabras, todos los elementos que existen en el búfer hasta en el estado anterior son válidos en el estado anterior y s posterior.

    La _bytes_ variante proporciona el tamaño en bytes en lugar de elementos. Use esta variante solo cuando el tamaño no se pueda expresar como elementos. Por ejemplo, char las cadenas usarían la variante solo si lo haría _bytes_ una función similar que use wchar_t .

  • _In_reads_to_ptr_(p)

    Puntero a una matriz para la que p - _Curr_ (es decir, p menos ) es una expresión _Curr_ válida. Los elementos anteriores p deben ser válidos en estado previo.

    Por ejemplo:

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

  • _In_reads_to_ptr_z_(p)

    Puntero a una matriz terminada en NULL para la que expresión p - _Curr_ (es decir, p menos ) es una expresión _Curr_ válida. Los elementos anteriores p deben ser válidos en estado previo.

  • _Out_writes_to_ptr_(p)

    Puntero a una matriz para la que p - _Curr_ (es decir, p menos ) es una expresión _Curr_ válida. Los elementos anteriores no tienen que ser válidos en estado previo y p deben ser válidos en estado posterior.

  • _Out_writes_to_ptr_z_(p)

    Puntero a una matriz terminada en NULL para la que p - _Curr_ (es decir, p menos ) es una expresión _Curr_ válida. Los elementos anteriores no tienen que ser válidos en estado previo y p deben ser válidos en estado posterior.

Parámetros de puntero opcionales

Cuando una anotación de parámetro de puntero _opt_ incluye , indica que el parámetro puede ser NULL. De lo contrario, la anotación se comporta igual que la versión que no incluye _opt_ . Esta es una lista de las _opt_ variantes de las anotaciones de parámetro de puntero:

_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 de puntero de salida

Los parámetros de puntero de salida requieren una notación especial para eliminar la ambigüedad de los valores NULL en el parámetro y la ubicación a la que se apunta.

Anotaciones y descripciones

  • _Outptr_

    El parámetro no puede ser NULL y, en el estado posterior, la ubicación a la que se apunta no puede ser null y debe ser válida.

  • _Outptr_opt_

    El parámetro puede ser NULL, pero en el estado posterior, la ubicación a la que se apunta no puede ser null y debe ser válida.

  • _Outptr_result_maybenull_

    El parámetro no puede ser NULL y, en el estado posterior, la ubicación a la que se apunta puede ser NULL.

  • _Outptr_opt_result_maybenull_

    El parámetro puede ser NULL y, en el estado posterior, la ubicación a la que se apunta puede ser NULL.

    En la tabla siguiente, se insertan subcadenas adicionales en el nombre de la anotación para calificar aún más el significado de la anotación. Las distintas subcadenas _z son , , , y _COM__buffer__bytebuffer__to_ .

Importante

Si la interfaz que está anotando es COM, use el formato COM de estas anotaciones. No use las anotaciones COM con ninguna otra interfaz de tipo.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    El puntero devuelto tiene la _Null_terminated_ anotación .

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    El puntero devuelto tiene semántica COM, por lo que lleva una condición posterior a _On_failure_ que el puntero devuelto sea NULL.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    El puntero devuelto apunta a un búfer válido de bytes s o elementos de tamaño.

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

    El puntero devuelto apunta a un búfer de bytes s o elementos de tamaño, de los que el primero c es válido.

Algunas convenciones de interfaz suponen que los parámetros de salida se anulan en caso de error. Excepto para el código COM explícitamente, se prefieren los formularios de la tabla siguiente. Para el código COM, use los formularios COM correspondientes que se muestran en la sección anterior.

  • _Result_nullonfailure_

    Modifica otras anotaciones. El resultado se establece en NULL si se produce un error en la función.

  • _Result_zeroonfailure_

    Modifica otras anotaciones. El resultado se establece en cero si se produce un error en la función.

  • _Outptr_result_nullonfailure_

    El puntero devuelto apunta a un búfer válido si la función se realiza correctamente o null si se produce un error en la función. Esta anotación es para un parámetro no opcional.

  • _Outptr_opt_result_nullonfailure_

    El puntero devuelto apunta a un búfer válido si la función se realiza correctamente o null si se produce un error en la función. Esta anotación es para un parámetro opcional.

  • _Outref_result_nullonfailure_

    El puntero devuelto apunta a un búfer válido si la función se realiza correctamente o null si se produce un error en la función. Esta anotación es para un parámetro de referencia.

Parámetros de referencia de salida

Un uso común del parámetro de referencia es para los parámetros de salida. Para los parámetros de referencia de salida simples, int& como , proporciona la semántica _Out_ correcta. Sin embargo, cuando el valor de salida es un puntero como , las anotaciones de puntero equivalentes como no proporcionan int *&_Outptr_ int ** la semántica correcta. Para expresar concisamente la semántica de los parámetros de referencia de salida para los tipos de puntero, use estas anotaciones compuestas:

Anotaciones y descripciones

  • _Outref_

    El resultado debe ser válido en el estado posterior y no puede ser NULL.

  • _Outref_result_maybenull_

    El resultado debe ser válido en el estado posterior, pero puede ser NULL en el estado posterior.

  • _Outref_result_buffer_(s)

    El resultado debe ser válido en el estado posterior y no puede ser NULL. Apunta al búfer válido de elementos de s tamaño.

  • _Outref_result_bytebuffer_(s)

    El resultado debe ser válido en el estado posterior y no puede ser NULL. Apunta al búfer válido de bytes s de tamaño.

  • _Outref_result_buffer_to_(s, c)

    El resultado debe ser válido en el estado posterior y no puede ser NULL. Apunta al búfer de s elementos, de los que el primero c es válido.

  • _Outref_result_bytebuffer_to_(s, c)

    El resultado debe ser válido en el estado posterior y no puede ser NULL. Apunta al búfer de s bytes de los que el primero es c válido.

  • _Outref_result_buffer_all_(s)

    El resultado debe ser válido en el estado posterior y no puede ser NULL. Apunta al búfer válido de los elementos s válidos de tamaño.

  • _Outref_result_bytebuffer_all_(s)

    El resultado debe ser válido en el estado posterior y no puede ser NULL. Apunta al búfer válido de s bytes de elementos válidos.

  • _Outref_result_buffer_maybenull_(s)

    El resultado debe ser válido en el estado posterior, pero puede ser NULL en el estado posterior. Apunta al búfer válido de elementos de s tamaño.

  • _Outref_result_bytebuffer_maybenull_(s)

    El resultado debe ser válido en el estado posterior, pero puede ser NULL en el estado posterior. Apunta al búfer válido de bytes s de tamaño.

  • _Outref_result_buffer_to_maybenull_(s, c)

    El resultado debe ser válido en el estado posterior, pero puede ser NULL en el estado posterior. Apunta al búfer de s elementos, de los que el primero c es válido.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    El resultado debe ser válido en el estado posterior, pero puede ser NULL en el estado posterior. Apunta al búfer de s bytes de los que el primero es c válido.

  • _Outref_result_buffer_all_maybenull_(s)

    El resultado debe ser válido en el estado posterior, pero puede ser NULL en el estado posterior. Apunta al búfer válido de los elementos s válidos de tamaño.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    El resultado debe ser válido en el estado posterior, pero puede ser NULL en el estado posterior. Apunta al búfer válido de s bytes de elementos válidos.

Valores devueltos

El valor devuelto de una función es similar a un parámetro, pero se encuentra en un nivel diferente de des-referencia y no tiene que tener en cuenta el concepto del puntero _Out_ al resultado. Para las anotaciones siguientes, el valor devuelto es el objeto anotado: un escalar, un puntero a un struct o un puntero a un búfer. Estas anotaciones tienen la misma semántica que la anotación _Out_ correspondiente.

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

Dar formato a los parámetros de cadena

  • _Printf_format_string_ Indica que el parámetro es una cadena de formato para su uso en una printf expresión.

    Ejemplo

    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 el parámetro es una cadena de formato para su uso en una scanf expresión.

    Ejemplo

    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 el parámetro es una cadena de formato para su uso en una scanf_s expresión.

    Ejemplo

    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;
}

Otras anotaciones comunes

Anotaciones y descripciones

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

    El parámetro, campo o resultado está en el intervalo (inclusivo) de low a hi . Equivalente a que se aplica al objeto anotado junto con las condiciones adecuadas de estado previo o _Satisfies_(_Curr_ >= low && _Curr_ <= hi) posterior.

    Importante

    Aunque los nombres contienen "in" y "out", la semántica de _In_ y _Out_ no _In_ aplica a estas anotaciones.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    El valor anotado es exactamente expr . Equivalente a que se aplica al objeto anotado junto con las condiciones adecuadas de estado previo o _Satisfies_(_Curr_ == expr) posterior.

  • _Struct_size_bytes_(size)

    Se aplica a una declaración de estructura o clase. Indica que un objeto válido de ese tipo puede ser mayor que el tipo declarado, con el número de bytes especificado por size . Por ejemplo:

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

    El tamaño del búfer en bytes de un parámetro de tipo se pMMyStruct * toma como:

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

Vea también