Metodo IDispatch::GetIDsOfNames (oaidl.h)

Articolo
08/25/2023

Esegue il mapping di un singolo membro e di un set facoltativo di nomi di argomenti a un set corrispondente di DISPID integer, che può essere usato nelle chiamate successive a Invoke. La funzione dispatch DispGetIDsOfNames fornisce un'implementazione standard di GetIDsOfNames.

Sintassi

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

Parametri

[in] riid

Riservato per usi futuri. Deve essere IID_NULL.

[in] rgszNames

Matrice di nomi di cui eseguire il mapping.

[in] cNames

Numero dei nomi da mappare.

[in] lcid

Contesto delle impostazioni locali in cui interpretare i nomi.

[out] rgDispId

Matrice allocata dal chiamante, ogni elemento di che contiene un identificatore (ID) corrispondente a uno dei nomi passati nella matrice rgszNames. Il primo elemento rappresenta il nome del membro. Gli elementi successivi rappresentano ognuno dei parametri del membro.

Valore restituito

Questo metodo può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	Operazione completata.
E_OUTOFMEMORY	Memoria insufficiente.
DISP_E_UNKNOWNNAME	Uno o più nomi specificati non sono noti. La matrice restituita di DISPID contiene DISPID_UNKNOWN per ogni voce corrispondente a un nome sconosciuto.
DISP_E_UNKNOWNLCID	L'identificatore delle impostazioni locali (LCID) non è stato riconosciuto.

Commenti

Un'implementazione IDispatch può associare qualsiasi valore ID intero positivo a un determinato nome. Zero è riservato per la proprietà predefinita o Value ; –1 è riservato per indicare un nome sconosciuto; e altri valori negativi vengono definiti per altri scopi. Ad esempio, se viene chiamato GetIDsOfNames e l'implementazione non riconosce uno o più nomi, restituisce DISP_E_UNKNOWNNAME e la matrice rgDispId contiene DISPID_UNKNOWN per le voci che corrispondono ai nomi sconosciuti.

Il membro e il parametro DISPID devono rimanere costanti per la durata dell'oggetto. In questo modo un client può ottenere i DISPID una sola volta e memorizzarli nella cache per usarli in un secondo momento.

Quando GetIDsOfNames viene chiamato con più nomi, il nome (rgszNames[0]) corrisponde al nome del membro e i nomi successivi corrispondono ai nomi dei parametri del membro.

Lo stesso nome può essere mappato a DISPID diversi, a seconda del contesto. Ad esempio, un nome può avere un DISPID quando viene usato come nome di membro con una particolare interfaccia, un ID diverso come membro di un'interfaccia diversa e un mapping diverso per ogni volta che viene visualizzato come parametro.

GetIDsOfNames viene usato quando un client IDispatch viene associato ai nomi in fase di esecuzione. Per eseguire il binding in fase di compilazione, invece, un client IDispatch può eseguire il mapping dei nomi ai DISPID usando le interfacce di informazioni sul tipo descritte in Interfacce di descrizione del tipo. In questo modo un client può eseguire l'associazione ai membri in fase di compilazione ed evitare di chiamare GetIDsOfNames in fase di esecuzione. Per una descrizione dell'associazione in fase di compilazione, vedere Interfacce di descrizione del tipo.

L'implementazione di GetIDsOfNames non fa distinzione tra maiuscole e minuscole. Gli utenti che necessitano di mapping dei nomi con distinzione tra maiuscole e minuscole devono usare interfacce di informazioni sul tipo per eseguire il mapping dei nomi a DISPID anziché chiamare GetIDsOfNames.

Attenzione Non è possibile usare questo metodo per accedere ai valori aggiunti dinamicamente, ad esempio i valori aggiunti tramite JavaScript. Usare invece GetDispID dell'interfaccia IDispatchEx. Per altre informazioni, vedere l'interfaccia IDispatchEx.

Esempio

Il codice seguente del file di esempio Lines Lines.cpp implementa la funzione membro GetIDsOfNames per la classe CLine. L'oggetto ActiveX o OLE usa l'implementazione standard DispGetIDsOfNames. Questa implementazione si basa su DispGetIdsOfNames per convalidare gli argomenti di input. Per ridurre al minimo i rischi per la sicurezza, includere codice che esegue una convalida più affidabile degli argomenti di input.

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

Il codice seguente potrebbe essere visualizzato in un client ActiveX che chiama GetIDsOfNames per ottenere il DISPID della proprietà 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);