Функция RoGetAgileReference (combaseapi.h)

Статья
08/22/2023

Создает гибкую ссылку для объекта, заданного заданным интерфейсом.

Синтаксис

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

Параметры

[in] options

Параметры регистрации.

[in] riid

Идентификатор интерфейса объекта, для которого получается гибкая ссылка.

[in] pUnk

Указатель на интерфейс, инкапсулированный в гибкой ссылке. Он должен иметь тот же тип, что и riid. Это может быть указатель на внутрипроцессный объект или указатель на прокси объекта.

[out] ppAgileReference

Справочник по гибкой модели для объекта . Вызовите метод Resolve , чтобы локализовать объект в квартире, в которой вызывается Resolve .

Возвращаемое значение

Эта функция может возвращать одно из этих значений.

Возвращаемое значение	Описание
S_OK	Функция успешно завершена.
E_INVALIDARG	Недопустимый параметр options .
E_OUTOFMEMORY	Не удалось создать гибкую ссылку из-за нехватки памяти.
E_NOINTERFACE	Параметр pUnk не поддерживает идентификатор интерфейса, указанный параметром riid .
CO_E_NOT_SUPPORTED	Объект реализует интерфейс INoMarshal .

Вызовите функцию RoGetAgileReference для существующего объекта, чтобы запросить гибкую ссылку на объект. Объект может быть гибким, но возвращенный объект IAgileReference является гибким. Гибкая ссылка может быть передана другому объекту в рамках того же процесса, где исходный объект извлекается с помощью интерфейса IAgileReference .

Это концептуально похоже на существующую таблицу глобального интерфейса (GIT). Вместо взаимодействия с GIT получается IAgileReference , который используется для получения объекта напрямую. Так же, как GIT предназначен только для каждого процесса, гибкие ссылки являются для каждого процесса и не могут быть маршалированы.

Функция гибкого справочника обеспечивает повышение производительности по сравнению с GIT. Гибкая ссылка по умолчанию выполняет неотложную маршалинг, которая сохраняет межквартирный вызов в случаях, когда объект извлекается из гибкой ссылки в квартире, отличной от того, где была создана гибкая ссылка. Для дополнительного повышения производительности пользователи функции RoGetAgileReference могут использовать тот же интерфейс для создания IAgileReference и разрешения исходного объекта. При этом сохраняется дополнительный вызов QueryInterface для получения требуемого интерфейса из разрешенного объекта.

Например, у вас есть негибкий объект CDemoExample, который реализует интерфейсы IDemo и IExample. Вызовите функцию RoGetAgileReference и передайте объект с IID_IDemo. Вы получите указатель интерфейса IAgileReference , который является гибким, чтобы его можно было передать в другое помещение. В другой квартире вызовите метод Resolve с IID_IExample. Вы получите обратно указатель IExample, который вы можете использовать в этой квартире. Этот указатель IExample является прокси-сервером IExample, подключенным к исходному объекту CDemoExample. Гибкий справочник обрабатывает сложность операций, таких как маршалинг вручную в поток и размежевание на другой стороне границы квартиры.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 R2 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	combaseapi.h
Библиотека	Ole32.lib
DLL	Ole32.dll

См. также раздел

AgileReferenceOptions

IAgileReference

Share via