attribut context_handle
L’attribut [context_handle] identifie un handle de liaison qui conserve les informations de contexte ou d’état sur le serveur entre les appels de procédure distante.
typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;
[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator], ...);
[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
[context_handle [ , parameter-attribute-list ] ] type-specifier [declarator], ...);
[ void __RPC_USER context-handle-type_rundown (
context-handle-type); ]
Paramètres
-
type-attribute-list
-
Spécifie un ou plusieurs attributs qui s’appliquent au type.
-
type-specifier
-
Spécifie un type de pointeur ou un identificateur de type. Une spécification de stockage facultative peut précéder le spécificateur de type.
-
declarator et declarator-list
-
Spécifie les déclarateurs C standard, tels que les identificateurs, les déclarateurs de pointeurs et les déclarateurs de tableau. Le déclarateur d’un handle de contexte doit inclure au moins un déclarateur de pointeur. 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.
-
function-attr-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 zéro ou plusieurs déclarateurs de pointeur. 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
-
Spécifie zéro ou plusieurs attributs directionnels, attributs de champ, attributs d’utilisation et attributs de pointeur appropriés pour le type de paramètre spécifié. Séparez plusieurs attributs par des virgules.
-
context-handle-type
-
Spécifie l’identificateur qui spécifie le type de handle de contexte tel que défini dans une déclaration typedef qui accepte l’attribut [context_handle]. La routine d’exécution est facultative.
Windows Server 2003 et Windows XP : Une seule interface peut prendre en charge les handles de contexte sérialisés et non sérialisés, ce qui permet à une méthode sur une interface d’accéder exclusivement à un handle de contexte (sérialisé), tandis que d’autres méthodes accèdent à ce handle de contexte en mode partagé (non sérialisé). Ces fonctionnalités d’accès sont comparables aux mécanismes de verrouillage en lecture/écriture ; les méthodes utilisant un handle de contexte sérialisé sont des utilisateurs exclusifs (writers), tandis que les méthodes utilisant un handle de contexte non sérialisé sont des utilisateurs partagés (lecteurs). Les méthodes qui détruisent ou modifient l’état d’un handle de contexte doivent être sérialisées. Les méthodes qui ne modifient pas l’état d’un handle de contexte, telles que celles qui lisent simplement à partir d’un handle de contexte, peuvent être nonsérialisées. Notez que les méthodes de création sont implicitement sérialisées.
Notes
L’attribut [context_handle] peut apparaître en tant qu’attribut de type typedef IDL, en tant qu’attribut de type de retour de fonction ou en tant qu’attribut de paramètre. Lorsque vous appliquez l’attribut [context_handle] à une définition de type, vous devez également fournir une routine d’exécution de contexte. Pour plus d’informations, consultez Routine d’exécution du contexte du serveur.
Lorsque vous utilisez le compilateur MIDL en mode par défaut (/ms_ext), un handle de contexte peut être n’importe quel type de pointeur sélectionné par l’utilisateur, tant qu’il est conforme aux exigences pour les handles de contexte décrites ici. Les données associées à ce type de handle de contexte ne sont pas transmises sur le réseau et doivent uniquement être manipulées par l’application serveur. Les compilateurs IDL DCE limitent les handles de contexte aux pointeurs de type void*. Par conséquent, cette fonctionnalité n’est pas disponible lorsque vous utilisez le commutateur / osf du compilateur MIDL.
Comme pour les autres types de handles, le handle de contexte est opaque pour l’application cliente et toutes les données qui lui sont associées ne sont pas transmises. Sur le serveur, le handle de contexte sert de handle sur le contexte actif, et toutes les données associées au type de handle de contexte sont accessibles.
Pour créer un handle de contexte, le client passe au serveur un pointeur [out], [ref] vers un handle de contexte. (Le handle de contexte lui-même peut avoir une valeur NULL ou non NULL , tant que sa valeur est cohérente avec ses attributs de pointeur. Par exemple, lorsque l’attribut [ref] est appliqué au type de handle de contexte, il ne peut pas avoir de valeur NULL .) Un autre handle de liaison doit être fourni pour accomplir la liaison jusqu’à ce que le handle de contexte soit créé. Lorsqu’aucun handle explicite n’est spécifié, la liaison implicite est utilisée. Lorsqu’aucun attribut [implicit_handle] n’est présent, un handle automatique est utilisé.
La procédure distante sur le serveur crée un handle de contexte actif. Le client doit utiliser ce handle de contexte en tant que paramètre [in] ou [in, out] dans les appels suivants. Un handle de contexte [in]-only peut être utilisé comme handle de liaison, il doit donc avoir une valeur non NULL . Un handle de contexte [in]-only ne reflète pas les changements d’état sur le serveur.
Sur le serveur, la procédure appelée peut interpréter le handle de contexte en fonction des besoins. Par exemple, la procédure appelée peut allouer du stockage de tas et utiliser le handle de contexte comme pointeur vers ce stockage.
Pour fermer un handle de contexte, le client passe le handle de contexte en tant qu’argument [in], [out]. Le serveur doit retourner un handle de contexte NULL lorsqu’il ne gère plus le contexte pour le compte de l’appelant. Par exemple, si le handle de contexte représente un fichier ouvert et que l’appel ferme le fichier, le serveur doit définir le handle de contexte sur NULL et le retourner au client. Une valeur NULL n’est pas valide en tant que handle de liaison sur les appels suivants.
Un handle de contexte n’est valide que pour un seul serveur. Lorsqu’une fonction a deux paramètres de handle et que le handle de contexte n’est pas NULL, les handles de liaison doivent faire référence au même espace d’adressage.
Lorsqu’une fonction a un handle de contexte [in] ou [in, out], son handle de contexte peut être utilisé comme handle de liaison. Dans ce cas, la liaison implicite n’est pas utilisée et l’attribut [implicit_handle] ou [auto_handle] est ignoré.
Les restrictions suivantes s’appliquent aux handles de contexte :
- Les handles de contexte ne peuvent pas être des éléments de tableau, des membres de structure ou des membres d’union. Il ne peut s’agir que de paramètres.
- Les handles de contexte ne peuvent pas avoir l’attribut [transmit_as] ou [represent_as].
- Les paramètres qui sont des pointeurs vers des handles de contexte [out] doivent être des pointeurs [ref].
- Un handle de contexte [in] peut être utilisé comme handle de liaison et ne peut pas être NULL.
- Un handle de contexte [in, out peut être NULL lors de l’entrée, mais uniquement si la procédure a un autre paramètre de handle explicite. S’il n’existe aucun autre paramètre de handle de contexte non NULL explicite, le handle de contexte [in, out] ne peut pas être NULL.
- Un handle de contexte ne peut pas être utilisé avec les rappels.
Exemples
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle);
short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle);
void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);
Voir aussi