CoCreateInstanceEx

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

The function creates an instance of a specific class on a specific machine.

Syntax

HRESULT CoCreateInstanceEx(
  REFCLSID rclsid,
  IUnknown* punkOuter,
  DWORD dwClsCtx,
  COSERVERINFO* pServerInfo,
  ULONG cmq,
  MULTI_QI* pResults
);

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] Information about the computer on which to instantiate the object. May 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 named value, according to the interpretation of the dwClsCtx parameter.

• cmq
  [in] Number of MULTI_QI structures in pResults. Must be greater than zero.

• pResults
  [in] 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 supports the standard return value E_INVALIDARG, as well as the following:

• S_OK
  Indicates success.

• REGDB_E_CLASSNOTREG
  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.

• CLASS_E_NOAGGREGATION
  This class cannot be created as part of an aggregate.

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

• E_NOINTERFACE
  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 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.

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.

When calling CoCreateInstanceEx or CoGetClassObject with the remote machine name set to the local machine and using the CLSTCTX_REMOTE_SERVER flag, the call fails.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

See Also

Reference

COM Functions