3.1.4.4 IDispatch::Invoke (Opnum 6)

The Invoke method provides access to properties and methods exposed by the automation server.

 HRESULT Invoke(
   [in] DISPID dispIdMember,
   [in] REFIID riid,
   [in] LCID lcid,
   [in] DWORD dwFlags,
   [in] DISPPARAMS* pDispParams,
   [out] VARIANT* pVarResult,
   [out] EXCEPINFO* pExcepInfo,
   [out] UINT* pArgErr,
   [in] UINT cVarRef,
   [in, size_is(cVarRef)] UINT* rgVarRefIdx,
   [in, out, size_is(cVarRef)] VARIANT* rgVarRef
 );

dispIdMember: MUST equal the DISPID of the method or property to call.

riid: MUST equal IID_NULL (see section 1.9).

lcid: MUST equal a locale ID supported by the automation server. This value SHOULD be used by the automation server if any of the arguments are strings whose meaning is dependent on a specific locale ID. If no such strings are present in the arguments the server SHOULD ignore this value.

dwFlags:  MUST be a combination of the bit flags specified in the following table.

Note The value MUST specify one and only one of the following bit flags: DISPATCH_METHOD, DISPATCH_PROPERTYGET, DISPATCH_PROPERTYPUT, or DISPATCH_PROPERTYPUTREF.

Value	Meaning
DISPATCH_METHOD 0x00000001	The member is invoked as a method.
DISPATCH_PROPERTYGET 0x00000002	The member is retrieved as a property or data member.
DISPATCH_PROPERTYPUT 0x00000004	The member is changed as a property or data member.
DISPATCH_PROPERTYPUTREF 0x00000008	The member is changed by a reference assignment, rather than by a value assignment. This flag is valid only when the property accepts a reference to an object.
DISPATCH_zeroVarResult 0x00020000	MUST specify that the client is not interested in the actual pVarResult [out] argument. On return the pVarResult argument MUST point to a VT_EMPTY variant, with all reserved fields set to 0.
DISPATCH_zeroExcepInfo 0x00040000	MUST specify that the client is not interested in the actual pExcepInfo [out] argument. On return pExcepInfo MUST point to an EXCEPINFO structure, with all scalar fields set to 0 and all BSTR fields set to NULL.
DISPATCH_zeroArgErr 0x00080000	MUST specify that the client is not interested in the actual pArgErr [out] argument. On return, pArgErr MUST be set to 0.

pDispParams:  MUST point to a DISPPARAMS structure that defines the arguments passed to the method. Arguments MUST be stored in pDispParams->rgvarg in reverse order, so that the first argument is the one with the highest index in the array. Byref arguments MUST be marked in this array as VT_EMPTY entries, and stored in rgVarRef instead. For more information, see section 2.2.33.

pVarResult: MUST point to a VARIANT that will be filled with the result of the method or property call.

pExcepInfo: If this value is not null and the return value is DISP_E_EXCEPTION, this structure MUST be filled by the automation server. Otherwise, it MUST specify a 0 value for the scode and wCode fields, and it MUST be ignored on receipt.

pArgErr: If this value is not null and the return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND, this argument MUST equal the index (within pDispParams->rgvarg) of the first argument that has an error. Otherwise, it MUST be ignored on receipt.

cVarRef: MUST equal the number of byref arguments passed in pDispParams.

rgVarRefIdx: MUST contain an array of cVarRef unsigned integers that holds the indices of the byref arguments marked as VT_EMPTY entries in pDispParams->rgvarg.

rgVarRef: MUST contain the byref arguments as set by the client at the time of the call, and by the server on successful return from the call. Arguments in this array MUST also be stored in reverse order, so that the first byref argument has the highest index in the array.

Return Values: The method MUST return information in an HRESULT data structure, defined in [MS-ERREF] section 2.1. The severity bit in the structure identifies the following conditions:

• If the severity bit is set to 0, the method completed successfully.

• If the severity bit is set to 1 and the entire HRESULT DWORD does not match a value in the following table, a fatal failure occurred.

• If the severity bit is set to 1 and the entire HRESULT DWORD matches a value in the following table, a failure occurred.

  Return value/code	Description
  0x80020009 DISP_E_EXCEPTION	The application needs to raise an exception. In this case, the structure passed in pExcepInfo MUST be filled in with a nonzero error code. See [MS-ERREF].
  0x80020004 DISP_E_PARAMNOTFOUND	One of the parameter DISPIDs does not correspond to a parameter on the method. In this case, pArgErr MUST be set to the first argument that contains the error. See [MS-ERREF].
  0x80020005 DISP_E_TYPEMISMATCH	One or more of the arguments could not be coerced into the type of the corresponding formal parameter. The index within rgvarg of the first parameter with the incorrect type MUST be returned in the pArgErr parameter. For more information, see section 3.1.4.4.4 and [MS-ERREF].
  0x8002000E DISP_E_BADPARAMCOUNT	The number of elements provided to DISPPARAMS is different from the number of arguments accepted by the method or property. See [MS-ERREF].
  0x80020008 DISP_E_BADVARTYPE	One of the arguments in rgvarg is not a valid variant type. See [MS-ERREF].
  0x80020003 DISP_E_MEMBERNOTFOUND	The requested member does not exist, or the call to Invoke tried to set the value of a read-only property. See [MS-ERREF].
  0x80020007 DISP_E_NONAMEDARGS	At least one named argument was provided for methods with a vararg parameter (see section 3.1.4.4.3), for which named arguments are illegal. See [MS-ERREF].
  0x8002000A DISP_E_OVERFLOW	One of the arguments in rgvarg could not be coerced to the type of its corresponding formal parameter. See [MS-ERREF].
  0x80020001 DISP_E_UNKNOWNINTERFACE	The interface identifier passed in riid is not IID_NULL. See [MS-ERREF].
  0x8002000F DISP_E_PARAMNOTOPTIONAL	A required parameter was omitted. See [MS-ERREF].

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC Protocol, as specified in [MS-RPCE].