CoGetInstanceFromIStorage  R7.JER

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

HRESULT CoGetInstanceFromIStorage(

Parameters

pServerInfo

[in] Pointer to a COSERVERINFOXK3RZ2 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._W2BG 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 ActivateAtStorage1MU9QUT 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:StatXY11ZW 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 CLSCTXV8M0PK enumeration.

pstg

Pointer to storage to initialize the object with using IPersistStorage::Load5V6EFR. May not be NULL.

cmq

Number of MULTI_QI structures in rgmqResults. Must be greater than zero.

rgmqResults

Array of MULTI_QIAMCFWU 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::Load5V6EFR. This function is similar to creating an instance using CoCreateInstanceEx1LNBERE 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 ActivateAtStorage1MU9QUT 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 StgCreateDocfileYN.O6Q, specifying  \\myserver\users\johndo\file , the object would be instantiated on the  myserver  machine, and the object would access the storage object directly.

See Also