Anotar parámetros de función y valores devueltos

  • Artículo

En este artículo se describen los usos habituales de las anotaciones para los parámetros de función simple - escalares y punteros para las estructuras y clases y la mayoría de las clases de búferes.Este artículo también muestra patrones de uso comunes para las anotaciones.Para anotaciones adicionales relacionadas con funciones, consulte Anotar el comportamiento de funciones

Parámetros de puntero

Para las anotaciones en la tabla siguiente, cuando se está anotando un parámetro de puntero, el analizador indica un error si el puntero es null.Esto se aplica a los punteros y a cualquier elemento de datos al que se señala.

Anotaciones

Descripción

_In_

Anota parámetros de entrada que son escalares, estructuras, punteros a las estructuras y similares.Se puede utilizar 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 las estructuras y similares.No aplique esto a un objeto que no puede devolver un valor por ejemplo, un 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 se cambia por la función.Debe ser válido tanto en estado previo como en estado posterior, pero se asume que tiene valores diferentes antes y después de la llamada.Debe aplicarse a un valor modificable.

_In_z_

Un puntero a una cadena terminada en null que se utiliza como entrada.La cadena debe ser válida en estado previo.Se prefieren las variantes PSTR, que ya tienen las anotaciones correctas.

_Inout_z_

Un puntero a una matriz de caracteres terminada en null que se modificará.Debe ser válida antes y después de la llamada, pero el valor se asume que ha cambiado.El terminador nulo puede ser movido, pero sólo los elementos hasta el terminador nulo original pueden obtener acceso a ellos.

_In_reads_(s)

_In_reads_bytes_(s)

Un puntero a una matriz, que es leída por la función.La matriz tiene un tamaño de s elementos, los cuales deben ser válidos.

La variante _bytes_ proporciona el tamaño en bytes en lugar de en elementos.Utilícela sólo cuando el tamaño no se pueda expresar como elementos.Por ejemplo, las cadenas char utilizarían la variante _bytes_ sólo si una función similar que utiliza wchar_t lo hiciera.

_In_reads_z_(s)

Un puntero a una matriz que termina en null y tiene un tamaño conocido.Los elementos hasta el terminador null —o s si no hay terminador null— deben ser válidos en estado previo.Si el tamaño se conoce en bytes, escale s por el tamaño del elemento.

_In_reads_or_z_(s)

Un puntero a una matriz que termina en null, tiene un tamaño conocido o ambos.Los elementos hasta el terminador null —o s si no hay terminador null— deben ser válidos en estado previo.Si el tamaño se conoce en bytes, escale s por el tamaño del elemento.(Usado para la familia strn.)

_Out_writes_(s)

_Out_writes_bytes_(s)

Un puntero a una matriz de elementos s (resp.bytes) que estarán escritos por la función.Los elementos de la matriz no tienen que ser válidos en estado previo y el número de elementos que sean válidos en estado posterior no está especificado.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 llamador proporciona un búfer de elementos size para p1.MyStringCopy hace algunos de esos elementos válidos.Más aún, la anotación _Null_terminated_ en PWSTR significa que p1 termina en null en estado posterior.De esta manera, el número de elementos válidos sigue bien definido, pero no se requiere un conteo específico de elementos.

La variante _bytes_ proporciona el tamaño en bytes en lugar de en elementos.Utilícela sólo cuando el tamaño no se pueda expresar como elementos.Por ejemplo, las cadenas char utilizarían la variante _bytes_ sólo si una función similar que utiliza wchar_t lo hiciera.

_Out_writes_z_(s)

Un puntero a una matriz de s objetos.Los elementos no tienen que ser válidos en estado previo.En estado posterior, los elementos hasta el terminador null —que debe estar presente— deben ser válidos.Si el tamaño se conoce en bytes, escale s por el tamaño del elemento.

_Inout_updates_(s)

_Inout_updates_bytes_(s)

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

La variante _bytes_ proporciona el tamaño en bytes en lugar de en elementos.Utilícela sólo cuando el tamaño no se pueda expresar como elementos.Por ejemplo, las cadenas char utilizarían la variante _bytes_ sólo si una función similar que utiliza wchar_t lo hiciera.

_Inout_updates_z_(s)

