| <chapter id="ole"> |
| <title>COM in Wine</title> |
| |
| <sect1 id="com-writing"> |
| <title>Writing COM Components for Wine</title> |
| |
| <para> |
| This section describes how to create your own natively |
| compiled COM 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 work arounds 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 in-line 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 preferred 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 dereference 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 method 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> |
| |
| <sect1 id="dcom-1"> |
| <title>A brief introduction to DCOM in Wine</title> |
| |
| <para> |
| This section explains the basic principles behind DCOM remoting as used by InstallShield and others. |
| </para> |
| |
| <sect2> |
| <title>BASICS</title> |
| |
| <para> |
| The basic idea behind DCOM is to take a COM object and make it location |
| transparent. That means you can use it from other threads, processes and |
| machines without having to worry about the fact that you can't just |
| dereference the interface vtable pointer to call methods on it. |
| </para> |
| |
| <para> |
| You might be wondering about putting threads next to processes and |
| machines in that last paragraph. You can access thread safe objects from |
| multiple threads without DCOM normally, right? Why would you need RPC |
| magic to do that? |
| </para> |
| |
| <para> |
| The answer is of course that COM doesn't assume that objects actually |
| are thread-safe. Most real-world objects aren't, in fact, for various |
| reasons. What these reasons are isn't too important here, though; it's |
| just important to realize that the problem of thread-unsafe objects is |
| what COM tries hard to solve with its apartment model. There are also |
| ways to tell COM that your object is truly thread-safe (namely the |
| free-threaded marshaller). In general, no object is truly thread-safe if |
| it could potentially use another not so thread-safe object, though, so |
| the free-threaded marshaller is less used than you'd think. |
| </para> |
| |
| <para> |
| For now, suffice it to say that COM lets you "marshal" interfaces into |
| other "apartments". An apartment (you may see it referred to as a |
| context in modern versions of COM) can be thought of as a location, and |
| contains objects. |
| </para> |
| |
| <para> |
| Every thread in a program that uses COM exists in an apartment. If a |
| thread wishes to use an object from another apartment, marshalling and |
| the whole DCOM infrastructure gets involved to make that happen behind |
| the scenes. |
| </para> |
| |
| <para> |
| So. Each COM object resides in an apartment, and each apartment |
| resides in a process, and each process resides in a machine, and each |
| machine resides in a network. Allowing those objects to be used |
| from <emphasis>any</emphasis> of these different places is what DCOM |
| is all about. |
| </para> |
| |
| <para> |
| The process of marshalling refers to taking a function call in an |
| apartment and actually performing it in another apartment. Let's say you |
| have two machines, A and B, and on machine B there is an object sitting |
| in a DLL on the hard disk. You want to create an instance of that object |
| (activate it) and use it as if you had compiled it into your own |
| program. This is hard, because the remote object is expecting to be |
| called by code in its own address space - it may do things like accept |
| pointers to linked lists and even return other objects. |
| </para> |
| |
| <para> |
| Very basic marshalling is easy enough to understand. You take a method |
| on a remote interface (that is a COM interface that is |
| implemented on the remote computer), copy each of its |
| parameters into a buffer, and |
| send it to the remote computer. On the other end, the remote server |
| reads each parameter from the buffer, calls the method, writes the |
| result into another buffer and sends it back. |
| </para> |
| |
| <para> |
| The tricky part is exactly how to encode those parameters in the buffer, |
| and how to convert standard stdcall/cdecl method calls to network |
| packets and back again. This is the job of the RPCRT4.DLL file - or the |
| Remote Procedure Call Runtime. |
| </para> |
| |
| <para> |
| The backbone of DCOM is this RPC runtime, which is an implementation |
| of <ulink |
| url="http://www.opengroup.org/onlinepubs/009629399/toc.htm">DCE |
| RPC</ulink>. DCE RPC is not naturally object oriented, so this |
| protocol is extended with some new constructs and by assigning new |
| meanings to some of the packet fields, to produce ORPC or Object |
| RPC. You might see it called MS-RPC as well. |
| </para> |
| |
| <para> |
| RPC packets contain a buffer containing marshalled data in NDR format. |
| NDR is short for "Network Data Representation" and is similar |
| to the XDR |
| format used in SunRPC (the closest native equivalent on Linux to DCE |
| RPC). NDR/XDR are all based on the idea of graph serialization and were |
| worked out during the 80s, meaning they are very powerful and can do |
| things like marshal doubly linked lists and other rather tricky |
| structures. |
| </para> |
| |
| <para> |
| In Wine, our DCOM implementation is <emphasis>not</emphasis> |
| currently based on the |
| RPC runtime, as while few programs use DCOM even fewer use |
| RPC directly so it was developed some time after |
| OLE32/OLEAUT32 were. Eventually this will have to be fixed, |
| otherwise our DCOM will never be compatible with |
| Microsoft's. Bear this in mind as you read through the code |
| however. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>PROXIES AND STUBS</title> |
| |
| <para> |
| Manually marshalling and unmarshalling each method call using the NDR |
| APIs (NdrConformantArrayMarshall etc) is very tedious work, so the |
| Platform SDK ships with a tool called "midl" which is an IDL compiler. |
| IDL or the "Interface Definition Language" is a tool designed |
| specifically for describing interfaces in a reasonably language neutral |
| fashion, though in reality it bears a close resemblence to C++. |
| </para> |
| |
| <para> |
| By describing the functions you want to expose via RPC in IDL therefore, |
| it becomes possible to pass this file to MIDL which spits out a huge |
| amount of C source code. That code defines functions which have the same |
| prototype as the functions described in your IDL but which internally |
| take each argument, marshal it using Ndr, send the packet, and unmarshal |
| the return. |
| </para> |
| |
| <para> |
| Because this code proxies the code from the client to the server, the |
| functions are called proxies. Easy, right? |
| </para> |
| |
| <para> |
| Of course, in the RPC server process at the other end, you need some way |
| to unmarshal the RPCs, so you have functions also generated by MIDL |
| which are the inverse of the proxies; they accept an NDR buffer, extract |
| the parameters, call the real function and then marshal the result back. |
| They are called stubs, and stand in for the real calling code in the |
| client process. |
| </para> |
| |
| <para> |
| The sort of marshalling/unmarshalling code that MIDL spits out can be |
| seen in dlls/oleaut32/oaidl_p.c - it's not exactly what it would look |
| like as that file contains DCOM proxies/stubs which are different, but |
| you get the idea. Proxy functions take the arguments and feed them to |
| the NDR marshallers (or picklers), invoke an NdrProxySendReceive and |
| then convert the out parameters and return code. There's a ton of goop |
| in there for dealing with buffer allocation, exceptions and so on - it's |
| really ugly code. But, this is the basic concept behind DCE RPC. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>INTERFACE MARSHALLING</title> |
| |
| <para> |
| Standard NDR only knows about C style function calls - they |
| can accept and even return structures, but it has no concept |
| of COM interfaces. Confusingly DCE RPC <emphasis>does</emphasis> have a |
| concept of RPC interfaces which are just convenient ways to |
| bundle function calls together into namespaces, but let's |
| ignore that for now as it just muddies the water. The |
| primary extension made by Microsoft to NDR then was the |
| ability to take a COM interface pointer and marshal that |
| into the NDR stream. |
| </para> |
| |
| <para> |
| The basic theory of proxies and stubs and IDL is still here, but it's |
| been modified slightly. Whereas before you could define a bunch of |
| functions in IDL, now a new "object" keyword has appeared. This tells |
| MIDL that you're describing a COM interface, and as a result the |
| proxies/stubs it generates are also COM objects. |
| </para> |
| |
| <para> |
| That's a very important distinction. When you make a call to a remote |
| COM object you do it via a proxy object that COM has constructed on the |
| fly. Likewise, a stub object on the remote end unpacks the RPC packet |
| and makes the call. |
| </para> |
| |
| <para> |
| Because this is object-oriented RPC, there are a few complications: for |
| instance, a call that goes via the same proxies/stubs may end up at a |
| different object instance, so the RPC runtime keeps track of "this" and |
| "that" in the RPC packets. |
| </para> |
| |
| <para> |
| This leads naturally onto the question of how we got those proxy/stub |
| objects in the first place, and where they came from. You can use the |
| CoCreateInstanceEx API to activate COM objects on a remote machine, this |
| works like CoCreateInstance API. Behind the scenes, a lot of stuff is |
| involved to do this (like IRemoteActivation, IOXIDResolver and so on) |
| but let's gloss over that for now. |
| </para> |
| |
| <para> |
| When DCOM creates an object on a remote machine, the DCOM runtime on |
| that machine activates the object in the usual way (by looking it up in |
| the registry etc) and then marshals the requested interface back to the |
| client. Marshalling an interface takes a pointer, and produces a buffer |
| containing all the information DCOM needs to construct a proxy object in |
| the client, a stub object in the server and link the two together. |
| </para> |
| |
| <para> |
| The structure of a marshalled interface pointer is somewhat complex. |
| Let's ignore that too. The important thing is how COM proxies/stubs are |
| loaded. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>COM PROXY/STUB SYSTEM</title> |
| |
| <para> |
| COM proxies are objects that implement both the interfaces needing to be |
| proxied and also IRpcProxyBuffer. Likewise, COM stubs implement |
| IRpcStubBuffer and understand how to invoke the methods of the requested |
| interface. |
| </para> |
| |
| <para> |
| You may be wondering what the word "buffer" is doing in those interface |
| names. I'm not sure either, except that a running theme in DCOM is that |
| interfaces which have nothing to do with buffers have the word Buffer |
| appended to them, seemingly at random. Ignore it and <emphasis>don't let it |
| confuse you</emphasis> |
| :) This stuff is convoluted enough ... |
| </para> |
| |
| <para> |
| The IRpc[Proxy/Stub]Buffer interfaces are used to control the proxy/stub |
| objects and are one of the many semi-public interfaces used in DCOM. |
| </para> |
| |
| <para> |
| DCOM is theoretically an internet RFC <ulink |
| url="http://www.grimes.demon.co.uk/DCOM/DCOMSpec.htm">[2]</ulink> and is |
| specced out, but in reality the only implementation of it apart from |
| ours is Microsoft's, and as a result there are lots of interfaces |
| which <emphasis>can</emphasis> be used if you want to customize or |
| control DCOM but in practice are badly documented or not documented at |
| all, or exist mostly as interfaces between MIDL generated code and COM |
| itself. Don't pay too much attention to the MSDN definitions of these |
| interfaces and APIs. |
| </para> |
| |
| <para> |
| COM proxies and stubs are like any other normal COM object - they are |
| registered in the registry, they can be loaded with CoCreateInstance and |
| so on. They have to be in process (in DLLs) however. They aren't |
| activated directly by COM however, instead the process goes something |
| like this: |
| |
| <itemizedlist> |
| <listitem> <para> COM receives a marshalled interface packet, and retrieves the IID of |
| the marshalled interface from it </para> </listitem> |
| |
| |
| <listitem> <para> COM looks in |
| HKEY_CLASSES_ROOT/Interface/{whatever-iid}/ProxyStubClsId32 |
| to retrieve the CLSID of another COM object, which |
| implements IPSFactoryBuffer. </para> </listitem> |
| |
| <listitem> <para> IPSFactoryBuffer has only two methods, CreateProxy and CreateStub. COM |
| calls whichever is appropriate: CreateStub for the server, CreateProxy |
| for the client. MIDL will normally provide an implementation of this |
| object for you in the code it generates. </para></listitem> |
| </itemizedlist> |
| |
| </para> |
| |
| <para> |
| Once CreateProxy has been called, the resultant object is QueryInterfaced to |
| IRpcProxyBuffer, which only has 1 method, IRpcProxyBuffer::Connect. |
| This method only takes one parameter, the IRpcChannelBuffer object which |
| encapsulates the "RPC Channel" between the client and server. |
| </para> |
| |
| <para> |
| On the server side, a similar process is performed - the PSFactoryBuffer |
| is created, CreateStub is called, result is QId to IRpcStubBuffer, and |
| IRpcStubBuffer::Connect is used to link it to the RPC channel. |
| </para> |
| |
| </sect2> |
| |
| <sect2> |
| <title>RPC CHANNELS</title> |
| |
| <para> |
| Remember the RPC runtime? Well, that's not just responsible for |
| marshalling stuff, it also controls the connection and protocols between |
| the client and server. We can ignore the details of this for now, |
| suffice it to say that an RPC Channel is a COM object that implements |
| IRpcChannelBuffer, and it's basically an abstraction of different RPC |
| methods. For instance, in the case of inter-thread marshalling (not |
| covered here) the RPC connection code isn't used, only the NDR |
| marshallers are, so IRpcChannelBuffer in that case isn't actually |
| implemented by RPCRT4 but rather just by the COM/OLE DLLS. |
| </para> |
| |
| <para> |
| On this topic, Ove Kaaven says: It depends on the Windows version, I |
| think. Windows 95 and Windows NT 4 certainly had very different models |
| when I looked. I'm pretty sure the Windows 98 version of RPCRT4 was |
| able to dispatch messages directly to individual apartments. I'd be |
| surprised if some similar functionality was not added to Windows |
| 2000. After all, if an object on machine A wanted to use an object on |
| machine B in an apartment C, wouldn't it be most efficient if the RPC |
| system knew about apartments and could dispatch the message directly |
| to it? And if RPC does know how to efficiently dispatch to apartments, |
| why should COM duplicate this functionality? There were, however, no |
| unified way to tell RPC about them across Windows versions, so in that |
| old patch of mine, I let the COM/OLE dlls do the apartment dispatch, |
| but even then, the RPC runtime was always involved. After all, it |
| could be quite tricky to tell whether the call is merely interthread, |
| without involving the RPC runtime... |
| </para> |
| |
| <para> |
| RPC channels are constructed on the fly by DCOM as part of the |
| marshalling process. So, when you make a call on a COM proxy, it goes |
| like this: |
| </para> |
| |
| <para> |
| Your code -> COM proxy object -> RPC Channel -> COM stub object -> Their code |
| </para> |
| |
| </sect2> |
| |
| <sect2> |
| <title>HOW THIS ACTUALLY WORKS IN WINE</title> |
| |
| <para> |
| Right now, Wine does not use the NDR marshallers or RPC to implement its |
| DCOM. When you marshal an interface in Wine, in the server process a |
| _StubMgrThread thread is started. I haven't gone into the stub manager |
| here. The important thing is that eventually a _StubReaderThread is |
| started which accepts marshalled DCOM RPCs, and then passes them to |
| IRpcStubBuffer::Invoke on the correct stub object which in turn |
| demarshals the packet and performs the call. The threads started by our |
| implementation of DCOM are never terminated, they just hang around until |
| the process dies. |
| </para> |
| |
| <para> |
| Remember that I said our DCOM doesn't use RPC? Well, you might be |
| thinking "but we use IRpcStubBuffer like we're supposed to ... isn't |
| that provided by MIDL which generates code that uses the NDR APIs?". If |
| so pat yourself on the back, you're still with me. Go get a cup of |
| coffee. |
| </para> |
| |
| </sect2> |
| |
| <sect2> |
| <title>TYPELIB MARSHALLER</title> |
| |
| <para> |
| In fact, the reason for the PSFactoryBuffer layer of indirection is |
| because not all interfaces are marshalled using MIDL generated code. |
| Why not? Well, to understand <emphasis>that</emphasis> |
| you have to see that one of the |
| driving forces behind OLE and by extension DCOM was the development of |
| Visual Basic. Microsoft wanted VB developers to be first class citizens |
| in the COM world, but things like writing IDL and compiling them with a |
| C compiler into DLLs wasn't easy enough. |
| </para> |
| |
| <para> |
| So, type libraries were invented. Actually they were invented as part of |
| a parallel line of COM development known as "OLE Automation", but let's |
| not get into that here. Type libraries are basically binary IDL files, |
| except that despite there being two type library formats neither of them |
| can fully express everything expressable in IDL. Anyway, with a type |
| library (which can be embedded as a resource into a DLL) you have |
| another option beyond compiling MIDL output - you can set the |
| ProxyStubClsId32 registry entry for your interfaces to the CLSID of the |
| "type library marshaller" or "universal marshaller". Both terms are |
| used, but in the Wine source it's called the typelib marshaller. |
| </para> |
| |
| <para> |
| The type library marshaller constructs proxy and stub objects on the |
| fly. It does so by having generic marshalling glue which reads the |
| information from the type libraries, and takes the parameters directly |
| off the stack. The CreateProxy method actually builds a vtable out of |
| blocks of assembly stitched together which pass control to _xCall, which |
| then does the marshalling. You can see all this magic in |
| dlls/oleaut32/tmarshal.c |
| </para> |
| |
| <para> |
| In the case of InstallShield, it actually comes with typelibs for all |
| the interfaces it needs to marshal (fixme: is this right?), but they |
| actually use a mix of MIDL and typelib marshalling. In order to cover up |
| for the fact that we don't really use RPC they're all forced to go via |
| the typelib marshaller - that's what the 1 || hack is for and what the |
| "Registering non-automation type library!" warning is about (I think). |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>WRAPUP</title> |
| |
| <para> |
| OK, so there are some (very) basic notes on DCOM. There's a ton of stuff |
| I have not covered: |
| </para> |
| |
| <itemizedlist> |
| <listitem><para> Format strings/MOPs</para></listitem> |
| |
| <listitem><para> Apartments, threading models, inter-thread marshalling</para></listitem> |
| |
| <listitem><para> OXIDs/OIDs, etc, IOXIDResolver</para></listitem> |
| |
| <listitem><para> IRemoteActivation</para></listitem> |
| |
| <listitem><para> Complex/simple pings, distributed garbage collection</para></listitem> |
| |
| <listitem><para> Marshalling IDispatch</para></listitem> |
| |
| <listitem><para> Structure of marshalled interface pointers (STDOBJREFs etc)</para></listitem> |
| |
| <listitem><para> Runtime class object registration (CoRegisterClassObject), ROT</para></listitem> |
| |
| <listitem><para> IRemUnknown</para></listitem> |
| |
| <listitem><para> Exactly how InstallShield uses DCOM</para></listitem> |
| </itemizedlist> |
| |
| <para> |
| Then there's a bunch of stuff I still don't understand, like ICallFrame, |
| interface pointer swizzling, exactly where and how all this stuff is |
| actually implemented and so on. |
| </para> |
| |
| <para> |
| But for now that's enough. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>FURTHER READING</title> |
| |
| <para> |
| Most of these documents assume you have knowledge only contained in |
| other documents. You may have to reread them a few times for it all to |
| make sense. Don't feel you need to read these to understand DCOM, you |
| don't, you only need to look at them if you're planning to help |
| implement it. |
| </para> |
| |
| <itemizedlist> |
| <listitem><para> |
| <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/htm/cmi_n2p_459u.asp"> |
| http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/htm/cmi_n2p_459u.asp</ulink> |
| |
| </para></listitem> |
| |
| |
| <listitem><para> |
| <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/htm/cmi_q2z_5ygi.asp"> |
| http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/htm/cmi_q2z_5ygi.asp</ulink> |
| </para></listitem> |
| |
| |
| <listitem><para> |
| <ulink url="http://www.microsoft.com/msj/0398/dcom.aspx"> |
| http://www.microsoft.com/msj/0398/dcom.aspx</ulink> |
| </para></listitem> |
| |
| <listitem><para> |
| <ulink url="http://www.microsoft.com/ntserver/techresources/appserv/COM/DCOM/4_ConnectionMgmt.asp"> |
| http://www.microsoft.com/ntserver/techresources/appserv/COM/DCOM/4_ConnectionMgmt.asp</ulink> |
| </para></listitem> |
| |
| |
| <listitem><para><ulink url="http://www.idevresource.com/com/library/articles/comonlinux.asp"> |
| http://www.idevresource.com/com/library/articles/comonlinux.asp</ulink> |
| |
| (unfortunately part 2 of this article does not seem to exist anymore, if it was ever written)</para></listitem> |
| </itemizedlist> |
| </sect2> |
| </sect1> |
| </chapter> |
| |
| <!-- Keep this comment at the end of the file |
| Local variables: |
| mode: sgml |
| sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "") |
| End: |
| --> |
