attribut de handle de contexte _

L’attribut de [ _ handle ] de contexte identifie un handle de liaison qui gère le contexte, ou les informations 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-attribut-List

Spécifie un ou plusieurs attributs qui s’appliquent au type.

spécificateur de type

Spécifie un type pointeur ou un identificateur de type. Une spécification de stockage facultative peut précéder le type-specifier.

déclarateur et déclarateur-liste

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 tableau et Sized-Pointer attributs, tableaux, tableaux et pointeurs. La liste déclarateur se compose d’un ou de 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, un 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 [ chaîne ] , [ Ignorer ] et [ _ handle ] de contexte.

pointeur-decl

Spécifie zéro ou plusieurs déclarateurs de pointeur. Un déclarateur de pointeur est le même que le déclarateur de pointeur utilisé dans C ; elle est construite à partir de l' * indicateur _, de modificateurs tels que _ Far et du qualificateur const.

nom de fonction

Spécifie le nom de la procédure distante.

Parameter-attribute-List

Spécifie zéro, un 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 prend l’attribut de [ _ handle ] de contexte . La routine d’arrêt est facultative.

Windows Server 2003 et Windows XP : Une interface unique peut prendre en charge des 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 qui utilisent un handle de contexte sérialisé sont des utilisateurs exclusifs (enregistreurs), tandis que les méthodes qui utilisent 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 les méthodes qui lisent simplement un handle de contexte, peuvent être non sérialisées. Notez que les méthodes de création sont implicitement sérialisées.

Notes

L’attribut de [ _ handle ] de contexte 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. Quand vous appliquez l’attribut de [ _ handle ] de contexte à une définition de type, vous devez également fournir une routine d’arrêt de contexte. Pour plus d’informations, consultez routine de fonctionnement du contexte de serveur .

Quand vous utilisez le compilateur MIDL en mode par défaut (/ms. _ ext), un descripteur de contexte peut être n’importe quel type pointeur sélectionné par l’utilisateur, à condition qu’il soit conforme aux exigences des handles de contexte décrits ici. Les données associées à ce type de descripteur 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 restreignent les handles de contexte aux pointeurs de type void * * _. Par conséquent, cette fonctionnalité n’est pas disponible lorsque vous utilisez le commutateur MIDL _ /OSF * du compilateur MIDL.

Comme avec d’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 descripteur de contexte sont accessibles.

Pour créer un handle de contexte, le client passe au serveur un [ ] [ ] pointeur Ref vers un handle de contexte. (Le handle de contexte lui-même peut avoir une valeur null ou non null , à condition que sa valeur soit cohérente avec ses attributs de pointeur. Par exemple, quand 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éé. Quand aucun handle explicite n’est spécifié, la liaison implicite est utilisée. Lorsqu’aucun [ attribut de _ handle implicite ] 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 ] en uniquement peut être utilisé comme handle de liaison, donc il doit avoir une valeur non null . Un handle [ de contexte en ] uniquement ne reflète pas les modifications d’État sur le serveur.

Sur le serveur, la procédure appelée peut interpréter le descripteur de contexte en fonction des besoins. Par exemple, la procédure appelée peut allouer le stockage du 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 la valeur null et le renvoyer au client. Une valeur null n’est pas valide en tant que handle de liaison lors des appels suivants.

Un descripteur 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’a pas la valeur null, les handles de liaison doivent faire référence au même espace d’adressage.

Quand une fonction possède 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 le [ _ handle implicite ] ou l’attribut de [ _ handle automatique ] 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 peuvent uniquement être des paramètres.
  • Les handles de contexte ne peuvent pas avoir l' [ attribut transmit _ As ] ou [ dereprésente _ As ] .
  • Les paramètres qui sont des pointeurs vers [ des ] Handles de contexte doivent être des [ ] pointeurs Ref.
  • Un [ handle de contexte in ] peut être utilisé comme handle de liaison et ne peut pas avoir la valeur null.
  • Un handle [ de contexte in, out peut avoir la valeur null en entrée, mais uniquement si la procédure a un autre paramètre de handle explicite. S’il n’existe aucun autre paramètre explicite [ de handle de contexte non null , le handle de contexte out ] ne peut pas être null.
  • Un descripteur 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

tableaux

_handle automatique

rappel

Réinitialisation du contexte client

const

Handles de contexte

traitée

Liaison et Handles

ignore

handle implicite _

dans

localisé

Clients multithread et handles de contexte

/ms. _ ext

à

ptr

ref

représenter _ comme

RpcSsDestroyClientContext

Routine d’exécution du contexte de serveur

chaîne

transmettre _ en tant que

typedef

unique

nullité