Функция OleCreateLinkEx (ole2.h)

Статья
08/25/2023

Расширяет функциональные возможности OleCreateLink , поддерживая более эффективное создание экземпляров объектов в контейнерах, требующих кэширования нескольких форматов презентаций или данных, а не одного формата, поддерживаемого OleCreateLink.

Синтаксис

HRESULT OleCreateLinkEx(
  [in]  LPMONIKER       pmkLinkSrc,
  [in]  REFIID          riid,
  [in]  DWORD           dwFlags,
  [in]  DWORD           renderopt,
  [in]  ULONG           cFormats,
  [in]  DWORD           *rgAdvf,
  [in]  LPFORMATETC     rgFormatEtc,
  [in]  IAdviseSink     *lpAdviseSink,
  [out] DWORD           *rgdwConnection,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Параметры

[in] pmkLinkSrc

Указатель на моникер на объект, на который необходимо создать ссылку.

[in] riid

Ссылка на идентификатор интерфейса возвращаемого объекта.

[in] dwFlags

Этот параметр может иметь значение 0 или OLECREATE_LEAVERUNNING (0x00000001).

[in] renderopt

Значение, взятое из перечисления OLERENDER .

[in] cFormats

Если параметр renderopt OLERENDER_FORMAT, указывает количество структур FORMATETC в массиве rgFormatEtc , которое должно быть по крайней мере одной. Во всех остальных случаях этот параметр должен быть равен нулю.

[in] rgAdvf

Если параметр renderopt OLERENDER_FORMAT, указывает на массив элементов DWORD , каждый из которых представляет собой сочетание значений из перечисления ADVF . Каждый элемент этого массива передается в качестве параметра advf в вызов IOleCache::Cache или IDataObject::D Advise в зависимости от того, имеет ли pAdviseSinkзначение NULL или не null (см. ниже). Во всех остальных случаях этот параметр должен иметь значение NULL.

[in] rgFormatEtc

Если параметр renderopt OLERENDER_FORMAT, указывает на массив структур FORMATETC . Если pAdviseSink имеет значение NULL, каждый элемент этого массива передается в качестве параметра pFormatEtc для вызова объекта IOleCache::Cache. При этом данные и кэш презентации, управляемые внутрипроцессным обработчиком объектов (обычно это обработчик по умолчанию), заполняется презентацией или другими кэшируемыми данными. Если pAdviseSink не равно NULL, каждый элемент этого массива передается в качестве параметра pFormatEtc в вызов IDataObject::D Advise. Это позволяет вызывающей объекту (обычно ole-контейнеру) выполнять собственное кэширование или обработку данных, полученных из объекта .

[in] lpAdviseSink

Если параметр renderopt OLERENDER_FORMAT, это может быть допустимый указатель IAdviseSink , указывающий на пользовательское кэширование или обработку рекомендаций по данным, или значение NULL, указывающее кэширование форматов данных по умолчанию.

[out] rgdwConnection

Расположение для возврата массива значений dwConnection , возвращаемых при регистрации интерфейса IAdviseSink для каждого консультативного подключения с помощью IDataObject::D Advise, или NULL , если возвращенные консультативные подключения не требуются. Этот параметр должен иметь значение NULL, если pAdviseSink имеет значение NULL.

[in] pClientSite

Указатель на основной интерфейс, через который объект будет запрашивать службы из своего контейнера. Этот параметр может иметь значение NULL. В этом случае вызывающий объект отвечает за создание клиентского сайта как можно скорее с помощью IOleObject::SetClientSite.

[in] pStg

Указатель на хранилище, используемое для объекта, и все данные по умолчанию или кэширование презентации, установленные для него.

[out] ppvObj

Адрес выходной переменной указателя, которая получает указатель интерфейса, запрошенный в riid. После успешного возврата *ppvObj содержит запрошенный указатель интерфейса на вновь созданный объект.

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

Эта функция возвращает S_OK при успешном выполнении. Ниже перечислены другие возможные значения.

Код возврата	Описание
E_NOINTERFACE	Предоставленный идентификатор интерфейса недопустим.
E_INVALIDARG	Один или несколько параметров недопустимы.

Существующие функции создания экземпляров (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile и OleCreateLinkFromData) создают только одну презентацию или кэш формата данных в расположении кэша по умолчанию (в потоках "\001OlePresXXX" переданного IStorage) во время создания экземпляра. Кроме того, эти кэши должны создаваться, когда объект переходит в состояние выполнения. Поскольку большинству приложений требуется кэширование по крайней мере в двух презентациях (на экране и на принтере) и может потребоваться кэширование данных в другом формате или расположении от обработчика, приложения, как правило, должны запускать и завершать сервер объектов несколько раз, чтобы создавать кэши данных во время создания объекта, т. е. вставлять объект, вставлять объект из файла. и Вставить объект .

Расширенная версия этих функций создания решает эту проблему. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx и OleCreateLinkFromDataEx содержат следующие новые параметры: dwFlags для указания дополнительных параметров, cFormats для указания количества форматов для кэширования, rgAdvf из перечисления ADVF , для указания флагов рекомендаций для каждого кэшируемого формата, pAdviseSink Чтобы указать, требуется ли кэширование представления (обработчик по умолчанию) или данных (не обработчик по умолчанию), rgdwConnection возвращает IDataObject::D Advise cookies и rgFormatEtc, массив форматов, а не один формат.

Контейнеры, требующие кэширования нескольких презентаций от их имени обработчиком объекта, могут просто вызывать эти функции и указывать количество форматов в cFormats, флаги ADVF для каждого формата в rgAdvf и набор форматов в rgFormatEtc. Эти контейнеры передают значение NULL для pAdviseSink.

Контейнеры, выполняющие все свои собственные кэширование данных или презентаций, выполняют те же действия, но передают не nullpAdviseSink. Они выполняют собственное кэширование или обработку объекта или данных во время IAdviseSink::OnDataChange. Как правило, такие контейнеры никогда не устанавливают консультативные связи с ADVF_NODATA, хотя им это не запрещается.

Эти новые функции предназначены для составных документов OLE. Используя эти функции, приложения могут избежать повторных шагов запуска и инициализации, необходимых для текущих функций. Они предназначены для приложений-контейнеров составных документов OLE, использующих кэширование данных и презентаций по умолчанию, а также для приложений, которые обеспечивают собственное кэширование и передачу данных из базовой поддержки IDataObject::D Advise .

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	ole2.h
Библиотека	Ole32.lib
DLL	Ole32.dll