Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Das Attribut [context_handle] identifiziert ein Bindungshandle, das Kontext- oder Statusinformationen auf dem Server zwischen Remoteprozeduraufrufen verwaltet.
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); ]
Parameter
-
type-attribute-list
-
Gibt ein oder mehrere Attribute an, die für den Typ gelten.
-
Typbezeichner
-
Gibt einen Zeigertyp oder einen Typbezeichner an. Eine optionale Speicherspezifikation kann dem Typbezeichner vorangehen.
-
Deklarator und Deklaratorliste
-
Gibt Standard-C-Deklaratoren an, z. B. Bezeichner, Zeiger-Deklaratoren und Array-Deklaratoren. Der Deklarator für ein Kontexthandle muss mindestens einen Zeiger-Deklarator enthalten. Weitere Informationen finden Sie unter Array- und Sized-Pointer Attribute, Arrays und Arrays und Zeiger. Die Deklaratorliste besteht aus einem oder mehreren Deklaratoren, getrennt durch Kommas. Der Parameternamebezeichner im Funktionsdeklarator ist optional.
-
function-attr-list
-
Gibt null oder mehr Attribute an, die für die Funktion gelten. Gültige Funktionsattribute sind [callback], [local]; das Zeiger-Attribut [ref], [unique], oder [ptr]; und die Verwendungsattribute [string], [ignore], und [context_handle].
-
ptr-decl
-
Gibt null oder mehr Zeiger-Deklaratoren an. Ein Zeiger-Deklarator ist identisch mit dem in C verwendeten Zeiger-Deklarator. sie wird vom * Kennzeichner, Modifizierern wie weit und dem Qualifizierer konstiert.
-
Funktionsname
-
Gibt den Namen der Remoteprozedur an.
-
parameter-attribute-list
-
Gibt null oder mehr Richtungsattribute, Feldattribute, Verwendungsattribute und Zeigerattribute an, die für den angegebenen Parametertyp geeignet sind. Trennen Sie mehrere Attribute durch Kommas.
-
context-handle-type
-
Gibt den Bezeichner an, der den Kontexthandletyp gemäß der Definition in einer Typedef-Deklaration angibt, die das Attribut [context_handle] verwendet. Die Ausführungsroutine ist optional.
Windows Server 2003 und Windows XP: Eine einzelne Schnittstelle kann sowohl serialisierte als auch nicht vererialisierte Kontexthandles aufnehmen, wodurch eine Methode auf eine Schnittstelle zugreifen kann, die ausschließlich auf ein Kontexthandle (serialisiert) zugreifen kann, während andere Methoden auf das Kontexthandle im gemeinsam genutzten Modus zugreifen (nichterialisiert). Diese Zugriffsfunktionen sind vergleichbar mit Lese-/Schreibsperrmechanismen; Methoden, die ein serialisiertes Kontexthandle verwenden, sind exklusive Benutzer (Autoren), während Methoden, die ein nichtserialisiertes Kontexthandle verwenden, freigegebene Benutzer (Leser) sind. Methoden, die den Zustand eines Kontexthandle zerstören oder ändern, müssen serialisiert werden. Methoden, die den Status eines Kontexthandles nicht ändern, z. B. methoden, die einfach aus einem Kontexthandle gelesen werden, können nicht geordnet sein. Beachten Sie, dass Erstellungsmethoden implizit serialisiert werden.
Bemerkungen
Das Attribut [context_handle] kann als IDL typedef-Typattribute , als Funktionsrückgabe-Attribut oder als Parameterattribute angezeigt werden. Wenn Sie das Attribut [context_handle] auf eine Typdefinition anwenden, müssen Sie auch eine Kontextausführungsroutine bereitstellen. Ausführliche Informationen finden Sie unter Serverkontextausführungsroutine .
Wenn Sie den MIDL-Compiler im Standardmodus (/ms_ext) verwenden, kann ein Kontexthandle ein beliebiger Zeigertyp sein, der vom Benutzer ausgewählt wird, sofern er den anforderungen für Kontexthandles entspricht, die hier beschrieben werden. Die daten, die einem solchen Kontexthandletyp zugeordnet sind, werden nicht im Netzwerk übertragen und sollten nur von der Serveranwendung bearbeitet werden. DCE IDL-Compiler beschränken Kontexthandles auf Zeiger vom Typ void*. Daher ist dieses Feature nicht verfügbar, wenn Sie den MIDL-Compiler /osf-Switch verwenden.
Wie bei anderen Handletypen ist das Kontexthandle für die Clientanwendung nicht transparent, und alle damit verbundenen Daten werden nicht übertragen. Auf dem Server dient das Kontexthandle als Handle im aktiven Kontext, und auf alle daten, die dem Kontexthandletyp zugeordnet sind, kann zugegriffen werden.
Zum Erstellen eines Kontexthandles übergibt der Client einen [out]-, [ref] -Zeiger auf ein Kontexthandle an den Server. (Das Kontexthandle selbst kann einen NULL - oder nicht NULL-Wert aufweisen, solange der Wert mit seinen Zeigerattributen konsistent ist. Wenn der Kontexthandletyp beispielsweise das Attribut "[ref]" darauf angewendet hat, kann er keinen NULL-Wert aufweisen.) Ein weiteres Bindungshandle muss bereitgestellt werden, um die Bindung auszuführen, bis das Kontexthandle erstellt wird. Wenn kein explizites Handle angegeben wird, wird implizite Bindung verwendet. Wenn kein [implicit_handle] -Attribut vorhanden ist, wird ein automatisches Handle verwendet.
Die Remoteprozedur auf dem Server erstellt ein aktives Kontexthandle. Der Client muss dieses Kontexthandle als [in] oder [in, out] -Parameter in nachfolgenden Aufrufen verwenden. Ein [in]-only-Kontexthandle kann als Bindungshandle verwendet werden, sodass er einen Wert ungleich NULL aufweisen muss. Ein [in]-only-Kontexthandle spiegelt keine Zustandsänderungen auf dem Server wider.
Auf dem Server kann die aufgerufene Prozedur das Kontexthandle nach Bedarf interpretieren. Die aufgerufene Prozedur kann beispielsweise Heapspeicher zuweisen und das Kontexthandle als Zeiger auf diesen Speicher verwenden.
Zum Schließen eines Kontexthandles übergibt der Client das Kontexthandle als [in]-, [out] -Argument. Der Server muss ein NULL-Kontexthandle zurückgeben, wenn der Kontext nicht mehr im Auftrag des Aufrufers beibehalten wird. Wenn das Kontexthandle beispielsweise eine geöffnete Datei darstellt und der Aufruf die Datei schließt, muss der Server das Kontexthandle auf NULL festlegen und an den Client zurückgeben. Ein NULL-Wert ist als Bindungshandle für nachfolgende Aufrufe ungültig.
Ein Kontexthandle ist nur für einen Server gültig. Wenn eine Funktion über zwei Handleparameter verfügt und das Kontexthandle nicht NULL ist, müssen die Bindungshandles auf denselben Adressraum verweisen.
Wenn eine Funktion ein [in] oder ein [in, out] -Kontexthandle aufweist, kann sein Kontexthandle als Bindungshandle verwendet werden. In diesem Fall wird keine implizite Bindung verwendet, und das Attribut [implicit_handle] oder [auto_handle] wird ignoriert.
Die folgenden Einschränkungen gelten für Kontexthandles:
- Kontexthandles dürfen keine Arrayelemente, Strukturelemente oder Union-Member sein. Sie können nur Parameter sein.
- Kontexthandles können nicht das Attribut [transmit_as] oder [represent_as] aufweisen.
- Parameter, die Zeiger auf [out] -Kontexthandles sind, müssen [bezug]- Zeiger sein.
- Ein [in] -Kontexthandle kann als Bindungshandle verwendet werden und darf nicht NULL sein.
- Ein [in, out context handle can be NULL on input, but only if the procedure has another explicit handle parameter. Wenn keine anderen expliziten Nicht-NULL-Kontexthandle-Parameter vorhanden sind, kann der Kontexthandle [in, out] nicht NULL sein.
- Ein Kontexthandle kann nicht mit Rückrufen verwendet werden.
Beispiele
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);
Siehe auch