Added entry for DirectSoundFullDuplexCreate.

[wine] / documentation / ole.sgml

  <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:
-->