Поделиться через

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

  • Статья

Создает вспомогательный объект внедрения OLE, используя предоставленный приложением код, агрегированный с фрагментами обработчика объектов OLE по умолчанию. Этот вспомогательный объект можно создать и использовать в определенном контексте и роли, как определено вызывающим объектом.

Синтаксис

HRESULT OleCreateEmbeddingHelper(
  [in]  REFCLSID       clsid,
  [in]  LPUNKNOWN      pUnkOuter,
  [in]  DWORD          flags,
  [in]  LPCLASSFACTORY pCF,
  [in]  REFIID         riid,
  [out] LPVOID         *lplpObj
);

Параметры

[in] clsid

CLSID класса, который требуется помочь.

[in] pUnkOuter

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

[in] flags

DWORD, содержащий флаги, указывающие роль и контекст создания для вспомогательного средства внедрения. Юридические значения см. в следующем разделе Примечания.

[in] pCF

Указатель на интерфейс IClassFactory на объект класса, который функция использует для создания вторичного объекта. В некоторых случаях это значение может иметь значение NULL. Дополнительные сведения см. в разделе "Примечания".

[in] riid

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

[out] lplpObj

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

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

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

Код возврата Описание
E_OUTOFMEMORY
 Недостаточно памяти для операции.
E_INVALIDARG
Один или несколько параметров недопустимы.
E_UNEXPECTED
 Произошла непредвиденная ошибка.
E_NOINTERFACE
 Предоставленный идентификатор интерфейса недопустим.

Комментарии

Функция OleCreateEmbeddingHelper создает объект , который поддерживает те же реализации интерфейса, что и в обработчике по умолчанию, но который имеет дополнительные обработчики, позволяющие использовать его в более общем плане, чем просто в качестве объекта обработчика. Следующие два вызова дают одинаковый результат:

OleCreateEmbeddingHelper(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER | 
    EMBDHLP_CREATENOW, NULL, iid, ppvObj) 
 
OleCreateDefaultHandler(clsid, pUnkOuter, iid, ppvObj)

Вспомогательный элемент внедрения является агрегируемым; pUnkOuter — это управляющая функция IUnknown агрегата, частью которого должен быть вспомогательный компонент внедрения. Он используется для создания нового экземпляра обработчика OLE по умолчанию, который можно использовать для поддержки объектов в различных ролях. Вызывающий объект передает указатель на свою реализацию IClassFactoryв OleCreateEmbeddingHelper. Затем этот объект и обработчик по умолчанию объединяются для создания нового вспомогательного объекта внедрения.

Функция OleCreateEmbeddingHelper обычно используется для поддержки одной из следующих реализаций:

  • Приложение объекта EXE, которое используется как контейнер и сервер и поддерживает вставку объектов в себя. В этом случае CreateEmbeddingHelper позволяет объекту поддерживать интерфейсы, которые обычно поддерживаются только в обработчике. Для этого приложение должно сначала зарегистрировать свой ИДЕНТИФИКАТОР CLSID для разных контекстов, выполнив два вызова регистрации функции CoRegisterClassObject , а не один, как показано ниже:
    CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER, 
        REGCLS_MULTI_SEPARATE...) 
 
    CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER, 
    
        REGCLS_MULTI_SEPARATE...)

    В этих вызовах вы будете передавать различные реализации фабрики классов каждому из pUnkCfLocal и pUnkCfInProc. Фабрика классов, на которую указывает pUnkCfLocal , будет использоваться для создания объектов, которые должны быть внедрены в удаленный процесс. В обычном случае используется объект обработчика, связанный с клиентом. Однако, когда сервер создает объект и внедряет его в себя, pUnkCfInProc указывает на объект класса, который может создать объект, поддерживающий интерфейсы обработчиков. Локальный класс используется для создания объекта, а внутрипроцессный класс создает вспомогатель внедрения, передавая указатель на фабрику класса первого объекта в pCF.

  • Пользовательский обработчик внутрипроцессных объектов, в этом случае библиотека DLL создает вспомогатель внедрения путем передачи указателя на частную реализацию IClassFactory в pCF.
Параметр flags указывает, как будет использоваться вспомогательная функция внедрения, а также как и когда инициализируется вспомогательная функция внедрения. Значения для флагов получаются с помощью or-ing значений из следующей таблицы.
Значения параметра flags Назначение
EMBDHLP_INPROC_HANDLER Создает вспомогательное средство внедрения, которое можно использовать с приложениями объектов DLL; В частности, вспомогающая предоставляет функции кэширования обработчика объектов по умолчанию.
EMBDHLP_INPROC_SERVER Создает вспомогательное средство внедрения, которое будет использоваться как часть внутрипроцессного сервера. PCF не может иметь значение NULL.
EMBDHLP_CREATENOW Немедленно создает дополнительный объект с помощью pCF ; Если pCF имеет значение NULL, используется стандартный диспетчер прокси-серверов.
EMBDHLP_DELAYCREATE Откладывает создание дополнительного объекта до тех пор, пока он не потребуется (когда вспомогательная служба перейдет в состояние выполнения) для повышения скорости и использования памяти. PCF не должен иметь значение NULL. Флаг EMBDHLP_INPROC_HANDLER нельзя использовать с этим флагом.

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header ole2.h
Библиотека Ole32.lib
DLL Ole32.dll
Набор API ext-ms-win-com-ole32-l1-1-5 (появилось в Windows 10 версии 10.0.15063)

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

OleCreateDefaultHandler