CoCreateInstanceEx function (combaseapi.h)
Creates an instance of a specific class on a specific computer.
Syntax
HRESULT CoCreateInstanceEx(
[in] REFCLSID Clsid,
[in] IUnknown *punkOuter,
[in] DWORD dwClsCtx,
[in] COSERVERINFO *pServerInfo,
[in] DWORD dwCount,
[in, out] MULTI_QI *pResults
);
Parameters
[in] Clsid
The CLSID of the object to be created.
[in] punkOuter
If this parameter 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-computer. When instantiating an object out of process, CLASS_E_NOAGGREGATION will be returned if punkOuter is non-NULL.
[in] dwClsCtx
A value from the CLSCTX enumeration.
[in] pServerInfo
Information about the computer on which to instantiate the object. See COSERVERINFO. This parameter can be NULL, in which case the object is instantiated on the local computer or at the computer specified in the registry under the class's RemoteServerName value, according to the interpretation of the dwClsCtx parameter.
[in] dwCount
The number of structures in pResults. This value must be greater than 0.
[in, out] pResults
An 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 value
This function can return the standard return value E_INVALIDARG, as well as the following values.
| Return code | Description |
|---|---|
|
Indicates success. |
|
A specified class is not registered in the registration database. Also can indicate that the type of server you requested in the CLSCTX enumeration is not registered or the values for the server types in the registry are corrupt. |
|
This class cannot be created as part of an aggregate. |
|
At least one, but not all of the interfaces requested in the pResults array were successfully retrieved. The hr member of each of the MULTI_QI structures in pResults indicates with S_OK or E_NOINTERFACE whether the specific interface was returned. |
|
None of the interfaces requested in the pResults array were successfully retrieved. |
Remarks
CoCreateInstanceEx creates a single uninitialized object associated with the given CLSID on a specified remote computer. This is an extension of the function CoCreateInstance, which creates an object on the local computer 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 computers.
This function encapsulates three calls: first, to CoGetClassObject to connect to the class object associated with the specified CLSID, specifying the 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). Two functions, CoGetInstanceFromFile and CoGetInstanceFromIStorage encapsulate both the instance creation and initialization from the obvious sources.
The COSERVERINFO structure passed as the pServerInfo parameter contains the security settings that COM will use when creating a new instance of the specified object. Note that this parameter does not influence the security settings used when making method calls on the instantiated object. Those security settings are configurable, on a per-interface basis, with the CoSetProxyBlanket function. Also see, IClientSecurity::SetBlanket.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | combaseapi.h (include Objbase.h) |
| Library | Ole32.lib |
| DLL | Ole32.dll |