CoGetInstanceFromFile

Creates a new object and initializes it from a file using IPersistFile::Load.

HRESULT CoGetInstanceFromFile(

COSERVERINFO * pServerInfo,

//Pointer to COSERVERINFO struct indicating remote system

CLSID* pclsid,

//Pointer to the class of the object to create

IUnknown * punkOuter,

//If part of an aggregate, pointer to the controlling IUnknown

DWORD dwClsCtx,

//CLSCTX values

OLECHAR* szName,

//File to initialize the object with

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 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 szName file resides if the ActivateAtStorage named-value is specified for the class in the registry or there is no local registry information.
pclsid: [in] Pointer to the class of the object to create. May be NULL, in which case there is a call to GetClassFile, using szName as its parameter to get the class of the object to be instantiated.
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.
szName: [in] File to initialize the object with using IPersistFile::Load. May not be NULL.
cmq: [in] Number of MULTI_QI structures in rgmqResults. Must be greater than zero.
rgmqResults: [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 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 or not the specific interface was returned.
E_NOINTERFACE: None of the interfaces requested in the rgmqResults array were successfully retrieved.

Remarks

CoGetInstanceFromFile creates a new object and initializes it from a file using IPersistFile::Load. The result of this function is similar to creating an instance with a call to CoCreateInstanceEx, followed by an initializing call to IPersistFile::Load, with the following important distinctions:

Fewer network round trips are required by this function when instantiating an object on a remote machine.
In the case where dwClsCtx is set to CLSCTX_REMOTE_SERVER and pServerInfo is NULL, if the class is registered with the ActivateAtStorage sub-key or has no associated registry information, this function will instantiate an object on the machine where szName resides, providing the least possible network traffic. For example, if szName specified “\\myserver\users\johndo\file”, the object would be instantiated on the “myserver” machine, and the object would access the file directly.

COSERVERINFO * pServerInfo,	//Pointer to COSERVERINFO struct indicating remote system
CLSID* pclsid,	//Pointer to the class of the object to create
IUnknown * punkOuter,	//If part of an aggregate, pointer to the controlling IUnknown
DWORD dwClsCtx,	//CLSCTX values
OLECHAR* szName,	//File to initialize the object with
ULONG cmq,	//Number of MULTI_QI structures in rgmqResults
MULTI_QI * rgmqResults	//Array of MULTI_QI structures
);