Windows Dev Center

Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

RoGetAgileReference function

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

Syntax


HRESULT WINAPI RoGetAgileReference(
  _In_  AgileReferenceOptions options,
  _In_  REFIID                riid,
  _In_  IUnknown              *pUnk,
  _Out_ IAgileReference       **ppAgileReference
);

Parameters

options [in]

The registration options.

riid [in]

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

pUnk [in]

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.

ppAgileReference [out]

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 valueDescription
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

Minimum supported client

Windows 8.1 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 R2 [desktop apps | Windows Store apps]

Header

ComBaseApi.h

Library

Ole32.lib

DLL

Ole32.dll

See also

AgileReferenceOptions
IAgileReference

 

 

Community Additions

Show:
© 2015 Microsoft