IDispatch::Invoke (Windows CE 5.0)

Windows CE 5.0
Send Feedback

This method provides access to properties and methods exposed by an object.

For more information about using this method, see Automation.

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
[in] Identifies the member. Use IDispatch::GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
[in] Reserved for future use; set to IID_NULL.
lcid
[in] Locale context in which to interpret parameters. The lcid is used by the GetIDsOfNames function, and is also passed to Invoke to allow the object to interpret its parameters specific to a locale.

Applications that do not support multiple national languages can ignore this parameter.

wFlags
[in] Flags describing the context of the Invoke call. It is one of the following values.
ValueDescription
DISPATCH_METHODThe member is invoked as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag may be set.
DISPATCH_PROPERTYGETThe member is retrieved as a property or data member.
DISPATCH_PROPERTYPUTThe member is changed as a property or data member.
DISPATCH_PROPERTYPUTREFThe 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
[in, out] Pointer to a structure that contains an array of parameters, an array of parameter DISPIDs for named parameters, and counts for the number of elements in the arrays. See the Remarks section that follows for a description of the DISPPARAMS structure.
pVarResult
[out] Pointer to the location where the result is to be stored, or NULL if the caller expects no result. This parameter 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. Can be NULL.
puArgErr
[out] The index within rgvarg of the first parameter that has an error. Arguments are stored in pDispParams->rgvarg in reverse order, so the first parameter 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. For details, see Returning Errors.

Return Values

The following table shows the return values for this function.

ValueDescription
S_OKSuccess.
DISP_E_BADPARAMCOUNTThe number of elements provided to DISPPARAMS is different from the number of parameters accepted by the method or property.
DISP_E_BADVARTYPEOne of the parameters in rgvarg is not a valid variant type.
DISP_E_EXCEPTIONThe application needs to raise an exception. In this case, the structure passed in pExcepInfo should be filled in.
DISP_E_MEMBERNOTFOUNDThe requested member does not exist, or the call to Invoke tried to set the value of a read-only property.
DISP_E_NONAMEDARGSThis implementation of IDispatch does not support named parameters.
DISP_E_OVERFLOWOne of the parameters in rgvarg could not be coerced to the specified type.
DISP_E_PARAMNOTFOUNDOne of the parameter DISPIDs does not correspond to a parameter on the method. In this case, puArgErr should be set to the first parameter that contains the error.
DISP_E_TYPEMISMATCHOne or more of the parameters could not be coerced. The index within rgvarg of the first parameter with the incorrect type is returned in the puArgErr parameter.
DISP_E_UNKNOWNINTERFACEThe interface identifier passed in riid is not IID_NULL.
DISP_E_UNKNOWNLCIDThe member being invoked interprets string parameters according to the LCID, and the LCID is not recognized. If the LCID is not needed to interpret parameters, this error should not be returned.
DISP_E_PARAMNOTOPTIONALA required parameter was omitted.

In 16-bit versions, you can define your own errors using the MAKE_SCODE value macro.

Remarks

Generally, you should not implement Invoke directly. Instead, use the dispatch interface create functions CreateStdDispatch and DispInvoke.

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 parameter 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 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.

Requirements

OS Versions: Windows CE 2.0 and later.
Header: Oaidl.h, Oaidl.idl.
Link Library: Oleaut32.lib, Uuid.lib.

See Also

IDispatch | DISPPARAMS | IDispatch::GetIDsOfNames | ITypeInfo | ITypeInfo::Invoke | dispinterface


Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.


Show: