CMInvoke
(Available in 01 TS COM - TS_COM_DelegateIDispatch)
Purpose
Invoke, Execute a method or property of the interface
Syntax
// See MSDN doc
oDIObject:CMInvoke( ... )
Arguments
ParamX
|
Param description
|
dwDispIDMember
|
DWORD
|
pstruIID
|
_WinGUID
|
dwLCID
|
DWORD
|
wFlags
|
WORD
|
pstruDispParams
|
_WinDISPPARAMS
|
pstruVarian
|
_WinVARIANT
|
pstruExeptionInfo
|
_WinEXCEPINFO
|
pdwArgErr
|
DWORD PTR
|
Description
Invoke, Execute a method or property of the interface
MSDN ==== IDispatch::Invoke Provides access to properties and methods exposed by an object. The dispatch function DispInvoke 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 );
Parameters
dispIdMember Identifies the member. Use GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid Reserved for future use. Must be IID_NULL.
lcid The locale context in which to interpret arguments. The lcid is used by the GetIDsOfNames function, and is also passed to IDispatch::Invoke to allow the object to interpret its arguments specific to a locale. Applications that do not support multiple national languages can ignore this parameter. For more information, refer to "Supporting Multiple National Languages" in Chapter 2, "Exposing ActiveX Objects."
wFlags Flags describing the context of the Invoke call, include: 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 may 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.
pDispParams Pointer to a structure containing an array of arguments, an array of argument DISPIDs for named arguments, and counts for the number of elements in the arrays. See the Comments section that follows for a description of the DISPPARAMS structure.
pVarResult Pointer to the location 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. Can be NULL.
puArgErr The 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. This argument can be set to null. For details, see "Returning Errors" in the following Comments section.
Return Value The return value obtained from the returned HRESULT is one of the following:
Return value Meaning
S_OK Success.
DISP_E_BADPARAMCOUNT The number of elements provided to DISPPARAMS is different from the number of arguments accepted by the method or property.
DISP_E_BADVARTYPE One of the arguments in rgvarg is not a valid variant type.
DISP_E_EXCEPTION The application needs to raise an exception. In this case, the structure passed in pExcepInfo should be filled in.
DISP_E_MEMBERNOTFOUND The requested member does not exist, or the call to Invoke tried to set the value of a read-only property.
DISP_E_NONAMEDARGS This implementation of IDispatch does not support named arguments.
DISP_E_OVERFLOW One of the arguments in rgvarg could not be coerced to the specified type.
DISP_E_PARAMNOTFOUND 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.
DISP_E_TYPEMISMATCH 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.
DISP_E_UNKNOWNINTERFACE The interface identifier passed in riid is not IID_NULL.
DISP_E_UNKNOWNLCID 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.
DISP_E_PARAMNOTOPTIONAL A required parameter was omitted.
Comments Generally, you should not implement Invoke directly. Instead, use the dispatch interface create functions CreateStdDispatch and DispInvoke. For details, refer to "CreateStdDispatch" and "DispInvoke" in this chapter, and "Creating the IDispatch Interface" in Chapter 2, "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.
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.
Returns
LONGINT, hResult
Source
METHOD CMInvoke( dwDispIDMember AS DWORD, pstruIID AS _WinGUID, dwLCID AS DWORD, ; ...
...wFlags AS WORD, pstruDispParams AS _WinDISPPARAMS, pstruVarian AS _WinVARIANT, ; ...
...pstruExeptionInfo AS _WinEXCEPINFO, pdwArgErr AS DWORD PTR ) AS LONG PASCAL CLASS ; ...
...TS_DelegateIDispatch
LOCAL loRetVal AS LONG
TSTrace Enter
IF SELF:FInit
#IFDEF TS_TRACETIMED_ENABLE
_TS_TraceTimedEnter( TS_TT_SYM_EXTERNAL, TS_TT_SYM_IDISPATCH, #Invoke_ANY ; ...
... )
#ENDIF
loRetVal:=SELF:_AIDispatch:Invoke( dwDispIDMember ; ...
... , pstruIID, dwLCID, wFlags, pstruDispParams, pstruVarian, pstruExeptionInfo ; ...
... , pdwArgErr