CoCreateInstanceEx

Creates an instance of a specific class on a specific machine.

HRESULT CoCreateInstanceEx(

REFCLSID rclsid,

//CLSID of the object to be created

IUnknown * punkOuter,

//If part of an aggregate, the controlling IUnknown

DWORD dwClsCtx,

//CLSCTX values

COSERVERINFO* pServerInfo,

//Machine on which the object is to be instantiated

ULONG cmq,

//Number of MULTI_QI structures in rgmqResults

MULTI_QI rgmqResults

//Array of MULTI_QI structures

);

Parameters

rclsid: [in] CLSID of the object to be created.
punkOuter: [in] When non-NULL, indicates the instance is being created as part of an aggregate, and punkOuter is to be used as the new instance’s controlling IUnknown. Aggregation is currently not supported cross-process or cross-machine. When instantiating an object out of process, CLASS_E_NOAGGREGATION will be returned if punkOuter is non-NULL.
dwClsCtx: [in] Values taken from the CLSCTX enumeration.
pServerInfo: [in] Machine on which to instantiate the object. May be NULL, in which case the object is instantiated on the current machine or at the machine specified in the registry under the class’s RemoteServerName named-value, according to the interpretation of the dwClsCtx parameter. See the CLSCTX documentation for details).
cmq: [in] Number of MULTI_QI structures in rgmqResults. Must be greater than zero.
rgmqResults: Array of MULTI_QI structures. Each structure has three members: the identifier for a requested interface (pIID), the location to return the interface pointer (pItf) and the return value of the call to QueryInterface (hr).

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK: Indicates success.
CO_S_NOTALLINTERFACES: At least one, but not all of the interfaces requested in the rgmqResults array were successfully retrieved. The hr field of each of the MULTI_QI structures in rgmqResults indicates with S_OK or E_NOINTERFACE whether the specific interface was returned.
E_NOINTERFACE: None of the interfaces requested in the rgmqResults array were successfully retrieved.

Remarks

CoCreateInstanceEx creates a single uninitialized object associated with the given CLSID on a specified remote machine. This is an extension of the function CoCreateInstance, which creates an object on the local machine only. In addition, rather than requesting a single interface and obtaining a single pointer to that interface, CoCreateInstanceEx makes it possible to specify an array of structures, each pointing to an interface identifier (IID) on input, and, on return, containing (if available) a pointer to the requested interface and the return value of the QueryInterface call for that interface. This permits fewer round trips between machines.

The CoCreateInstanceEx helper function encapsulates three calls: first, to CoGetClassObject to connect to the class object associated with the specified CLSID, specifying the machine location of the class; second, to IClassFactory::CreateInstance to create an uninitialized instance, and finally, to IClassFactory::Release, to release the class object.

The object so created must still be initialized through a call to one of the initialization interfaces (such as IPersistStorage:::Load). The two helper functions, CoGetInstanceFromFile and CoGetInstanceFromIStorage encapsulate both the instance creation and initialization from the obvious sources.

REFCLSID rclsid,	//CLSID of the object to be created
IUnknown * punkOuter,	//If part of an aggregate, the controlling IUnknown
DWORD dwClsCtx,	//CLSCTX values
COSERVERINFO* pServerInfo,	//Machine on which the object is to be instantiated
ULONG cmq,	//Number of MULTI_QI structures in rgmqResults
MULTI_QI rgmqResults	//Array of MULTI_QI structures
);