Função DispInvoke (oleauto.h)

Artigo
08/25/2023

Chama automaticamente funções membro em uma interface, considerando as informações de tipo da interface. Você pode descrever uma interface com informações de tipo e implementar Invoke para a interface usando essa única chamada.

Sintaxe

HRESULT DispInvoke(
  void       *_this,
  ITypeInfo  *ptinfo,
  DISPID     dispidMember,
  WORD       wFlags,
  DISPPARAMS *pparams,
  VARIANT    *pvarResult,
  EXCEPINFO  *pexcepinfo,
  UINT       *puArgErr
);

Parâmetros

_this

Uma implementação da interface IDispatch descrita por ptinfo.

ptinfo

As informações de tipo que descrevem a interface.

dispidMember

O membro a ser invocado. Use GetIDsOfNames ou a documentação do objeto para obter o DISPID.

wFlags

Sinalizadores que descrevem o contexto da chamada Invoke .

Valor	Significado
DISPATCH_METHOD	O membro é invocado como um método . Se uma propriedade tiver o mesmo nome, esse e o sinalizador DISPATCH_PROPERTYGET poderão ser definidos.
DISPATCH_PROPERTYGET	O membro é recuperado como uma propriedade ou membro de dados.
DISPATCH_PROPERTYPUT	O membro é alterado como uma propriedade ou membro de dados.
DISPATCH_PROPERTYPUTREF	O membro é alterado por uma atribuição de referência, em vez de uma atribuição de valor. Esse sinalizador só é válido quando a propriedade aceita uma referência a um objeto .

pparams

Ponteiro para uma estrutura que contém uma matriz de argumentos, uma matriz de DISPIDs de argumento para argumentos nomeados e contagens para o número de elementos nas matrizes.

pvarResult

Ponteiro para onde o resultado deve ser armazenado ou Null se o chamador não espera nenhum resultado. Esse argumento será ignorado se DISPATCH_PROPERTYPUT ou DISPATCH_PROPERTYPUTREF for especificado.

pexcepinfo

Ponteiro para uma estrutura que contém informações de exceção. Essa estrutura deverá ser preenchida se DISP_E_EXCEPTION for retornado.

puArgErr

O índice dentro de rgvarg do primeiro argumento que tem um erro. Os argumentos são armazenados em pdispparams-rgvarg> em ordem inversa, portanto, o primeiro argumento é aquele com o índice mais alto na matriz. Esse parâmetro é retornado somente quando o valor retornado resultante é DISP_E_TYPEMISMATCH ou DISP_E_PARAMNOTFOUND.

Retornar valor

Código de retorno	Descrição
S_OK	Êxito.
DISP_E_BADPARAMCOUNT	O número de elementos fornecidos ao DISPPARAMS é diferente do número de argumentos aceitos pelo método ou propriedade.
DISP_E_BADVARTYPE	Um dos argumentos no DISPPARAMS não é um tipo variante válido.
DISP_E_EXCEPTION	O aplicativo precisa gerar uma exceção. Nesse caso, a estrutura passada em pexcepinfo deve ser preenchida.
DISP_E_MEMBERNOTFOUND	O membro solicitado não existe.
DISP_E_NONAMEDARGS	Essa implementação de IDispatch não dá suporte a argumentos nomeados.
DISP_E_OVERFLOW	Um dos argumentos em DISPPARAMS não pôde ser coagido ao tipo especificado.
DISP_E_PARAMNOTFOUND	Uma das IDs de parâmetro não corresponde a um parâmetro no método . Nesse caso, puArgErr é definido como o primeiro argumento que contém o erro.
DISP_E_PARAMNOTOPTIONAL	Um parâmetro necessário foi omitido.
DISP_E_TYPEMISMATCH	Não foi possível coagir um ou mais argumentos. O índice do primeiro parâmetro com o tipo incorreto dentro de rgvarg é retornado em puArgErr.
E_INVALIDARG	Um dos parâmetros não é válido.
E_OUTOFMEMORY	Memória insuficiente para concluir a operação.

Qualquer um dos erros ITypeInfo::Invoke também pode ser retornado.

Comentários

O parâmetro _this é um ponteiro para uma implementação da interface que está sendo adiada. DispInvoke cria um quadro de pilha, impõe parâmetros usando regras de coerção padrão, envia-os por push na pilha e, em seguida, chama a função membro correta no VTBL.

Exemplos

O código a seguir do arquivo de exemplo Linhas Lines.cpp implementa Invoke usando DispInvoke. Essa implementação depende do DispInvoke 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
CLines::Invoke(
   DISPID dispidMember,
   REFIID riid,
   LCID lcid,
   WORD wFlags,
   DISPPARAMS * pdispparams,
   VARIANT * pvarResult,
   EXCEPINFO* pexcepinfo,
   UINT * puArgErr)
{
   return DispInvoke(
   this, m_ptinfo,
   dispidMember, wFlags, pdispparams,
   pvarResult, pexcepinfo, puArgErr); 
}