Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

A version of this page is also available for

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

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 IDispatchinterface described by ptinfo.

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

dispidMember

[in] Identifies the member.

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

wFlags

[in] Flags describing the context of the Invokecall, 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 rgvargof the first argument that has an error.

Arguments are stored in pdispparams->rgvargin 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.

Value	Description
S_OK	Success.
DISP_E_BADPARAMCOUNT	The number of elements provided in DISPPARAMS is different from the number of arguments accepted by the method or property.
DISP_E_BADVARTYPE	An argument in DISPPARAMS is not a valid variant type.
DISP_E_EXCEPTION	The application needs to raise an exception. In this case, the structure passed in pexcepinfoshould be filled in.
DISP_E_MEMBERNOTFOUND	The requested member does not exist.
DISP_E_NONAMEDARGS	This implementation of IDispatchdoes not support named arguments.
DISP_E_OVERFLOW	An argument in DISPPARAMS could not be coerced to the specified type.
DISP_E_PARAMNOTFOUND	A parameter ID does not correspond to a parameter on the method. In this case, puArgErris set to the first argument that contains the error.
DISP_E_PARAMNOTOPTIONAL	A required parameter was omitted.
DISP_E_TYPEMISMATCH	One or more arguments could not be coerced. The index of the first parameter with the incorrect type within rgvargis returned in puArgErr.
E_INVALIDARG	An argument is invalid.
E_OUTOFMEMORY	Insufficient memory to complete the operation.
Other return codes	Any ITypeInfo::Invokeerror can be returned.

Remarks

The parameter thisis a pointer to an implementation of the interface that is being deferred to. DispInvokebuilds 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::Invokeusing DispInvoke. This function uses m_bRaiseExceptionto signal that an error occurred during the DispInvokecall.

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

Copy Code

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

Header	oleauto.h
Library	oleaut32.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later