ptr (attribut)

Article
06/13/2023

L’attribut [ptr] désigne un pointeur comme pointeur complet.

pointer_default(ptr)

typedef [ ptr [ , type-attribute-list ] ] type-specifier declarator-list; 

typedef [ struct | union ]
{
    [ ptr [ , field-attribute-list ] ] type-specifier declarator-list;
    ...
}

[ ptr [ , function-attribute-list ] ] type-specifier ptr-decl function-name(
    [ [ parameter-attribute-list ] ] type-specifier [standard-declarator]
    , ...);

[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
    [ ptr [[ , parameter-attribute-list ]] ] type-specifier [[standard-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 pointeur [ref], [unique ou [ptr]; et les attributs d’utilisation [context_handle], [string] et [ignore]. Séparez plusieurs attributs par des virgules.
type-specifier: Spécifie un type de base, un struct, une union ou 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.
standard-declarator: Spécifie un déclarateur C standard, tel qu’un identificateur, un déclarateur de pointeur ou un déclarateur de tableau. Pour plus d’informations, consultez Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers.
declarator-list: Spécifie les déclarateurs C standard, tels que les identificateurs, les déclarateurs de pointeurs et les déclarateurs de tableau. Pour plus d’informations, consultez Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. Le declarator-list se compose d’un ou plusieurs déclarateurs séparés par des virgules. L’identificateur nom-paramètre dans le déclarateur de fonction est facultatif.
field-attribute-list: Spécifie zéro ou plusieurs attributs de champ qui s’appliquent au paramètre de fonction ou membre de structure ou d’union. Les attributs de champ valides incluent [first_is],[last_is], [length_is], [max_is], [size_is]; les attributs d’utilisation [string], [ignore] et [context_handle] ; l’attribut 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 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 [ptr] s’applique. Un déclarateur de pointeur est identique au déclarateur de pointeur utilisé dans C ; il est construit à partir du désignateur *, des modificateurs tels que far, et du qualificateur const.
function-name: 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 en entrée et en sortie ; les 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 chaîne. L’attribut d’utilisation ignore ne peut pas être utilisé comme attribut de paramètre. Séparez plusieurs attributs par des virgules.

Notes

Le pointeur complet désigné par l’attribut [ptr] s’approche de toutes les fonctionnalités du pointeur en langage C. Le pointeur complet peut avoir la valeur NULL et peut changer pendant l’appel de NULL en non-NULL. Le stockage pointé par des pointeurs complets est accessible par d’autres noms dans l’application prenant en charge les cycles et les alias. Cette fonctionnalité nécessite davantage de surcharge lors d’un appel de procédure distante pour identifier les données référencées par le pointeur, déterminer si la valeur est NULL et découvrir si deux pointeurs pointent vers les mêmes données.

Utilisez des pointeurs complets pour :

Valeurs de retour distantes.
Pointeurs doubles lorsque la taille d’un paramètre de sortie n’est pas connue.
Pointeurs NULL .

Les pointeurs complets (et uniques) ne peuvent pas être utilisés pour décrire la taille d’un tableau ou d’une union, car ces pointeurs peuvent avoir la valeur NULL. Cette restriction par MIDL empêche une erreur qui peut se produire lorsqu’une valeur NULL est utilisée comme taille.

Les pointeurs de référence et uniques sont supposés ne pas provoquer d’alias de données. Un graphe dirigé obtenu en commençant à partir d’un pointeur unique ou de référence et en suivant uniquement des pointeurs uniques ou de référence ne contient ni reconvergence ni cycles.

Pour éviter les alias, toutes les valeurs de pointeur doivent être obtenues à partir d’un pointeur d’entrée de la même classe de pointeur. Si plusieurs pointeurs pointent vers le même emplacement de mémoire, tous ces pointeurs doivent être des pointeurs complets.

Dans certains cas, les pointeurs complets et les pointeurs uniques peuvent être mélangés. Un pointeur complet peut se voir attribuer la valeur d’un pointeur unique, tant que l’affectation ne viole pas les restrictions relatives à la modification de la valeur d’un pointeur unique. Toutefois, lorsque vous affectez à un pointeur unique la valeur d’un pointeur complet, vous pouvez provoquer un alias.

Le mélange de pointeurs complets et uniques peut entraîner un alias, comme illustré dans l’exemple suivant :

typedef struct 
{ 
    [ptr] short * pdata;          // full pointer  
} GRAPH_NODE_TYPE; 
 
typedef struct 
{ 
    [unique] graph_node * left;   // unique pointer  
    [unique] graph_node * right;  // unique pointer 
} TREE_NODE_TYPE; 
 
// application code: 
short a = 5; 
TREE_NODE_TYPE * t; 
GRAPH_NODE_TYPE g, h; 
 
g.pdata = h.pdata = &a; 
t->left = &g; 
t->right = &h; 
// t->left->pdata == t->right->pdata == &a

Bien que « t-left> » et « t-right> » pointent vers des emplacements de mémoire uniques, « t-left-pdata>> » et « t-right-pdata>> » sont alias. Pour cette raison, les algorithmes de prise en charge des alias doivent suivre tous les pointeurs (y compris les pointeurs uniques et de référence) qui peuvent éventuellement atteindre un pointeur complet.

Exemples

pointer_default(ptr) 
 
typedef [ptr, string] unsigned char * MY_STRING_TYPE; 
 
[ptr] char * MyFunction([in, out, unique] long * plNumber);

Voir aussi

Tableaux
Tableaux et pointeurs
Attributs de tableau et de Sized-Pointer
MIDL Base Types
rappel
const
context_handle
Enum
first_is
Poignée
Fichier de définition d’interface (IDL)
Ignorer
last_is
length_is
Local
max_is
pointer_default
Ref
size_is
String
Struct
switch_type
transmit_as
Union
Unique