| blob | 16e7241535484791f237df8af3b45ed31b0b1f1a |
7 <para>
8 This section describes how to create your own natively
9 compiled COM/OLE components.
10 </para>
12 <sect2>
15 <para>
16 The goal of the following set of definitions is to provide a
17 way to use the same header file definitions to provide both
18 a C interface and a C++ object oriented interface to COM
19 interfaces. The type of interface is selected automatically
20 depending on the language but it is always possible to get
21 the C interface in C++ by defining CINTERFACE.
22 </para>
23 <para>
24 It is based on the following assumptions:
25 </para>
26 <itemizedlist>
27 <listitem>
28 <para>
29 all COM interfaces derive from IUnknown, this should not
30 be a problem.
31 </para>
32 </listitem>
33 <listitem>
34 <para>
35 the header file only defines the interface, the actual
36 fields are defined separately in the C file implementing
37 the interface.
38 </para>
39 </listitem>
40 </itemizedlist>
41 <para>
42 The natural approach to this problem would be to make sure
43 we get a C++ class and virtual methods in C++ and a
44 structure with a table of pointer to functions in C.
45 Unfortunately the layout of the virtual table is compiler
46 specific, the layout of g++ virtual tables is not the same
47 as that of an egcs virtual table which is not the same as
48 that generated by Visual C+. There are work arounds to make
49 the virtual tables compatible via padding but unfortunately
50 the one which is imposed to the Wine emulator by the Windows
51 binaries, i.e. the Visual C++ one, is the most compact of
52 all.
53 </para>
54 <para>
55 So the solution I finally adopted does not use virtual
56 tables. Instead I use in-line non virtual methods that
57 dereference the method pointer themselves and perform the
58 call.
59 </para>
60 <para>
61 Let's take Direct3D as an example:
62 </para>
63 <programlisting>#define ICOM_INTERFACE IDirect3D
64 #define IDirect3D_METHODS \
65 ICOM_METHOD1(HRESULT,Initialize, REFIID,) \
66 ICOM_METHOD2(HRESULT,EnumDevices, LPD3DENUMDEVICESCALLBACK,, LPVOID,) \
67 ICOM_METHOD2(HRESULT,CreateLight, LPDIRECT3DLIGHT*,, IUnknown*,) \
68 ICOM_METHOD2(HRESULT,CreateMaterial,LPDIRECT3DMATERIAL*,, IUnknown*,) \
69 ICOM_METHOD2(HRESULT,CreateViewport,LPDIRECT3DVIEWPORT*,, IUnknown*,) \
70 ICOM_METHOD2(HRESULT,FindDevice, LPD3DFINDDEVICESEARCH,, LPD3DFINDDEVICERESULT,)
71 #define IDirect3D_IMETHODS \
72 IUnknown_IMETHODS \
73 IDirect3D_METHODS
74 ICOM_DEFINE(IDirect3D,IUnknown)
75 #undef ICOM_INTERFACE
77 #ifdef ICOM_CINTERFACE
78 // *** IUnknown methods *** //
79 #define IDirect3D_QueryInterface(p,a,b) ICOM_CALL2(QueryInterface,p,a,b)
80 #define IDirect3D_AddRef(p) ICOM_CALL (AddRef,p)
81 #define IDirect3D_Release(p) ICOM_CALL (Release,p)
82 // *** IDirect3D methods *** //
83 #define IDirect3D_Initialize(p,a) ICOM_CALL1(Initialize,p,a)
84 #define IDirect3D_EnumDevices(p,a,b) ICOM_CALL2(EnumDevice,p,a,b)
85 #define IDirect3D_CreateLight(p,a,b) ICOM_CALL2(CreateLight,p,a,b)
86 #define IDirect3D_CreateMaterial(p,a,b) ICOM_CALL2(CreateMaterial,p,a,b)
87 #define IDirect3D_CreateViewport(p,a,b) ICOM_CALL2(CreateViewport,p,a,b)
88 #define IDirect3D_FindDevice(p,a,b) ICOM_CALL2(FindDevice,p,a,b)
89 #endif</programlisting>
90 <para>
91 Comments:
92 </para>
93 <para>
94 The ICOM_INTERFACE macro is used in the ICOM_METHOD macros
95 to define the type of the 'this' pointer. Defining this
96 macro here saves us the trouble of having to repeat the
97 interface name everywhere. Note however that because of the
98 way macros work, a macro like ICOM_METHOD1 cannot use
99 'ICOM_INTERFACE##_VTABLE' because this would give
100 'ICOM_INTERFACE_VTABLE' and not 'IDirect3D_VTABLE'.
101 </para>
102 <para>
103 ICOM_METHODS defines the methods specific to this
104 interface. It is then aggregated with the inherited methods
105 to form ICOM_IMETHODS.
106 </para>
107 <para>
108 ICOM_IMETHODS defines the list of methods that are
109 inheritable from this interface. It must be written manually
110 (rather than using a macro to generate the equivalent code)
111 to avoid macro recursion (which compilers don't like).
112 </para>
113 <para>
114 The ICOM_DEFINE finally declares all the structures
115 necessary for the interface. We have to explicitly use the
116 interface name for macro expansion reasons again. Inherited
117 methods are inherited in C by using the IDirect3D_METHODS
118 macro and the parent's Xxx_IMETHODS macro. In C++ we need
119 only use the IDirect3D_METHODS since method inheritance is
120 taken care of by the language.
121 </para>
122 <para>
123 In C++ the ICOM_METHOD macros generate a function prototype
124 and a call to a function pointer method. This means using
125 once 't1 p1, t2 p2, ...' and once 'p1, p2' without the
126 types. The only way I found to handle this is to have one
127 ICOM_METHOD macro per number of parameters and to have it
128 take only the type information (with const if necessary) as
129 parameters. The 'undef ICOM_INTERFACE' is here to remind
130 you that using ICOM_INTERFACE in the following macros will
131 not work. This time it's because the ICOM_CALL macro
132 expansion is done only once the 'IDirect3D_Xxx' macro is
133 expanded. And by that time ICOM_INTERFACE will be long gone
134 anyway.
135 </para>
136 <para>
137 You may have noticed the double commas after each parameter
138 type. This allows you to put the name of that parameter
139 which I think is good for documentation. It is not required
140 and since I did not know what to put there for this example
141 (I could only find doc about IDirect3D2), I left them blank.
142 </para>
143 <para>
144 Finally the set of 'IDirect3D_Xxx' macros is a standard set
145 of macros defined to ease access to the interface methods in
146 C. Unfortunately I don't see any way to avoid having to
147 duplicate the inherited method definitions there. This time
148 I could have used a trick to use only one macro whatever the
149 number of parameters but I preferred to have it work the same
150 way as above.
151 </para>
152 <para>
153 You probably have noticed that we don't define the fields we
154 need to actually implement this interface: reference count,
155 pointer to other resources and miscellaneous fields. That's
156 because these interfaces are just that: interfaces. They may
157 be implemented more than once, in different contexts and
158 sometimes not even in Wine. Thus it would not make sense to
159 impose that the interface contains some specific fields.
160 </para>
161 </sect2>
163 <sect2>
166 <para>
167 In C this gives:
168 </para>
169 <programlisting>typedef struct IDirect3DVtbl IDirect3DVtbl;
170 struct IDirect3D {
171 IDirect3DVtbl* lpVtbl;
172 };
173 struct IDirect3DVtbl {
174 HRESULT (*fnQueryInterface)(IDirect3D* me, REFIID riid, LPVOID* ppvObj);
175 ULONG (*fnAddRef)(IDirect3D* me);
176 ULONG (*fnRelease)(IDirect3D* me);
177 HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
178 HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
179 HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
180 HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
181 HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
182 HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
183 };
185 #ifdef ICOM_CINTERFACE
186 // *** IUnknown methods *** //
190 // *** IDirect3D methods *** //
197 #endif</programlisting>
198 <para>
199 Comments:
200 </para>
201 <para>
202 IDirect3D only contains a pointer to the IDirect3D
203 virtual/jump table. This is the only thing the user needs to
204 know to use the interface. Of course the structure we will
205 define to implement this interface will have more fields but
206 the first one will match this pointer.
207 </para>
208 <para>
209 The code generated by ICOM_DEFINE defines both the structure
210 representing the interface and the structure for the jump
211 table. ICOM_DEFINE uses the parent's Xxx_IMETHODS macro to
212 automatically repeat the prototypes of all the inherited
213 methods and then uses IDirect3D_METHODS to define the
214 IDirect3D methods.
215 </para>
216 <para>
217 Each method is declared as a pointer to function field in
218 the jump table. The implementation will fill this jump table
219 with appropriate values, probably using a static variable,
220 and initialize the lpVtbl field to point to this variable.
221 </para>
222 <para>
223 The IDirect3D_Xxx macros then just dereference the lpVtbl
224 pointer and use the function pointer corresponding to the
225 macro name. This emulates the behavior of a virtual table
226 and should be just as fast.
227 </para>
228 <para>
229 This C code should be quite compatible with the Windows
230 headers both for code that uses COM interfaces and for code
231 implementing a COM interface.
232 </para>
233 </sect2>
235 <sect2>
237 <para>
238 And in C++ (with gcc's g++):
239 </para>
240 <programlisting>typedef struct IDirect3D: public IUnknown {
241 private: HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
242 public: inline HRESULT Initialize(REFIID a) { return ((IDirect3D*)t.lpVtbl)->fnInitialize(this,a); };
243 private: HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
244 public: inline HRESULT EnumDevices(LPD3DENUMDEVICESCALLBACK a, LPVOID b)
245 { return ((IDirect3D*)t.lpVtbl)->fnEnumDevices(this,a,b); };
246 private: HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
247 public: inline HRESULT CreateLight(LPDIRECT3DLIGHT* a, IUnknown* b)
248 { return ((IDirect3D*)t.lpVtbl)->fnCreateLight(this,a,b); };
249 private: HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
250 public: inline HRESULT CreateMaterial(LPDIRECT3DMATERIAL* a, IUnknown* b)
251 { return ((IDirect3D*)t.lpVtbl)->fnCreateMaterial(this,a,b); };
252 private: HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
253 public: inline HRESULT CreateViewport(LPDIRECT3DVIEWPORT* a, IUnknown* b)
254 { return ((IDirect3D*)t.lpVtbl)->fnCreateViewport(this,a,b); };
255 private: HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
256 public: inline HRESULT FindDevice(LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b)
257 { return ((IDirect3D*)t.lpVtbl)->fnFindDevice(this,a,b); };
258 };</programlisting>
259 <para>
260 Comments:
261 </para>
262 <para>
263 In C++ IDirect3D does double duty as both the virtual/jump
264 table and as the interface definition. The reason for this
265 is to avoid having to duplicate the method definitions: once
266 to have the function pointers in the jump table and once to
267 have the methods in the interface class. Here one macro can
268 generate both. This means though that the first pointer,
269 t.lpVtbl defined in IUnknown, must be interpreted as the
270 jump table pointer if we interpret the structure as the
271 interface class, and as the function pointer to the
272 QueryInterface method, t.fnQueryInterface, if we interpret
273 the structure as the jump table. Fortunately this gymnastic
274 is entirely taken care of in the header of IUnknown.
275 </para>
276 <para>
277 Of course in C++ we use inheritance so that we don't have to
278 duplicate the method definitions.
279 </para>
280 <para>
281 Since IDirect3D does double duty, each ICOM_METHOD macro
282 defines both a function pointer and a non-virtual inline
283 method which dereferences it and calls it. This way this
284 method behaves just like a virtual method but does not
285 create a true C++ virtual table which would break the
286 structure layout. If you look at the implementation of these
287 methods you'll notice that they would not work for void
288 functions. We have to return something and fortunately this
289 seems to be what all the COM methods do (otherwise we would
290 need another set of macros).
291 </para>
292 <para>
293 Note how the ICOM_METHOD generates both function prototypes
294 mixing types and formal parameter names and the method
295 invocation using only the formal parameter name. This is the
296 reason why we need different macros to handle different
297 numbers of parameters.
298 </para>
299 <para>
300 Finally there is no IDirect3D_Xxx macro. These are not
301 needed in C++ unless the CINTERFACE macro is defined in
302 which case we would not be here.
303 </para>
304 <para>
305 This C++ code works well for code that just uses COM
306 interfaces. But it will not work with C++ code implement a
307 COM interface. That's because such code assumes the
308 interface methods are declared as virtual C++ methods which
309 is not the case here.
310 </para>
311 </sect2>
313 <sect2>
316 <para>
317 This continues the above example. This example assumes that
318 the implementation is in C.
319 </para>
320 <programlisting>typedef struct _IDirect3D {
321 void* lpVtbl;
322 // ...
323 } _IDirect3D;
325 static ICOM_VTABLE(IDirect3D) d3dvt;
327 // implement the IDirect3D methods here
329 int IDirect3D_fnQueryInterface(IDirect3D* me)
330 {
331 ICOM_THIS(IDirect3D,me);
332 // ...
333 }
335 // ...
337 static ICOM_VTABLE(IDirect3D) d3dvt = {
338 ICOM_MSVTABLE_COMPAT_DummyRTTIVALUE
339 IDirect3D_fnQueryInterface,
340 IDirect3D_fnAdd,
341 IDirect3D_fnAdd2,
342 IDirect3D_fnInitialize,
343 IDirect3D_fnSetWidth
344 };</programlisting>
345 <para>
346 Comments:
347 </para>
348 <para>
349 We first define what the interface really contains. This is
350 the _IDirect3D structure. The first field must of course be
351 the virtual table pointer. Everything else is free.
352 </para>
353 <para>
354 Then we predeclare our static virtual table variable, we
355 will need its address in some methods to initialize the
356 virtual table pointer of the returned interface objects.
357 </para>
358 <para>
359 Then we implement the interface methods. To match what has
360 been declared in the header file they must take a pointer to
361 a IDirect3D structure and we must cast it to an _IDirect3D
362 so that we can manipulate the fields. This is performed by
363 the ICOM_THIS macro.
364 </para>
365 <para>
366 Finally we initialize the virtual table.
367 </para>
368 </sect2>
369 </sect1>
370 </chapter>
372 <!-- Keep this comment at the end of the file
373 Local variables:
374 mode: sgml
375 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
376 End:
377 -->