Funzione DispInvoke (oleauto.h)

Articolo
03/13/2024

Chiama automaticamente le funzioni membro in un'interfaccia, in base alle informazioni sul tipo per l'interfaccia. È possibile descrivere un'interfaccia con informazioni sul tipo e implementare Invoke per l'interfaccia usando questa singola chiamata.

Sintassi

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

Parametri

_this

Implementazione dell'interfaccia IDispatch descritta da ptinfo.

ptinfo

Informazioni sul tipo che descrivono l'interfaccia.

dispidMember

Membro da richiamare. Usare GetIDsOfNames o la documentazione dell'oggetto per ottenere DISPID.

wFlags

Flag che descrivono il contesto della chiamata Invoke .

Valore	Significato
DISPATCH_METHOD	Il membro viene richiamato come metodo. Se una proprietà ha lo stesso nome, è possibile impostare sia il flag DISPATCH_PROPERTYGET.
DISPATCH_PROPERTYGET	Il membro viene recuperato come proprietà o membro dati.
DISPATCH_PROPERTYPUT	Il membro viene modificato come proprietà o membro dati.
DISPATCH_PROPERTYPUTREF	Il membro viene modificato da un'assegnazione di riferimento anziché da un'assegnazione di valore. Questo flag è valido solo quando la proprietà accetta un riferimento a un oggetto.

pparams

Puntatore a una struttura contenente una matrice di argomenti, una matrice di DISPID di argomenti per gli argomenti denominati e conta per il numero di elementi nelle matrici.

pvarResult

Puntatore a dove archiviare il risultato oppure Null se il chiamante non prevede alcun risultato. Questo argomento viene ignorato se viene specificato DISPATCH_PROPERTYPUT o DISPATCH_PROPERTYPUTREF.

pexcepinfo

Puntatore a una struttura contenente informazioni sull'eccezione. Questa struttura deve essere compilata se viene restituita DISP_E_EXCEPTION.

puArgErr

Indice all'interno di rgvarg del primo argomento che ha un errore. Gli argomenti vengono archiviati in pdispparams-rgvarg> in ordine inverso, quindi il primo argomento è quello con l'indice più alto nella matrice. Questo parametro viene restituito solo quando il valore restituito risultante è DISP_E_TYPEMISMATCH o DISP_E_PARAMNOTFOUND.

Valore restituito

Codice restituito	Descrizione
S_OK	Operazione completata.
DISP_E_BADPARAMCOUNT	Il numero di elementi forniti a DISPPARAMS è diverso dal numero di argomenti accettati dal metodo o dalla proprietà.
DISP_E_BADVARTYPE	Uno degli argomenti in DISPPARAMS non è un tipo variant valido.
DISP_E_EXCEPTION	L'applicazione deve generare un'eccezione. In questo caso, la struttura passata in pexcepinfo deve essere compilata.
DISP_E_MEMBERNOTFOUND	Il membro richiesto non esiste.
DISP_E_NONAMEDARGS	Questa implementazione di IDispatch non supporta argomenti denominati.
DISP_E_OVERFLOW	Uno degli argomenti in DISPPARAMS non è stato possibile eseguire la coercizione al tipo specificato.
DISP_E_PARAMNOTFOUND	Uno degli ID dei parametri non corrisponde a un parametro nel metodo. In questo caso, puArgErr è impostato sul primo argomento contenente l'errore.
DISP_E_PARAMNOTOPTIONAL	È stato omesso un parametro obbligatorio.
DISP_E_TYPEMISMATCH	Uno o più argomenti non possono essere coerciti. L'indice del primo parametro con il tipo non corretto all'interno di rgvarg viene restituito in puArgErr.
E_INVALIDARG	Uno dei parametri non è valido.
E_OUTOFMEMORY	Memoria insufficiente per completare l'operazione.

È anche possibile restituire uno degli errori ITypeInfo::Invoke .

Commenti

Il parametro _this è un puntatore a un'implementazione dell'interfaccia a cui viene posticipata. DispInvoke compila un frame dello stack, coercisce i parametri usando regole di coercizione standard, li esegue il push nello stack e quindi chiama la funzione membro corretta nel VTBL.

Esempio

Il codice seguente dal file di esempio Righe Lines.cpp implementa Invoke usando DispInvoke. Questa implementazione si basa su DispInvoke per convalidare gli argomenti di input. Per ridurre al minimo i rischi di sicurezza, includere il codice che esegue una convalida più affidabile degli argomenti di input.

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); 
}