RoGetAgileReference-Funktion (combaseapi.h)

  • Artikel

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
S_OK
 Die Funktion wurde erfolgreich abgeschlossen.
E_INVALIDARG
 Der Optionsparameter in ungültig.
E_OUTOFMEMORY
 Der agile Verweis konnte aufgrund einer Nicht-Arbeitsspeicher-Bedingung nicht erstellt werden.
E_NOINTERFACE
 Der pUnk-Parameter unterstützt die durch den riid-Parameter angegebene Schnittstellen-ID nicht.
CO_E_NOT_SUPPORTED
 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

Weitere Informationen

AgileReferenceOptions

IAgileReference