CoGetInstanceFromFile 函数 (objbase.h)
创建一个新对象,并使用 IPersistFile::Load 从文件初始化它。
语法
HRESULT CoGetInstanceFromFile(
[in, optional] COSERVERINFO *pServerInfo,
[in, optional] CLSID *pClsid,
[in, optional] IUnknown *punkOuter,
[in] DWORD dwClsCtx,
[in] DWORD grfMode,
[in] OLECHAR *pwszName,
[in] DWORD dwCount,
[in, out] MULTI_QI *pResults
);
参数
[in, optional] pServerInfo
指向 COSERVERINFO 结构的指针,该结构指定要实例化对象的计算机以及要使用的身份验证设置。 此参数可以为 NULL,在这种情况下,对象在当前计算机上实例化,在 类的 RemoteServerName 注册表值下指定的计算机上实例化,或者在 pwszName 文件所在的计算机上(如果为类指定 了 ActivateAtStorage 值或没有本地注册表信息)。
[in, optional] pClsid
指向要创建的对象的类标识符的指针。 此参数可以为 NULL,在这种情况下,调用 GetClassFile,使用 pwszName 作为其参数来获取要实例化的对象的类。
[in, optional] punkOuter
如果为非 NULL,则指示实例是作为聚合的一部分创建的,而 punkOuter 将用作指向新实例控制 IUnknown 的指针。 跨进程或跨计算机不支持聚合。 在进程外实例化对象时,如果 punkOuter 非 NULL,将返回CLASS_E_NOAGGREGATION。
[in] dwClsCtx
CLSCTX 枚举中的值。
[in] grfMode
指定如何打开文件。 请参阅 STGM 常量。
[in] pwszName
用于使用 IPersistFile::Load 初始化对象的文件。 此参数不能为 NULL。
[in] dwCount
pResults 中的结构数。 此参数必须大于 0。
[in, out] pResults
MULTI_QI结构的数组。 每个结构都有三个成员:请求的接口 (pIID) 的标识符、 (pItf) 返回接口指针的位置,以及对 QueryInterface (小时) 调用的返回值。
返回值
此函数可以返回E_INVALIDARG的标准返回值,以及以下值。
返回代码 | 说明 |
---|---|
|
函数已成功检索所有接口。 |
|
至少一个,但不是所有 在 pResults 数组中请求的接口已成功检索。 每个MULTI_QI结构的 hr 成员使用 S_OK 或 E_NOINTERFACE 指示是否返回了特定接口。 |
|
未成功检索 pResults 数组中请求的任何接口。 |
注解
CoGetInstanceFromFile 创建一个新对象,并使用 IPersistFile::Load 从文件初始化它。 此函数的结果类似于创建一个调用 CoCreateInstanceEx 的实例,然后初始化对 IPersistFile::Load 的调用,但具有以下重要区别:
- 在远程计算机上实例化对象时,此函数所需的网络往返次数更少。
- 如果 dwClsCtx 设置为 CLSCTX_REMOTE_SERVER pServerInfo 为 NULL,则如果类已注册到 ActivateAtStorage 子键或没有关联的注册表信息,则此函数将实例化 pwszName 所在的计算机上的对象,从而提供尽可能少的网络流量。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
目标平台 | Windows |
标头 | objbase.h |
Library | Ole32.lib |
DLL | ComBase.dll |