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.
See Also