d3d8: Add a separate function for surface initialization.
[wine] / dlls / oleaut32 / dispatch.c
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 }