CoGetInstanceFromIStorage

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

HRESULT CoGetInstanceFromIStorage(
  COSERVERINFO * pServerInfo,
                         //Pointer to COSERVERINFO struct indicating 
                         // remote system
  CLSID * pclsid,        //Pointer to the CLSID of the object to be 
                         // created
  Iunknown * punkOuter,  //If part of an aggregate, pointer to the 
                         // controlling IUnknown
  DWORD dwClsCtx,        //Values taken from the CLSCTX enumeration
  Istorage * pstg,       //Pointer to storage from which object is 
                         // to be initialized
  ULONG cmq,             //Number of MULTI_QI structures in 
                         // rgmqResults
  MULTI_QI * rgmqResults //Array of MULTI_QI structures
);
 

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

Values taken from the CLSCTX enumeration.

pstg

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 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 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 thisfunction 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.

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in objbase.h.
  Import Library: Included as a resource in ole32.dll.

See Also

CoCreateInstanceEx, CoGetInstanceFromFile, CLSCTX, Instance Creation Helper Functions