 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. |
This function automatically calls member functions on an interface, given the type information for the interface.
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
- Pointer to an implementation of the IDispatchinterface described by ptinfo.
- ptinfo
- Pointer to the type information that describes the interface.
- dispidMember
- Identifies the member. Use GetIDsOfNamesor the object's documentation to obtain the DISPID.
- wFlags
- 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 an array of arguments, an array of argument DISPIDs for named arguments, and counts for number of elements in the arrays.
- pvarResult
- Pointer to where the result is to be stored, or NULL if the caller expects no result. This argument is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified.
- pexcepinfo
- Pointer to a structure that contains exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.
- puArgErr
- 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 Values
One of the values obtained from the returned HRESULTand described in the following table is returned.
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 One of the arguments 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 One of the arguments in DISPPARAMS could not be coerced to the specified type. DISP_E_PARAMNOTFOUND One of the parameter IDs 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 of the arguments could not be coerced. The index of the first parameter with the incorrect type within rgvargis returned in puArgErr. E_INVALIDARG One of the arguments is invalid. E_OUTOFMEMORY Insufficient memory to complete the operation. Other return codes Any of the ITypeInfo::Invokeerrors can also 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 into this function any invalid and, under some circumstances, NULL pointers will result in 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.
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
Runs on Versions Defined in Include Link to Windows CE OS 2.0 and later Oleauto.h Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.