Partager via

Annotation de paramètres de fonction et valeurs de retour

  • Article

Cet article décrit les utilisations classiques des annotations pour les paramètre-scalaires de fonction simple, et les pointeurs vers des structures et des classes et la plupart des types de mémoires tampons. Cet article indique également les modèles d'utilisation communs pour les annotations.Pour les annotations supplémentaires qui sont liées aux fonctions, consultez l' Annotation du comportement d'une fonction

Paramètres des pointeurs

Pour les annotations dans le tableau suivant, lorsqu'un paramètre de type pointeur est annoté, l'analyseur signale une erreur si le pointeur est null. Cela s'applique aux pointeurs et tout élément de données vers lequel il pointe.

Annotation

Description

_In_

Annote les paramètres d'entrée qui sont scalaires, les structures, les pointeurs vers les structures et similaire. Explicitement, cela peut être utilisé sur les amplitudes scalaires simples. Le paramètre doit être valide à l'état préalable et ne sera pas modifié.

_Out_

L'annotation de paramètres qui sont des scalaires, des structures, des pointeurs vers des structures et similaires. N'appliquez pas cette opération à un objet qui ne peut pas retourner une valeur, par exemple, une variable scalaire qui est passée par valeur. Le paramètre ne doit pas être valide à l'état préalable, mais doit être valide dans l'état d'après.

_Inout_

Annote un paramètre qui sera modifié par la fonction. Il suppose qu'il doit être valide à l'état préalable et après le rapport, mais a différentes valeurs avant et après l'appel.Doit s'appliquer à une valeur modifiable.

_In_z_

Un pointeur vers une chaîne terminée par le caractère NULL qui est utilisée comme entrée. La chaîne doit être valide à l'état préalable. Les variantes de PSTR, qui possèdent déjà des annotations correctes, sont préférées.

_Inout_z_

Un pointeur vers un tableau de caractères se terminant par null qui sera modifié. Il doit être valide avant et après le supposé appel, mais la valeur change. La marque de fin null peut être déplacée, mais uniquement les éléments jusqu'à la marque de fin null d'origine sont accessibles.

_In_reads_(s)

_In_reads_bytes_(s)

Un pointeur vers un tableau, qui est indiquée par la fonction. Le tableau est d'une taille de s éléments, qui doivent être valides.

Le variant _bytes_ donne la taille en octets au lieu des éléments.Utilisez cela uniquement lorsque la taille ne peut pas être exprimés en éléments. Par exemple, la chaîne de char voudra utiliser la variante _bytes_ uniquement si une fonction similaire qui utilise wchar_t le désire.

_In_reads_z_(s)

Un pointeur vers un tableau qui se termine par null et qui a une taille connue.Les éléments jusqu'à la marque de fin null, ou jusqu'à s s'il n'existe aucune marque de fin null, doivent être valides à l'état préalable. Si la taille en octets est connues, redimensionnez s par la taille de l'élément.

_In_reads_or_z_(s)

Un pointeur vers un tableau qui se termine par NULL ou a une taille connue, voire les deux.Les éléments jusqu'à la marque de fin null, ou jusqu'à s s'il n'existe aucune marque de fin null, doivent être valides à l'état préalable. Si la taille en octets est connues, redimensionnez s par la taille de l'élément. (Utilisé pour la famille strn.)

_Out_writes_(s)

_Out_writes_bytes_(s)

Un pointeur vers un tableau d'éléments s (resp. octets) qui seront écrits par la fonction. Les éléments de tableau ne doivent pas être valides à l'état préalable, et le nombre d'éléments valides de l'état d'après n'est pas spécifié. S'il existe des annotations sur le type paramètre, elles sont appliquées à l'état d'après.Par exemple, prenons le code suivant.

typedef _Null_terminated_ wchar_t *PWSTR;
void MyStringCopy(_Out_writes_ (size) PWSTR p1,
   _In_ size_t size,
   _In_ PWSTR p2);