Un puntero a una matriz que termina en null y tiene un tamaño conocido.Los elementos hasta el terminador null —que debe estar presente— deben ser válidos en estado previo y en estado posterior.El valor en el estado posterior se supone que es diferente del valor en el estado previo; esto incluye la ubicación del terminador null.Si el tamaño se conoce en bytes, escale s por 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)

Un puntero a una matriz de s objetos.Los elementos no tienen que ser válidos en estado previo.En estado posterior, los elementos hasta el c-ésimo elemento deben ser válidos.Si el tamaño se conoce en bytes, escale s y c por el tamaño del elemento o utilice la variante _bytes_, que se define como:

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

Es decir cada elemento que existe en el búfer hasta s en el estado previo es válido en el estado posterior.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)

Un puntero a una matriz, que es leído y escrito por la función.Su tamaño es de s elementos, que deben ser válidos en estado previo mientas que los elementos c deben ser válidos en estado posterior.

La variante _bytes_ proporciona el tamaño en bytes en lugar de en elementos.Utilícela sólo cuando el tamaño no se pueda expresar como elementos.Por ejemplo, las cadenas char utilizarían la variante _bytes_ sólo si una función similar que utiliza wchar_t lo hiciera.

_Inout_updates_all_(s)

_Inout_updates_bytes_all_(s)

Un puntero a una matriz, que es leído y escrito por la función de tamaño s elementos.Definido como equivalente a:

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

Es decir, cada elemento que existe en el búfer hasta s en el estado previo es válido en el estado previo y en el estado posterior.

La variante _bytes_ proporciona el tamaño en bytes en lugar de en elementos.Utilícela sólo cuando el tamaño no se pueda expresar como elementos.Por ejemplo, las cadenas char utilizarían la variante _bytes_ sólo si una función similar que utiliza wchar_t lo hiciera.

_In_reads_to_ptr_(p)

Un puntero a una matriz para el que la expresión p – _Curr_ (es decir, p menos _Curr_) se define en la norma de idioma adecuada.Los elementos antes de p deben ser válidos en estado previo.

_In_reads_to_ptr_z_(p)

Un puntero a una matriz terminada en null para el que la expresión p – _Curr_ (es decir, p menos _Curr_) se define en la norma de idioma adecuada.Los elementos antes de p deben ser válidos en estado previo.

_Out_writes_to_ptr_(p)

Un puntero a una matriz para el que la expresión p – _Curr_ (es decir, p menos _Curr_) se define en la norma de idioma adecuada.Los elementos anteriores a p no tienen que ser válidos en estado previo pero deben ser válidos en estado posterior.

_Out_writes_to_ptr_z_(p)

Un puntero a una matriz terminada en null para el que la expresión p – _Curr_ (es decir, p menos _Curr_) se define en la norma de idioma adecuada.Los elementos anteriores a p no tienen que ser válidos en estado previo pero deben ser válidos en estado posterior.

Parámetros opcionales de puntero

Cuando una anotación de parámetro de puntero incluye _opt_, indica que el parámetro puede ser NULL.Si no, la anotación se realiza igual que la versión que no incluye _opt_.A continuación se muestra una lista de las variantes _opt_ de anotaciones del 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 la notación especial para eliminar la ambigüedad null en el parámetro y la ubicación a la que se apunta.

Anotaciones

Descripción

_Outptr_

El parámetro no puede ser null y, en el estado posterior, la ubicación a la que señala 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ñala 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ñala 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ñala puede ser null.

En la siguiente tabla, las subcadenas adicionales se insertan en el nombre de la anotación para calificar aún más el significado de la anotación.Varias subcadenas son _z, _COM_, _buffer_, _bytebuffer_, y _to_.

Nota importanteImportante

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

Anotaciones

Descripción

_Outptr_result_z_

_Outptr_opt_result_z_

_Outptr_result_maybenull_z_

_Ouptr_opt_result_maybenull_z_

El puntero devuelto tiene la anotación _Null_terminated_.

_COM_Outptr_

_COM_Outptr_opt_

_COM_Outptr_result_maybenull_

_COM_Outptr_opt_result_maybenull_

El puntero devuelto tiene semántica COM y, por consiguiente lleva una condición posterior _On_failure_ de que el puntero devuelto debe ser 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 con un tamaño de s elementos o 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)

Los puntos de puntero devueltos a un búfer con un tamaño de s elementos o bytes, de los cuales el primer c es válido.

