RpcBindingBind-Funktion (rpcasync.h)

Artikel
08/25/2023

Die RpcBindingBind-Funktion kontaktiert einen RPC-Server und bindet ihn.

Syntax

RPC_STATUS RpcBindingBind(
  [in, optional] PRPC_ASYNC_STATE   pAsync,
  [in]           RPC_BINDING_HANDLE Binding,
  [in]           RPC_IF_HANDLE      IfSpec
);

Parameter

[in, optional] pAsync

Zeiger auf die RPC_ASYNC_STATE-Struktur , die asynchrone Aufrufinformationen enthält. Diese Zustandsinformationen enthalten die Vervollständigungsmethode, mit der signalisiert wird, wann der Bindungsvorgang abgeschlossen ist.

[in] Binding

RPC_BINDING_HANDLE Struktur, die das Bindungshandle enthält, das mit einem vorherigen Aufruf von RpcBindingCreate erstellt wurde.

[in] IfSpec

RPC_IF_HANDLE Wert, der die Schnittstelle angibt, auf der dieses Bindungshandle aufgerufen wird.

Rückgabewert

Diese Funktion gibt bei Erfolg RPC_S_OK zurück. Andernfalls wird ein RPC_S_*-Fehlercode zurückgegeben. Informationen zu diesen Fehlercodes finden Sie unter RPC-Rückgabewerte.

Rückgabecode	Beschreibung
RPC_S_OK	Der RPC ist erfolgreich an den Server gebunden, und Es können Remoteaufrufe ausgeführt werden.
RPC_S_CANNOT_SUPPORT	Für diesen Bindungsvorgang wurde ein veraltetes Feature von RPC angefordert.

Hinweis Eine Liste der gültigen Fehlercodes finden Sie unter RPC-Rückgabewerte.

Hinweise

RpcBindingBind kontaktiert den RPC-Server und bindet ihn mithilfe des Bindungshandles, das von einem vorherigen Aufruf von RpcBindingCreate zurückgegeben wurde. Bindungshandles, die mit dieser Methode eingerichtet wurden, werden als "schnelle" Bindungshandles bezeichnet.

Wenn der Wert des pAsync-Parameters nicht NULL ist, ist die Bindung asynchron, und Aufrufe von RpcAsyncCancelCall und RpcAsyncGetCallStatus können für den angegebenen asynchronen Zustand ausgeführt werden. Die Vervollständigungsmethode, die in den asynchronen Zustandsinformationen angegeben wird, die verwendet wird, um dem Aufrufer zu signalisieren, dass die Bindung abgeschlossen ist. Nach der Benachrichtigung über die Vervollständigung können Aufrufe mithilfe des neu gebundenen Bindungshandles ausgeführt werden.

Die Bindmethode bestimmt nicht, welche Aufrufe mithilfe des Bindungshandles ausgeführt werden können. Wenn die Bindung synchron ist, können weiterhin asynchrone Aufrufe für das Bindungshandle ausgeführt werden und umgekehrt. Die bind-Methode bestimmt, wie eine Benachrichtigung für eine erfolgreiche Bindung signalisiert wird, insbesondere bei asynchronen Bindungen.

Da diese API Nachrichten mit dem RPC-Server austauscht, können Bindungsvorgänge aufgrund einer Reihe von unabhängigen Faktoren wie Netzwerkdatenverkehr und Serverblockierung lange dauern. Wenn die Bindung synchron ist, kann der Bindungsvorgang blockiert werden, wenn der Server blockiert ist.

Nachdem die Bindung abgeschlossen ist, ist die Semantik von Aufrufen, die für das Bindungshandle ausgeführt werden, identisch mit aufrufen, die für einen beliebigen anderen Typ von Bindungshandle ausgeführt werden, jedoch mit vier bemerkenswerten Unterschieden, die unten aufgeführt sind:

Alle Aufrufe dieses Bindungshandles müssen auf der in IfSpec angegebenen Schnittstelle erfolgen. Das Bindungshandle ist eindeutig an diese Schnittstelle gebunden. Die Schnittstelle selbst kann entladen werden, bevor das Bindungshandle zerstört wird, aber umfangreiche Informationen zur Schnittstelle werden im Bindungshandle zwischengespeichert, und wenn ein Aufruf des gleichen Bindungshandles für eine andere Schnittstelle erfolgt, sind die Ergebnisse nicht definiert.
RPC-Rückrufe sind für ein Bindungshandle nicht zulässig. Wenn der RPC-Server versucht, mithilfe einer Methode mit dem Attribut [callback] einen Rückruf auszuführen, wird der Aufruf mit dem RPC_S_CANNOT_SUPPORT Fehler status Code abgelehnt.
Bei klassischen Bindungshandles versucht RPC, die Verbindung mit dem Server transparent wiederherzustellen, wenn die Verbindung gelöscht wird. Bei schnellen Bindungshandles versucht RPC nicht, eine transparente Verbindung mit dem Server herzustellen. Stattdessen wird einer der folgenden Fehler zurückgegeben: RPC_S_SERVER_UNAVAILABLE, RPC_S_CALL_FAILED und RPC_C_CALL_FAILED_DNE. Wenn die Verbindung aufgrund abgelehnter Anmeldeinformationen gelöscht wird, wird RPC_S_ACCESS_DENIED zurückgegeben. und wenn auf dem Server aufgrund von Arbeitsspeichermangel ein vorübergehender Fehler auftritt, wird RPC_S_OUT_OF_MEMORY zurückgegeben. Alle anderen Konnektivitätsfehler sind das Ergebnis von Marshalling- oder Entmarstungsfehlern, die von Serverroutinen zurückgegeben werden. Im Falle eines Verbindungsverlusts muss das aufgerufene durch Aufrufen von RpcBindingUnbind die Bindung aufheben und dann mit einem anderen Aufruf von RpcBindingBind erneut gebunden werden.

Wenn beim Aufruf von RpcBindingBind ein Fehler auftritt, ist das Bindungshandle nicht an den Server gebunden, und der Aufrufer kann versuchen, mit einem anderen Aufruf an dieselbe API erneut zu binden, oder das Bindungshandle kann freigegeben werden. Da ein fehlerbehafteter Bindungsvorgang das Bindungshandle nicht in den gebundenen Zustand versetzt, darf RpcBindingUnbind nicht aufgerufen werden.

Bestimmte Funktionen dürfen erst aufgerufen werden, wenn der Bindungsvorgang die Vervollständigung signalisiert hat, insbesondere:

Hinweis Derzeit unterstützt diese Funktion nur die ncalrpc-Protokollsequenz .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista, Windows XP mit SP2 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008, Windows Server 2003 mit SP1 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	rpcasync.h (include Rpc.h)
Bibliothek	Rpcrt4.lib
DLL	Rpcrt4.dll

Weitere Informationen

RpcBindingCreate

RpcBindingUnbind

Freigeben über