398 lines
17 KiB
Plaintext
398 lines
17 KiB
Plaintext
|
<chapter id="ole">
|
||
|
|
<title>COM/OLE in Wine</title>
|
||
|
|
|
||
|
|
<sect1 id="ole-architecture">
|
||
|
|
<title>COM/OLE Architecture in Wine</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The section goes into detail about how COM/OLE2 are
|
||
|
|
implemented in Wine.
|
||
|
|
</para>
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
<sect1 id="ole-binary">
|
||
|
|
<title>Using Binary OLE components in Wine</title>
|
||
|
|
<para>
|
||
|
|
This section describes how to import pre-compiled COM/OLE
|
||
|
|
components...
|
||
|
|
</para>
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
<sect1 id="com-writing">
|
||
|
|
<title>Writing OLE Components for Wine</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Based on the comments in <filename>wine/include/wine/obj_base.h</filename>.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
This section describes how to create your own natively
|
||
|
|
compiled COM/OLE components.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<sect2>
|
||
|
|
<title>Macros to define a COM interface</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The goal of the following set of definitions is to provide a
|
||
|
|
way to use the same header file definitions to provide both
|
||
|
|
a C interface and a C++ object oriented interface to COM
|
||
|
|
interfaces. The type of interface is selected automatically
|
||
|
|
depending on the language but it is always possible to get
|
||
|
|
the C interface in C++ by defining CINTERFACE.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
It is based on the following assumptions:
|
||
|
|
</para>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
all COM interfaces derive from IUnknown, this should not
|
||
|
|
be a problem.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>
|
||
|
|
the header file only defines the interface, the actual
|
||
|
|
fields are defined separately in the C file implementing
|
||
|
|
the interface.
|
||
|
|
</para>
|
||
|
|
</listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>
|
||
|
|
The natural approach to this problem would be to make sure
|
||
|
|
we get a C++ class and virtual methods in C++ and a
|
||
|
|
structure with a table of pointer to functions in C.
|
||
|
|
Unfortunately the layout of the virtual table is compiler
|
||
|
|
specific, the layout of g++ virtual tables is not the same
|
||
|
|
as that of an egcs virtual table which is not the same as
|
||
|
|
that generated by Visual C+. There are workarounds to make
|
||
|
|
the virtual tables compatible via padding but unfortunately
|
||
|
|
the one which is imposed to the WINE emulator by the Windows
|
||
|
|
binaries, i.e. the Visual C++ one, is the most compact of
|
||
|
|
all.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
So the solution I finally adopted does not use virtual
|
||
|
|
tables. Instead I use inline non virtual methods that
|
||
|
|
dereference the method pointer themselves and perform the
|
||
|
|
call.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Let's take Direct3D as an example:
|
||
|
|
</para>
|
||
|
|
<programlisting>#define ICOM_INTERFACE IDirect3D
|
||
|
|
#define IDirect3D_METHODS \
|
||
|
|
ICOM_METHOD1(HRESULT,Initialize, REFIID,) \
|
||
|
|
ICOM_METHOD2(HRESULT,EnumDevices, LPD3DENUMDEVICESCALLBACK,, LPVOID,) \
|
||
|
|
ICOM_METHOD2(HRESULT,CreateLight, LPDIRECT3DLIGHT*,, IUnknown*,) \
|
||
|
|
ICOM_METHOD2(HRESULT,CreateMaterial,LPDIRECT3DMATERIAL*,, IUnknown*,) \
|
||
|
|
ICOM_METHOD2(HRESULT,CreateViewport,LPDIRECT3DVIEWPORT*,, IUnknown*,) \
|
||
|
|
ICOM_METHOD2(HRESULT,FindDevice, LPD3DFINDDEVICESEARCH,, LPD3DFINDDEVICERESULT,)
|
||
|
|
#define IDirect3D_IMETHODS \
|
||
|
|
IUnknown_IMETHODS \
|
||
|
|
IDirect3D_METHODS
|
||
|
|
ICOM_DEFINE(IDirect3D,IUnknown)
|
||
|
|
#undef ICOM_INTERFACE
|
||
|
|
|
||
|
|
#ifdef ICOM_CINTERFACE
|
||
|
|
// *** IUnknown methods *** //
|
||
|
|
#define IDirect3D_QueryInterface(p,a,b) ICOM_CALL2(QueryInterface,p,a,b)
|
||
|
|
#define IDirect3D_AddRef(p) ICOM_CALL (AddRef,p)
|
||
|
|
#define IDirect3D_Release(p) ICOM_CALL (Release,p)
|
||
|
|
// *** IDirect3D methods *** //
|
||
|
|
#define IDirect3D_Initialize(p,a) ICOM_CALL1(Initialize,p,a)
|
||
|
|
#define IDirect3D_EnumDevices(p,a,b) ICOM_CALL2(EnumDevice,p,a,b)
|
||
|
|
#define IDirect3D_CreateLight(p,a,b) ICOM_CALL2(CreateLight,p,a,b)
|
||
|
|
#define IDirect3D_CreateMaterial(p,a,b) ICOM_CALL2(CreateMaterial,p,a,b)
|
||
|
|
#define IDirect3D_CreateViewport(p,a,b) ICOM_CALL2(CreateViewport,p,a,b)
|
||
|
|
#define IDirect3D_FindDevice(p,a,b) ICOM_CALL2(FindDevice,p,a,b)
|
||
|
|
#endif</programlisting>
|
||
|
|
<para>
|
||
|
|
Comments:
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The ICOM_INTERFACE macro is used in the ICOM_METHOD macros
|
||
|
|
to define the type of the 'this' pointer. Defining this
|
||
|
|
macro here saves us the trouble of having to repeat the
|
||
|
|
interface name everywhere. Note however that because of the
|
||
|
|
way macros work, a macro like ICOM_METHOD1 cannot use
|
||
|
|
'ICOM_INTERFACE##_VTABLE' because this would give
|
||
|
|
'ICOM_INTERFACE_VTABLE' and not 'IDirect3D_VTABLE'.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
ICOM_METHODS defines the methods specific to this
|
||
|
|
interface. It is then aggregated with the inherited methods
|
||
|
|
to form ICOM_IMETHODS.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
ICOM_IMETHODS defines the list of methods that are
|
||
|
|
inheritable from this interface. It must be written manually
|
||
|
|
(rather than using a macro to generate the equivalent code)
|
||
|
|
to avoid macro recursion (which compilers don't like).
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The ICOM_DEFINE finally declares all the structures
|
||
|
|
necessary for the interface. We have to explicitly use the
|
||
|
|
interface name for macro expansion reasons again. Inherited
|
||
|
|
methods are inherited in C by using the IDirect3D_METHODS
|
||
|
|
macro and the parent's Xxx_IMETHODS macro. In C++ we need
|
||
|
|
only use the IDirect3D_METHODS since method inheritance is
|
||
|
|
taken care of by the language.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
In C++ the ICOM_METHOD macros generate a function prototype
|
||
|
|
and a call to a function pointer method. This means using
|
||
|
|
once 't1 p1, t2 p2, ...' and once 'p1, p2' without the
|
||
|
|
types. The only way I found to handle this is to have one
|
||
|
|
ICOM_METHOD macro per number of parameters and to have it
|
||
|
|
take only the type information (with const if necessary) as
|
||
|
|
parameters. The 'undef ICOM_INTERFACE' is here to remind
|
||
|
|
you that using ICOM_INTERFACE in the following macros will
|
||
|
|
not work. This time it's because the ICOM_CALL macro
|
||
|
|
expansion is done only once the 'IDirect3D_Xxx' macro is
|
||
|
|
expanded. And by that time ICOM_INTERFACE will be long gone
|
||
|
|
anyway.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
You may have noticed the double commas after each parameter
|
||
|
|
type. This allows you to put the name of that parameter
|
||
|
|
which I think is good for documentation. It is not required
|
||
|
|
and since I did not know what to put there for this example
|
||
|
|
(I could only find doc about IDirect3D2), I left them blank.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Finally the set of 'IDirect3D_Xxx' macros is a standard set
|
||
|
|
of macros defined to ease access to the interface methods in
|
||
|
|
C. Unfortunately I don't see any way to avoid having to
|
||
|
|
duplicate the inherited method definitions there. This time
|
||
|
|
I could have used a trick to use only one macro whatever the
|
||
|
|
number of parameters but I prefered to have it work the same
|
||
|
|
way as above.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
You probably have noticed that we don't define the fields we
|
||
|
|
need to actually implement this interface: reference count,
|
||
|
|
pointer to other resources and miscellaneous fields. That's
|
||
|
|
because these interfaces are just that: interfaces. They may
|
||
|
|
be implemented more than once, in different contexts and
|
||
|
|
sometimes not even in Wine. Thus it would not make sense to
|
||
|
|
impose that the interface contains some specific fields.
|
||
|
|
</para>
|
||
|
|
</sect2>
|
||
|
|
|
||
|
|
<sect2>
|
||
|
|
<title>Bindings in C</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
In C this gives:
|
||
|
|
</para>
|
||
|
|
<programlisting>typedef struct IDirect3DVtbl IDirect3DVtbl;
|
||
|
|
struct IDirect3D {
|
||
|
|
IDirect3DVtbl* lpVtbl;
|
||
|
|
};
|
||
|
|
struct IDirect3DVtbl {
|
||
|
|
HRESULT (*fnQueryInterface)(IDirect3D* me, REFIID riid, LPVOID* ppvObj);
|
||
|
|
ULONG (*fnAddRef)(IDirect3D* me);
|
||
|
|
ULONG (*fnRelease)(IDirect3D* me);
|
||
|
|
HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
|
||
|
|
HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
|
||
|
|
HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
|
||
|
|
HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
|
||
|
|
HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
|
||
|
|
HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
|
||
|
|
};
|
||
|
|
|
||
|
|
#ifdef ICOM_CINTERFACE
|
||
|
|
// *** IUnknown methods *** //
|
||
|
|
#define IDirect3D_QueryInterface(p,a,b) (p)->lpVtbl->fnQueryInterface(p,a,b)
|
||
|
|
#define IDirect3D_AddRef(p) (p)->lpVtbl->fnAddRef(p)
|
||
|
|
#define IDirect3D_Release(p) (p)->lpVtbl->fnRelease(p)
|
||
|
|
// *** IDirect3D methods *** //
|
||
|
|
#define IDirect3D_Initialize(p,a) (p)->lpVtbl->fnInitialize(p,a)
|
||
|
|
#define IDirect3D_EnumDevices(p,a,b) (p)->lpVtbl->fnEnumDevice(p,a,b)
|
||
|
|
#define IDirect3D_CreateLight(p,a,b) (p)->lpVtbl->fnCreateLight(p,a,b)
|
||
|
|
#define IDirect3D_CreateMaterial(p,a,b) (p)->lpVtbl->fnCreateMaterial(p,a,b)
|
||
|
|
#define IDirect3D_CreateViewport(p,a,b) (p)->lpVtbl->fnCreateViewport(p,a,b)
|
||
|
|
#define IDirect3D_FindDevice(p,a,b) (p)->lpVtbl->fnFindDevice(p,a,b)
|
||
|
|
#endif</programlisting>
|
||
|
|
<para>
|
||
|
|
Comments:
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
IDirect3D only contains a pointer to the IDirect3D
|
||
|
|
virtual/jump table. This is the only thing the user needs to
|
||
|
|
know to use the interface. Of course the structure we will
|
||
|
|
define to implement this interface will have more fields but
|
||
|
|
the first one will match this pointer.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The code generated by ICOM_DEFINE defines both the structure
|
||
|
|
representing the interface and the structure for the jump
|
||
|
|
table. ICOM_DEFINE uses the parent's Xxx_IMETHODS macro to
|
||
|
|
automatically repeat the prototypes of all the inherited
|
||
|
|
methods and then uses IDirect3D_METHODS to define the
|
||
|
|
IDirect3D methods.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Each method is declared as a pointer to function field in
|
||
|
|
the jump table. The implementation will fill this jump table
|
||
|
|
with appropriate values, probably using a static variable,
|
||
|
|
and initialize the lpVtbl field to point to this variable.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The IDirect3D_Xxx macros then just derefence the lpVtbl
|
||
|
|
pointer and use the function pointer corresponding to the
|
||
|
|
macro name. This emulates the behavior of a virtual table
|
||
|
|
and should be just as fast.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
This C code should be quite compatible with the Windows
|
||
|
|
headers both for code that uses COM interfaces and for code
|
||
|
|
implementing a COM interface.
|
||
|
|
</para>
|
||
|
|
</sect2>
|
||
|
|
|
||
|
|
<sect2>
|
||
|
|
<title>Bindings in C++</title>
|
||
|
|
<para>
|
||
|
|
And in C++ (with gcc's g++):
|
||
|
|
</para>
|
||
|
|
<programlisting>typedef struct IDirect3D: public IUnknown {
|
||
|
|
private: HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
|
||
|
|
public: inline HRESULT Initialize(REFIID a) { return ((IDirect3D*)t.lpVtbl)->fnInitialize(this,a); };
|
||
|
|
private: HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
|
||
|
|
public: inline HRESULT EnumDevices(LPD3DENUMDEVICESCALLBACK a, LPVOID b)
|
||
|
|
{ return ((IDirect3D*)t.lpVtbl)->fnEnumDevices(this,a,b); };
|
||
|
|
private: HRESULT (*fnCreateLight)(IDirect3D* me, LPDIRECT3DLIGHT* a, IUnknown* b);
|
||
|
|
public: inline HRESULT CreateLight(LPDIRECT3DLIGHT* a, IUnknown* b)
|
||
|
|
{ return ((IDirect3D*)t.lpVtbl)->fnCreateLight(this,a,b); };
|
||
|
|
private: HRESULT (*fnCreateMaterial)(IDirect3D* me, LPDIRECT3DMATERIAL* a, IUnknown* b);
|
||
|
|
public: inline HRESULT CreateMaterial(LPDIRECT3DMATERIAL* a, IUnknown* b)
|
||
|
|
{ return ((IDirect3D*)t.lpVtbl)->fnCreateMaterial(this,a,b); };
|
||
|
|
private: HRESULT (*fnCreateViewport)(IDirect3D* me, LPDIRECT3DVIEWPORT* a, IUnknown* b);
|
||
|
|
public: inline HRESULT CreateViewport(LPDIRECT3DVIEWPORT* a, IUnknown* b)
|
||
|
|
{ return ((IDirect3D*)t.lpVtbl)->fnCreateViewport(this,a,b); };
|
||
|
|
private: HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
|
||
|
|
public: inline HRESULT FindDevice(LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b)
|
||
|
|
{ return ((IDirect3D*)t.lpVtbl)->fnFindDevice(this,a,b); };
|
||
|
|
};</programlisting>
|
||
|
|
<para>
|
||
|
|
Comments:
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
In C++ IDirect3D does double duty as both the virtual/jump
|
||
|
|
table and as the interface definition. The reason for this
|
||
|
|
is to avoid having to duplicate the mehod definitions: once
|
||
|
|
to have the function pointers in the jump table and once to
|
||
|
|
have the methods in the interface class. Here one macro can
|
||
|
|
generate both. This means though that the first pointer,
|
||
|
|
t.lpVtbl defined in IUnknown, must be interpreted as the
|
||
|
|
jump table pointer if we interpret the structure as the
|
||
|
|
interface class, and as the function pointer to the
|
||
|
|
QueryInterface method, t.fnQueryInterface, if we interpret
|
||
|
|
the structure as the jump table. Fortunately this gymnastic
|
||
|
|
is entirely taken care of in the header of IUnknown.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Of course in C++ we use inheritance so that we don't have to
|
||
|
|
duplicate the method definitions.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Since IDirect3D does double duty, each ICOM_METHOD macro
|
||
|
|
defines both a function pointer and a non-virtual inline
|
||
|
|
method which dereferences it and calls it. This way this
|
||
|
|
method behaves just like a virtual method but does not
|
||
|
|
create a true C++ virtual table which would break the
|
||
|
|
structure layout. If you look at the implementation of these
|
||
|
|
methods you'll notice that they would not work for void
|
||
|
|
functions. We have to return something and fortunately this
|
||
|
|
seems to be what all the COM methods do (otherwise we would
|
||
|
|
need another set of macros).
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Note how the ICOM_METHOD generates both function prototypes
|
||
|
|
mixing types and formal parameter names and the method
|
||
|
|
invocation using only the formal parameter name. This is the
|
||
|
|
reason why we need different macros to handle different
|
||
|
|
numbers of parameters.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Finally there is no IDirect3D_Xxx macro. These are not
|
||
|
|
needed in C++ unless the CINTERFACE macro is defined in
|
||
|
|
which case we would not be here.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
This C++ code works well for code that just uses COM
|
||
|
|
interfaces. But it will not work with C++ code implement a
|
||
|
|
COM interface. That's because such code assumes the
|
||
|
|
interface methods are declared as virtual C++ methods which
|
||
|
|
is not the case here.
|
||
|
|
</para>
|
||
|
|
</sect2>
|
||
|
|
|
||
|
|
<sect2>
|
||
|
|
<title>Implementing a COM interface.</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This continues the above example. This example assumes that
|
||
|
|
the implementation is in C.
|
||
|
|
</para>
|
||
|
|
<programlisting>typedef struct _IDirect3D {
|
||
|
|
void* lpVtbl;
|
||
|
|
// ...
|
||
|
|
} _IDirect3D;
|
||
|
|
|
||
|
|
static ICOM_VTABLE(IDirect3D) d3dvt;
|
||
|
|
|
||
|
|
// implement the IDirect3D methods here
|
||
|
|
|
||
|
|
int IDirect3D_fnQueryInterface(IDirect3D* me)
|
||
|
|
{
|
||
|
|
ICOM_THIS(IDirect3D,me);
|
||
|
|
// ...
|
||
|
|
}
|
||
|
|
|
||
|
|
// ...
|
||
|
|
|
||
|
|
static ICOM_VTABLE(IDirect3D) d3dvt = {
|
||
|
|
ICOM_MSVTABLE_COMPAT_DummyRTTIVALUE
|
||
|
|
IDirect3D_fnQueryInterface,
|
||
|
|
IDirect3D_fnAdd,
|
||
|
|
IDirect3D_fnAdd2,
|
||
|
|
IDirect3D_fnInitialize,
|
||
|
|
IDirect3D_fnSetWidth
|
||
|
|
};</programlisting>
|
||
|
|
<para>
|
||
|
|
Comments:
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
We first define what the interface really contains. This is
|
||
|
|
the _IDirect3D structure. The first field must of course be
|
||
|
|
the virtual table pointer. Everything else is free.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Then we predeclare our static virtual table variable, we
|
||
|
|
will need its address in some methods to initialize the
|
||
|
|
virtual table pointer of the returned interface objects.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Then we implement the interface methods. To match what has
|
||
|
|
been declared in the header file they must take a pointer to
|
||
|
|
a IDirect3D structure and we must cast it to an _IDirect3D
|
||
|
|
so that we can manipulate the fields. This is performed by
|
||
|
|
the ICOM_THIS macro.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
Finally we initialize the virtual table.
|
||
|
|
</para>
|
||
|
|
</sect2>
|
||
|
|
</sect1>
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
<!-- Keep this comment at the end of the file
|
||
|
|
Local variables:
|
||
|
|
mode: sgml
|
||
|
|
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
|
||
|
|
End:
|
||
|
|
-->
|