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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 * TODO: Type coercion is implemented in variant.c but not called yet.
39 #include "winnls.h" /* for PRIMARYLANGID */
41 #include "wine/debug.h"
43 WINE_DEFAULT_DEBUG_CHANNEL(ole
);
44 WINE_DECLARE_DEBUG_CHANNEL(typelib
);
46 static IDispatch
* WINAPI
StdDispatch_Construct(IUnknown
* punkOuter
, void * pvThis
, ITypeInfo
* pTypeInfo
);
48 /******************************************************************************
49 * DispInvoke (OLEAUT32.30)
51 * Call an object method using the information from its type library.
55 * Failure: Returns DISP_E_EXCEPTION and updates pexcepinfo if an exception occurs.
56 * DISP_E_BADPARAMCOUNT if the number of parameters is incorrect.
57 * DISP_E_MEMBERNOTFOUND if the method does not exist.
58 * puArgErr is updated if a parameter error (see notes) occurs.
59 * Otherwise, returns the result of calling ITypeInfo_Invoke().
62 * Parameter errors include the following:
64 *| E_INVALIDARG An argument was invalid
65 *| DISP_E_TYPEMISMATCH,
66 *| DISP_E_OVERFLOW An argument was valid but could not be coerced
67 *| DISP_E_PARAMNOTOPTIONAL A non optional parameter was not passed
68 *| DISP_E_PARAMNOTFOUND A parameter was passed that was not expected by the method
69 * This call defers to ITypeInfo_Invoke().
71 HRESULT WINAPI
DispInvoke(
72 VOID
*_this
, /* [in] Object to call method on */
73 ITypeInfo
*ptinfo
, /* [in] Object type info */
74 DISPID dispidMember
, /* [in] DISPID of the member (e.g. from GetIDsOfNames()) */
75 USHORT wFlags
, /* [in] Kind of method call (DISPATCH_ flags from "oaidl.h") */
76 DISPPARAMS
*pparams
, /* [in] Array of method arguments */
77 VARIANT
*pvarResult
, /* [out] Destination for the result of the call */
78 EXCEPINFO
*pexcepinfo
, /* [out] Destination for exception information */
79 UINT
*puArgErr
) /* [out] Destination for bad argument */
83 * For each param, call DispGetParam to perform type coercion
85 FIXME("Coercion of arguments not implemented\n");
87 return ITypeInfo_Invoke(ptinfo
, _this
, dispidMember
, wFlags
,
88 pparams
, pvarResult
, pexcepinfo
, puArgErr
);
91 /******************************************************************************
92 * DispGetIDsOfNames (OLEAUT32.29)
94 * Convert a set of parameter names to DISPID's for DispInvoke().
98 * Failure: An HRESULT error code.
101 * This call defers to ITypeInfo_GetIDsOfNames(). The ITypeInfo interface passed
102 * as ptinfo contains the information to map names to DISPID's.
104 HRESULT WINAPI
DispGetIDsOfNames(
105 ITypeInfo
*ptinfo
, /* [in] Object's type info */
106 OLECHAR
**rgszNames
, /* [in] Array of names to get DISPID's for */
107 UINT cNames
, /* [in] Number of names in rgszNames */
108 DISPID
*rgdispid
) /* [out] Destination for converted DISPID's */
110 return ITypeInfo_GetIDsOfNames(ptinfo
, rgszNames
, cNames
, rgdispid
);
113 /******************************************************************************
114 * DispGetParam (OLEAUT32.28)
116 * Retrive a parameter from a DISPPARAMS structure and coerce it to the
117 * specified variant type.
120 * Coercion is done using system (0) locale.
124 * Failure: DISP_E_PARAMNOTFOUND, if position is invalid. or
125 * DISP_E_TYPEMISMATCH, if the coercion failed. puArgErr is
126 * set to the index of the argument in pdispparams.
128 HRESULT WINAPI
DispGetParam(
129 DISPPARAMS
*pdispparams
, /* [in] Parameter list */
130 UINT position
, /* [in] Position of parameter to coerce in pdispparams */
131 VARTYPE vtTarg
, /* [in] Type of value to coerce to */
132 VARIANT
*pvarResult
, /* [out] Destination for resulting variant */
133 UINT
*puArgErr
) /* [out] Destination for error code */
135 /* position is counted backwards */
139 TRACE("position=%d, cArgs=%d, cNamedArgs=%d\n",
140 position
, pdispparams
->cArgs
, pdispparams
->cNamedArgs
);
141 if (position
< pdispparams
->cArgs
) {
142 /* positional arg? */
143 pos
= pdispparams
->cArgs
- position
- 1;
145 /* FIXME: is this how to handle named args? */
146 for (pos
=0; pos
<pdispparams
->cNamedArgs
; pos
++)
147 if (pdispparams
->rgdispidNamedArgs
[pos
] == position
) break;
149 if (pos
==pdispparams
->cNamedArgs
)
150 return DISP_E_PARAMNOTFOUND
;
152 hr
= VariantChangeType(pvarResult
,
153 &pdispparams
->rgvarg
[pos
],
155 if (hr
== DISP_E_TYPEMISMATCH
) *puArgErr
= pos
;
159 /******************************************************************************
160 * CreateStdDispatch [OLEAUT32.32]
162 * Create and return a standard IDispatch object.
165 * Success: S_OK. ppunkStdDisp contains the new object.
166 * Failure: An HRESULT error code.
169 * Outer unknown appears to be completely ignored.
171 HRESULT WINAPI
CreateStdDispatch(
175 IUnknown
** ppunkStdDisp
)
177 TRACE("(%p, %p, %p, %p)\n", punkOuter
, pvThis
, ptinfo
, ppunkStdDisp
);
179 *ppunkStdDisp
= (LPUNKNOWN
)StdDispatch_Construct(punkOuter
, pvThis
, ptinfo
);
181 return E_OUTOFMEMORY
;
186 /******************************************************************************
187 * IDispatch {OLEAUT32}
190 * The IDispatch interface provides a single interface to dispatch method calls,
191 * regardless of whether the object to be called is in or out of process,
192 * local or remote (e.g. being called over a network). This interface is late-bound
193 * (linked at run-time), as opposed to early-bound (linked at compile time).
195 * The interface is used by objects that wish to called by scripting
196 * languages such as VBA, in order to minimise the amount of COM and C/C++
197 * knowledge required, or by objects that wish to live out of process from code
198 * that will call their methods.
200 * Method, property and parameter names can be localised. The details required to
201 * map names to methods and parameters are collected in a type library, usually
202 * output by an IDL compiler using the objects IDL description. This information is
203 * accessible programatically through the ITypeLib interface (for a type library),
204 * and the ITypeInfo interface (for an object within the type library). Type information
205 * can also be created at run-time using CreateDispTypeInfo().
208 * Instead of using IDispatch directly, there are several wrapper functions available
209 * to simplify the process of calling an objects methods through IDispatch.
211 * A standard implementation of an IDispatch object is created by calling
212 * CreateStdDispatch(). Numeric Id values for the parameters and methods (DISPID's)
213 * of an object of interest are retrieved by calling DispGetIDsOfNames(). DispGetParam()
214 * retrieves information about a particular parameter. Finally the DispInvoke()
215 * function is responsable for actually calling methods on an object.
222 IDispatchVtbl
*lpVtbl
;
224 ITypeInfo
* pTypeInfo
;
228 /******************************************************************************
229 * IDispatch_QueryInterface {OLEAUT32}
231 * See IUnknown_QueryInterface.
233 static HRESULT WINAPI
StdDispatch_QueryInterface(
238 StdDispatch
*This
= (StdDispatch
*)iface
;
239 TRACE("(%p)->(%s, %p)\n", iface
, debugstr_guid(riid
), ppvObject
);
241 if (IsEqualIID(riid
, &IID_IDispatch
) ||
242 IsEqualIID(riid
, &IID_IUnknown
))
244 *ppvObject
= (LPVOID
)This
;
245 IUnknown_AddRef((LPUNKNOWN
)*ppvObject
);
248 return E_NOINTERFACE
;
251 /******************************************************************************
252 * IDispatch_AddRef {OLEAUT32}
254 * See IUnknown_AddRef.
256 static ULONG WINAPI
StdDispatch_AddRef(LPDISPATCH iface
)
258 StdDispatch
*This
= (StdDispatch
*)iface
;
261 return InterlockedIncrement(&This
->ref
);
264 /******************************************************************************
265 * IDispatch_Release {OLEAUT32}
267 * See IUnknown_Release.
269 static ULONG WINAPI
StdDispatch_Release(LPDISPATCH iface
)
271 StdDispatch
*This
= (StdDispatch
*)iface
;
273 TRACE("(%p)->()\n", This
);
275 ref
= InterlockedDecrement(&This
->ref
);
279 ITypeInfo_Release(This
->pTypeInfo
);
286 /******************************************************************************
287 * IDispatch_GetTypeInfoCount {OLEAUT32}
289 * Get the count of type information in an IDispatch interface.
292 * iface [I] IDispatch interface
293 * pctinfo [O] Destination for the count
296 * Success: S_OK. pctinfo is updated with the count. This is always 1 if
297 * the object provides type information, and 0 if it does not.
298 * Failure: E_NOTIMPL. The object does not provide type information.
301 * See IDispatch() and IDispatch_GetTypeInfo().
303 static HRESULT WINAPI
StdDispatch_GetTypeInfoCount(LPDISPATCH iface
, UINT
* pctinfo
)
305 StdDispatch
*This
= (StdDispatch
*)iface
;
306 TRACE("(%p)\n", pctinfo
);
308 *pctinfo
= This
->pTypeInfo
? 1 : 0;
312 /******************************************************************************
313 * IDispatch_GetTypeInfo {OLEAUT32}
315 * Get type information from an IDispatch interface.
318 * iface [I] IDispatch interface
319 * iTInfo [I] Index of type information.
320 * lcid [I] Locale of the type information to get
321 * ppTInfo [O] Destination for the ITypeInfo object
324 * Success: S_OK. ppTInfo is updated with the objects type information
325 * Failure: DISP_E_BADINDEX, if iTInfo is any value other than 0.
330 static HRESULT WINAPI
StdDispatch_GetTypeInfo(LPDISPATCH iface
, UINT iTInfo
, LCID lcid
, ITypeInfo
** ppTInfo
)
332 StdDispatch
*This
= (StdDispatch
*)iface
;
333 TRACE("(%d, %lx, %p)\n", iTInfo
, lcid
, ppTInfo
);
337 return DISP_E_BADINDEX
;
341 *ppTInfo
= This
->pTypeInfo
;
342 ITypeInfo_AddRef(*ppTInfo
);
347 /******************************************************************************
348 * IDispatch_GetIDsOfNames {OLEAUT32}
350 * Convert a methods name and an optional set of parameter names into DISPID's
351 * for passing to IDispatch_Invoke().
354 * iface [I] IDispatch interface
355 * riid [I] Reserved, set to IID_NULL
356 * rgszNames [I] Name to convert
357 * cNames [I] Number of names in rgszNames
358 * lcid [I] Locale of the type information to convert from
359 * rgDispId [O] Destination for converted DISPID's.
363 * Failure: DISP_E_UNKNOWNNAME, if any of the names is invalid.
364 * DISP_E_UNKNOWNLCID if lcid is invalid.
365 * Otherwise, an An HRESULT error code.
368 * This call defers to ITypeInfo_GetIDsOfNames(), using the ITypeInfo object
369 * contained within the IDispatch object.
370 * The first member of the names list must be a method name. The names following
371 * the method name are the parameters for that method.
373 static HRESULT WINAPI
StdDispatch_GetIDsOfNames(LPDISPATCH iface
, REFIID riid
, LPOLESTR
* rgszNames
, UINT cNames
, LCID lcid
, DISPID
* rgDispId
)
375 StdDispatch
*This
= (StdDispatch
*)iface
;
376 TRACE("(%s, %p, %d, 0x%lx, %p)\n", debugstr_guid(riid
), rgszNames
, cNames
, lcid
, rgDispId
);
378 if (!IsEqualGUID(riid
, &IID_NULL
))
380 FIXME(" expected riid == IID_NULL\n");
383 return DispGetIDsOfNames(This
->pTypeInfo
, rgszNames
, cNames
, rgDispId
);
386 /******************************************************************************
387 * IDispatch_Invoke {OLEAUT32}
389 * Call an object method.
392 * iface [I] IDispatch interface
393 * dispIdMember [I] DISPID of the method (from GetIDsOfNames())
394 * riid [I] Reserved, set to IID_NULL
395 * lcid [I] Locale of the type information to convert parameters with
396 * wFlags, [I] Kind of method call (DISPATCH_ flags from "oaidl.h")
397 * pDispParams [I] Array of method arguments
398 * pVarResult [O] Destination for the result of the call
399 * pExcepInfo [O] Destination for exception information
400 * puArgErr [O] Destination for bad argument
404 * Failure: See DispInvoke() for failure cases.
407 * See DispInvoke() and IDispatch().
409 static HRESULT WINAPI
StdDispatch_Invoke(LPDISPATCH iface
, DISPID dispIdMember
, REFIID riid
, LCID lcid
,
410 WORD wFlags
, DISPPARAMS
* pDispParams
, VARIANT
* pVarResult
,
411 EXCEPINFO
* pExcepInfo
, UINT
* puArgErr
)
413 StdDispatch
*This
= (StdDispatch
*)iface
;
414 TRACE("(%ld, %s, 0x%lx, 0x%x, %p, %p, %p, %p)\n", dispIdMember
, debugstr_guid(riid
), lcid
, wFlags
, pDispParams
, pVarResult
, pExcepInfo
, puArgErr
);
416 if (!IsEqualGUID(riid
, &IID_NULL
))
418 FIXME(" expected riid == IID_NULL\n");
421 return DispInvoke(This
->pvThis
, This
->pTypeInfo
, dispIdMember
, wFlags
, pDispParams
, pVarResult
, pExcepInfo
, puArgErr
);
424 static IDispatchVtbl StdDispatch_VTable
=
426 StdDispatch_QueryInterface
,
429 StdDispatch_GetTypeInfoCount
,
430 StdDispatch_GetTypeInfo
,
431 StdDispatch_GetIDsOfNames
,
435 static IDispatch
* WINAPI
StdDispatch_Construct(
436 IUnknown
* punkOuter
,
438 ITypeInfo
* pTypeInfo
)
440 StdDispatch
* pStdDispatch
;
442 pStdDispatch
= CoTaskMemAlloc(sizeof(StdDispatch
));
444 return (IDispatch
*)pStdDispatch
;
446 pStdDispatch
->lpVtbl
= &StdDispatch_VTable
;
447 pStdDispatch
->pvThis
= pvThis
;
448 pStdDispatch
->pTypeInfo
= pTypeInfo
;
449 pStdDispatch
->ref
= 1;
451 /* we keep a reference to the type info so prevent it from
452 * being destroyed until we are done with it */
453 ITypeInfo_AddRef(pTypeInfo
);
455 return (IDispatch
*)pStdDispatch
;