Provides access to properties and methods exposed by an object. The dispatch function DispInvoke Function provides a standard implementation of IDispatch::Invoke.
HRESULT Invoke( DISPID dispIdMember, REFIID riid, LCID lcid, WORD wFlags, DISPPARAMS FAR* pDispParams, VARIANT FAR* pVarResult, EXCEPINFO FAR* pExcepInfo, unsigned int FAR* puArgErr );
The return value obtained from the returned HRESULT is one of the following:
The number of elements provided to DISPPARAMS is different from the number of arguments accepted by the method or property.
One of the arguments in rgvarg is not a valid variant type.
The application needs to raise an exception. In this case, the structure passed in pExcepInfo should be filled in.
The requested member does not exist, or the call to Invoke tried to set the value of a read-only property.
This implementation of IDispatch does not support named arguments.
One of the arguments in rgvarg could not be coerced to the specified type.
One of the parameter DISPIDs does not correspond to a parameter on the method. In this case, puArgErr should be set to the first argument that contains the error. You get the error DISP_E_PARAMNOTFOUND when you try to set a property and you have not initialized the cNamedArgs and rgdispidNamedArgs elements of your DISPPARAMS structure.
One or more of the arguments could not be coerced. The index within rgvarg of the first parameter with the incorrect type is returned in the puArgErr parameter.
The interface identifier passed in riid is not IID_NULL.
The member being invoked interprets string arguments according to the LCID, and the LCID is not recognized. If the LCID is not needed to interpret arguments, this error should not be returned.
A required parameter was omitted.
Generally, you should not implement Invoke directly. Instead, use the dispatch interface to create functions CreateStdDispatch and DispInvoke. For details, refer to CreateStdDispatch, DispInvoke, Creating the IDispatch Interface and Exposing ActiveX Objects.
If some application-specific processing needs to be performed before calling a member, the code should perform the necessary actions, and then call ITypeInfo::Invoke to invoke the member. ITypeInfo::Invoke acts exactly like IDispatch::Invoke. The standard implementations of IDispatch::Invoke created by CreateStdDispatch and DispInvoke defer to ITypeInfo::Invoke.
In an ActiveX client, IDispatch::Invoke should be used to get and set the values of properties, or to call a method of an ActiveX object. The dispIdMember argument identifies the member to invoke. The DISPIDs that identify members are defined by the implementor of the object and can be determined by using the object's documentation, the IDispatch::GetIDsOfNames function, or the ITypeInfo interface.
When you use IDispatch::Invoke() with DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF, you have to specially initialize the cNamedArgs and rgdispidNamedArgs elements of your DISPPARAMS structure with the following:
DISPID dispidNamed = DISPID_PROPERTYPUT; dispparams.cNamedArgs = 1; dispparams.rgdispidNamedArgs = &dispidNamed;
The information that follows addresses developers of ActiveX clients and others who use code to expose ActiveX objects. It describes the behavior that users of exposed objects should expect.