RoGetAgileReference-Funktion (combaseapi.h)
Erstellt einen agilen Verweis für ein Objekt, das von der angegebenen Schnittstelle angegeben wird.
Syntax
HRESULT RoGetAgileReference(
[in] AgileReferenceOptions options,
[in] REFIID riid,
[in] IUnknown *pUnk,
[out] IAgileReference **ppAgileReference
);
Parameter
[in] options
Die Registrierungsoptionen.
[in] riid
Die Schnittstellen-ID des Objekts, für das ein agiler Verweis abgerufen wird.
[in] pUnk
Zeiger auf die Schnittstelle, die in einem agilen Verweis gekapselt werden soll. Es muss derselbe Typ wie riid sein. Es kann sich um einen Zeiger auf ein In-Process-Objekt oder um einen Zeiger auf einen Proxy eines Objekts handeln.
[out] ppAgileReference
Die agile Referenz für das Objekt. Rufen Sie die Resolve-Methode auf, um das Objekt in der Wohnung zu lokalisieren, in der Resolve aufgerufen wird.
Rückgabewert
Diese Funktion kann einen dieser Werte zurückgeben.
| Rückgabewert | BESCHREIBUNG |
|---|---|
|
Die Funktion wurde erfolgreich abgeschlossen. |
|
Der Optionsparameter in ungültig. |
|
Der agile Verweis konnte aufgrund einer Nicht-Arbeitsspeicher-Bedingung nicht erstellt werden. |
|
Der pUnk-Parameter unterstützt die durch den riid-Parameter angegebene Schnittstellen-ID nicht. |
|
Das -Objekt implementiert die INoMarshal-Schnittstelle . |
Hinweise
Rufen Sie die RoGetAgileReference-Funktion für ein vorhandenes Objekt auf, um einen agilen Verweis auf das Objekt anzufordern. Das Objekt kann agil sein, aber das zurückgegebene IAgileReference ist agil. Der agile Verweis kann innerhalb desselben Prozesses an ein anderes Apartment übergeben werden, in dem das ursprüngliche Objekt mithilfe der IAgileReference-Schnittstelle abgerufen wird.
Dies ähnelt konzeptionell der vorhandenen Global Interface Table (GIT). Anstatt mit GIT zu interagieren, wird ein IAgileReference abgerufen und verwendet, um das Objekt direkt abzurufen. Genauso wie git nur prozessbezogen ist, sind agile Verweise prozessbezogen und können nicht gemarst werden.
Das Agile-Referenzfeature bietet eine Leistungsverbesserung gegenüber GIT. Die agile Referenz führt standardmäßig eifrig Marshalling durch, wodurch ein apartmentübergreifender Aufruf in Fällen gespeichert wird, in denen das Objekt aus dem agilen Verweis in einem Apartment abgerufen wird, das sich von dem, in dem der agile Verweis erstellt wurde, unterscheidet. Zur weiteren Leistungsverbesserung können Benutzer der RoGetAgileReference-Funktion dieselbe Schnittstelle verwenden, um eine IAgileReference zu erstellen und das ursprüngliche Objekt aufzulösen. Dadurch wird ein zusätzlicher QueryInterface-Aufruf gespeichert, um die gewünschte Schnittstelle aus dem aufgelösten Objekt abzurufen.
Beispielsweise verfügen Sie über ein nicht agiles Objekt namens CDemoExample, das die IDemo- und IExample-Schnittstellen implementiert. Rufen Sie die RoGetAgileReference-Funktion auf, und übergeben Sie das Objekt mit IID_IDemo. Sie erhalten einen IAgileReference-Schnittstellenzeiger zurück, der agil ist, sodass Sie ihn an ein anderes Apartment übergeben können. Rufen Sie im anderen Apartment die Resolve-Methode mit IID_IExample auf. Sie erhalten einen IExample-Zeiger zurück, den Sie in diesem Apartment verwenden können. Dieser IExample-Zeiger ist ein IExample-Proxy, der mit dem ursprünglichen CDemoExample-Objekt verbunden ist. Die agile Referenz behandelt die Komplexität von Vorgängen wie das manuelle Marshallen in einen Stream und das Entkoppeln auf der anderen Seite der Wohnungsgrenze.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 8.1 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2012 R2 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | combaseapi.h |
| Bibliothek | Ole32.lib |
| DLL | Ole32.dll |