22.214.171.124 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.
The member is invoked as a method.
The member is retrieved as a property or data member.
The member is changed as a property or data member.
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.
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.
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.
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
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
of the first argument that has an error. Otherwise, it MUST be ignored on
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
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.
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.
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].
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].
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 126.96.36.199.4 and [MS-ERREF].
The number of elements provided to DISPPARAMS is different from the number of arguments accepted by the method or property. See [MS-ERREF].
One of the arguments in rgvarg is not a valid variant type. See [MS-ERREF].
The requested member does not exist, or the call to Invoke tried to set the value of a read-only property. See [MS-ERREF].
At least one named argument was provided for methods with a vararg parameter (see section 188.8.131.52.3), for which named arguments are illegal. See [MS-ERREF].
One of the arguments in rgvarg could not be coerced to the type of its corresponding formal parameter. See [MS-ERREF].
The interface identifier passed in riid is not IID_NULL. See [MS-ERREF].
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].