Annotations d’en-tête

[cette rubrique décrit les annotations prises en charge dans les en-têtes de Windows via Windows 7. si vous développez pour Windows 8, vous devez utiliser les annotations décrites dans les 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 de Windows pour vous aider à vous assurer que vous appelez correctement l’API Windows. si vous activez l’analyse du code, qui est disponible à partir de la Visual Studio 2005, le compilateur produira des avertissements de niveau 6000 si vous n’appelez pas ces fonctions selon l’utilisation décrite par les annotations. Vous pouvez également ajouter ces annotations dans votre propre code pour vous assurer qu’elles sont appelées correctement. pour activer l’analyse du code dans Visual Studio, consultez la documentation de votre version de Visual Studio.

Ces annotations sont définies dans Specstrings. h. Ils reposent sur les primitives qui font partie du langage de l’annotation standard (SAL) et implémentent à l’aide de _declspec("SAL_*") .

Il existe deux classes d’annotations : les annotations de mémoire tampon et les 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.

buffer_size Description
(taille)
Spécifie la taille totale de la mémoire tampon. Utilisez avec _ bcount et _ ecount ; n’utilisez pas with _ 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. Utilisez avec la partie _ bcount _ et _ ecount _ . La taille totale peut être inférieure à l’espace alloué.
Unités de taille de la mémoire tampon Description
_bcount
La taille de la mémoire tampon est en octets.
_ecount
La taille de la mémoire tampon est dans les éléments.
Sens Description
_dans
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. S’il est utilisé avec _ Deref, la mémoire tampon peut être réallouée par la fonction.

La fonction écrit dans la mémoire tampon. S’il est utilisé sur la valeur de retour ou avec _ Deref, la fonction fournit la mémoire tampon et l’initialise. Dans le cas contraire, l’appelant fournit la mémoire tampon et la fonction l’initialise.
Adressage indirect 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.
_option _ Deref
Déréférencez le paramètre pour obtenir le pointeur de la mémoire tampon. Ce paramètre peut être NULL.
Initialisation Description
_sauvegarde
La fonction initialise la mémoire tampon entière. À utiliser uniquement avec les mémoires tampons de sortie.
_étape
La fonction Initialise une partie de la mémoire tampon et indique explicitement le volume. À utiliser uniquement avec les mémoires tampons de sortie.
Mémoire tampon obligatoire ou facultative Description
_possibilité
Ce paramètre peut être NULL.

L’exemple suivant montre les annotations pour 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 comprend le caractère de fin null. 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 des 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)
__deref_in_opt
__deref_inout
__deref_inout_bcount (taille)
__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)
__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)
__in
__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)
__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
__out
__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.
__rappel
La fonction peut être utilisée comme pointeur de fonction.
__checkReturn
Les appelants doivent vérifier la valeur de retour.
__chaîne de format _
Le paramètre est une chaîne qui contient des marqueurs% de style printf.
__dans _ awcount (expr,taille)
Si l’expression a la valeur true à la sortie, la taille de la mémoire tampon d’entrée est spécifiée en octets. Si l’expression a la valeur false, la taille est spécifiée dans les éléments.
__nullnullterminated
La mémoire tampon peut être accessible jusqu’à la première séquence de deux caractères ou pointeurs null , y compris.
__NullTerminated
La mémoire tampon peut être accessible jusqu’à et y compris le premier caractère ou pointeur null .
__out _ awcount (expr,taille)
Si l’expression a la valeur true à la sortie, la taille de la mémoire tampon de sortie est spécifiée en octets. Si l’expression a la valeur false, la taille est spécifiée dans les éléments.
__remplacer
Spécifie le comportement de substitution de style C# pour les méthodes virtuelles.
__réservé
Le paramètre est réservé pour une utilisation ultérieure et doit être égal à zéro ou null.
__opération réussie (expr)
Si l’expression a la valeur true à la sortie, l’appelant peut s’appuyer sur toutes les garanties spécifiées par d’autres annotations. Si l’expression a la valeur 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)
Traite le paramètre en tant que type spécifié plutôt qu’en tant que type déclaré.

Les exemples suivants illustrent la mémoire tampon et les annotations avancées pour les fonctions DeleteTimerQueueTimer, FreeEnvironmentStringset 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 rechercher les erreurs