Anotaciones de encabezado

[En este tema se describen las anotaciones admitidas en los encabezados de Windows a través de Windows 7. Si está desarrollando para Windows 8, debe usar las anotaciones descritas en Anotaciones SAL.

Las anotaciones de encabezado describen cómo una función usa sus parámetros y el valor devuelto. Estas anotaciones se han agregado a muchos de los archivos de encabezado de Windows para ayudarle a asegurarse de que llama correctamente a la API de Windows. Si habilita el análisis de código, que está disponible a partir de Visual Studio 2005, el compilador generará advertencias de nivel 6000 si no llama a estas funciones por el uso descrito a través de las anotaciones. También puede agregar estas anotaciones en su propio código para asegurarse de que se llama correctamente. Para habilitar el análisis de código en Visual Studio, consulte la documentación de la versión de Visual Studio.

Estas anotaciones se definen en Specstrings.h. Se basan en primitivos que forman parte del lenguaje de anotación estándar (SAL) y se implementan mediante _declspec("SAL_*").

Hay dos clases de anotaciones: anotaciones de búfer y anotaciones avanzadas.

Anotaciones de búfer

Las anotaciones de búfer describen cómo las funciones usan sus punteros y se pueden usar para detectar saturaciones de búfer. Cada parámetro puede usar cero o una anotación de búfer. Una anotación de búfer se construye con un carácter de subrayado inicial y los componentes descritos en las secciones siguientes.

Tamaño de búfer	Descripción
(tamaño)	Especifica el tamaño total del búfer. Uso con _bcount y _ecount; no use con _part. Este valor es el espacio accesible; puede ser menor que el espacio asignado.
(tamaño, longitud)	Especifica el tamaño total y la longitud inicializada del búfer. Use con _bcount_part y _ecount_part. El tamaño total puede ser menor que el espacio asignado.

Unidades de tamaño de búfer	Descripción
_bcount	El tamaño del búfer está en bytes.
_ecount	El tamaño del búfer está en elementos.

Dirección	Descripción
_En	La función lee del búfer. El autor de la llamada proporciona el búfer y lo inicializa.
_Inout	La función lee y escribe en el búfer. El autor de la llamada proporciona el búfer y lo inicializa. Si se usa con _deref, la función puede reasignar el búfer.
_out	La función escribe en el búfer. Si se usa en el valor devuelto o con _deref, la función proporciona el búfer y la inicializa. De lo contrario, el autor de la llamada proporciona el búfer y la función la inicializa.

Direccionamiento indirecto	Descripción
_deref	Desreferenciar el parámetro para obtener el puntero del búfer. Este parámetro puede no ser NULL.
_deref_opt	Desreferenciar el parámetro para obtener el puntero del búfer. Este parámetro puede ser NULL.

Inicialización	Descripción
_Completo	La función inicializa todo el búfer. Use solo con búferes de salida.
_Parte	La función inicializa parte del búfer e indica explícitamente cuánto. Use solo con búferes de salida.

Búfer obligatorio o opcional	Descripción
_Optar	Este parámetro puede ser NULL.

En el ejemplo siguiente se muestran las anotaciones de la función GetModuleFileName . El parámetro hModule es un parámetro de entrada opcional. El parámetro lpFilename es un parámetro de salida; el parámetro nSize especifica su tamaño en caracteres y su longitud incluye el carácter de terminación NULL. El parámetro nSize es un parámetro de entrada.

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

A continuación se muestran las anotaciones definidas en Specstrings.h. Use la información de las tablas anteriores para interpretar su significado.

__bcount(size)
__bcount_opt(size)
__deref_bcount(size)
__deref_bcount_opt(size)
__deref_ecount(size)
__deref_ecount_opt(size)
__deref_in
__deref_in_bcount(size)
__deref_in_bcount_opt(size)
__deref_in_ecount(size)
__deref_in_ecount_opt(size)
__deref_in_opt
__deref_inout
__deref_inout_bcount(size)
__deref_inout_bcount_full(size)
__deref_inout_bcount_full_opt(size)
__deref_inout_bcount_opt(size)
__deref_inout_bcount_part(size,length)
__deref_inout_bcount_part_opt(size,length)
__deref_inout_ecount(size)
__deref_inout_ecount_full(size)
__deref_inout_ecount_full_opt(size)
__deref_inout_ecount_opt(size)
__deref_inout_ecount_part(size,length)
__deref_inout_ecount_part_opt(size,length)
__deref_inout_opt
__deref_opt_bcount(size)
__deref_opt_bcount_opt(size)
__deref_opt_ecount(size)
__deref_opt_ecount_opt(size)
__deref_opt_in
__deref_opt_in_bcount(size)
__deref_opt_in_bcount_opt(size)
__deref_opt_in_ecount(size)
__deref_opt_in_ecount_opt(size)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(size)
__deref_opt_inout_bcount_full(size)
__deref_opt_inout_bcount_full_opt(size)
__deref_opt_inout_bcount_opt(size)
__deref_opt_inout_bcount_part(size,length)
__deref_opt_inout_bcount_part_opt(size,length)
__deref_opt_inout_ecount(size)
__deref_opt_inout_ecount_full(size)
__deref_opt_inout_ecount_full_opt(size)
__deref_opt_inout_ecount_opt(size)
__deref_opt_inout_ecount_part(size,length)
__deref_opt_inout_ecount_part_opt(size,length)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(size)
__deref_opt_out_bcount_full(size)
__deref_opt_out_bcount_full_opt(size)
__deref_opt_out_bcount_opt(size)
__deref_opt_out_bcount_part(size,length)
__deref_opt_out_bcount_part_opt(size,length)
__deref_opt_out_ecount(size)
__deref_opt_out_ecount_full(size)
__deref_opt_out_ecount_full_opt(size)
__deref_opt_out_ecount_opt(size)
__deref_opt_out_ecount_part(size,length)
__deref_opt_out_ecount_part_opt(size,length)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(size)
__deref_out_bcount_full(size)
__deref_out_bcount_full_opt(size)
__deref_out_bcount_opt(size)
__deref_out_bcount_part(size,length)
__deref_out_bcount_part_opt(size,length)
__deref_out_ecount(size)
__deref_out_ecount_full(size)
__deref_out_ecount_full_opt(size)
__deref_out_ecount_opt(size)
__deref_out_ecount_part(size,length)
__deref_out_ecount_part_opt(size,length)
__deref_out_opt
__ecount(size)
__ecount_opt(size)
__En
__in_bcount(size)
__in_bcount_opt(size)
__in_ecount(size)
__in_ecount_opt(size)
__in_opt
__Inout
__inout_bcount(size)
__inout_bcount_full(size)
__inout_bcount_full_opt(size)
__inout_bcount_opt(size)
__inout_bcount_part(size,length)
__inout_bcount_part_opt(size,length)
__inout_ecount(size)
__inout_ecount_full(size)
__inout_ecount_full_opt(size)
__inout_ecount_opt(size)
__inout_ecount_part(size,length)
__inout_ecount_part_opt(size,length)
__inout_opt
__out
__out_bcount(size)
__out_bcount_full(size)
__out_bcount_full_opt(size)
__out_bcount_opt(size)
__out_bcount_part(size,length)
__out_bcount_part_opt(size,length)
__out_ecount(size)
__out_ecount_full(size)
__out_ecount_full_opt(size)
__out_ecount_opt(size)
__out_ecount_part(size,length)
__out_ecount_part_opt(size,length)
__out_opt

Anotaciones avanzadas

Las anotaciones avanzadas proporcionan información adicional sobre el parámetro o el valor devuelto. Cada parámetro o valor devuelto puede usar cero o una anotación avanzada.

Anotación	Descripción
__blocksOn(recurso)	Las funciones se bloquean en el recurso especificado.
__Callback	La función se puede usar como puntero de función.
__checkReturn	Los autores de llamadas deben comprobar el valor devuelto.
__format_string	El parámetro es una cadena que contiene marcadores de % de estilo printf.
__in_awcount(expr,size)	Si la expresión es true al salir, el tamaño del búfer de entrada se especifica en bytes. Si la expresión es false, el tamaño se especifica en elementos .
__nullnullterminated	Se puede acceder al búfer hasta e incluir la primera secuencia de dos caracteres o punteros NULL .
__nullterminated	Se puede tener acceso al búfer hasta e incluir el primer carácter nulo o puntero.
__out_awcount(expr,size)	Si la expresión es true al salir, el tamaño del búfer de salida se especifica en bytes. Si la expresión es false, el tamaño se especifica en elementos .
__Anular	Especifica el comportamiento de invalidación de estilo C#para los métodos virtuales.
__Reservados	El parámetro está reservado para uso futuro y debe ser cero o NULL.
__success(expr)	Si la expresión es true al salir, el autor de la llamada puede confiar en todas las garantías especificadas por otras anotaciones. Si la expresión es false, el autor de la llamada no puede confiar en las garantías. Esta anotación se agrega automáticamente a las funciones que devuelven un valor HRESULT .
__typefix(ctype)	Trate el parámetro como el tipo especificado en lugar de su tipo declarado.

En los ejemplos siguientes se muestran el búfer y las anotaciones avanzadas para las funciones DeleteTimerQueueTimer, FreeEnvironmentStrings y UnhandledExceptionFilter .

__checkReturn
BOOL
WINAPI
DeleteTimerQueueTimer(
    __in_opt HANDLE TimerQueue,
    __in     HANDLE Timer,
    __in_opt HANDLE CompletionEvent
    );

BOOL
WINAPI
FreeEnvironmentStrings(
    __in __nullnullterminated LPTCH
    );

__callback
LONG
WINAPI
UnhandledExceptionFilter(
    __in struct _EXCEPTION_POINTERS *ExceptionInfo
    );

Temas relacionados

Anotaciones SAL

Tutorial: Análisis de código de C/C++ para defectos