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.
34 #include "winreg.h" /* for HKEY_LOCAL_MACHINE */
35 #include "winnls.h" /* for PRIMARYLANGID */
37 #include "wine/debug.h"
39 WINE_DEFAULT_DEBUG_CHANNEL(ole
);
40 WINE_DECLARE_DEBUG_CHANNEL(typelib
);
42 static IDispatch
* WINAPI
StdDispatch_Construct(IUnknown
* punkOuter
, void * pvThis
, ITypeInfo
* pTypeInfo
);
44 /******************************************************************************
45 * DispInvoke (OLEAUT32.30)
47 * Call an object method using the information from its type library.
51 * Failure: Returns DISP_E_EXCEPTION and updates pexcepinfo if an exception occurs.
52 * DISP_E_BADPARAMCOUNT if the number of parameters is incorrect.
53 * DISP_E_MEMBERNOTFOUND if the method does not exist.
54 * puArgErr is updated if a parameter error (see notes) occurs.
55 * Otherwise, returns the result of calling ITypeInfo_Invoke().
58 * Parameter errors include the following:
60 *| E_INVALIDARG An argument was invalid
61 *| DISP_E_TYPEMISMATCH,
62 *| DISP_E_OVERFLOW An argument was valid but could not be coerced
63 *| DISP_E_PARAMNOTOPTIONAL A non optional parameter was not passed
64 *| DISP_E_PARAMNOTFOUND A parameter was passed that was not expected by the method
65 * This call defers to ITypeInfo_Invoke().
67 HRESULT WINAPI
DispInvoke(
68 VOID
*_this
, /* [in] Object to call method on */
69 ITypeInfo
*ptinfo
, /* [in] Object type info */
70 DISPID dispidMember
, /* [in] DISPID of the member (e.g. from GetIDsOfNames()) */
71 USHORT wFlags
, /* [in] Kind of method call (DISPATCH_ flags from "oaidl.h") */
72 DISPPARAMS
*pparams
, /* [in] Array of method arguments */
73 VARIANT
*pvarResult
, /* [out] Destination for the result of the call */
74 EXCEPINFO
*pexcepinfo
, /* [out] Destination for exception information */
75 UINT
*puArgErr
) /* [out] Destination for bad argument */
79 * For each param, call DispGetParam to perform type coercion
81 FIXME("Coercion of arguments not implemented\n");
83 return ITypeInfo_Invoke(ptinfo
, _this
, dispidMember
, wFlags
,
84 pparams
, pvarResult
, pexcepinfo
, puArgErr
);
87 /******************************************************************************
88 * DispGetIDsOfNames (OLEAUT32.29)
90 * Convert a set of parameter names to DISPID's for DispInvoke().
94 * Failure: An HRESULT error code.
97 * This call defers to ITypeInfo_GetIDsOfNames(). The ITypeInfo interface passed
98 * as ptinfo contains the information to map names to DISPID's.
100 HRESULT WINAPI
DispGetIDsOfNames(
101 ITypeInfo
*ptinfo
, /* [in] Object's type info */
102 OLECHAR
**rgszNames
, /* [in] Array of names to get DISPID's for */
103 UINT cNames
, /* [in] Number of names in rgszNames */
104 DISPID
*rgdispid
) /* [out] Destination for converted DISPID's */
106 return ITypeInfo_GetIDsOfNames(ptinfo
, rgszNames
, cNames
, rgdispid
);
109 /******************************************************************************
110 * DispGetParam (OLEAUT32.28)
112 * Retrive a parameter from a DISPPARAMS structure and coerce it to the
113 * specified variant type.
116 * Coercion is done using system (0) locale.
120 * Failure: DISP_E_PARAMNOTFOUND, if position is invalid. or
121 * DISP_E_TYPEMISMATCH, if the coercion failed. puArgErr is
122 * set to the index of the argument in pdispparams.
124 HRESULT WINAPI
DispGetParam(
125 DISPPARAMS
*pdispparams
, /* [in] Parameter list */
126 UINT position
, /* [in] Position of parameter to coerce in pdispparams */
127 VARTYPE vtTarg
, /* [in] Type of value to coerce to */
128 VARIANT
*pvarResult
, /* [out] Destination for resulting variant */
129 UINT
*puArgErr
) /* [out] Destination for error code */
131 /* position is counted backwards */
135 TRACE("position=%d, cArgs=%d, cNamedArgs=%d\n",
136 position
, pdispparams
->cArgs
, pdispparams
->cNamedArgs
);
137 if (position
< pdispparams
->cArgs
) {
138 /* positional arg? */
139 pos
= pdispparams
->cArgs
- position
- 1;
141 /* FIXME: is this how to handle named args? */
142 for (pos
=0; pos
<pdispparams
->cNamedArgs
; pos
++)
143 if (pdispparams
->rgdispidNamedArgs
[pos
] == position
) break;
145 if (pos
==pdispparams
->cNamedArgs
)
146 return DISP_E_PARAMNOTFOUND
;
148 hr
= VariantChangeType(pvarResult
,
149 &pdispparams
->rgvarg
[pos
],
151 if (hr
== DISP_E_TYPEMISMATCH
) *puArgErr
= pos
;
155 /******************************************************************************
156 * CreateStdDispatch [OLEAUT32.32]
158 * Create and return a standard IDispatch object.
161 * Success: S_OK. ppunkStdDisp contains the new object.
162 * Failure: An HRESULT error code.
165 * Outer unknown appears to be completely ignored.
167 HRESULT WINAPI
CreateStdDispatch(
171 IUnknown
** ppunkStdDisp
)
173 TRACE("(%p, %p, %p, %p)\n", punkOuter
, pvThis
, ptinfo
, ppunkStdDisp
);
175 *ppunkStdDisp
= (LPUNKNOWN
)StdDispatch_Construct(punkOuter
, pvThis
, ptinfo
);
177 return E_OUTOFMEMORY
;
181 /******************************************************************************
182 * CreateDispTypeInfo [OLEAUT32.31]
184 * Build type information for an object so it can be called through an
185 * IDispatch interface.
188 * Success: S_OK. pptinfo contains the created ITypeInfo object.
189 * Failure: E_INVALIDARG, if one or more arguments is invalid.
192 * This call allows an objects methods to be accessed through IDispatch, by
193 * building an ITypeInfo object that IDispatch can use to call through.
195 HRESULT WINAPI
CreateDispTypeInfo(
196 INTERFACEDATA
*pidata
, /* [I] Description of the interface to build type info for */
197 LCID lcid
, /* [I] Locale Id */
198 ITypeInfo
**pptinfo
) /* [O] Destination for created ITypeInfo object */
200 FIXME("(%p,%ld,%p),stub\n",pidata
,lcid
,pptinfo
);
204 /******************************************************************************
205 * IDispatch {OLEAUT32}
208 * The IDispatch interface provides a single interface to dispatch method calls,
209 * regardless of whether the object to be called is in or out of process,
210 * local or remote (e.g. being called over a network). This interface is late-bound
211 * (linked at run-time), as opposed to early-bound (linked at compile time).
213 * The interface is used by objects that wish to called by scripting
214 * languages such as VBA, in order to minimise the amount of COM and C/C++
215 * knowledge required, or by objects that wish to live out of process from code
216 * that will call their methods.
218 * Method, property and parameter names can be localised. The details required to
219 * map names to methods and parameters are collected in a type library, usually
220 * output by an IDL compiler using the objects IDL description. This information is
221 * accessable programatically through the ITypeLib interface (for a type library),
222 * and the ITypeInfo interface (for an object within the type library). Type information
223 * can also be created at run-time using CreateDispTypeInfo().
226 * Instead of using IDispatch directly, there are several wrapper functions available
227 * to simplify the process of calling an objects methods through IDispatch.
229 * A standard implementation of an IDispatch object is created by calling
230 * CreateStdDispatch(). Numeric Id values for the parameters and methods (DISPID's)
231 * of an object of interest are retrieved by calling DispGetIDsOfNames(). DispGetParam()
232 * retrieves information about a particular parameter. Finally the DispInvoke()
233 * function is responsable for actually calling methods on an object.
240 ICOM_VFIELD(IDispatch
);
242 ITypeInfo
* pTypeInfo
;
246 /******************************************************************************
247 * IDispatch_QueryInterface {OLEAUT32}
249 * See IUnknown_QueryInterface.
251 static HRESULT WINAPI
StdDispatch_QueryInterface(
256 ICOM_THIS(StdDispatch
, iface
);
257 TRACE("(%p)->(%s, %p)\n", iface
, debugstr_guid(riid
), ppvObject
);
259 if (IsEqualIID(riid
, &IID_IDispatch
) ||
260 IsEqualIID(riid
, &IID_IUnknown
))
262 *ppvObject
= (LPVOID
)This
;
263 IUnknown_AddRef((LPUNKNOWN
)*ppvObject
);
266 return E_NOINTERFACE
;
269 /******************************************************************************
270 * IDispatch_AddRef {OLEAUT32}
272 * See IUnknown_AddRef.
274 static ULONG WINAPI
StdDispatch_AddRef(LPDISPATCH iface
)
276 ICOM_THIS(StdDispatch
, iface
);
282 /******************************************************************************
283 * IDispatch_Release {OLEAUT32}
285 * See IUnknown_Release.
287 static ULONG WINAPI
StdDispatch_Release(LPDISPATCH iface
)
289 ICOM_THIS(StdDispatch
, iface
);
291 TRACE("(%p)->()\n", This
);
297 ITypeInfo_Release(This
->pTypeInfo
);
304 /******************************************************************************
305 * IDispatch_GetTypeInfoCount {OLEAUT32}
307 * Get the count of type information in an IDispatch interface.
310 * iface [I] IDispatch interface
311 * pctinfo [O] Destination for the count
314 * Success: S_OK. pctinfo is updated with the count. This is always 1 if
315 * the object provides type information, and 0 if it does not.
316 * Failure: E_NOTIMPL. The object does not provide type information.
319 * See IDispatch() and IDispatch_GetTypeInfo().
321 static HRESULT WINAPI
StdDispatch_GetTypeInfoCount(LPDISPATCH iface
, UINT
* pctinfo
)
323 ICOM_THIS(StdDispatch
, iface
);
324 TRACE("(%p)\n", pctinfo
);
326 *pctinfo
= This
->pTypeInfo
? 1 : 0;
330 /******************************************************************************
331 * IDispatch_GetTypeInfo {OLEAUT32}
333 * Get type information from an IDispatch interface.
336 * iface [I] IDispatch interface
337 * iTInfo [I] Index of type information.
338 * lcid [I] Locale of the type information to get
339 * ppTInfo [O] Destination for the ITypeInfo object
342 * Success: S_OK. ppTInfo is updated with the objects type information
343 * Failure: DISP_E_BADINDEX, if iTInfo is any value other than 0.
348 static HRESULT WINAPI
StdDispatch_GetTypeInfo(LPDISPATCH iface
, UINT iTInfo
, LCID lcid
, ITypeInfo
** ppTInfo
)
350 ICOM_THIS(StdDispatch
, iface
);
351 TRACE("(%d, %lx, %p)\n", iTInfo
, lcid
, ppTInfo
);
355 return DISP_E_BADINDEX
;
359 *ppTInfo
= This
->pTypeInfo
;
360 ITypeInfo_AddRef(*ppTInfo
);
365 /******************************************************************************
366 * IDispatch_GetIDsOfNames {OLEAUT32}
368 * Convert a methods name and an optional set of parameter names into DISPID's
369 * for passing to IDispatch_Invoke().
372 * iface [I] IDispatch interface
373 * riid [I] Reserved, set to IID_NULL
374 * rgszNames [I] Name to convert
375 * cNames [I] Number of names in rgszNames
376 * lcid [I] Locale of the type information to convert from
377 * rgDispId [O] Destination for converted DISPID's.
381 * Failure: DISP_E_UNKNOWNNAME, if any of the names is invalid.
382 * DISP_E_UNKNOWNLCID if lcid is invalid.
383 * Otherwise, an An HRESULT error code.
386 * This call defers to ITypeInfo_GetIDsOfNames(), using the ITypeInfo object
387 * contained within the IDispatch object.
388 * The first member of the names list must be a method name. The names following
389 * the method name are the parameters for that method.
391 static HRESULT WINAPI
StdDispatch_GetIDsOfNames(LPDISPATCH iface
, REFIID riid
, LPOLESTR
* rgszNames
, UINT cNames
, LCID lcid
, DISPID
* rgDispId
)
393 ICOM_THIS(StdDispatch
, iface
);
394 TRACE("(%s, %p, %d, 0x%lx, %p)\n", debugstr_guid(riid
), rgszNames
, cNames
, lcid
, rgDispId
);
396 if (!IsEqualGUID(riid
, &IID_NULL
))
398 FIXME(" expected riid == IID_NULL\n");
401 return DispGetIDsOfNames(This
->pTypeInfo
, rgszNames
, cNames
, rgDispId
);
404 /******************************************************************************
405 * IDispatch_Invoke {OLEAUT32}
407 * Call an object method.
410 * iface [I] IDispatch interface
411 * dispIdMember [I] DISPID of the method (from GetIDsOfNames())
412 * riid [I] Reserved, set to IID_NULL
413 * lcid [I] Locale of the type information to convert parameters with
414 * wFlags, [I] Kind of method call (DISPATCH_ flags from "oaidl.h")
415 * pDispParams [I] Array of method arguments
416 * pVarResult [O] Destination for the result of the call
417 * pExcepInfo [O] Destination for exception information
418 * puArgErr [O] Destination for bad argument
422 * Failure: See DispInvoke() for failure cases.
425 * See DispInvoke() and IDispatch().
427 static HRESULT WINAPI
StdDispatch_Invoke(LPDISPATCH iface
, DISPID dispIdMember
, REFIID riid
, LCID lcid
,
428 WORD wFlags
, DISPPARAMS
* pDispParams
, VARIANT
* pVarResult
,
429 EXCEPINFO
* pExcepInfo
, UINT
* puArgErr
)
431 ICOM_THIS(StdDispatch
, iface
);
432 TRACE("(%ld, %s, 0x%lx, 0x%x, %p, %p, %p, %p)\n", dispIdMember
, debugstr_guid(riid
), lcid
, wFlags
, pDispParams
, pVarResult
, pExcepInfo
, puArgErr
);
434 if (!IsEqualGUID(riid
, &IID_NULL
))
436 FIXME(" expected riid == IID_NULL\n");
439 return DispInvoke(This
->pvThis
, This
->pTypeInfo
, dispIdMember
, wFlags
, pDispParams
, pVarResult
, pExcepInfo
, puArgErr
);
442 static ICOM_VTABLE(IDispatch
) StdDispatch_VTable
=
444 ICOM_MSVTABLE_COMPAT_DummyRTTIVALUE
445 StdDispatch_QueryInterface
,
448 StdDispatch_GetTypeInfoCount
,
449 StdDispatch_GetTypeInfo
,
450 StdDispatch_GetIDsOfNames
,
454 static IDispatch
* WINAPI
StdDispatch_Construct(
455 IUnknown
* punkOuter
,
457 ITypeInfo
* pTypeInfo
)
459 StdDispatch
* pStdDispatch
;
461 pStdDispatch
= CoTaskMemAlloc(sizeof(StdDispatch
));
463 return (IDispatch
*)pStdDispatch
;
465 pStdDispatch
->lpVtbl
= &StdDispatch_VTable
;
466 pStdDispatch
->pvThis
= pvThis
;
467 pStdDispatch
->pTypeInfo
= pTypeInfo
;
468 pStdDispatch
->ref
= 1;
470 /* we keep a reference to the type info so prevent it from
471 * being destroyed until we are done with it */
472 ITypeInfo_AddRef(pTypeInfo
);
474 return (IDispatch
*)pStdDispatch
;