Schnittstellenentwicklung mithilfe von Kontexthandles

In der Regel erstellen Sie ein Kontexthandle, indem Sie das Attribut [context_handle] für eine Typdefinition in der IDL-Datei angeben. Die Typdefinition gibt auch implizit eine Kontextausführungsroutine an, die Sie bereitstellen müssen. Wenn die Kommunikation zwischen Client und Server unterbrochen wird, ruft die Serverlaufzeit diese Routine auf, um alle erforderlichen Bereinigungen durchzuführen. Weitere Informationen zu heruntergefahrenen Kontextroutinen finden Sie unter Serverkontext-Herunterlaufroutine.

Eine Schnittstelle, die ein Kontexthandle verwendet, muss über ein Bindungshandle für die anfängliche Bindung verfügen, die erfolgen muss, bevor der Server ein Kontexthandle zurückgeben kann. Sie können ein automatisches, implizites oder explizites Bindungshandle verwenden, um die Bindung zu erstellen und den Kontext einzurichten.

Ein Kontexthandle muss vom Typ void * oder ein Typ sein, der in void * aufgelöst wird. Das Serverprogramm wandelt es in den erforderlichen Typ um.

Hinweis

Die Verwendung von [in, out] für Kontexthandleparameter wird mit Ausnahme von Routinen abgeraten, die Kontexthandles schließen. Wenn kontextbezogene Parameter verwendet werden, die [in, out] markiert sind, übergeben Sie kein NULL - oder nicht initialisiertes Kontexthandle vom Client an den Server. Stattdessen sollte ein NULL-Zeiger auf ein Kontexthandle übergeben werden. Beachten Sie, dass kontextbezogene Handle-Parameter, die [in] markiert sind, keine NULL-Zeiger akzeptieren.

 

Das folgende Fragment einer Beispielschnittstellendefinition zeigt, wie eine verteilte Anwendung ein Kontexthandle verwenden kann, um einen Server zu öffnen und eine Datendatei für jeden Client zu aktualisieren.

Die Schnittstelle muss einen Remoteprozeduraufruf enthalten, um das Handle zu initialisieren und auf einen Wert ungleich NULL festzulegen. In diesem Beispiel führt die RemoteOpen-Funktion diesen Vorgang aus. Es gibt das Kontexthandle mit einem [out]-direktionalen Attribut an. Alternativ können Sie das Kontexthandle als Rückgabewert der Prozedur zurückgeben. In diesem Beispiel übergeben wir jedoch die Kontextbehandlung über die Parameterliste.

In diesem Beispiel sind die Kontextinformationen ein Dateihandle. Der aktuelle Speicherort in der Datei wird nachverfolgt. Die Schnittstelle packt das Dateihandle als Kontexthandle und übergibt es als Parameter an Remoteprozeduraufrufe. Eine Struktur enthält den Dateinamen und das Dateihandle.

/* file: cxhndl.idl (fragment of interface definition file) */
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
typedef [ref] PCONTEXT_HANDLE_TYPE * PPCONTEXT_HANDLE_TYPE;
 
short RemoteOpen([out] PPCONTEXT_HANDLE_TYPE pphContext,
    [in, string] unsigned char * pszFile);
 
void RemoteRead(
    [in] PCONTEXT_HANDLE_TYPE phContext,
    [out, size_is(cbBuf)] unsigned char achBuf[],
    [in, out] short *pcbBuf);
 
short RemoteClose([in, out] PPCONTEXT_HANDLE_TYPE pphContext);

Die RemoteOpen-Funktion erstellt ein gültiges Kontexthandle, das nicht NULL ist. Das Kontexthandle wird an den Client übergeben. Nachfolgende Remoteprozeduraufrufe, z. B. RemoteRead, verwenden das Kontexthandle als Zeiger.

Zusätzlich zur Remoteprozedur, die das Kontexthandle initialisiert, muss die Schnittstelle eine Prozedur enthalten, die den Serverkontext freigibt und das Kontexthandle auf NULL festlegt. Im vorherigen Beispiel führt die RemoteClose-Funktion diesen Vorgang aus.