Funzione RoGetAgileReference (combaseapi.h)

Articolo
08/22/2023

Crea un riferimento agile per un oggetto specificato dall'interfaccia specificata.

Sintassi

HRESULT RoGetAgileReference(
  [in]  AgileReferenceOptions options,
  [in]  REFIID                riid,
  [in]  IUnknown              *pUnk,
  [out] IAgileReference       **ppAgileReference
);

Parametri

[in] options

Opzioni di registrazione.

[in] riid

ID interfaccia dell'oggetto per cui viene ottenuto un riferimento agile.

[in] pUnk

Puntatore all'interfaccia da incapsulare in un riferimento agile. Deve essere lo stesso tipo di riid. Può essere un puntatore a un oggetto in-process o a un puntatore a un proxy di un oggetto.

[out] ppAgileReference

Riferimento agile per l'oggetto. Chiamare il metodo Resolve per localizzare l'oggetto nell'appartamento in cui viene chiamato Resolve.

Valore restituito

Questa funzione può restituire uno di questi valori.

Valore restituito	Descrizione
S_OK	La funzione è stata completata correttamente.
E_INVALIDARG	Parametro delle opzioni non valido.
E_OUTOFMEMORY	Impossibile costruire il riferimento agile a causa di una condizione di memoria insufficiente.
E_NOINTERFACE	Il parametro pUnk non supporta l'ID dell'interfaccia specificato dal parametro riid .
CO_E_NOT_SUPPORTED	L'oggetto implementa l'interfaccia INoMarshal .

Commenti

Chiamare la funzione RoGetAgileReference in un oggetto esistente per richiedere un riferimento agile all'oggetto. L'oggetto può o non essere agile, ma l'oggetto restituito IAgileReference è agile. Il riferimento agile può essere passato a un altro appartamento nello stesso processo, in cui l'oggetto originale viene recuperato usando l'interfaccia IAgileReference .

Si tratta di una tabella di interfaccia globale esistente simile a quella esistente. Anziché interagire con GIT, viene ottenuto un oggetto IAgileReference e usato per recuperare direttamente l'oggetto. Proprio come git è solo per processo, i riferimenti agile sono per processo e non possono essere marshallati.

La funzionalità di riferimento agile offre un miglioramento delle prestazioni rispetto a GIT. Il riferimento agile esegue il marshalling ansioso per impostazione predefinita, che salva una chiamata cross-apartment nei casi in cui l'oggetto viene recuperato dal riferimento agile in un appartamento diverso da dove è stato creato il riferimento agile. Per migliorare le prestazioni aggiuntive, gli utenti della funzione RoGetAgileReference possono usare la stessa interfaccia per creare un oggetto IAgileReference e risolvere l'oggetto originale. In questo modo viene salvata una chiamata QueryInterface aggiuntiva per ottenere l'interfaccia desiderata dall'oggetto risolto.

Ad esempio, si dispone di un oggetto non agile denominato CDemoExample, che implementa le interfacce IDemo e IExample. Chiamare la funzione RoGetAgileReference e passare l'oggetto, con IID_IDemo. Si torna a un puntatore dell'interfaccia IAgileReference , che è agile, quindi è possibile passarlo a un appartamento diverso. Nell'altro appartamento chiamare il metodo Resolve con IID_IExample. Si torna a un puntatore IExample che è possibile usare all'interno di questo appartamento. Questo puntatore IExample è un proxy IExample connesso all'oggetto CDemoExample originale. Il riferimento agile gestisce la complessità delle operazioni come il marshalling manuale di un flusso e unmarshaling sull'altro lato del limite dell'appartamento.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 R2 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	combaseapi.h
Libreria	Ole32.lib
DLL	Ole32.dll

Vedi anche

AgileReferenceOptions

IAgileReference

Condividi tramite