IDispatch::GetIDsOfNames-Methode (oaidl.h)

Artikel
08/25/2023

Ordnet einen einzelnen Member und einen optionalen Satz von Argumentnamen einem entsprechenden Satz ganzzahliger DISPIDs zu, die bei nachfolgenden Aufrufen von Invoke verwendet werden können. Die Dispatchfunktion DispGetIDsOfNames stellt eine Standardimplementierung von GetIDsOfNames bereit.

Syntax

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

Parameter

[in] riid

Für zukünftige Verwendung reserviert. Muss IID_NULL sein.

[in] rgszNames

Das Array von Namen, die zugeordnet werden sollen.

[in] cNames

Die Anzahl der zuzuordnenden Namen.

[in] lcid

Der Gebietsschemakontext, in dem die Namen interpretiert werden sollen.

[out] rgDispId

Vom Aufrufer zugeordnetes Array, dessen Jedes Element einen Bezeichner (ID) enthält, der einem der Namen entspricht, die im rgszNames-Array übergeben werden. Das erste Element stellt den Membernamen dar. Die nachfolgenden Elemente stellen jeden Parameter des Members dar.

Rückgabewert

Diese Methode kann einen dieser Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Erfolg.
E_OUTOFMEMORY	Nicht genügend Arbeitsspeicher.
DISP_E_UNKNOWNNAME	Mindestens einer der angegebenen Namen war nicht bekannt. Das zurückgegebene Array von DISPIDs enthält DISPID_UNKNOWN für jeden Eintrag, der einem unbekannten Namen entspricht.
DISP_E_UNKNOWNLCID	Der Gebietsschemabezeichner (LCID) wurde nicht erkannt.

Hinweise

Eine IDispatch-Implementierung kann einen beliebigen positiven ganzzahligen ID-Wert einem angegebenen Namen zuordnen. Null ist für die Standard- oder Value-Eigenschaft reserviert. –1 ist reserviert, um einen unbekannten Namen anzugeben; und andere negative Werte werden für andere Zwecke definiert. Wenn beispielsweise GetIDsOfNames aufgerufen wird und die Implementierung mindestens einen der Namen nicht erkennt, wird DISP_E_UNKNOWNNAME zurückgegeben, und das rgDispId-Array enthält DISPID_UNKNOWN für die Einträge, die den unbekannten Namen entsprechen.

Der Member und der Parameter DISPIDs müssen für die Lebensdauer des Objekts konstant bleiben. Dadurch kann ein Client die DISPIDs einmal abrufen und zur späteren Verwendung zwischenspeichern.

Wenn GetIDsOfNames mit mehr als einem Namen aufgerufen wird, entspricht der Vorname (rgszNames[0]) dem Membernamen, und nachfolgende Namen entsprechen den Namen der Parameter des Members.

Derselbe Name kann je nach Kontext verschiedenen DISPIDs zugeordnet werden. Beispielsweise kann ein Name eine DISPID aufweisen, wenn er als Membername mit einer bestimmten Schnittstelle verwendet wird, eine andere ID als Member einer anderen Schnittstelle und eine andere Zuordnung für jedes Mal, wenn er als Parameter angezeigt wird.

GetIDsOfNames wird verwendet, wenn ein IDispatch-Client zur Laufzeit an Namen gebunden wird. Um stattdessen zur Kompilierzeit zu binden, kann ein IDispatch-Client Namen dispiDs zuordnen, indem er die unter Typbeschreibungsschnittstellen beschriebenen Typinformationsschnittstellen verwendet. Dadurch kann ein Client zur Kompilierzeit eine Bindung an Member herstellen und getIDsOfNames zur Laufzeit nicht aufrufen. Eine Beschreibung der Bindung zur Kompilierzeit finden Sie unter Typbeschreibungsschnittstellen.

Bei der Implementierung von GetIDsOfNames wird die Groß-/Kleinschreibung nicht beachtet. Benutzer, die die Namenszuordnung zwischen Groß- und Kleinschreibung benötigen, sollten Typinformationsschnittstellen verwenden, um Namen DISPIDs zuzuordnen, anstatt GetIDsOfNames aufzurufen.

Vorsicht Sie können diese Methode nicht verwenden, um auf dynamisch hinzugefügte Werte zuzugreifen, z. B. werte, die über JavaScript hinzugefügt wurden. Verwenden Sie stattdessen die GetDispID der IDispatchEx-Schnittstelle. Weitere Informationen finden Sie unter der IDispatchEx-Schnittstelle.

Beispiele

Der folgende Code aus der Lines-Beispieldatei Lines.cpp implementiert die GetIDsOfNames-Memberfunktion für die CLine-Klasse. Das ActiveX- oder OLE-Objekt verwendet die Standardimplementierung DispGetIDsOfNames. Diese Implementierung basiert auf DispGetIdsOfNames , um Eingabeargumente zu überprüfen. Um Sicherheitsrisiken zu minimieren, schließen Sie Code ein, der eine robustere Überprüfung der Eingabeargumente durchführt.

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

Der folgende Code kann in einem ActiveX-Client angezeigt werden, der GetIDsOfNames aufruft , um die DISPID der CLineColor-Eigenschaft abzurufen.

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