Dans cet exemple, l'appelant est une mémoire tampon d'éléments size pour p1. MyStringCopy rend certains de ces éléments valides.Plus important encore, l'annotation _Null_terminated_ sur PWSTR signifie que p1 se termine par null dans l'état d'après. De cette manière, le nombre d'éléments valides est encore bien défini, mais un nombre spécifique de l'élément n'est pas obligatoire.

Le variant _bytes_ donne la taille en octets au lieu des éléments.Utilisez cela uniquement lorsque la taille ne peut pas être exprimés en éléments. Par exemple, la chaîne de char voudra utiliser la variante _bytes_ uniquement si une fonction similaire qui utilise wchar_t le désire.

_Out_writes_z_(s)

Un pointer vers un tableau d'éléments s. Les éléments ne doivent pas être valides à l'état préalable. Dans l'état postérieur, les éléments jusqu'à la marque de fin NULL, qui doit être présente, doivent être valides. Si la taille en octets est connues, redimensionnez s par la taille de l'élément.

_Inout_updates_(s)

_Inout_updates_bytes_(s)

Un pointeur vers un tableau, qui est à la fois indiquée et écrite dans la fonction. Il s'agit des éléments de taille s, et valide au préalable état et après le rapport.

Le variant _bytes_ donne la taille en octets au lieu des éléments.Utilisez cela uniquement lorsque la taille ne peut pas être exprimés en éléments. Par exemple, la chaîne de char voudra utiliser la variante _bytes_ uniquement si une fonction similaire qui utilise wchar_t le désire.

_Inout_updates_z_(s)

Un pointeur vers un tableau qui se termine par null et qui a une taille connue.Les éléments jusqu'à la marque de fin NULL, qui doit être présente, doivent être valides à l'état préalable et postérieur. La valeur au niveau du rapport est présumée être différente de la valeur de l'état préalable ; cela inclut l'emplacement de la marque de fin null.Si la taille en octets est connues, redimensionnez s par la taille de l'élément.

_Out_writes_to_(s,c)

_Out_writes_bytes_to_(s,c)

_Out_writes_all_(s)

_Out_writes_bytes_all_(s)

Un pointer vers un tableau d'éléments s. Les éléments ne doivent pas être valides à l'état préalable. Dans le rapport, les éléments vont jusqu'au c- élément qui doit être valide. Si la taille est connue en octets, redimensionnez s et c par la taille d'élément ou utilisez le variant _bytes_, qui est définie comme suit :

   _Out_writes_to_(_Old_(s), _Old_(s))
   _Out_writes_bytes_to_(_Old_(s), _Old_(s))

En d'autres termes, chaque élément existant dans la mémoire tampon jusqu'à s dans l'état préalable est valide au niveau du rapport. Par exemple :

void *memcpy(_Out_writes_bytes_all_(s) char *p1,
   _In_reads_bytes_(s) char *p2,
   _In_ int s);
void * wordcpy(_Out_writes_all_(s) DWORD *p1, 
   _In_reads_(s) DWORD *p2,
   _In_ int s);

_Inout_updates_to_(s,c)

_Inout_updates_bytes_to_(s,c)

Un pointeur sur un tableau, qui est à la fois lu et écrit par la fonction. Il s'agit des éléments de taille s, qui doivent être valides au préalable, et les éléments c doivent être valides après.

Le variant _bytes_ donne la taille en octets au lieu des éléments.Utilisez cela uniquement lorsque la taille ne peut pas être exprimés en éléments. Par exemple, la chaîne de char voudra utiliser la variante _bytes_ uniquement si une fonction similaire qui utilise wchar_t le désire.

_Inout_updates_all_(s)

_Inout_updates_bytes_all_(s)

Un pointeur vers un tableau, qui est à la fois lu et écrit par la fonction de la taille des éléments s.Défini comme équivalent à :

   _Inout_updates_to_(_Old_(s), _Old_(s))
   _Inout_updates_bytes_to_(_Old_(s), _Old_(s))

En d'autres termes, chaque élément qui existe dans la mémoire tampon jusqu'à s dans l'état préalable est valide dans l'état préalable et dans l'état d'après.

