Метод IDispatch::GetIDsOfNames (oaidl.h)

Статья
08/25/2023

Сопоставляет один член и необязательный набор имен аргументов с соответствующим набором целых чисел 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

Массив, выделенный вызывающим объектом, каждый элемент которого содержит идентификатор, соответствующий одному из имен, передаваемых в массиве rgszNames. Первый элемент представляет имя элемента. Последующие элементы представляют каждый из параметров элемента.

Возвращаемое значение

Этот метод может возвращать одно из этих значений.

Код возврата	Описание
S_OK	Успешно.
E_OUTOFMEMORY	Недостаточно памяти.
DISP_E_UNKNOWNNAME	Одно или несколько указанных имен не известны. Возвращаемый массив DISPID содержит DISPID_UNKNOWN для каждой записи, соответствующей неизвестному имени.
DISP_E_UNKNOWNLCID	Идентификатор языкового стандарта (LCID) не распознан.

Реализация IDispatch может связать любое положительное целочисленное значение идентификатора с заданным именем. Нуль зарезервирован для значения по умолчанию или свойства Value ; Значение –1 зарезервировано для указания неизвестного имени; и другие отрицательные значения определяются для других целей. Например, если вызывается метод GetIDsOfNames и реализация не распознает одно или несколько имен, она возвращает DISP_E_UNKNOWNNAME, а массив rgDispId содержит DISPID_UNKNOWN для записей, соответствующих неизвестным именам.

DisPID элемента и параметра должны оставаться постоянными в течение всего времени существования объекта. Это позволяет клиенту получить DISPID один раз и кэшировать их для последующего использования.

При вызове GetIDsOfNames с несколькими именами имя (rgszNames[0]) соответствует имени члена, а последующие имена соответствуют именам параметров элемента.

Одно и то же имя может сопоставляться с разными идентификаторами DISPID в зависимости от контекста. Например, имя может иметь DISPID, если оно используется в качестве имени члена с определенным интерфейсом, другой идентификатор как член другого интерфейса и другое сопоставление для каждого случая, когда оно появляется в качестве параметра.

GetIDsOfNames используется, когда клиент IDispatch привязывается к именам во время выполнения. Для привязки во время компиляции клиент IDispatch может сопоставлять имена с DISPID с помощью интерфейсов сведений о типе, описанных в разделе Интерфейсы описания типов. Это позволяет клиенту привязаться к членам во время компиляции и избежать вызова GetIDsOfNames во время выполнения. Описание привязки во время компиляции см. в разделе Интерфейсы описания типов.

Реализация GetIDsOfNames не учитывает регистр. Пользователи, которым требуется сопоставление имен с учетом регистра, должны использовать интерфейсы сведений о типах для сопоставления имен с DISPID, а не вызывать GetIDsOfNames.

Осторожностью Этот метод нельзя использовать для доступа к значениям, добавленным динамически, например значениям, добавленным с помощью JavaScript. Вместо этого используйте GetDispID интерфейса IDispatchEx. Дополнительные сведения см. в интерфейсе IDispatchEx.

Примеры

Следующий код из примера файла Lines Lines.cpp реализует функцию-член GetIDsOfNames для класса CLine. Объект ActiveX или OLE использует стандартную реализацию DispGetIDsOfNames. Эта реализация использует DispGetIdsOfNames для проверки входных аргументов. Чтобы свести к минимуму риски безопасности, включите код, который выполняет более надежную проверку входных аргументов.

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

Следующий код может отображаться в клиенте ActiveX, который вызывает GetIDsOfNames для получения DISPID свойства CLineColor .

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);