Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
L’attribut [context_handle] identifie un handle de liaison qui gère 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.
-
spécificateur de type
-
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.
-
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. Le déclarateur d’un handle de contexte doit inclure au moins un déclarateur de pointeur. 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.
-
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 de 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é en C ; elle est construite à partir de l’indicateur * , des modificateurs comme jusqu’à présent et le qualificateur const.
-
nom de fonction
-
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 à un handle de contexte exclusivement (sérialisé), tandis que d’autres méthodes accèdent à ce handle 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 (enregistreurs), 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 nonialisées. Notez que les méthodes de création sont sérialisées implicitement.
Remarques
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 des handles de contexte décrits ici. Les données associées à un tel type de handle de contexte ne sont pas transmises sur le réseau et ne doivent être manipulées que 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 d’autres types de handles, le handle de contexte est opaque pour l’application cliente et toutes les données associées à celui-ci 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 le type de handle de contexte a l’attribut [ref] appliqué à celui-ci, 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 comme paramètre [in] ou [in, out] dans les appels suivants. Un handle de contexte [in]uniquement peut être utilisé comme handle de liaison. Il doit donc avoir une valeur non NULL . Un handle de contexte [in]uniquement ne reflète pas les modifications d’état sur le serveur.
Sur le serveur, la procédure appelée peut interpréter le handle de contexte selon les besoins. Par exemple, la procédure appelée peut allouer le stockage de tas et utiliser le handle de contexte comme pointeur vers ce stockage.
Pour fermer un handle de contexte, le client transmet le handle de contexte en tant qu’argument [in], [out]. Le serveur doit retourner un handle de contexte NULL lorsqu’il ne conserve 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. Ils ne peuvent être que des 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 des 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 également