OleCreateEmbeddingHelper - OLE Programmer's Reference (ole.hlp)

OleCreateEmbeddingHelper

Creates an OLE embedding helper object using application-supplied code aggregated with pieces of the OLE default object handler. This helper object can be created and used in a specific context and role, as determined by the caller.

HRESULT OleCreateEmbeddingHelper(

REFCLSID clsid,	//The ID of the class to be helped
LPUNKNOWN pUnkOuter,	//Points to controlling IUnknown
DWORD flags,	//Specifies the purpose for the helper
LPCLASSFACTORY pCF,	//Points to IClassFactory instance
REFIID riid,	//The ID of the interface sought by caller
LPVOID * lplpvObj	//Points to return point for helper
);

Parameters
clsid

Specifies the CLSID of the class to be helped.

pUnkOuter

Points to the controlling IUnknown interface if the handler is to be aggregated; NULL if it is not to be aggregated.

flags

Specifies the role and creation context for the embedding helper; see the following comments for legal values.

pCF

Points to the application's IClassFactory instance; can be NULL.

riid

Specifies the interface ID desired by the caller.

lplpvObj

Points to where to return the newly created embedding helper.

Return Values
S_OK

Indicates that the OLE embedding helper was created successfully.

E_NOINTERFACE

Indicates that the interface is not supported by the object.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

Indicates that one or more arguments are invalid.

E_UNEXPECTED

Indicates that an unexpected error occurred.

Comments
The OleCreateEmbeddingHelper function is used to create a new instance of the OLE default handler, which can be used to support objects in various roles. The caller passes a pointer to its IClassFactory implementation to OleCreateEmbeddingHelper. This object and the default handler are then aggregated to create the new embedding helper object.

The OleCreateEmbeddingHelper function is usually used to support one of the following implementations:

An object application that is being used as both a container and a server, and which supports inserting objects into itself. In this case, the application registers its CLSID for different contexts by calling the CoRegisterClassObject function and specifying CLSCTX_LOCAL_SERVER | CLSCTX_INPROC_SERVER as the dwClsctx parameter, and REGCLS_MULTI_SEPARATE as the flags parameter. The local class is used to create the object and the in-process class creates the embedding helper, passing in the pointer to the first object's class factory in pCF.
An in-process object handler, in which case, the DLL creates the embedding helper by passing in a pointer to a private implementation of IClassFactory in pCF.

The flags parameter indicates how the embedding helper is to be used and how and when the embedding helper is initialized. The values for flags are obtained by OR-ing together values from the following table:

*Values for flags* Parameter**	Purpose
EMBDHLP_INPROC_HANDLER	Creates an embedding helper that can be used with DLL object applications; specifically, the helper exposes the caching features of the default object handler.
EMBDHLP_INPROC_SERVER	Creates an embedding helper that can be used with in-process servers.
EMBDHLP_CREATENOW	EMBDHLP_CREATENOW creates the application-supplied piece of the object immediately.
EMBDHLP_DELAYCREATE	EMBDHLP_DELAYCREATE delays creating the application-supplied piece of the object until the object is put into its running state.

Calling

OleCreateEmbeddingHelper
(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER | EMBDHLP_CREATENOW,
NULL, riid, ppvObj)

is the same as calling

OleCreateDefaultHandler(clsid, pUnkOuter, riid, ppvObj)