Le variant _bytes_ donne la taille en octets au lieu des éléments.Utilisez cela uniquement lorsque la taille ne peut pas être exprimés en éléments. Par exemple, la chaîne de char voudra utiliser la variante _bytes_ uniquement si une fonction similaire qui utilise wchar_t le désire.

_In_reads_to_ptr_(p)

Un pointeur vers un tableau pour laquelle l'expression p – _Curr_ (autrement dit, p moins _Curr_) est défini par la norme de langue. Les éléments avant p doivent être valides à l'état préalable.

_In_reads_to_ptr_z_(p)

Un pointeur vers un tableau se terminant par null pour laquelle l'expression p – _Curr_ (autrement dit, p moins _Curr_) est défini par la norme de langage standard. Les éléments avant p doivent être valides à l'état préalable.

_Out_writes_to_ptr_(p)

Un pointeur vers un tableau pour laquelle l'expression p – _Curr_ (autrement dit, p moins _Curr_) est défini par la norme de langue. Les éléments avant p ne doivent pas être valides dans l'état préalable et doivent être valides après dans le rapport.

_Out_writes_to_ptr_z_(p)

Un pointeur vers un tableau se terminant par null pour laquelle l'expression p – _Curr_ (autrement dit, p moins _Curr_) est défini par la norme de langage standard. Les éléments avant p ne doivent pas être valides dans l'état préalable et doivent être valides après dans le rapport.

Paramètres facultatifs de pointeur

Lorsqu'une annotation de paramètre de type inclut _opt_, elle indique que le paramètre peut être null.Sinon, l'annotation exécute les mêmes que la version qui n'inclut pas _opt_.Voici une liste des variantes _opt_ des annotations de paramètre de pointeur :

_In_opt_

_Out_opt_

_Inout_opt_

_In_opt_z_

_Inout_opt_z_

_In_reads_opt_

_In_reads_bytes_opt_

_In_reads_opt_z_

_Out_writes_opt_

_Out_writes_opt_z_

_Inout_updates_opt_

_Inout_updates_bytes_opt_

_Inout_updates_opt_z_

_Out_writes_to_opt_

_Out_writes_bytes_to_opt_

_Out_writes_all_opt_

_Out_writes_bytes_all_opt_

_Inout_updates_to_opt_

_Inout_updates_bytes_to_opt_

_Inout_updates_all_opt_

_Inout_updates_bytes_all_opt_

_In_reads_to_ptr_opt_

_In_reads_to_ptr_opt_z_

_Out_writes_to_ptr_opt_

_Out_writes_to_ptr_opt_z_

Paramètres de pointeurs de type de sortie

Les paramètres de type de sortie requièrent la notation spéciale pour lever l'ambiguïté du null-ness sur le paramètre et l'emplacement pointé.

Annotation

Description

_Outptr_

Le paramètre ne peut pas être null, et dans le rapport l'emplacement du pointeur ne peut pas être null et doit être valide.

_Outptr_opt_

Le paramètre peut être NULL, mais dans le rapport, l'emplacement du pointeur ne peut pas être NULL et doit être valide.

_Outptr_result_maybenull_

Le paramètre ne peut pas être null, et dans le rapport l'emplacement du pointeur peut être null.

_Outptr_opt_result_maybenull_

Le paramètre peut être NULL, et dans le rapport l'emplacement du pointeur peut être null.

Dans le tableau suivant, les sous-chaînes supplémentaires sont insérées dans le nom de l'annotation pour davantage qualifier la signification de l'annotation. Les différentes sous-chaînes sont _z, _COM_, _buffer_, _bytebuffer_, et _to_.

Important

Si l'interface que vous annotez est COM, utilisez la forme COM de ces annotations.N'utilisez pas les annotations de type COM avec un autre type interface.

Annotation

Description

_Outptr_result_z_

_Outptr_opt_result_z_

_Outptr_result_maybenull_z_

_Ouptr_opt_result_maybenull_z_

Le pointeur a retourné l'annotation d' _Null_terminated_.

_COM_Outptr_

