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

Artigo
08/25/2023

Mapeia um único membro e um conjunto opcional de nomes de argumento para um conjunto correspondente de DISPIDs inteiros, que podem ser usados em chamadas subsequentes para Invocar. A função de expedição DispGetIDsOfNames fornece uma implementação padrão de GetIDsOfNames.

Sintaxe

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. Deve ser IID_NULL.

[in] rgszNames

A matriz de nomes a ser mapeada.

[in] cNames

A contagem dos nomes a serem mapeados.

[in] lcid

O contexto de localidade no qual interpretar os nomes.

[out] rgDispId

Matriz alocada pelo chamador, cada elemento do qual contém um identificador (ID) correspondente a um dos nomes passados na matriz rgszNames. O primeiro elemento representa o nome do membro. Os elementos subsequentes representam cada um dos parâmetros do membro.

Retornar valor

Esse método pode retornar um desses valores.

Código de retorno	Descrição
S_OK	Êxito.
E_OUTOFMEMORY	Sem memória.
DISP_E_UNKNOWNNAME	Um ou mais dos nomes especificados não eram conhecidos. A matriz retornada de DISPIDs contém DISPID_UNKNOWN para cada entrada que corresponde a um nome desconhecido.
DISP_E_UNKNOWNLCID	O LCID (identificador de localidade) não foi reconhecido.

Comentários

Uma implementação de IDispatch pode associar qualquer valor de ID de inteiro positivo a um determinado nome. Zero é reservado para a propriedade padrão ou Value ; –1 é reservado para indicar um nome desconhecido; e outros valores negativos são definidos para outras finalidades. Por exemplo, se GetIDsOfNames for chamado e a implementação não reconhecer um ou mais nomes, ela retornará DISP_E_UNKNOWNNAME e a matriz rgDispId conterá DISPID_UNKNOWN para as entradas que correspondem aos nomes desconhecidos.

Os DISPIDs de membro e parâmetro devem permanecer constantes durante o tempo de vida do objeto. Isso permite que um cliente obtenha os DISPIDs uma vez e armazene-os em cache para uso posterior.

Quando GetIDsOfNames é chamado com mais de um nome, o nome (rgszNames[0]) corresponde ao nome do membro e os nomes subsequentes correspondem aos nomes dos parâmetros do membro.

O mesmo nome pode ser mapeado para DISPIDs diferentes, dependendo do contexto. Por exemplo, um nome pode ter um DISPID quando é usado como um nome de membro com uma interface específica, uma ID diferente como membro de uma interface diferente e mapeamento diferente para cada vez que ele aparece como um parâmetro.

GetIDsOfNames é usado quando um cliente IDispatch é associado a nomes em tempo de execução. Para associar em tempo de compilação, um cliente IDispatch pode mapear nomes para DISPIDs usando as interfaces de informações de tipo descritas em Interfaces de Descrição de Tipo. Isso permite que um cliente se associe aos membros em tempo de compilação e evite chamar GetIDsOfNames em tempo de execução. Para obter uma descrição da associação em tempo de compilação, consulte Interfaces de descrição de tipo.

A implementação de GetIDsOfNames não diferencia maiúsculas de minúsculas. Os usuários que precisam de mapeamento de nomes que diferenciam maiúsculas de minúsculas devem usar interfaces de informações de tipo para mapear nomes para DISPIDs, em vez de chamar GetIDsOfNames.

Cuidado Você não pode usar esse método para acessar valores que foram adicionados dinamicamente, como valores adicionados por meio de JavaScript. Em vez disso, use o GetDispID da interface IDispatchEx. Para obter mais informações, consulte a interface IDispatchEx.

Exemplos

O código a seguir do arquivo de exemplo Lines Lines.cpp implementa a função membro GetIDsOfNames para a classe CLine. O objeto ActiveX ou OLE usa a implementação padrão DispGetIDsOfNames. Essa implementação depende de DispGetIdsOfNames para validar argumentos de entrada. Para ajudar a minimizar os riscos de segurança, inclua o código que executa uma validação mais robusta dos argumentos de entrada.

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

O código a seguir pode aparecer em um cliente ActiveX que chama GetIDsOfNames para obter o DISPID da propriedade 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);