2 * Dispatch API functions
4 * Copyright 2000 Francois Jacques, Macadamian Technologies Inc.
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
36 #include "wine/debug.h"
38 WINE_DEFAULT_DEBUG_CHANNEL(ole
);
40 /******************************************************************************
41 * DispInvoke (OLEAUT32.30)
43 * Call an object method using the information from its type library.
47 * Failure: Returns DISP_E_EXCEPTION and updates pexcepinfo if an exception occurs.
48 * DISP_E_BADPARAMCOUNT if the number of parameters is incorrect.
49 * DISP_E_MEMBERNOTFOUND if the method does not exist.
50 * puArgErr is updated if a parameter error (see notes) occurs.
51 * Otherwise, returns the result of calling ITypeInfo_Invoke().
54 * Parameter errors include the following:
56 *| E_INVALIDARG An argument was invalid
57 *| DISP_E_TYPEMISMATCH,
58 *| DISP_E_OVERFLOW An argument was valid but could not be coerced
59 *| DISP_E_PARAMNOTOPTIONAL A non optional parameter was not passed
60 *| DISP_E_PARAMNOTFOUND A parameter was passed that was not expected by the method
61 * This call defers to ITypeInfo_Invoke().
63 HRESULT WINAPI
DispInvoke(
64 VOID
*_this
, /* [in] Object to call method on */
65 ITypeInfo
*ptinfo
, /* [in] Object type info */
66 DISPID dispidMember
, /* [in] DISPID of the member (e.g. from GetIDsOfNames()) */
67 USHORT wFlags
, /* [in] Kind of method call (DISPATCH_ flags from "oaidl.h") */
68 DISPPARAMS
*pparams
, /* [in] Array of method arguments */
69 VARIANT
*pvarResult
, /* [out] Destination for the result of the call */
70 EXCEPINFO
*pexcepinfo
, /* [out] Destination for exception information */
71 UINT
*puArgErr
) /* [out] Destination for bad argument */
75 return ITypeInfo_Invoke(ptinfo
, _this
, dispidMember
, wFlags
,
76 pparams
, pvarResult
, pexcepinfo
, puArgErr
);
79 /******************************************************************************
80 * DispGetIDsOfNames (OLEAUT32.29)
82 * Convert a set of parameter names to DISPIDs for DispInvoke().
86 * Failure: An HRESULT error code.
89 * This call defers to ITypeInfo_GetIDsOfNames(). The ITypeInfo interface passed
90 * as ptinfo contains the information to map names to DISPIDs.
92 HRESULT WINAPI
DispGetIDsOfNames(
93 ITypeInfo
*ptinfo
, /* [in] Object's type info */
94 OLECHAR
**rgszNames
, /* [in] Array of names to get DISPIDs for */
95 UINT cNames
, /* [in] Number of names in rgszNames */
96 DISPID
*rgdispid
) /* [out] Destination for converted DISPIDs */
98 return ITypeInfo_GetIDsOfNames(ptinfo
, rgszNames
, cNames
, rgdispid
);
101 /******************************************************************************
102 * DispGetParam (OLEAUT32.28)
104 * Retrieve a parameter from a DISPPARAMS structure and coerce it to the
105 * specified variant type.
108 * Coercion is done using system (0) locale.
112 * Failure: DISP_E_PARAMNOTFOUND, if position is invalid. or
113 * DISP_E_TYPEMISMATCH, if the coercion failed. puArgErr is
114 * set to the index of the argument in pdispparams.
116 HRESULT WINAPI
DispGetParam(
117 DISPPARAMS
*pdispparams
, /* [in] Parameter list */
118 UINT position
, /* [in] Position of parameter to coerce in pdispparams */
119 VARTYPE vtTarg
, /* [in] Type of value to coerce to */
120 VARIANT
*pvarResult
, /* [out] Destination for resulting variant */
121 UINT
*puArgErr
) /* [out] Destination for error code */
123 /* position is counted backwards */
127 TRACE("position=%d, cArgs=%d, cNamedArgs=%d\n",
128 position
, pdispparams
->cArgs
, pdispparams
->cNamedArgs
);
130 if (position
< pdispparams
->cArgs
)
132 /* positional arg? */
133 pos
= pdispparams
->cArgs
- position
- 1;
137 /* FIXME: is this how to handle named args? */
138 for (pos
=0; pos
<pdispparams
->cNamedArgs
; pos
++)
139 if (pdispparams
->rgdispidNamedArgs
[pos
] == position
) break;
141 if (pos
==pdispparams
->cNamedArgs
)
142 return DISP_E_PARAMNOTFOUND
;
145 if (pdispparams
->cArgs
> 0 && !pdispparams
->rgvarg
)
157 hr
= VariantChangeType(pvarResult
,
158 &pdispparams
->rgvarg
[pos
],
169 /******************************************************************************
170 * IDispatch {OLEAUT32}
173 * The IDispatch interface provides a single interface to dispatch method calls,
174 * regardless of whether the object to be called is in or out of process,
175 * local or remote (e.g. being called over a network). This interface is late-bound
176 * (linked at run-time), as opposed to early-bound (linked at compile time).
178 * The interface is used by objects that wish to called by scripting
179 * languages such as VBA, in order to minimize the amount of COM and C/C++
180 * knowledge required, or by objects that wish to live out of process from code
181 * that will call their methods.
183 * Method, property and parameter names can be localised. The details required to
184 * map names to methods and parameters are collected in a type library, usually
185 * output by an IDL compiler using the objects IDL description. This information is
186 * accessible programmatically through the ITypeLib interface (for a type library),
187 * and the ITypeInfo interface (for an object within the type library). Type information
188 * can also be created at run-time using CreateDispTypeInfo().
191 * Instead of using IDispatch directly, there are several wrapper functions available
192 * to simplify the process of calling an objects methods through IDispatch.
194 * A standard implementation of an IDispatch object is created by calling
195 * CreateStdDispatch(). Numeric Id values for the parameters and methods (DISPIDs)
196 * of an object of interest are retrieved by calling DispGetIDsOfNames(). DispGetParam()
197 * retrieves information about a particular parameter. Finally the DispInvoke()
198 * function is responsible for actually calling methods on an object.
205 IDispatch IDispatch_iface
;
207 ITypeInfo
* pTypeInfo
;
211 static inline StdDispatch
*impl_from_IDispatch(IDispatch
*iface
)
213 return CONTAINING_RECORD(iface
, StdDispatch
, IDispatch_iface
);
216 /******************************************************************************
217 * IDispatch_QueryInterface {OLEAUT32}
219 * See IUnknown_QueryInterface.
221 static HRESULT WINAPI
StdDispatch_QueryInterface(
226 StdDispatch
*This
= impl_from_IDispatch(iface
);
227 TRACE("(%p)->(%s, %p)\n", This
, debugstr_guid(riid
), ppvObject
);
231 if (IsEqualIID(riid
, &IID_IDispatch
) ||
232 IsEqualIID(riid
, &IID_IUnknown
))
235 IDispatch_AddRef(iface
);
238 return E_NOINTERFACE
;
241 /******************************************************************************
242 * IDispatch_AddRef {OLEAUT32}
244 * See IUnknown_AddRef.
246 static ULONG WINAPI
StdDispatch_AddRef(LPDISPATCH iface
)
248 StdDispatch
*This
= impl_from_IDispatch(iface
);
249 ULONG refCount
= InterlockedIncrement(&This
->ref
);
251 TRACE("%p, refcount %lu.\n", iface
, refCount
);
256 /******************************************************************************
257 * IDispatch_Release {OLEAUT32}
259 * See IUnknown_Release.
261 static ULONG WINAPI
StdDispatch_Release(LPDISPATCH iface
)
263 StdDispatch
*This
= impl_from_IDispatch(iface
);
264 ULONG refCount
= InterlockedDecrement(&This
->ref
);
266 TRACE("%p, refcount %lu.\n", iface
, refCount
);
270 ITypeInfo_Release(This
->pTypeInfo
);
277 /******************************************************************************
278 * IDispatch_GetTypeInfoCount {OLEAUT32}
280 * Get the count of type information in an IDispatch interface.
283 * iface [I] IDispatch interface
284 * pctinfo [O] Destination for the count
287 * Success: S_OK. pctinfo is updated with the count. This is always 1 if
288 * the object provides type information, and 0 if it does not.
289 * Failure: E_NOTIMPL. The object does not provide type information.
292 * See IDispatch() and IDispatch_GetTypeInfo().
294 static HRESULT WINAPI
StdDispatch_GetTypeInfoCount(LPDISPATCH iface
, UINT
* pctinfo
)
296 TRACE("(%p)\n", pctinfo
);
301 /******************************************************************************
302 * IDispatch_GetTypeInfo {OLEAUT32}
304 * Get type information from an IDispatch interface.
307 * iface [I] IDispatch interface
308 * iTInfo [I] Index of type information.
309 * lcid [I] Locale of the type information to get
310 * ppTInfo [O] Destination for the ITypeInfo object
313 * Success: S_OK. ppTInfo is updated with the objects type information
314 * Failure: DISP_E_BADINDEX, if iTInfo is any value other than 0.
319 static HRESULT WINAPI
StdDispatch_GetTypeInfo(LPDISPATCH iface
, UINT iTInfo
, LCID lcid
, ITypeInfo
** ppTInfo
)
321 StdDispatch
*This
= impl_from_IDispatch(iface
);
323 TRACE("%d, %#lx, %p.\n", iTInfo
, lcid
, ppTInfo
);
327 return DISP_E_BADINDEX
;
329 *ppTInfo
= This
->pTypeInfo
;
330 ITypeInfo_AddRef(*ppTInfo
);
335 /******************************************************************************
336 * IDispatch_GetIDsOfNames {OLEAUT32}
338 * Convert a methods name and an optional set of parameter names into DISPIDs
339 * for passing to IDispatch_Invoke().
342 * iface [I] IDispatch interface
343 * riid [I] Reserved, set to IID_NULL
344 * rgszNames [I] Name to convert
345 * cNames [I] Number of names in rgszNames
346 * lcid [I] Locale of the type information to convert from
347 * rgDispId [O] Destination for converted DISPIDs.
351 * Failure: DISP_E_UNKNOWNNAME, if any of the names is invalid.
352 * DISP_E_UNKNOWNLCID if lcid is invalid.
353 * Otherwise, an HRESULT error code.
356 * This call defers to ITypeInfo_GetIDsOfNames(), using the ITypeInfo object
357 * contained within the IDispatch object.
358 * The first member of the names list must be a method name. The names following
359 * the method name are the parameters for that method.
361 static HRESULT WINAPI
StdDispatch_GetIDsOfNames(LPDISPATCH iface
, REFIID riid
, LPOLESTR
* rgszNames
, UINT cNames
, LCID lcid
, DISPID
* rgDispId
)
363 StdDispatch
*This
= impl_from_IDispatch(iface
);
365 TRACE("%s, %p, %d, %#lx, %p.\n", debugstr_guid(riid
), rgszNames
, cNames
, lcid
, rgDispId
);
367 if (!IsEqualGUID(riid
, &IID_NULL
))
369 FIXME(" expected riid == IID_NULL\n");
372 return DispGetIDsOfNames(This
->pTypeInfo
, rgszNames
, cNames
, rgDispId
);
375 /******************************************************************************
376 * IDispatch_Invoke {OLEAUT32}
378 * Call an object method.
381 * iface [I] IDispatch interface
382 * dispIdMember [I] DISPID of the method (from GetIDsOfNames())
383 * riid [I] Reserved, set to IID_NULL
384 * lcid [I] Locale of the type information to convert parameters with
385 * wFlags, [I] Kind of method call (DISPATCH_ flags from "oaidl.h")
386 * pDispParams [I] Array of method arguments
387 * pVarResult [O] Destination for the result of the call
388 * pExcepInfo [O] Destination for exception information
389 * puArgErr [O] Destination for bad argument
393 * Failure: See DispInvoke() for failure cases.
396 * See DispInvoke() and IDispatch().
398 static HRESULT WINAPI
StdDispatch_Invoke(LPDISPATCH iface
, DISPID dispIdMember
, REFIID riid
, LCID lcid
,
399 WORD wFlags
, DISPPARAMS
* pDispParams
, VARIANT
* pVarResult
,
400 EXCEPINFO
* pExcepInfo
, UINT
* puArgErr
)
402 StdDispatch
*This
= impl_from_IDispatch(iface
);
404 TRACE("%ld, %s, %#lx, 0x%x, %p, %p, %p, %p.\n", dispIdMember
, debugstr_guid(riid
), lcid
, wFlags
, pDispParams
, pVarResult
, pExcepInfo
, puArgErr
);
406 if (!IsEqualGUID(riid
, &IID_NULL
))
408 FIXME(" expected riid == IID_NULL\n");
411 return DispInvoke(This
->pvThis
, This
->pTypeInfo
, dispIdMember
, wFlags
, pDispParams
, pVarResult
, pExcepInfo
, puArgErr
);
414 static const IDispatchVtbl StdDispatch_VTable
=
416 StdDispatch_QueryInterface
,
419 StdDispatch_GetTypeInfoCount
,
420 StdDispatch_GetTypeInfo
,
421 StdDispatch_GetIDsOfNames
,
425 /******************************************************************************
426 * CreateStdDispatch [OLEAUT32.32]
428 * Create and return a standard IDispatch object.
431 * Success: S_OK. ppunkStdDisp contains the new object.
432 * Failure: An HRESULT error code.
435 * Outer unknown appears to be completely ignored.
437 HRESULT WINAPI
CreateStdDispatch(
443 StdDispatch
*pStdDispatch
;
445 TRACE("(%p, %p, %p, %p)\n", punkOuter
, pvThis
, ptinfo
, stddisp
);
447 if (!pvThis
|| !ptinfo
|| !stddisp
)
450 pStdDispatch
= CoTaskMemAlloc(sizeof(StdDispatch
));
452 return E_OUTOFMEMORY
;
454 pStdDispatch
->IDispatch_iface
.lpVtbl
= &StdDispatch_VTable
;
455 pStdDispatch
->pvThis
= pvThis
;
456 pStdDispatch
->pTypeInfo
= ptinfo
;
457 pStdDispatch
->ref
= 1;
459 /* we keep a reference to the type info so prevent it from
460 * being destroyed until we are done with it */
461 ITypeInfo_AddRef(ptinfo
);
462 *stddisp
= (IUnknown
*)&pStdDispatch
->IDispatch_iface
;