Método IDispatch::GetIDsOfNames (oaidl.h)

Artículo
08/25/2023

Asigna un único miembro y un conjunto opcional de nombres de argumentos a un conjunto correspondiente de DISPID de enteros, que se pueden usar en llamadas posteriores a Invoke. La función dispatch DispGetIDsOfNames proporciona una implementación estándar de GetIDsOfNames.

Sintaxis

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

Parámetros

[in] riid

Reservado para uso futuro. Debe ser IID_NULL.

[in] rgszNames

Matriz de nombres que se va a asignar.

[in] cNames

Número de nombres que se van a asignar.

[in] lcid

Contexto de configuración regional en el que se van a interpretar los nombres.

[out] rgDispId

Matriz asignada por el autor de la llamada, cada elemento del que contiene un identificador (ID) correspondiente a uno de los nombres pasados en la matriz rgszNames. El primer elemento representa el nombre del miembro. Los elementos siguientes representan cada uno de los parámetros del miembro.

Valor devuelto

Este método puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	Correcto.
E_OUTOFMEMORY	Memoria insuficiente
DISP_E_UNKNOWNNAME	No se conocían uno o varios de los nombres especificados. La matriz de DISPID devuelta contiene DISPID_UNKNOWN para cada entrada que corresponde a un nombre desconocido.
DISP_E_UNKNOWNLCID	No se reconoció el identificador de configuración regional (LCID).

Comentarios

Una implementación de IDispatch puede asociar cualquier valor de identificador entero positivo con un nombre determinado. Cero está reservado para la propiedad default o Value ; –1 está reservado para indicar un nombre desconocido; y otros valores negativos se definen para otros fines. Por ejemplo, si se llama a GetIDsOfNames y la implementación no reconoce uno o varios de los nombres, devuelve DISP_E_UNKNOWNNAME y la matriz rgDispId contiene DISPID_UNKNOWN para las entradas que corresponden a los nombres desconocidos.

Los DISPID del miembro y del parámetro deben permanecer constantes durante la vigencia del objeto. Esto permite a un cliente obtener los DISPID una vez y almacenarlos en caché para su uso posterior.

Cuando se llama a GetIDsOfNames con más de un nombre, el nombre (rgszNames[0]) corresponde al nombre de miembro y los nombres posteriores corresponden a los nombres de los parámetros del miembro.

El mismo nombre puede asignarse a diferentes DISPID, dependiendo del contexto. Por ejemplo, un nombre puede tener un DISPID cuando se usa como nombre de miembro con una interfaz determinada, un identificador diferente como miembro de una interfaz diferente y una asignación diferente para cada vez que aparece como parámetro.

GetIDsOfNames se usa cuando un cliente IDispatch se enlaza a nombres en tiempo de ejecución. Para enlazar en tiempo de compilación en su lugar, un cliente IDispatch puede asignar nombres a DISPID mediante las interfaces de información de tipo descritas en Interfaces de descripción de tipo. Esto permite que un cliente se enlace a miembros en tiempo de compilación y evite llamar a GetIDsOfNames en tiempo de ejecución. Para obtener una descripción del enlace en tiempo de compilación, consulte Interfaces de descripción de tipos.

La implementación de GetIDsOfNames no distingue mayúsculas de minúsculas. Los usuarios que necesitan la asignación de nombres que distinguen mayúsculas de minúsculas deben usar interfaces de información de tipo para asignar nombres a DISPID, en lugar de llamar a GetIDsOfNames.

Precaución No puede usar este método para acceder a los valores que se han agregado dinámicamente, como los valores agregados a través de JavaScript. En su lugar, use getDispID de la interfaz IDispatchEx. Para obtener más información, consulte la interfaz IDispatchEx.

Ejemplos

El código siguiente del archivo de ejemplo Lines Lines.cpp implementa la función miembro GetIDsOfNames para la clase CLine. El objeto ActiveX o OLE usa la implementación estándar DispGetIDsOfNames. Esta implementación se basa en DispGetIdsOfNames para validar los argumentos de entrada. Para ayudar a minimizar los riesgos de seguridad, incluya código que realice una validación más sólida de los argumentos de entrada.

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

El código siguiente puede aparecer en un cliente ActiveX que llama a GetIDsOfNames para obtener el DISPID de la propiedad 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);