Annotations d’en-tête
[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 à la plupart des fichiers d’en-tête Windows pour vous assurer que vous appelez correctement l’API Windows. Si vous activez l’analyse du code, qui est disponible à partir de Visual Studio 2005, le compilateur génère des avertissements de niveau 6 000 si vous n’appelez pas ces fonctions selon l’utilisation décrite par le biais des 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. Ils sont basés sur des primitives qui font partie du langage d’annotation standard (SAL) et implémentés à 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. 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. Utilisez 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 est en é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 à partir de 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. |
| Adressage indirect | Description |
|---|---|
|
_deref |
Déréférencer le paramètre pour obtenir le pointeur de mémoire tampon. Ce paramètre n’est peut-être pas NULL. |
|
_deref_opt |
Déréférencer le paramètre pour obtenir le pointeur de mémoire tampon. Ce paramètre peut être NULL. |
| Initialisation | Description |
|---|---|
|
_Plein |
La fonction initialise la mémoire tampon entière. Utilisez uniquement avec des mémoires tampons de sortie. |
|
_Partie |
La fonction initialise une partie de la mémoire tampon et indique explicitement la quantité. Utilisez uniquement avec des mémoires tampons de sortie. |
| Mémoire tampon obligatoire ou facultative | Description |
|---|---|
|
_Opter |
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 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(size,length)
__deref_inout_bcount_part_opt(size,length)
__deref_inout_ecount(taille)
__deref_inout_ecount_full(taille)
__deref_inout_ecount_full_opt(taille)
__deref_inout_ecount_opt(taille)
__deref_inout_ecount_part(size,length)
__deref_inout_ecount_part_opt(size,length)
__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(size,length)
__deref_opt_inout_bcount_part_opt(size,length)
__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(size,length)
__deref_opt_inout_ecount_part_opt(size,length)
__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(size,length)
__deref_opt_out_bcount_part_opt(size,length)
__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(size,length)
__deref_opt_out_ecount_part_opt(size,length)
__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(size,length)
__deref_out_bcount_part_opt(size,length)
__deref_out_ecount(taille)
__deref_out_ecount_full(taille)
__deref_out_ecount_full_opt(taille)
__deref_out_ecount_opt(taille)
__deref_out_ecount_part(size,length)
__deref_out_ecount_part_opt(size,length)
__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)
__inout_bcount_opt(taille)
__inout_bcount_part(size,length)
__inout_bcount_part_opt(size,length)
__inout_ecount(taille)
__inout_ecount_full(taille)
__inout_ecount_full_opt(taille)
__inout_ecount_opt(taille)
__inout_ecount_part(size,length)
__inout_ecount_part_opt(size,length)
__inout_opt
__out
__out_bcount(taille)
__out_bcount_full(taille)
__out_bcount_full_opt(taille)
__out_bcount_opt(taille)
__out_bcount_part(size,length)
__out_bcount_part_opt(size,length)
__out_ecount(taille)
__out_ecount_full(taille)
__out_ecount_full_opt(taille)
__out_ecount_opt(taille)
__out_ecount_part(size,length)
__out_ecount_part_opt(size,length)
__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 blocs de fonctions sur la ressource spécifiée. |
|
__Rappel |
La fonction peut être utilisée comme pointeur de fonction. |
|
__checkReturn |
Les appelants doivent case activée la valeur de retour. |
|
__format_string |
Le paramètre est une chaîne qui contient des marqueurs de style printf % . |
|
__in_awcount(expr,size) |
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 est false, la taille est spécifiée dans les éléments. |
|
__nullnullterminated |
La mémoire tampon est accessible jusqu’à et y compris la première séquence de deux caractères null ou pointeurs. |
|
__nullterminated |
La mémoire tampon est accessible jusqu’à et y compris le premier caractère null ou pointeur. |
|
__out_awcount(expr,size) |
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 est false, la taille est spécifiée dans les éléments. |
|
__Substituer |
Spécifie le comportement de remplacement de style C#pour les méthodes virtuelles. |
|
__Réservés au |
Le paramètre est réservé à une utilisation ultérieure et doit être égal à zéro ou NULL. |
|
__success(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 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 comme son type déclaré. |
Les exemples suivants montrent la mémoire tampon et les annotations avancées pour les fonctions DeleteTimerQueueTimer, FreeEnvironmentStrings et 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
);