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

Статья
08/22/2023

Создает аггрегатируемый объект, способный к контекстно-зависимому маршалингу.

Синтаксис

HRESULT CoCreateFreeThreadedMarshaler(
  [in]  LPUNKNOWN punkOuter,
  [out] LPUNKNOWN *ppunkMarshal
);

Параметры

[in] punkOuter

Указатель на управляющий IUnknown объекта агрегирования.

[out] ppunkMarshal

Адрес переменной указателя, которая получает указатель интерфейса на агрегируемый маршалер.

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

Эта функция может возвращать стандартное возвращаемое значение E_OUTOFMEMORY, а также следующее значение.

Код возврата	Описание
S_OK	Маршалер создан.

Функция CoCreateFreeThreadedMarshaler позволяет объекту эффективно маршалировать указатели интерфейса между потоками в одном процессе. Если объекты не поддерживают маршалинг между потоками, вам не нужно вызывать эту функцию. Он предназначен для использования на серверах DLL со свободными потоками, к которым должны напрямую обращаться все потоки в процессе, даже те потоки, которые связаны с однопоточными квартирами. Он настраивает маршалинг реального указателя памяти на другие квартиры в качестве фиктивного "прокси-сервера" и тем самым предоставляет прямой доступ ко всем вызывающим абонентам, даже если они не являются свободными.

Функция CoCreateFreeThreadedMarshaler выполняет следующие задачи:

Создает объект маршалера со свободным потоком.
Объединяет этот маршалер с объектом, заданным параметром punkOuter . Обычно это объект, для которого необходимо маршалировать указатели интерфейса.

Реализация объекта агрегирования IMarshal должна делегировать вызовы QueryInterface для IID_IMarshal В IUnknown свободнопоточного маршалера. При получении вызова маршалер со свободным потоком выполняет следующие задачи:

Проверяет контекст назначения, заданный параметром dwDestContext функции CoMarshalInterface.
Если контекст назначения MSHCTX_INPROC, копирует указатель интерфейса в поток маршалинга.
Если контекст назначения является любым другим значением, находит или создает экземпляр стандартного маршалера COM по умолчанию и делегирует его.

Значения для dwDestContext поступают из перечисления MSHCTX . MSHCTX_INPROC указывает, что указатель интерфейса должен быть маршалирован между разными потоками в одном процессе. Поскольку оба потока имеют доступ к одному адресному пространству, поток клиента может разыменовывать указатель напрямую, а не направлять вызовы к прокси-серверу. Во всех остальных случаях требуется прокси-сервер, поэтому CoCreateFreeThreadedMarshaler делегирует задание маршалинга в реализацию COM по умолчанию.

При использовании функции CoCreateFreeThreadedMarshaler следует проявлять большую осторожность. Это связано с тем, что производительность объектов, которые агрегируют маршалер со свободным потоком, достигается путем вычисляемого нарушения правил COM с постоянно присутствующим риском неопределенного поведения, если объект не работает в рамках определенных ограничений. Ниже перечислены наиболее важные ограничения.

Объект маршалера со свободным потоком не может содержать прямые указатели на интерфейсы объекта, который не агрегирует свободнопотоковой маршалер как часть своего состояния. Если объект будет использовать прямые ссылки на обычные однопоточные агрегатные объекты, он может нарушить их однопоточное свойство. Если объект должен был использовать прямые ссылки на обычные многопоточные агрегатные объекты, эти объекты могут вести себя таким образом, чтобы не было никакой чувствительности к потребностям прямых однопоточных клиентов агрегата. Например, эти объекты могут вращать новые потоки и передавать параметры потокам, которые являются ссылками на обычные однопоточные агрегатные объекты.
Объект маршалера со свободным потоком не может содержать ссылки на прокси-серверы на объекты в других квартирах. Прокси-серверы чувствительны к модели потоков и могут возвращать RPC_E_WRONG_THREAD при вызове неправильным клиентом.

Требования

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

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

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream

Share via