Ciertas convenciones de interfaz presuponen que los parámetros de salida se compensan en caso de error.Salvo por el código explícito COM, se prefieren los formularios en la tabla siguiente.Para el código COM, utilice los formularios COM correspondientes que se enumeran en la sección anterior.

Anotaciones

Descripción

_Result_nullonfailure_

Modifica otras anotaciones.El resultado se establece en null si la función no se puede realizar.

_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 tiene éxito, o NULL si se produce un error en la función.Esta anotación es para un parámetro que no es opcional.

_Outptr_opt_result_nullonfailure_

El puntero devuelto apunta a un búfer válido si la función tiene éxito, 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 tiene éxito, 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 simple —por ejemplo, int&—_Out_ proporciona la semántica correcta.Sin embargo, cuando el valor de salida es un puntero —por ejemplo int *&— las anotaciones equivalentes de puntero como _Outptr_ int ** no proporcionan la semántica correcta.Para expresar sucintamente la semántica de los parámetros de referencia de salida para los tipos de puntero, utilice estas anotaciones compuestas:

Anotaciones

Descripción

_Outref_

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

_Outref_result_maybenull_

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

_Outref_result_buffer_(s)

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

_Outref_result_bytebuffer_(s)

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

_Outref_result_buffer_to_(s, c)

El resultado debe ser válido en estado posterior y no puede ser nulo.Señala al búfer de s elementos, cuyo primer c es válido.

_Outref_result_bytebuffer_to_(s, c)

El resultado debe ser válido en estado posterior y no puede ser nulo.Señala al búfer de s bytes cuyo primer c es válido.

_Outref_result_buffer_all_(s)

El resultado debe ser válido en estado posterior y no puede ser nulo.Señala al búfer válido con un tamaño de s elementos válidos.

_Outref_result_bytebuffer_all_(s)

El resultado debe ser válido en estado posterior y no puede ser nulo.Señala al búfer válido con un tamaño de s bytes de elementos válidos.

_Outref_result_buffer_maybenull_(s)

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

_Outref_result_bytebuffer_maybenull_(s)

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

_Outref_result_buffer_to_maybenull_(s, c)

El resultado debe ser válido en estado posterior, pero puede ser nulo en estado posterior.Señala al búfer de s elementos, cuyo primer c es válido.

_Outref_result_bytebuffer_to_maybenull_(s,c)

El resultado debe ser válido en estado posterior, pero puede ser nulo en estado posterior.Señala al búfer de s bytes cuyo primer c es válido.

_Outref_result_buffer_all_maybenull_(s)

El resultado debe ser válido en estado posterior, pero puede ser nulo en estado posterior.Señala al búfer válido con un tamaño de s elementos válidos.

_Outref_result_bytebuffer_all_maybenull_(s)

El resultado debe ser válido en estado posterior, pero puede ser nulo en estado posterior.Señala al búfer válido con un tamaño de s bytes de elementos válidos.

Valores devueltos

El valor devuelto de una función se parece a un parámetro de _Out_ pero está en otro nivel de desreferenciación y no se debe considerar el concepto del puntero al resultado.Para las siguientes anotaciones, 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 correspondiente _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_

Otras anotaciones comunes

Anotaciones

Descripción

_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) desde low a hi.Equivalente a _Satisfies_(_Curr_ >= low && _Curr_ <= hi) que se aplica al objeto anotado junto con las condiciones adecuadas del estado previo o estado posterior.

Nota importanteImportante
Aunque los nombres contienen “in” y “out”, la semántica de _In_ y _Out_no se aplican a estas anotaciones.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

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

_Struct_size_bytes_(size)

Se aplica a un struct o declaración de clase.Indica que un objeto válido de ese tipo puede ser mayor que el tipo declarado, con el número de bytes que son especificados 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 pM de tipo MyStruct * se supone que es:

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

Recursos relacionados

Blog del equipo de análisis de código

Vea también

Referencia

Anotar el comportamiento de funciones

Anotar structs y clases

Anotar comportamiento de bloqueo

Especificar cuándo y dónde se aplica una anotación

Funciones intrínsecas

Procedimientos recomendados y ejemplos (SAL)

Conceptos

Introducción a SAL

Otros recursos

Utilizar anotaciones SAL para reducir defectos de código de C/C++