Export (0) Print
Expand All

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

 
Show:
© 2015 Microsoft