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
);