attribut context_handle
Das [context_handle] -Attribut identifiziert ein Bindungshandle, das kontext- oder zustandsbezogene Informationen 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 mindestens ein Attribut an, das für den Typ gilt.
-
Typspezifizierer
-
Gibt einen Zeigertyp oder einen Typbezeichner an. Eine optionale Speicherspezifikation kann dem Typbezeichner vorangestellt werden.
-
deklarator und deklarator-list
-
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, die durch Kommas getrennt sind. 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 [Rückruf], [lokal]; das Zeigerattribute [ref], [unique] oder [ptr]; und die Verwendungsattribute [Zeichenfolge], [ignorieren] und [context_handle].
-
ptr-decl
-
Gibt null oder mehr Zeiger-Deklaratoren an. Ein Zeigerdeklarations-Deklarator ist mit dem in C verwendeten Zeiger-Deklarator identisch. es wird aus dem * Bezeichner, Modifizierern wie far und dem Qualifizierer const erstellt.
-
Funktionsname
-
Gibt den Namen der Remoteprozedur an.
-
parameter-attribute-list
-
Gibt null oder mehr Richtungsattribute, Feldattribute, Nutzungsattribute 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 Kontexthandle-Typ angibt, der in einer typedef-Deklaration definiert ist, die das Attribut [context_handle] übernimmt. Die Rundownroutine ist optional.
Windows Server 2003 und Windows XP: Eine einzelne Schnittstelle kann sowohl serialisierte als auch nicht-nicht-ialisierte Kontexthandles aufnehmen, sodass eine Methode auf einer Schnittstelle ausschließlich auf ein Kontexthandle zugreifen kann (serialisiert), während andere Methoden im freigegebenen Modus auf dieses Kontexthandle zugreifen (nicht-ialisiert). Diese Zugriffsfunktionen sind mit Lese-/Schreibsperrmechanismen vergleichbar. Methoden, die ein serialisiertes Kontexthandle verwenden, sind exklusive Benutzer (Writer), während Methoden, die ein nicht-ialisiertes Kontexthandle verwenden, freigegebene Benutzer (Reader) sind. Methoden, die den Zustand eines Kontexthandles zerstören oder ändern, müssen serialisiert werden. Methoden, die den Zustand eines Kontexthandles nicht ändern, z. B. die Methoden, die einfach aus einem Kontexthandle lesen, können nicht verwendet werden. Beachten Sie, dass Erstellungsmethoden implizit serialisiert werden.
Bemerkungen
Das Attribut [context_handle] kann als IDL-Typedef-Typattribute, als Attribut des Funktionsrückgabetyps oder als Parameterattribute angezeigt werden. Wenn Sie das Attribut [context_handle] auf eine Typdefinition anwenden, müssen Sie auch eine Kontextablaufroutine bereitstellen. Weitere Informationen finden Sie unter Ausführungsroutine für den Serverkontext .
Wenn Sie den MIDL-Compiler im Standardmodus (/ms_ext) verwenden, kann ein Kontexthandle jeder vom Benutzer ausgewählte Zeigertyp sein, sofern es die hier beschriebenen Anforderungen für Kontexthandles erfüllt. 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-Schalter verwenden.
Wie bei anderen Handle-Typen ist das Kontexthandle für die Clientanwendung undurchsichtig, und alle damit verknüpften Daten werden nicht übertragen. Auf dem Server dient das Kontexthandle als Handle für den aktiven Kontext, und auf alle Daten, die dem Kontexthandletyp zugeordnet sind, kann zugegriffen werden.
Um ein Kontexthandle zu erstellen, ü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 sein Wert mit seinen Zeigerattributen konsistent ist. Wenn beispielsweise für den Kontexthandletyp das [ref] -Attribut angewendet wird, kann er keinen NULL-Wert aufweisen.) Ein weiteres Bindungshandle muss angegeben 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 [rein]-reines Kontexthandle kann als Bindungshandle verwendet werden, sodass es über einen Wert ohne NULL verfügen muss. Ein [Rein]-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 zuordnen und das Kontexthandle als Zeiger auf diesen Speicher verwenden.
Um ein Kontexthandle zu schließen, übergibt der Client das Kontexthandle als [in], [out] -Argument. Der Server muss ein NULL-Kontexthandle zurückgeben, wenn der Kontext nicht mehr im Namen 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 bei nachfolgenden Aufrufen ungültig.
Ein Kontexthandle ist nur für einen Server gültig. Wenn eine Funktion über zwei Handle-Parameter verfügt und das Kontexthandle nicht NULL ist, müssen die Bindungshandles auf denselben Adressraum verweisen.
Wenn eine Funktion über ein [in] - oder ein [in-, out]- Kontexthandle verfügt, kann ihr Kontexthandle als Bindungshandle verwendet werden. In diesem Fall wird die implizite Bindung nicht 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 Unionselemente sein. Sie können nur Parameter sein.
- Kontexthandles dürfen nicht über das Attribut [transmit_as] oder [represent_as] verfügen.
- Parameter, die Zeiger auf [out] -Kontexthandles sind, müssen [ref] -Zeiger sein.
- Ein [in] -Kontexthandle kann als Bindungshandle verwendet werden und darf nicht NULL sein.
- Ein [in, out-Kontexthandle kann bei der Eingabe NULL sein, aber nur, wenn die Prozedur einen weiteren expliziten Handle-Parameter aufweist. Wenn keine anderen expliziten Nicht-NULL-Kontexthandleparameter vorhanden sind, kann das 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);
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für