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

Fornece acesso a propriedades e métodos expostos por um objeto. A função de expedição DispInvoke fornece uma implementação padrão de Invoke.

Sintaxe

HRESULT Invoke(
  [in]      DISPID     dispIdMember,
  [in]      REFIID     riid,
  [in]      LCID       lcid,
  [in]      WORD       wFlags,
  [in, out] DISPPARAMS *pDispParams,
  [out]     VARIANT    *pVarResult,
  [out]     EXCEPINFO  *pExcepInfo,
  [out]     UINT       *puArgErr
);

Parâmetros

[in] dispIdMember

Identifica o membro. Use GetIDsOfNames ou a documentação do objeto para obter o identificador de expedição.

[in] riid

Reservado para uso futuro. Deve ser IID_NULL.

[in] lcid

O contexto de localidade no qual interpretar argumentos. O lcid é usado pela função GetIDsOfNames e também é passado para Invoke para permitir que o objeto interprete seus argumentos específicos a uma localidade.

Aplicativos que não dão suporte a vários idiomas nacionais podem ignorar esse parâmetro. Para obter mais informações, consulte Suporte a várias linguagens nacionais e exposição de objetos ActiveX.

[in] 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 .

[in, out] pDispParams

Ponteiro para uma estrutura DISPPARAMS 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.

[out] pVarResult

Ponteiro para o local 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.

[out] pExcepInfo

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

[out] 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 da matriz. Esse parâmetro é retornado somente quando o valor retornado resultante é DISP_E_TYPEMISMATCH ou DISP_E_PARAMNOTFOUND. Esse argumento pode ser definido como nulo. Para obter detalhes, consulte Retornando erros.

Retornar valor

Esse método pode retornar um desses valores.

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_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.
DISP_E_UNKNOWNINTERFACE	O identificador de interface passado no riid não é IID_NULL.
DISP_E_UNKNOWNLCID	O membro que está sendo invocado interpreta argumentos de cadeia de caracteres de acordo com o LCID e o LCID não é reconhecido. Se o LCID não for necessário para interpretar argumentos, esse erro não deverá ser retornado
DISP_E_PARAMNOTOPTIONAL	Um parâmetro necessário foi omitido.

Comentários

Em geral, você não deve implementar Invocar diretamente. Em vez disso, use a interface de expedição para criar funções CreateStdDispatch e DispInvoke. Para obter detalhes, consulte CreateStdDispatch, DispInvoke, Criando a interface IDispatch e expondo objetos ActiveX.

Se algum processamento específico do aplicativo precisar ser executado antes de chamar um membro, o código deverá executar as ações necessárias e, em seguida, chamar ITypeInfo::Invoke para invocar o membro. ITypeInfo::Invoke atua exatamente como Invoke. As implementações padrão de Invoke criadas por CreateStdDispatch e DispInvoke adiam para ITypeInfo::Invoke.

Em um cliente ActiveX, Invoke deve ser usado para obter e definir os valores das propriedades ou para chamar um método de um objeto ActiveX. O argumento dispIdMember identifica o membro a ser invocado. Os DISPIDs que identificam membros são definidos pelo implementador do objeto e podem ser determinados usando a documentação do objeto, a função IDispatch::GetIDsOfNames ou a interface ITypeInfo .

Ao usar IDispatch::Invoke() com DISPATCH_PROPERTYPUT ou DISPATCH_PROPERTYPUTREF, você precisa inicializar especialmente os elementos cNamedArgs e rgdispidNamedArgs de sua estrutura DISPPARAMS com o seguinte:

DISPID dispidNamed = DISPID_PROPERTYPUT;
dispparams.cNamedArgs = 1;
dispparams.rgdispidNamedArgs = &dispidNamed;

As informações a seguir abordam desenvolvedores de clientes ActiveX e outros que usam código para expor objetos ActiveX. Ele descreve o comportamento que os usuários de objetos expostos devem esperar.

Requisitos

Requisito	Valor
Plataforma de Destino	Windows
Cabeçalho	oaidl.h

Confira também

IDispatch