_COM_Outptr_opt_

_COM_Outptr_result_maybenull_

_COM_Outptr_opt_result_maybenull_

Le pointeur a retourné la sémantique de COM, et distribue donc une condition _On_failure_ indiquant que le pointeur retourné est null.

_Outptr_result_buffer_(s)

_Outptr_result_bytebuffer_(s)

_Outptr_opt_result_buffer_(s)

_Outptr_opt_result_bytebuffer_(s)

Les pointeurs retournés pointent vers une mémoire tampon valide d'éléments ou d'octets d'une taille s.

_Outptr_result_buffer_to_(s, c)

_Outptr_result_bytebuffer_to_(s, c)

_Outptr_opt_result_buffer_to_(s,c)

_Outptr_opt_result_bytebuffer_to_(s,c)

Les pointeurs retournés pointent vers une mémoire tampon d'éléments ou d'octets d'une taille s, dont le premier c est valide.

Certaines conventions d'interface présument que des paramètres de sortie sont annulées en cas de échec. À l'exception du code COM, les formes dans le tableau suivant sont préférées. Pour le code COM, utilisez les formulaires correspondants COM répertoriées dans la section précédente.

Annotation

Description

_Result_nullonfailure_

Modifie d'autres annotations.Le résultat a la valeur null si la fonction échoue.

_Result_zeroonfailure_

Modifie d'autres annotations.Le résultat est fixé à zéro si la fonction échoue.

_Outptr_result_nullonfailure_

Les pointeurs retournés pointent vers une mémoire tampon valide si la fonction réussit, ou NULL si la fonction échoue.Cette annotation est pour un paramètre non facultative.

_Outptr_opt_result_nullonfailure_

Les pointeurs retournés pointent vers une mémoire tampon valide si la fonction réussit, ou NULL si la fonction échoue.Cette annotation est pour les paramètres optionnels.

_Outref_result_nullonfailure_

Les pointeurs retournés pointent vers une mémoire tampon valide si la fonction réussit, ou NULL si la fonction échoue.Cette annotation est pour un paramètre de référence.

Paramètres de référence de sortie

Une utilisation courante du paramètre de référence concerne les paramètres de sortie. Pour les paramètres de référence de sortie simple, par exemple, int&—_Out_ fournit une sémantique correcte. Toutefois, lorsque la valeur de sortie est un pointeur- pour l'exemple int *&— les annotations équivalentes de pointeur comme _Outptr_ int ** ne fournissent pas la sémantique correcte. Pour exprimer de façon concise la sémantique des paramètres de référence de sortie pour les types pointeur, utilisez ces annotations composites :

Annotation

Description

_Outref_

Le résultat doit être valide dans le l'état d'après et ne peut pas être null.

_Outref_result_maybenull_

Le résultat doit être valide dans le rapport, mais peut être null dans le rapport.

_Outref_result_buffer_(s)

Le résultat doit être valide dans le l'état d'après et ne peut pas être null.Pointe vers une mémoire tampon valide d'une taille d'éléments s.

_Outref_result_bytebuffer_(s)

Le résultat doit être valide dans le l'état d'après et ne peut pas être null.Pointe vers une mémoire tampon d'une taille de s octets.

_Outref_result_buffer_to_(s, c)

Le résultat doit être valide dans le l'état d'après et ne peut pas être null.Pointe vers une mémoire tampon d'éléments s, dont le premier c est valide.

_Outref_result_bytebuffer_to_(s, c)

Le résultat doit être valide dans le l'état d'après et ne peut pas être null.Pointe vers une mémoire tampon d'octets s, dont le premier c est valide.

_Outref_result_buffer_all_(s)

Le résultat doit être valide dans le l'état d'après et ne peut pas être null.Pointe vers une mémoire tampon valide d'une taille de s éléments valides.

_Outref_result_bytebuffer_all_(s)

Le résultat doit être valide dans le l'état d'après et ne peut pas être null.Pointe vers une mémoire tampon valide d'octets d'éléments valides s.

_Outref_result_buffer_maybenull_(s)

