CoGetInstanceFromIStorage

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates a new object and initializes it from a storage object through an internal call to IPersistStorage::Load.

Syntax

HRESULT CoGetInstanceFromIStorage(
  COSERVERINFO* pServerInfo,
  CLSID* pclsid,
  IUnknown* punkOuter,
  DWORD dwClsCtx,
  IStorage* pstg,
  ULONG cmq,
  MULTI_QI* rgmqResults
);

Parameters

• pServerInfo
  [in] Pointer to a COSERVERINFO structure that specifies the machine on which to instantiate the object and the authentication setting to be used.

  May be NULL, in which case the object is either instantiated (1) on the current machine, (2) at the machine specified under the RemoteServerName named-value for the class in the registry, or (3) at the machine where the storage object pointed to by pstg is located if the class is registered with ActivateAtStorage specified or has no local registry information.

• pclsid
  [in] Pointer to the class identifier (CLSID) of the object to be created. May be NULL, in which case there is a call to IStorage::Stat to find the class of the object.

• punkOuter
  [in] When non-NULL, indicates the instance is being created as part of an aggregate, and punkOuter is to be used as the pointer to 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.

• pstg
  [in] Pointer to storage to initialize the object with using IPersistStorage::Load. May not be NULL.

• cmq
  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 Value

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 pointer was retrieved.

• E_NOINTERFACE
  None of the interfaces requested in the rgmqResults array were successfully retrieved.

Remarks

CoGetInstanceFromIStorage creates a new object and initializes it from a storage object through a call to IPersistStorage::Load. This function is similar to creating an instance using CoCreateInstanceEx followed by a call to IPersistStorage::Load, with the following important distinctions:

• Fewer network round trips are required by this function when instantiating remotely.
• In the case where dwClsCtx is set to CLSCTX_REMOTE_SERVER and pServerInfo is NULL, if the class is registered with the ActivateAtStorage named value or has no associated registry information, this function will instantiate an object on the same machine where the storage object pointed to by pstg resides, providing the least possible network traffic.
  For example, if pstg were obtained through a call to StgCreateDocfile, specifying "\\myserver\users\johndo\file", the object would be instantiated on the "myserver" machine, and the object would access the storage object directly.

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

Requirements

See Also

Reference

COM Functions