Partager via

Annotations d’en-tête

  • Article

[Cette rubrique décrit les annotations prises en charge dans les en-têtes Windows via Windows 7. Si vous développez pour Windows 8, vous devez utiliser les annotations décrites dans annotations SAL.]

Les annotations d’en-tête décrivent comment une fonction utilise ses paramètres et sa valeur de retour. Ces annotations ont été ajoutées à de nombreux fichiers d’en-tête Windows pour vous aider à vous assurer que vous appelez correctement l’API Windows. Si vous activez l’analyse du code, disponible à partir de Visual Studio 2005, le compilateur génère des avertissements de niveau 6000 si vous n’appelez pas ces fonctions conformément à l’utilisation décrite par les annotations. Vous pouvez également ajouter ces annotations dans votre propre code pour vous assurer qu’elle est appelée correctement. Pour activer l’analyse du code dans Visual Studio, consultez la documentation relative à votre version de Visual Studio.

Ces annotations sont définies dans Specstrings.h. Elles sont basées sur des primitives qui font partie du langage d’annotation standard (SAL) et implémentées à l’aide de _declspec("SAL_*").

Il existe deux classes d’annotations : annotations de mémoire tampon et annotations avancées.

Annotations de mémoire tampon

Les annotations de mémoire tampon décrivent comment les fonctions utilisent leurs pointeurs et peuvent être utilisées pour détecter les dépassements de mémoire tampon. Chaque paramètre peut utiliser zéro ou une annotation de mémoire tampon. Une annotation de mémoire tampon est construite avec un trait de soulignement de début et les composants décrits dans les sections suivantes.

Taille de la mémoire tampon Description
( taille)
 Spécifie la taille totale de la mémoire tampon. Utiliser avec _bcount et _ecount ; ne pas utiliser avec _part. Cette valeur est l’espace accessible ; il peut être inférieur à l’espace alloué.
(taille,longueur)
 Spécifie la taille totale et la longueur initialisée de la mémoire tampon. Utiliser avec _bcount_part et _ecount_part. La taille totale peut être inférieure à l’espace alloué.
Unités de taille de mémoire tampon Description
_bcount
 La taille de la mémoire tampon est en octets.
_ecount
 La taille de la mémoire tampon se trouve dans les éléments.
Direction Description
_in
 La fonction lit à partir de la mémoire tampon. L’appelant fournit la mémoire tampon et l’initialise.
_inout
 La fonction lit et écrit dans la mémoire tampon. L’appelant fournit la mémoire tampon et l’initialise. Si elle est utilisée avec _deref, la mémoire tampon peut être réaffectée par la fonction.
_out
 La fonction écrit dans la mémoire tampon. Si elle est utilisée sur la valeur de retour ou avec _deref, la fonction fournit la mémoire tampon et l’initialise. Sinon, l’appelant fournit la mémoire tampon et la fonction l’initialise.
Indirection Description
_deref
 Déréférencez le paramètre pour obtenir le pointeur de la mémoire tampon. Ce paramètre ne peut pas être NULL.
_deref_opt
 Déréférencez le paramètre pour obtenir le pointeur de la mémoire tampon. Ce paramètre peut être NULL.
Initialisation Description
_full
 La fonction initialise l’intégralité de la mémoire tampon. Utilisez uniquement les mémoires tampons de sortie.
_part
 La fonction initialise une partie de la mémoire tampon et indique explicitement la quantité. Utilisez uniquement les mémoires tampons de sortie.
Mémoire tampon requise ou facultative Description
_opt
 Ce paramètre peut être NULL.

L’exemple suivant montre les annotations de la fonction GetModuleFileName. Le paramètre hModule est un paramètre d’entrée facultatif. Le paramètre lpFilename est un paramètre de sortie ; sa taille en caractères est spécifiée par le paramètre nSize et sa longueur inclut le caractère null-terminateting. Le paramètre nSize est un paramètre d’entrée.

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

Voici les annotations définies dans Specstrings.h. Utilisez les informations contenues dans les tableaux ci-dessus pour interpréter leur signification.

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

Annotations avancées

Les annotations avancées fournissent des informations supplémentaires sur le paramètre ou la valeur de retour. Chaque paramètre ou valeur de retour peut utiliser zéro ou une annotation avancée.

Annotation Description
__blocksOn(ressource)
 Les fonctions se bloquent sur la ressource spécifiée.
__callback
 La fonction peut être utilisée comme pointeur de fonction.
__checkReturn
 Les appelants doivent vérifier la valeur de retour.
__format_string
 Le paramètre est une chaîne qui contient des marqueurs de style printf %.
__in_awcount(expr,taille)
 Si l’expression est vraie à la sortie, la taille de la mémoire tampon d’entrée est spécifiée en octets. Si l’expression est false, la taille est spécifiée dans les éléments.
__nullnullterminated
 La mémoire tampon est accessible jusqu’à la première séquence de deux caractères ou pointeurs null.
__nullterminated
 La mémoire tampon est accessible jusqu’à la première caractère ou pointeur null.
__out_awcount(expr,taille)
 Si l’expression est vraie à la sortie, la taille de la mémoire tampon de sortie est spécifiée en octets. Si l’expression est false, la taille est spécifiée dans les éléments.
__override
 Spécifie le comportement de remplacement du style C#pour les méthodes virtuelles.
__reserved
 Le paramètre est réservé pour une utilisation ultérieure et doit être égal à zéro ou NULL.
__success(expr)
 Si l’expression est vraie à la sortie, l’appelant peut compter sur toutes les garanties spécifiées par d’autres annotations. Si l’expression est false, l’appelant ne peut pas compter sur les garanties. Cette annotation est automatiquement ajoutée aux fonctions qui retournent une valeur HRESULT.
__typefix(ctype)
 Traitez le paramètre comme le type spécifié plutôt que son type déclaré.

Les exemples suivants montrent la mémoire tampon et les annotations avancées pour les fonctionsDeleteTimerQueueTimer, FreeEnvironmentStringset Fonctions 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
    );

annotations SAL

procédure pas à pas : analyse du code C/C++ pour les défauts