iDispatch：：GetIDsOfNames 方法 (oaidl.h)

项目
08/25/2023

将单个成员和一组可选的参数名称映射到一组相应的整数 DISPID，这些整数 DISPID 可用于对 Invoke 的后续调用。调度函数 DispGetIDsOfNames 提供 GetIDsOfNames 的标准实现。

语法

HRESULT GetIDsOfNames(
  [in]  REFIID   riid,
  [in]  LPOLESTR *rgszNames,
  [in]  UINT     cNames,
  [in]  LCID     lcid,
  [out] DISPID   *rgDispId
);

参数

[in] riid

保留供将来使用。必须为 IID_NULL。

[in] rgszNames

要映射的名称数组。

[in] cNames

要映射的名称的计数。

[in] lcid

要在其中解释名称的区域设置上下文。

[out] rgDispId

调用方分配的数组，其每个元素都包含一个标识符 (ID) 对应于在 rgszNames 数组中传递的名称之一。第一个元素表示成员名称。后续元素表示成员的每个参数。

返回值

此方法可以返回其中一个值。

返回代码	说明
S_OK	成功。
E_OUTOFMEMORY	内存不足。
DISP_E_UNKNOWNNAME	一个或多个指定名称未知。返回的 DISPID 数组包含对应于未知名称的每个条目的DISPID_UNKNOWN。
DISP_E_UNKNOWNLCID	无法识别 LCID) (区域设置标识符。

注解

IDispatch 实现可以将任何正整数 ID 值与给定名称相关联。零是为默认值或 Value 属性保留的;保留 –1 以指示未知名称;和其他负值是为其他目的定义的。例如，如果调用 GetIDsOfNames ，并且实现无法识别一个或多个名称，则返回DISP_E_UNKNOWNNAME，并且 rgDispId 数组包含对应于未知名称的条目的DISPID_UNKNOWN。

成员和参数 DISPID 在对象的生存期内必须保持不变。这允许客户端获取 DISPID 一次，并缓存它们以供以后使用。

当使用多个名称调用 GetIDsOfNames 时，名字 (rgszNames[0]) 对应于成员名称，后续名称对应于成员参数的名称。

同一名称可能会映射到不同的 DISPID，具体取决于上下文。例如，当某个名称用作具有特定接口的成员名称时，该名称可能具有 DISPID，将不同的 ID 用作不同接口的成员，并且每次它显示为参数时具有不同的映射。

当 IDispatch 客户端在运行时绑定到名称时，将使用 GetIDsOfNames。若要改为在编译时绑定， IDispatch 客户端可以使用类型说明接口中描述的类型信息接口将名称映射到 DISPID。这允许客户端在编译时绑定到成员，并避免在运行时调用 GetIDsOfNames 。有关编译时绑定的说明，请参阅类型说明接口。

GetIDsOfNames 的实现不区分大小写。需要区分大小写的名称映射的用户应使用类型信息接口将名称映射到 DISPID，而不是调用 GetIDsOfNames。

谨慎不能使用此方法访问已动态添加的值，例如通过 JavaScript 添加的值。请改用 IDispatchEx 接口的 GetDispID。有关详细信息，请参阅 IDispatchEx 接口。

示例

Lines 示例文件中的以下代码Lines.cpp实现 CLine 类的 GetIDsOfNames 成员函数。 ActiveX 或 OLE 对象使用标准实现 DispGetIDsOfNames。此实现依赖于 DispGetIdsOfNames 来验证输入参数。为了帮助最大程度地降低安全风险，请包含对输入参数执行更可靠的验证的代码。

STDMETHODIMP 
CLine::GetIDsOfNames(
      REFIID riid,
      OLECHAR ** rgszNames,
      UINT cNames,
      LCID lcid,
      DISPID * rgDispId)
{
      return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

以下代码可能会出现在调用 GetIDsOfNames 以获取 CLineColor 属性的 DISPID 的 ActiveX 客户端中。

HRESULT hresult;
IDispatch * pdisp = (IDispatch *)NULL;
DISPID dispid;
OLECHAR * szMember = "color";

// Code that sets a pointer to the dispatch (pdisp) is omitted.

hresult = pdisp->GetIDsOfNames(
   IID_NULL,
   &szMember,
   1, LOCALE_SYSTEM_DEFAULT,
   &dispid);