Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function creates a new object and initializes it from a file using IPersistFile::Load.

Syntax 

HRESULT CoGetInstanceFromFile(
  COSERVERINFO* 
pServerInfo,
  CLSID* 
pclsid,
  IUnknown* 
punkOuter,
  DWORD 
dwClsCtx,
  DWORD 
grfMode,
  OLECHAR* 
szName,
  ULONG 
cmq,
  MULTI_QI* 
rgmqResults
);

Parameters

pServerInfo

[in] Pointer to a COSERVERINFOstructure 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 RemoteServerNamenamed-value for the class in the registry, or (3) at the machine where the szNamefile resides if the ActivateAtStoragenamed-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 szNameas 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 punkOuteris 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 punkOuteris non-NULL.

dwClsCtx

[in] Values taken from the CLSCTXenumeration.

grfMode

[in] Flags specifying how the file is to be opened. Values are taken from the STGMenumeration.

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_QIstructures. 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 rgmqResultsarray were successfully retrieved. The hrfield of each of the MULTI_QIstructures in rgmqResultsindicates with S_OK or E_NOINTERFACE whether or not the specific interface was returned.

E_NOINTERFACE

None of the interfaces requested in the rgmqResultsarray were successfully retrieved.

Remarks

CoGetInstanceFromFilecreates 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 dwClsCtxis set to CLSCTX_REMOTE_SERVER and pServerInfois NULL, if the class is registered with the ActivateAtStoragesub-key or has no associated registry information, this function will instantiate an object on the machine where szNameresides, providing the least possible network traffic.

    For example, if szNamespecified "\\myserver\users\johndo\file", the object would be instantiated on the "myserver" machine, and the object would access the file directly.

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

Requirements

Header objbase.h
Library ole32.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also