RoGetAgileReference function (combaseapi.h)

Article
10/13/2021

Creates an agile reference for an object specified by the given interface.

Syntax

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

Parameters

[in] options

The registration options.

[in] riid

The interface ID of the object for which an agile reference is being obtained.

[in] pUnk

Pointer to the interface to be encapsulated in an agile reference. It must be the same type as riid. It may be a pointer to an in-process object or a pointer to a proxy of an object.

[out] ppAgileReference

The agile reference for the object. Call the Resolve method to localize the object into the apartment in which Resolve is called.

Return value

This function can return one of these values.

Return value	Description
S_OK	The function completed successfully.
E_INVALIDARG	The options parameter in invalid.
E_OUTOFMEMORY	The agile reference couldn't be constructed due to an out-of-memory condition.
E_NOINTERFACE	The pUnk parameter doesn't support the interface ID specified by the riid parameter.
CO_E_NOT_SUPPORTED	The object implements the INoMarshal interface.

Remarks

Call the RoGetAgileReference function on an existing object to request an agile reference to the object. The object may or may not be agile, but the returned IAgileReference is agile. The agile reference can be passed to another apartment within the same process, where the original object is retrieved by using the IAgileReference interface.

This is conceptually similar to the existing Global Interface Table (GIT). Rather than interacting with the GIT, an IAgileReference is obtained and used to retrieve the object directly. Just as the GIT is per-process only, agile references are per-process and can't be marshaled.

The agile reference feature provides a performance improvement over the GIT. The agile reference performs eager marshaling by default, which saves a cross-apartment call in cases where the object is retrieved from the agile reference in an apartment that's different from where the agile reference was created. For additional performance improvement, users of the RoGetAgileReference function can use the same interface to create an IAgileReference and resolve the original object. This saves an additional QueryInterface call to obtain the desired interface from the resolved object.

For example, you have a non-agile object named CDemoExample, which implements the IDemo and IExample interfaces. Call the RoGetAgileReference function and pass the object, with IID_IDemo. You get back an IAgileReference interface pointer, which is agile, so you can pass it to a different apartment. In the other apartment, call the Resolve method, with IID_IExample. You get back an IExample pointer that you can use within this apartment. This IExample pointer is an IExample proxy that's connected to the original CDemoExample object. The agile reference handles the complexity of operations like manually marshaling to a stream and unmarshaling on the other side of the apartment boundary.

Requirements

Requirement	Value
Minimum supported client	Windows 8.1 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	combaseapi.h
Library	Ole32.lib
DLL	Ole32.dll