DispInvoke

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function automatically calls member functions on an interface, given the type information for the interface.

Syntax

HRESULT DispInvoke(
  void FAR* _this, 
  ITypeInfo FAR* ptinfo, 
  DISPID dispidMember, 
  unsigned short wFlags, 
  DISPPARAMS FAR* pparams, 
  VARIANT FAR* pvarResult, 
  EXCEPINFO pexcepinfo, 
  unsigned int FAR* puArgErr 
);

Parameters

• _this
  [in] Pointer to an implementation of the IDispatch interface described by ptinfo.

• ptinfo
  [in] Pointer to the type information that describes the interface.

• dispidMember
  [in] Identifies the member.

  Use IDispatch::GetIDsOfNames or the object's documentation to obtain the DISPID.

• wFlags
  [in] Flags describing the context of the Invoke call, as follows.

  Value	Description
  DISPATCH_METHOD	The member is invoked as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag can be set.
  DISPATCH_PROPERTYGET	The member is retrieved as a property or data member.
  DISPATCH_PROPERTYPUT	The member is changed as a property or data member.
  DISPATCH_PROPERTYPUTREF	The member is changed by a reference assignment, rather than a value assignment. This flag is valid only when the property accepts a reference to an object.

• pparams
  Pointer to a structure that contains the following:

  • An array of arguments
  • An array of argument DISPIDs for named arguments
  • Counts for number of elements in the arrays

• pvarResult
  [out] Pointer to where the result is to be stored, orNULL if the caller expects no result.

  This argument is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified.

• pexcepinfo
  [out] Pointer to a structure that contains exception information.

  This structure should be filled in if DISP_E_EXCEPTION is returned.

• puArgErr
  [out] Index within rgvarg of the first argument that has an error.

  Arguments are stored in pdispparams->rgvarg in reverse order, so the first argument is the one with the highest index in the array.

  This parameter is returned only when the resulting return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND.

Return Value

Returns the HRESULT values shown in the following table.

Remarks

The parameter this is a pointer to an implementation of the interface that is being deferred to. DispInvoke builds a stack frame, coerces parameters using standard coercion rules, pushes them on the stack, and then calls the correct member function in the VTBL.

Passing invalid (and under some circumstances NULL) pointers to this function causes an unexpected termination of the application.

Example

The following code from the Lines sample file Lines.cpp implements IDispatch::Invoke using DispInvoke. This function uses m_bRaiseException to signal that an error occurred during the DispInvoke call.

STDMETHODIMP
CLines::Invoke(
  DISPID dispidMember,
  REFIID riid,
  LCID lcid,
  WORD wFlags,
  DISPPARAMS FAR* pdispparams,
  VARIANT FAR* pvarResult,
  EXCEPINFO FAR* pexcepinfo,
  UINT FAR* puArgErr)
{
  return DispInvoke(this,
                    m_ptinfo,
                    dispidMember, 
                    wFlags, 
                    pdispparams,
                    pvarResult,
                    pexcepinfo, 
                    puArgErr); 
}

Requirements

See Also

Reference

Automation Functions
IDispatch
IDispatch::GetIDsOfNames
IDispatch::Invoke