unique (attribut)
L’attribut [unique] spécifie un pointeur unique.
pointer_default(unique)
typedef [ unique [[ , type-attribute-list ]] ] type-specifier declarator-list;
typedef struct-or-union-declarator
{
[ unique [[ , field-attribute-list ]] ] type-specifier declarator-list;
...}
[ unique [[ , function-attribute-list ]] ] type-specifier ptr-decl function-name(
[[ [ parameter-attribute-list ] ]] type-specifier [[declarator]]
, ...);
[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
[ unique [[ , parameter-attribute-list ]] ] type-specifier [[declarator]]
, ...);
Paramètres
-
type-attribute-list
-
Spécifie un ou plusieurs attributs qui s’appliquent au type. Les attributs de type valides incluent [handle], [switch_type], [transmit_as]; l’attribut de pointeur [ref], [unique] ou [ptr] ; et les attributs d’utilisation [context_handle], [string] et [ignore]. Séparez plusieurs attributs par des virgules.
-
spécificateur de type
-
Spécifie un type de base, un struct, un union, un type d’énumération ou un identificateur de type. Une spécification de stockage facultative peut précéder le spécificateur de type.
-
déclarateur et déclarateur-list
-
Spécifie des déclarateurs C standard, tels que des identificateurs, des déclarateurs de pointeur et des déclarateurs de tableau. Pour plus d’informations, consultez Tableau et Sized-Pointer Attributs, tableaux et tableaux et pointeurs. La liste des déclarateurs se compose d’un ou plusieurs déclarateurs séparés par des virgules. L’identificateur de nom de paramètre dans le déclarateur de fonction est facultatif.
-
struct-or-union-declarator
-
field-attribute-list
-
Spécifie zéro ou plusieurs attributs de champ qui s’appliquent au paramètre de membre de structure, de membre d’union ou de fonction. Les attributs de champ valides sont [first_is],[last_is], [length_is], [max_is], [size_is]; attributs d’utilisation [string], [ignore] et [context_handle] ; l’attribut de pointeur [ref], [unique] ou [ptr] ; et l’attribut union [switch_type]. Séparez plusieurs attributs de champ par des virgules.
-
function-attribute-list
-
Spécifie zéro ou plusieurs attributs qui s’appliquent à la fonction. Les attributs de fonction valides sont [callback], [local]; l’attribut de pointeur [ref], [unique] ou [ptr] ; et les attributs d’utilisation [string], [ignore] et [context_handle].
-
ptr-decl
-
Spécifie au moins un déclarateur de pointeur auquel l’attribut [unique] s’applique. Un déclarateur de pointeur est identique au déclarateur de pointeur utilisé en C ; il est construit à partir de l’indicateur *, modificateurs tels que loin, et le qualificateur const.
-
nom de la fonction
-
Spécifie le nom de la procédure distante.
-
parameter-attribute-list
-
Se compose de zéro ou plusieurs attributs appropriés pour le type de paramètre spécifié. Les attributs de paramètre peuvent prendre les attributs directionnels [in] et [out]; attributs de champ [first_is],[last_is], [length_is], [max_is], [size_is] et [switch_type] ; l’attribut de pointeur [ref], unique ou ptr ; et les attributs d’utilisation [context_handle] et [string]. L’attribut d’utilisation [ignore] ne peut pas être utilisé comme attribut de paramètre. Séparez plusieurs attributs par des virgules.
Notes
Les attributs de pointeur peuvent être appliqués en tant qu’attribut de type ; en tant qu’attribut de champ qui s’applique à un membre de structure, à un membre d’union ou à un paramètre ; ou en tant qu’attribut de fonction qui s’applique au type de retour de fonction. L’attribut pointeur peut également apparaître avec le mot clé [pointer_default].
Un pointeur unique présente les caractéristiques suivantes :
- Peut avoir la valeur NULL.
- Peut changer lors d’un appel de NULL en valeur non NULL, non NULL enNULL ou d’une valeur non NULL à une autre.
- Peut allouer de la nouvelle mémoire sur le client. Lorsque le pointeur unique passe de NULL à non NULL, les données retournées par le serveur sont écrites dans un nouveau stockage.
- Peut utiliser la mémoire existante sur le client sans allouer de nouvelle mémoire. Lorsqu’un pointeur unique passe d’une valeur non NULL à une autre, le pointeur est supposé pointer vers un objet de données du même type. Les données retournées par le serveur sont écrites dans un stockage existant spécifié par la valeur du pointeur unique avant l’appel.
- Mémoire orpheline sur le client. La mémoire référencée par un pointeur unique non NULL peut ne jamais être libérée si le pointeur unique passe à NULL lors d’un appel et que le client n’a pas d’autre moyen de déreferencer le stockage.
- Ne provoque pas l’alias. Comme le stockage vers lequel pointe un pointeur de référence, le stockage vers lequel pointe un pointeur unique ne peut pas être atteint à partir d’un autre nom dans la fonction.
Les stubs appellent les fonctions de gestion de mémoire fournies par l’utilisateur midl_user_allocate et midl_user_free pour allouer et libérer de la mémoire requise pour les pointeurs uniques et leurs référentiels.
Les restrictions suivantes s’appliquent aux pointeurs uniques :
- L’attribut [unique] ne peut pas être appliqué aux paramètres de handle de liaison ( handle_t) et aux paramètres de handle de contexte.
- L’attribut [unique] ne peut pas être appliqué aux paramètres de pointeur de niveau supérieur [out]uniquement (paramètres qui ont uniquement l’attribut directionnel [out].
- Par défaut, les pointeurs de niveau supérieur dans les listes de paramètres sont des pointeurs [ref]. Cela est vrai même si l’interface spécifie pointer_default(unique). Les paramètres de niveau supérieur dans les listes de paramètres doivent être spécifiés avec l’attribut [unique] pour être un pointeur unique.
- Les pointeurs uniques ne peuvent pas être utilisés pour décrire la taille d’un tableau ou d’un bras d’union, car les pointeurs uniques peuvent avoir la valeur NULL. Cette restriction empêche l’erreur qui se produit si une valeur NULL est utilisée comme taille de tableau ou taille union-arm.
Exemples
pointer_default(unique)
typedef [unique, string] unsigned char * MY_STRING_TYPE;
[unique] char * MyFunction([in, out, unique] long * plNumber);
Voir aussi