Le résultat doit être valide dans le rapport, mais peut être null dans le rapport.Pointe vers une mémoire tampon valide d'une taille d'éléments s.

_Outref_result_bytebuffer_maybenull_(s)

Le résultat doit être valide dans le rapport, mais peut être null dans le rapport.Pointe vers une mémoire tampon d'une taille de s octets.

_Outref_result_buffer_to_maybenull_(s, c)

Le résultat doit être valide dans le rapport, mais peut être null dans le rapport.Pointe vers une mémoire tampon d'éléments s, dont le premier c est valide.

_Outref_result_bytebuffer_to_maybenull_(s,c)

Le résultat doit être valide dans le rapport, mais peut être NULL dans le rapport.Pointe vers une mémoire tampon d'octets s, dont le premier c est valide.

_Outref_result_buffer_all_maybenull_(s)

Le résultat doit être valide dans le rapport, mais peut être NULL dans le rapport.Pointe vers une mémoire tampon valide d'une taille de s éléments valides.

_Outref_result_bytebuffer_all_maybenull_(s)

Le résultat doit être valide dans le rapport, mais peut être NULL dans le rapport.Pointe vers une mémoire tampon valide d'octets d'éléments valides s.

Valeurs de retour

La valeur de retour d'une fonction ressemble à un paramètre _Out_ mais est à un niveau différent de déréférence, et vous ne devez pas considérer le concept de pointeur vers le résultat. Pour les annotations suivantes, la valeur de retour est la variable scalaire annotée d'un objet, un pointeur vers une structure, ou un pointeur vers une mémoire tampon.Ces annotations ont la même sémantique que l'annotation correspondante _Out_.

_Ret_z_

_Ret_writes_(s)

_Ret_writes_bytes_(s)

_Ret_writes_z_(s)

_Ret_writes_to_(s,c)

_Ret_writes_maybenull_(s)

_Ret_writes_to_maybenull_(s)

_Ret_writes_maybenull_z_(s)

_Ret_maybenull_

_Ret_maybenull_z_

_Ret_null_

_Ret_notnull_

_Ret_writes_bytes_to_

_Ret_writes_bytes_maybenull_

_Ret_writes_bytes_to_maybenull_

D'autres annotations courantes

Annotation

Description

_In_range_(low, hi)

_Out_range_(low, hi)

_Ret_range_(low, hi)

_Deref_in_range_(low, hi)

_Deref_out_range_(low, hi)

_Deref_inout_range_(low, hi)

_Field_range_(low, hi)

Le paramètre, le champ, ou le résultat est dans la plage (inclusifs) de low à hi. Équivalent à _Satisfies_(_Curr_ >= low && _Curr_ <= hi) qui est appliqué à l'objet annoté avec les conditions préalable et de rapport appropriés.

Important

Bien que le nom contienne « in » et « out », la sémantique _In_ et _Out_ fait que not s'appliquent à ces annotations.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

La valeur est annotée exactement expr. Equivalent à _Satisfies_(_Curr_ == expr) qui s'applique à l'objet annoté avec les conditions préalable et de rapport appropriés.

_Struct_size_bytes_(size)

S'applique au struct ou à la déclaration de classe. Indique qu'un objet valide de ce type peut être plus grand que le type déclaré, avec le nombre d'octets donné par size. Par exemple :

typedef _Struct_size_bytes_(nSize)
struct MyStruct {
   size_t nSize;
   ...
};

La taille de mémoire tampon en octets d'un paramètre pM de type MyStruct * est ensuite prise pour être :

   min(pM->nSize, sizeof(MyStruct))

Ressources connexes

Blog de l'équipe d'analyse du code

Voir aussi

Référence

Annotation du comportement d'une fonction

Structs et classes d'annotation

Annotation du comportement de verrouillage

Spécification du moment où une annotation est applicable et dans quel cas

Fonctions intrinsèques

Meilleures pratiques et exemples (SAL)

Concepts

Présentation de SAL

Autres ressources

Utilisation d'annotations SAL pour réduire les défauts du code C/C++