1 /**
2 * Dispatch API functions
3 *
4 * Copyright 2000 Francois Jacques, Macadamian Technologies Inc.
5 *
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.
10 *
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.
15 *
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
19 *
20 */
21
22 #include "config.h"
23
24 #include <stdlib.h>
25 #include <string.h>
26 #include <stdarg.h>
27 #include <stdio.h>
28 #include <ctype.h>
29
30 #define COBJMACROS
31
32 #include "windef.h"
33 #include "winbase.h"
34 #include "objbase.h"
35 #include "oleauto.h"
36 #include "winerror.h"
37
38 #include "wine/debug.h"
39
40 WINE_DEFAULT_DEBUG_CHANNEL(ole);
41
42 static IDispatch * StdDispatch_Construct(IUnknown * punkOuter, void * pvThis, ITypeInfo * pTypeInfo);
43
44 /******************************************************************************
45 * DispInvoke (OLEAUT32.30)
46 *
47 * Call an object method using the information from its type library.
48 *
49 * RETURNS
50 * Success: S_OK.
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().
56 *
57 * NOTES
58 * Parameter errors include the following:
59 *| DISP_E_BADVARTYPE
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().
66 */
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 */
76 {
77 TRACE("\n");
78
79 return ITypeInfo_Invoke(ptinfo, _this, dispidMember, wFlags,
80 pparams, pvarResult, pexcepinfo, puArgErr);
81 }
82
83 /******************************************************************************
84 * DispGetIDsOfNames (OLEAUT32.29)
85 *
86 * Convert a set of parameter names to DISPIDs for DispInvoke().
87 *
88 * RETURNS
89 * Success: S_OK.
90 * Failure: An HRESULT error code.
91 *
92 * NOTES
93 * This call defers to ITypeInfo_GetIDsOfNames(). The ITypeInfo interface passed
94 * as ptinfo contains the information to map names to DISPIDs.
95 */
96 HRESULT WINAPI DispGetIDsOfNames(
97 ITypeInfo *ptinfo, /* [in] Object's type info */
98 OLECHAR **rgszNames, /* [in] Array of names to get DISPIDs for */
99 UINT cNames, /* [in] Number of names in rgszNames */
100 DISPID *rgdispid) /* [out] Destination for converted DISPIDs */
101 {
102 return ITypeInfo_GetIDsOfNames(ptinfo, rgszNames, cNames, rgdispid);
103 }
104
105 /******************************************************************************
106 * DispGetParam (OLEAUT32.28)
107 *
108 * Retrieve a parameter from a DISPPARAMS structure and coerce it to the
109 * specified variant type.
110 *
111 * NOTES
112 * Coercion is done using system (0) locale.
113 *
114 * RETURNS
115 * Success: S_OK.
116 * Failure: DISP_E_PARAMNOTFOUND, if position is invalid. or
117 * DISP_E_TYPEMISMATCH, if the coercion failed. puArgErr is
118 * set to the index of the argument in pdispparams.
119 */
120 HRESULT WINAPI DispGetParam(
121 DISPPARAMS *pdispparams, /* [in] Parameter list */
122 UINT position, /* [in] Position of parameter to coerce in pdispparams */
123 VARTYPE vtTarg, /* [in] Type of value to coerce to */
124 VARIANT *pvarResult, /* [out] Destination for resulting variant */
125 UINT *puArgErr) /* [out] Destination for error code */
126 {
127 /* position is counted backwards */
128 UINT pos;
129 HRESULT hr;
130
131 TRACE("position=%d, cArgs=%d, cNamedArgs=%d\n",
132 position, pdispparams->cArgs, pdispparams->cNamedArgs);
133 if (position < pdispparams->cArgs) {
134 /* positional arg? */
135 pos = pdispparams->cArgs - position - 1;
136 } else {
137 /* FIXME: is this how to handle named args? */
138 for (pos=0; pos<pdispparams->cNamedArgs; pos++)
139 if (pdispparams->rgdispidNamedArgs[pos] == position) break;
140
141 if (pos==pdispparams->cNamedArgs)
142 return DISP_E_PARAMNOTFOUND;
143 }
144 hr = VariantChangeType(pvarResult,
145 &pdispparams->rgvarg[pos],
146 0, vtTarg);
147 if (hr == DISP_E_TYPEMISMATCH) *puArgErr = pos;
148 return hr;
149 }
150
151 /******************************************************************************
152 * CreateStdDispatch [OLEAUT32.32]
153 *
154 * Create and return a standard IDispatch object.
155 *
156 * RETURNS
157 * Success: S_OK. ppunkStdDisp contains the new object.
158 * Failure: An HRESULT error code.
159 *
160 * NOTES
161 * Outer unknown appears to be completely ignored.
162 */
163 HRESULT WINAPI CreateStdDispatch(
164 IUnknown* punkOuter,
165 void* pvThis,
166 ITypeInfo* ptinfo,
167 IUnknown** ppunkStdDisp)
168 {
169 TRACE("(%p, %p, %p, %p)\n", punkOuter, pvThis, ptinfo, ppunkStdDisp);
170
171 *ppunkStdDisp = (LPUNKNOWN)StdDispatch_Construct(punkOuter, pvThis, ptinfo);
172 if (!*ppunkStdDisp)
173 return E_OUTOFMEMORY;
174 return S_OK;
175 }
176
177
178 /******************************************************************************
179 * IDispatch {OLEAUT32}
180 *
181 * NOTES
182 * The IDispatch interface provides a single interface to dispatch method calls,
183 * regardless of whether the object to be called is in or out of process,
184 * local or remote (e.g. being called over a network). This interface is late-bound
185 * (linked at run-time), as opposed to early-bound (linked at compile time).
186 *
187 * The interface is used by objects that wish to called by scripting
188 * languages such as VBA, in order to minimise the amount of COM and C/C++
189 * knowledge required, or by objects that wish to live out of process from code
190 * that will call their methods.
191 *
192 * Method, property and parameter names can be localised. The details required to
193 * map names to methods and parameters are collected in a type library, usually
194 * output by an IDL compiler using the objects IDL description. This information is
195 * accessible programmatically through the ITypeLib interface (for a type library),
196 * and the ITypeInfo interface (for an object within the type library). Type information
197 * can also be created at run-time using CreateDispTypeInfo().
198 *
199 * WRAPPERS
200 * Instead of using IDispatch directly, there are several wrapper functions available
201 * to simplify the process of calling an objects methods through IDispatch.
202 *
203 * A standard implementation of an IDispatch object is created by calling
204 * CreateStdDispatch(). Numeric Id values for the parameters and methods (DISPIDs)
205 * of an object of interest are retrieved by calling DispGetIDsOfNames(). DispGetParam()
206 * retrieves information about a particular parameter. Finally the DispInvoke()
207 * function is responsible for actually calling methods on an object.
208 *
209 * METHODS
210 */
211
212 typedef struct
213 {
214 const IDispatchVtbl *lpVtbl;
215 void * pvThis;
216 ITypeInfo * pTypeInfo;
217 LONG ref;
218 } StdDispatch;
219
220 /******************************************************************************
221 * IDispatch_QueryInterface {OLEAUT32}
222 *
223 * See IUnknown_QueryInterface.
224 */
225 static HRESULT WINAPI StdDispatch_QueryInterface(
226 LPDISPATCH iface,
227 REFIID riid,
228 void** ppvObject)
229 {
230 StdDispatch *This = (StdDispatch *)iface;
231 TRACE("(%p)->(%s, %p)\n", iface, debugstr_guid(riid), ppvObject);
232
233 if (IsEqualIID(riid, &IID_IDispatch) ||
234 IsEqualIID(riid, &IID_IUnknown))
235 {
236 *ppvObject = This;
237 IUnknown_AddRef((LPUNKNOWN)*ppvObject);
238 return S_OK;
239 }
240 return E_NOINTERFACE;
241 }
242
243 /******************************************************************************
244 * IDispatch_AddRef {OLEAUT32}
245 *
246 * See IUnknown_AddRef.
247 */
248 static ULONG WINAPI StdDispatch_AddRef(LPDISPATCH iface)
249 {
250 StdDispatch *This = (StdDispatch *)iface;
251 ULONG refCount = InterlockedIncrement(&This->ref);
252
253 TRACE("(%p)->(ref before=%u)\n",This, refCount - 1);
254
255 return refCount;
256 }
257
258 /******************************************************************************
259 * IDispatch_Release {OLEAUT32}
260 *
261 * See IUnknown_Release.
262 */
263 static ULONG WINAPI StdDispatch_Release(LPDISPATCH iface)
264 {
265 StdDispatch *This = (StdDispatch *)iface;
266 ULONG refCount = InterlockedDecrement(&This->ref);
267
268 TRACE("(%p)->(ref before=%u)\n", This, refCount + 1);
269
270 if (!refCount)
271 {
272 ITypeInfo_Release(This->pTypeInfo);
273 CoTaskMemFree(This);
274 }
275
276 return refCount;
277 }
278
279 /******************************************************************************
280 * IDispatch_GetTypeInfoCount {OLEAUT32}
281 *
282 * Get the count of type information in an IDispatch interface.
283 *
284 * PARAMS
285 * iface [I] IDispatch interface
286 * pctinfo [O] Destination for the count
287 *
288 * RETURNS
289 * Success: S_OK. pctinfo is updated with the count. This is always 1 if
290 * the object provides type information, and 0 if it does not.
291 * Failure: E_NOTIMPL. The object does not provide type information.
292 *
293 * NOTES
294 * See IDispatch() and IDispatch_GetTypeInfo().
295 */
296 static HRESULT WINAPI StdDispatch_GetTypeInfoCount(LPDISPATCH iface, UINT * pctinfo)
297 {
298 StdDispatch *This = (StdDispatch *)iface;
299 TRACE("(%p)\n", pctinfo);
300
301 *pctinfo = This->pTypeInfo ? 1 : 0;
302 return S_OK;
303 }
304
305 /******************************************************************************
306 * IDispatch_GetTypeInfo {OLEAUT32}
307 *
308 * Get type information from an IDispatch interface.
309 *
310 * PARAMS
311 * iface [I] IDispatch interface
312 * iTInfo [I] Index of type information.
313 * lcid [I] Locale of the type information to get
314 * ppTInfo [O] Destination for the ITypeInfo object
315 *
316 * RETURNS
317 * Success: S_OK. ppTInfo is updated with the objects type information
318 * Failure: DISP_E_BADINDEX, if iTInfo is any value other than 0.
319 *
320 * NOTES
321 * See IDispatch.
322 */
323 static HRESULT WINAPI StdDispatch_GetTypeInfo(LPDISPATCH iface, UINT iTInfo, LCID lcid, ITypeInfo** ppTInfo)
324 {
325 StdDispatch *This = (StdDispatch *)iface;
326 TRACE("(%d, %x, %p)\n", iTInfo, lcid, ppTInfo);
327
328 *ppTInfo = NULL;
329 if (iTInfo != 0)
330 return DISP_E_BADINDEX;
331
332 if (This->pTypeInfo)
333 {
334 *ppTInfo = This->pTypeInfo;
335 ITypeInfo_AddRef(*ppTInfo);
336 }
337 return S_OK;
338 }
339
340 /******************************************************************************
341 * IDispatch_GetIDsOfNames {OLEAUT32}
342 *
343 * Convert a methods name and an optional set of parameter names into DISPIDs
344 * for passing to IDispatch_Invoke().
345 *
346 * PARAMS
347 * iface [I] IDispatch interface
348 * riid [I] Reserved, set to IID_NULL
349 * rgszNames [I] Name to convert
350 * cNames [I] Number of names in rgszNames
351 * lcid [I] Locale of the type information to convert from
352 * rgDispId [O] Destination for converted DISPIDs.
353 *
354 * RETURNS
355 * Success: S_OK.
356 * Failure: DISP_E_UNKNOWNNAME, if any of the names is invalid.
357 * DISP_E_UNKNOWNLCID if lcid is invalid.
358 * Otherwise, an HRESULT error code.
359 *
360 * NOTES
361 * This call defers to ITypeInfo_GetIDsOfNames(), using the ITypeInfo object
362 * contained within the IDispatch object.
363 * The first member of the names list must be a method name. The names following
364 * the method name are the parameters for that method.
365 */
366 static HRESULT WINAPI StdDispatch_GetIDsOfNames(LPDISPATCH iface, REFIID riid, LPOLESTR * rgszNames, UINT cNames, LCID lcid, DISPID * rgDispId)
367 {
368 StdDispatch *This = (StdDispatch *)iface;
369 TRACE("(%s, %p, %d, 0x%x, %p)\n", debugstr_guid(riid), rgszNames, cNames, lcid, rgDispId);
370
371 if (!IsEqualGUID(riid, &IID_NULL))
372 {
373 FIXME(" expected riid == IID_NULL\n");
374 return E_INVALIDARG;
375 }
376 return DispGetIDsOfNames(This->pTypeInfo, rgszNames, cNames, rgDispId);
377 }
378
379 /******************************************************************************
380 * IDispatch_Invoke {OLEAUT32}
381 *
382 * Call an object method.
383 *
384 * PARAMS
385 * iface [I] IDispatch interface
386 * dispIdMember [I] DISPID of the method (from GetIDsOfNames())
387 * riid [I] Reserved, set to IID_NULL
388 * lcid [I] Locale of the type information to convert parameters with
389 * wFlags, [I] Kind of method call (DISPATCH_ flags from "oaidl.h")
390 * pDispParams [I] Array of method arguments
391 * pVarResult [O] Destination for the result of the call
392 * pExcepInfo [O] Destination for exception information
393 * puArgErr [O] Destination for bad argument
394 *
395 * RETURNS
396 * Success: S_OK.
397 * Failure: See DispInvoke() for failure cases.
398 *
399 * NOTES
400 * See DispInvoke() and IDispatch().
401 */
402 static HRESULT WINAPI StdDispatch_Invoke(LPDISPATCH iface, DISPID dispIdMember, REFIID riid, LCID lcid,
403 WORD wFlags, DISPPARAMS * pDispParams, VARIANT * pVarResult,
404 EXCEPINFO * pExcepInfo, UINT * puArgErr)
405 {
406 StdDispatch *This = (StdDispatch *)iface;
407 TRACE("(%d, %s, 0x%x, 0x%x, %p, %p, %p, %p)\n", dispIdMember, debugstr_guid(riid), lcid, wFlags, pDispParams, pVarResult, pExcepInfo, puArgErr);
408
409 if (!IsEqualGUID(riid, &IID_NULL))
410 {
411 FIXME(" expected riid == IID_NULL\n");
412 return E_INVALIDARG;
413 }
414 return DispInvoke(This->pvThis, This->pTypeInfo, dispIdMember, wFlags, pDispParams, pVarResult, pExcepInfo, puArgErr);
415 }
416
417 static const IDispatchVtbl StdDispatch_VTable =
418 {
419 StdDispatch_QueryInterface,
420 StdDispatch_AddRef,
421 StdDispatch_Release,
422 StdDispatch_GetTypeInfoCount,
423 StdDispatch_GetTypeInfo,
424 StdDispatch_GetIDsOfNames,
425 StdDispatch_Invoke
426 };
427
428 static IDispatch * StdDispatch_Construct(
429 IUnknown * punkOuter,
430 void * pvThis,
431 ITypeInfo * pTypeInfo)
432 {
433 StdDispatch * pStdDispatch;
434
435 pStdDispatch = CoTaskMemAlloc(sizeof(StdDispatch));
436 if (!pStdDispatch)
437 return (IDispatch *)pStdDispatch;
438
439 pStdDispatch->lpVtbl = &StdDispatch_VTable;
440 pStdDispatch->pvThis = pvThis;
441 pStdDispatch->pTypeInfo = pTypeInfo;
442 pStdDispatch->ref = 1;
443
444 /* we keep a reference to the type info so prevent it from
445 * being destroyed until we are done with it */
446 ITypeInfo_AddRef(pTypeInfo);
447
448 return (IDispatch *)pStdDispatch;
449 }
450
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.