COM
Expand Minimize

CoCreateInstanceEx function

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

Syntax


HRESULT CoCreateInstanceEx(
  _In_     REFCLSID rclsid,
  _In_     IUnknown *punkOuter,
  _In_     DWORD dwClsCtx,
  _In_     COSERVERINFO *pServerInfo,
  _In_     DWORD dwCount,
  _Inout_  MULTI_QI *pResults
);

Parameters

rclsid [in]

The CLSID of the object to be created.

punkOuter [in]

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.

dwClsCtx [in]

A value from the CLSCTX enumeration.

pServerInfo [in]

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.

dwCount [in]

The number of structures in pResults. This value must be greater than 0.

pResults [in, out]

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 codeDescription
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 member 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 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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Objbase.h

Library

Ole32.lib

DLL

Ole32.dll

See also

CoGetInstanceFromFile
CoGetInstanceFromIStorage

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.