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

Статья
02/29/2024

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

Синтаксис

HRESULT OleCreateEx(
  [in]  REFCLSID        rclsid,
  [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] rclsid

Определяет класс создаваемого объекта.

[in] riid

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

[in] dwFlags

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

[in] renderopt

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

[in] cFormats

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

[in] rgAdvf

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

[in] rgFormatEtc

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

[in] lpAdviseSink

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

[out] rgdwConnection

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

[in] pClientSite

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

[in] pStg

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

[out] ppvObj

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

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

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

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

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

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

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

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

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

Требования

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