CoCreateInstanceEx

HRESULT CoCreateInstanceEx(clsid, pUnkOuter, grfContext, pServerInfo, dwCount, rgMultiQI)

Create an uninitialized instance of the class clsid on a specific computer, asking for a set of interface iids in pResult using the execution contexts given in grfContext. If the object is being used as part of an aggregation then pUnkOuter contains a pointer to the controlling unknown.

To help optimize round-trips to a remote computer during instantiation, this API allow the client to specify a set of interfaces to return on the object via the rgMultiQI array of MULTI_QI structures, defined as follows:

typedef struct tagMULTI_QI {
.....REFIID..........riid;..........// interface to return
.....void*...............pvObj;.....// location to return interface pointer
.....HRESULT.....hr;..........// location to return result of QueryInterface for riid
.....} MULTI_QI;

The semantics of using this API and passing a MULTI_QI array are identical to the following sequence of operations, but incur less overhead for the client, the server, and the network:

IClassFactory.....*pCF;
IUnknown..........*punk;
COMSERVERINFO csi;

CoGetClassObject(clsid, CLSCTX_SERVER, &csi, IID_IClassFactory, (void**)&pCF);
pCF->CreateInstance(NULL, IID_IUnknown, (void**)&punk);
for (DWORD i=0; i<dwCount; i++)
.....rgMultiQI[I].hr = punk->QueryInterface(rgMultiQI[i].riid, &rgMultiQI[i].pvObj);
punk->Release();

Argument	Type	Description
clsid	REFCLSID	The class of which an instance is desired
pUnkOuter	IUnknown*	The controlling unknown, if any.
grfContext	DWORD	The CLSCTX to be used.
pServerInfo	COMSERVERINFO*	Identifies the computer on which to activate the executable code. Must be NULL when grfContext does not contain CLSCTX_REMOTE_SERVER. When NULL and grfContext contains CLSCTX_REMOTE_SERVER, COM uses the default computer location for this class.
dwCount	DWORD	The number of MULTI_QI structures in the rgMultiQI array.
rgMultiQI	MULTI_QI*	An array of MULTI_QI structures. On input, each element should be cleared and the riid member set to an IID being requested. On output, one or more of the interfaces may be retrieved, and individual pvObj members will be non-NULL.

Return Value	Meaning
S_OK	Success.
CO_S_NOTALLINTERFACES	Not all of dwCount interfaces requested in the MULTI_QI array were successfully retrieved. Examine individual pvObj members of MULTI_QI to determine exactly which interfaces were returned.
Any error that can be returned from CoGetClassObject or IClassFactory::CreateInstance	Semantics as in those functions.
E_UNEXPECTED	An unknown error occurred.