[docs] winedev: Assorted formatting & tagging fixes
Frédéric Delanoy
frederic.delanoy at gmail.com
Fri Aug 30 02:34:03 CDT 2013
Note that OLE/COM chapter needs an overhaul but that's outside the scope of this patch.
---
en/winedev-ole.sgml | 352 +++++++++++++++++++++++++++-------------------------
1 file changed, 185 insertions(+), 167 deletions(-)
diff --git a/en/winedev-ole.sgml b/en/winedev-ole.sgml
index ed0097b..ef59f29 100644
--- a/en/winedev-ole.sgml
+++ b/en/winedev-ole.sgml
@@ -18,7 +18,7 @@
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.
+ the C interface in C++ by defining <symbol>CINTERFACE</symbol>.
</para>
<para>
It is based on the following assumptions:
@@ -26,7 +26,7 @@
<itemizedlist>
<listitem>
<para>
- all COM interfaces derive from IUnknown, this should not
+ all COM interfaces derive from <classname>IUnknown</classname>, this should not
be a problem.
</para>
</listitem>
@@ -43,9 +43,9 @@
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
+ specific, the layout of <command>g++</command> virtual tables is not the same
+ as that of an <command>egcs</command> virtual table which is not the same as
+ that generated by <application>Visual C++</application>. 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
@@ -91,58 +91,60 @@ ICOM_DEFINE(IDirect3D,IUnknown)
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'.
+ The <systemitem class="macro">ICOM_INTERFACE</systemitem> macro is used in the <systemitem
+ class="macro">ICOM_METHOD</systemitem> macros to define the type of the
+ <literal>this</literal> 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 <systemitem class="macro">ICOM_METHOD1</systemitem> cannot use
+ <symbol>ICOM_INTERFACE##_VTABLE</symbol> because this would give
+ <symbol>ICOM_INTERFACE_VTABLE</symbol> and not <symbol>IDirect3D_VTABLE</symbol>.
</para>
<para>
- ICOM_METHODS defines the methods specific to this
+ <literal>ICOM_METHODS</literal> defines the methods specific to this
interface. It is then aggregated with the inherited methods
- to form ICOM_IMETHODS.
+ to form <literal>ICOM_IMETHODS</literal>.
</para>
<para>
- ICOM_IMETHODS defines the list of methods that are
+ <symbol>ICOM_IMETHODS</symbol> 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
+ The <symbol>ICOM_DEFINE</symbol> 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 <replaceable>Xxx</replaceable>_IMETHODS macro. In C++ we need
- only use the IDirect3D_METHODS since method inheritance is
- taken care of by the language.
+ methods are inherited in C by using the <systemitem
+ class="macro">IDirect3D_METHODS</systemitem> macro and the parent's <systemitem
+ class="macro"><replaceable>Xxx</replaceable>_IMETHODS</systemitem> macro.
+ In C++ we need only use the <symbol>IDirect3D_METHODS</symbol> since method
+ inheritance is taken care of by the language.
</para>
<para>
- In C++ the ICOM_METHOD macros generate a function prototype
+ In C++ the <systemitem class="macro">ICOM_METHOD</systemitem> 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
+ once <literal>t1 p1, t2 p2, ...</literal> and once <literal>p1, p2</literal> 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_<replaceable>Xxx</replaceable>' macro is
- expanded. And by that time ICOM_INTERFACE will be long gone
- anyway.
+ <systemitem class="macro">ICOM_METHOD</systemitem> macro per number of parameters and to have it
+ take only the type information (with <literal>const</literal> if necessary) as
+ parameters. The <literal>undef ICOM_INTERFACE</literal> is here to remind
+ you that using <symbol>ICOM_INTERFACE</symbol> in the following macros will
+ not work. This time it's because the <systemitem class="macro">ICOM_CALL</systemitem> macro
+ expansion is done only once the
+ <systemitem class="macro">IDirect3D_<replaceable>Xxx</replaceable></systemitem> macro is
+ expanded. And by that time <systemitem class="macro">ICOM_INTERFACE</systemitem> 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.
+ (I could only find doc about <classname>IDirect3D2</classname>), I left them blank.
</para>
<para>
- Finally the set of 'IDirect3D_<replaceable>Xxx</replaceable>' macros is a standard set
- of macros defined to ease access to the interface methods in
+ Finally the set of <symbol>IDirect3D_<replaceable>Xxx</replaceable></symbol> 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
@@ -199,30 +201,31 @@ struct IDirect3DVtbl {
Comments:
</para>
<para>
- IDirect3D only contains a pointer to the IDirect3D
+ <classname>IDirect3D</classname> only contains a pointer to the
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
+ The code generated by <symbol>ICOM_DEFINE</symbol> defines both the structure
representing the interface and the structure for the jump
- table. ICOM_DEFINE uses the parent's <replaceable>Xxx</replaceable>_IMETHODS macro to
+ table. <symbol>ICOM_DEFINE</symbol> uses the parent
+ <systemitem class="macro"><replaceable>Xxx_</replaceable>IMETHODS</systemitem> macro to
automatically repeat the prototypes of all the inherited
- methods and then uses IDirect3D_METHODS to define the
- IDirect3D methods.
+ methods and then uses <symbol>IDirect3D_METHODS</symbol> to define the
+ <classname>IDirect3D</classname> 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.
+ and initialize the <structfield>lpVtbl</structfield> field to point to this variable.
</para>
<para>
- The IDirect3D_<replaceable>Xxx</replaceable> 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
+ The <systemitem class="macro">IDirect3D_<replaceable>Xxx</replaceable></systemitem> macros then just
+ dereference the <structfield>lpVtbl</structfield> 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>
@@ -235,7 +238,7 @@ struct IDirect3DVtbl {
<sect2>
<title>Bindings in C++</title>
<para>
- And in C++ (with gcc's g++):
+ And in C++ (with <command>g++</command>):
</para>
<programlisting>typedef struct IDirect3D: public IUnknown {
private: HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
@@ -260,27 +263,28 @@ struct IDirect3DVtbl {
Comments:
</para>
<para>
- In C++ IDirect3D does double duty as both the virtual/jump
+ In C++ <classname>IDirect3D</classname> 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
+ <structfield>t.lpVtbl</structfield> defined in <classname>IUnknown</classname>, 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.
+ <function>QueryInterface</function> method,
+ <structfield>t.fnQueryInterface</structfield>, if we interpret the structure as the jump
+ table. Fortunately this gymnastic
+ is entirely taken care of in the header of <classname>IUnknown</classname>.
</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
+ Since <classname>IDirect3D</classname> does double duty, each
+ <systemitem class="macro">ICOM_METHOD</systemitem> 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
@@ -290,16 +294,17 @@ struct IDirect3DVtbl {
need another set of macros).
</para>
<para>
- Note how the ICOM_METHOD generates both function prototypes
+ Note how the <symbol>ICOM_METHOD</symbol> 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_<replaceable>Xxx</replaceable> macro. These are not
- needed in C++ unless the CINTERFACE macro is defined in
- which case we would not be here.
+ Finally there is no <systemitem
+ class="macro">IDirect3D_<replaceable>Xxx</replaceable></systemitem> macro.
+ These are not needed in C++ unless the <systemitem class="macro">CINTERFACE</systemitem>
+ macro is defined in which case we would not be here.
</para>
<para>
This C++ code works well for code that just uses COM
@@ -347,7 +352,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
</para>
<para>
We first define what the interface really contains. This is
- the _IDirect3D structure. The first field must of course be
+ the <structname>_IDirect3D</structname> structure. The first field must of course be
the virtual table pointer. Everything else is free.
</para>
<para>
@@ -358,9 +363,10 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
Then we implement the interface methods. To match what has
been declared in the header file they must take a pointer to
- an IDirect3D structure and we must cast it to an _IDirect3D
+ an <structname>IDirect3D</structname> structure and we must cast it to an
+ <structname>_IDirect3D</structname>
so that we can manipulate the fields. This is performed by
- the ICOM_THIS macro.
+ the <systemitem class="macro">ICOM_THIS</systemitem> macro.
</para>
<para>
Finally we initialize the virtual table.
@@ -372,7 +378,8 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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.
+ This section explains the basic principles behind DCOM remoting as used by
+ <application>InstallShield</application> and others.
</para>
<sect2>
@@ -406,7 +413,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
For now, suffice it to say that COM lets you <quote>marshal</quote> interfaces into
- other apartments. An apartment (you may see it referred to as a
+ other <firstterm>apartments</firstterm>. 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>
@@ -449,8 +456,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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 <filename>RPCRT4.DLL</filename> file:
+ and how to convert standard <literal>stdcall</literal>/<literal>cdecl</literal> method
+ calls to network packets and back again. This is the job of the
+ <filename>RPCRT4.DLL</filename> file:
the <firstterm>Remote Procedure Call Runtime</firstterm>.
</para>
@@ -492,9 +500,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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 <quote>Interface Definition Language</quote> is a tool designed
+ APIs (<function>NdrConformantArrayMarshall</function> etc) is very tedious work, so the
+ Platform SDK ships with a tool called <command>midl</command> which is an IDL compiler.
+ IDL or the <quote>Interface Definition Language</quote> is a language designed
specifically for describing interfaces in a reasonably language neutral
fashion, though in reality it bears a close resemblance to C++.
</para>
@@ -504,7 +512,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
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
+ take each argument, marshal it using NDR, send the packet, and unmarshal
the return.
</para>
@@ -524,10 +532,10 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
The sort of marshalling/unmarshalling code that MIDL spits out can be
- seen in <filename>dlls/oleaut32/oaidl_p.c</filename> - it's not exactly what it would
- look like as that file contains DCOM proxies/stubs which are different, but
+ seen in <filename>dlls/oleaut32/oleaut32_oaidl_p.c</filename> - 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
+ the NDR marshallers (or picklers), invoke an <function>NdrProxySendReceive</function> 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.
@@ -552,7 +560,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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
+ functions in IDL, now a new <literal>object</literal> 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>
@@ -574,10 +582,10 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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.
+ <function>CoCreateInstanceEx</function> API to activate COM objects on a remote machine,
+ this works like <function>CoCreateInstance</function> API. Behind the scenes, a lot of
+ stuff is involved to do this (like <classname>IRemoteActivation</classname>,
+ <classname>IOXIDResolver</classname> and so on) but let's gloss over that for now.
</para>
<para>
@@ -601,9 +609,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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.
+ proxied and also <classname>IRpcProxyBuffer</classname>. Likewise, COM stubs implement
+ <classname>IRpcStubBuffer</classname> and understand how to invoke the methods of the
+ requested interface.
</para>
<para>
@@ -611,12 +619,12 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
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 <quote>Buffer</quote>
appended to them, seemingly at random. Ignore it and <emphasis>don't let it
- confuse you</emphasis> :) This stuff is convoluted enough ...
+ 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.
+ The <classname>IRpc[Proxy/Stub]Buffer</classname> interfaces are used to control the
+ proxy/stub objects and are one of the many semi-public interfaces used in DCOM.
</para>
<para>
@@ -632,23 +640,25 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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:
-
+ registered in the registry, they can be loaded with
+ <function>CoCreateInstance</function> 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/<replaceable>whatever-iid</replaceable>/ProxyStubClsId32
+ <literal>HKEY_CLASSES_ROOT/Interface/<replaceable>whatever-iid</replaceable>/ProxyStubClsId32</literal>
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
+ implements <classname>IPSFactoryBuffer</classname>. </para> </listitem>
+
+ <listitem> <para> <classname>IPSFactoryBuffer</classname> has only two methods,
+ <function>CreateProxy</function> and <function>CreateStub</function>. COM
+ calls whichever is appropriate: <function>CreateStub</function> for the server,
+ <function>CreateProxy</function>
for the client. MIDL will normally provide an implementation of this
object for you in the code it generates. </para></listitem>
</itemizedlist>
@@ -656,16 +666,19 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
</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.
+ Once <function>CreateProxy</function> has been called, the resultant object is
+ <function>QueryInterface</function>d to <classname>IRpcProxyBuffer</classname>, which only
+ has one method, <function>IRpcProxyBuffer::Connect</function>.
+ This method only takes one parameter, the <classname>IRpcChannelBuffer</classname> object
+ which encapsulates the <quote>RPC Channel</quote> 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.
+ On the server side, a similar process is performed: the
+ <classname>PSFactoryBuffer</classname> is created, <function>CreateStub</function> is
+ called, result is <function>QueryInterface</function>d to
+ <classname>IRpcStubBuffer</classname>, and <function>IRpcStubBuffer::Connect</function> is
+ used to link it to the RPC channel.
</para>
</sect2>
@@ -678,10 +691,10 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
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
+ <classname>IRpcChannelBuffer</classname>, 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
+ marshallers are, so <classname>IRpcChannelBuffer</classname> in that case isn't actually
implemented by RPCRT4 but rather just by the COM/OLE DLLS.
</para>
@@ -723,10 +736,10 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<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
+ <type>_StubMgrThread</type> thread is started. I haven't gone into the stub manager
+ here. The important thing is that eventually a <type>_StubReaderThread</type> is
started which accepts marshalled DCOM RPCs, and then passes them to
- IRpcStubBuffer::Invoke on the correct stub object which in turn
+ <function>IRpcStubBuffer::Invoke</function> on the correct stub object which in turn
demarshalls 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.
@@ -734,10 +747,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
Remember that I said our DCOM doesn't use RPC? Well, you might be
- thinking <quote>but we use <type>IRpcStubBuffer</type> like we're supposed to ... isn't
- that provided by MIDL which generates code that uses the NDR APIs?</quote>. If
- so pat yourself on the back, you're still with me. Go get a cup of
- coffee.
+ thinking <quote>but we use <classname>IRpcStubBuffer</classname> like we're supposed
+ to... isn't that provided by MIDL which generates code that uses the NDR APIs?</quote>.
+ If so pat yourself on the back, you're still with me. Go get a cup of coffee.
</para>
</sect2>
@@ -746,7 +758,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<title>Typelib Marshaller</title>
<para>
- In fact, the reason for the PSFactoryBuffer layer of indirection is
+ In fact, the reason for the <classname>PSFactoryBuffer</classname> 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
@@ -774,9 +786,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
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
- <filename>dlls/oleaut32/tmarshal.c</filename>.
+ blocks of assembly stitched together which pass control to <function>_xCall</function>,
+ which then does the marshalling. You can see all this magic in
+ <filename>dlls/oleaut32/tmarshal.c</filename>
</para>
<para>
@@ -853,14 +865,17 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
When an interface is marshaled using <function>CoMarshalInterface()</function>,
- the result is a serialized OBJREF structure. An OBJREF actually contains a union,
- but we'll be assuming the variant that embeds a STDOBJREF here which is what's
- used by the system provided standard marshaling. A STDOBJREF (standard object
- reference) consists of the magic signature 'MEOW', then some flags, then the IID
- of the marshaled interface. Quite what MEOW stands for is a mystery, but it's
- definitely not <quote>Microsoft Extended Object Wire</quote>. Next comes the
- STDOBJREF flags, identified by their SORF_ prefix. Most of these are reserved,
- and their purpose (if any) is unknown, but a few are defined.
+ the result is a serialized <structname>OBJREF</structname> structure. An
+ <structname>OBJREF</structname> actually contains a union,
+ but we'll be assuming the variant that embeds a <structname>STDOBJREF</structname> here
+ which is what's used by the system provided standard marshaling. A
+ <structname>STDOBJREF</structname> (standard object reference) consists of the magic
+ signature <literal>MEOW</literal>, then some flags, then the IID of the marshaled
+ interface. Quite what <literal>MEOW</literal> stands for is a mystery, but it's definitely
+ not <quote>Microsoft Extended Object Wire</quote>. Next comes the
+ <structname>STDOBJREF</structname> flags, identified by their <literal>SORF_</literal>
+ prefix. Most of these are reserved, and their purpose (if any) is unknown, but a few are
+ defined.
</para>
<para>
@@ -869,7 +884,8 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
for table-strong and table-weak marshals (the difference between these is explained below).
The reasoning is this: in the general case, we want to know exactly when an object
is unmarshaled and released, so we can accurately control the lifetime of the stub
- object. This is what happens when cPublicRefs is zero. However, in many cases, we
+ object. This is what happens when <structfield>cPublicRefs</structfield> is zero. However,
+ in many cases, we
only want to unmarshal an object once. Therefore, if we strengthen the rules to say
when marshaling that we will only unmarshal once, then we no longer have to know when
it is unmarshaled. Therefore, we can give out an arbitrary number of references when
@@ -877,7 +893,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
</para>
<para>
- The most interesting part of a STDOBJREF is the OXID, OID, IPID triple. This triple
+ The most interesting part of a <structname>STDOBJREF</structname> is the
+ <structfield>OXID</structfield>, <structfield>OID</structfield>,
+ <structfield>IPID</structfield> triple. This triple
identifies any given marshaled interface pointer in the network. OXIDs are apartment
identifiers, and are supposed to be unique network-wide. How this is guaranteed is
currently unknown: the original algorithm Windows used was something like the current
@@ -886,50 +904,55 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
OXIDs are generated and registered with the OXID resolver by performing local RPCs
- to the RPC subsystem (rpcss.exe). In a fully security-patched Windows system they
- appear to be randomly generated. This registration is done using the
- <function>ILocalOxidResolver</function> interface, however the exact structure of
+ to the RPC subsystem (<command>rpcss.exe</command>). In a fully security-patched Windows
+ system they appear to be randomly generated. This registration is done using the
+ <classname>ILocalOxidResolver</classname> interface, however the exact structure of
this interface is currently unknown.
</para>
<para>
OIDs are object identifiers, and identify a stub manager. The stub manager manages
interface stubs. For each exported COM object there are multiple interfaces and
- therefore multiple interface stubs (<function>IRpcStubBuffer</function> implementations).
- OIDs are apartment scoped. Each ifstub is identified by an IPID, which identifies
- a marshaled interface pointer. IPIDs are apartment scoped.
+ therefore multiple interface stubs (<classname>IRpcStubBuffer</classname>
+ implementations). OIDs are apartment scoped. Each interface stub is identified by an
+ IPID, which identifies a marshaled interface pointer. IPIDs are apartment scoped.
</para>
<para>
Unmarshaling one of these streams therefore means setting up a connection to the
object exporter (the apartment holding the marshaled interface pointer) and being
- able to send RPCs to the right ifstub. Each apartment has its own RPC endpoint and
+ able to send RPCs to the right interface stub. Each apartment has its own RPC endpoint and
calls can be routed to the correct interface pointer by embedding the IPID into the
- call using RpcBindingSetObject. IRemUnknown, discussed below, uses a reserved IPID.
- Please note that this is true only in the current implementation. The native version
- generates an IPID as per any other object and simply notifies the SCM of this IPID.
+ call using <function>RpcBindingSetObject</function>. <classname>IRemUnknown</classname>,
+ discussed below, uses a reserved IPID. Please note that this is true only in the current
+ implementation. The native version generates an IPID as per any other object and simply
+ notifies the SCM of this IPID.
</para>
<para>
- Both standard and handler marshaled OBJREFs contains an OXID resolver endpoint which
- is an RPC string binding in a DUALSTRINGARRAY. This is necessary because an OXID
- alone is not enough to contact the host, as it doesn't contain any network address
+ Both standard and handler marshaled <structname>OBJREF</structname>s contains an OXID
+ resolver endpoint which is an RPC string binding in a
+ <structname>DUALSTRINGARRAY</structname>. This is necessary because an OXID alone is not
+ enough to contact the host, as it doesn't contain any network address
data. Instead, the combination of the remote OXID resolver RPC endpoint and the OXID
- itself are passed to the local OXID resolver. It then returns the apartment string binding.
+ itself are passed to the local OXID resolver. It then returns the apartment string
+ binding.
</para>
<para>
- This step is an optimisation: technically the OBJREF itself could contain the string
- binding of the apartment endpoint and the OXID resolver could be bypassed, but by using
- this DCOM can optimise out a server round-trip by having the local OXID resolver cache
- the query results. The OXID resolver is a service in the RPC subsystem (rpcss.exe) which
- implements a raw (non object-oriented) RPC interface called <function>IOXIDResolver</function>.
+ This step is an optimisation: technically the <structname>OBJREF</structname> itself could
+ contain the string binding of the apartment endpoint and the OXID resolver could be
+ bypassed, but by using this DCOM can optimise out a server round-trip by having the local
+ OXID resolver cache the query results. The OXID resolver is a service in the RPC subsystem
+ (<command>rpcss.exe</command>) which implements a raw (non object-oriented) RPC interface
+ called <classname>IOXIDResolver</classname>.
Despite the identical naming convention this is not a COM interface.
</para>
<para>
- Unmarshaling an interface pointer stream therefore consists of
- reading the OXID, OID and IPID from the STDOBJREF, then reading
+ Unmarshaling an interface pointer stream therefore consists of reading the
+ <structfield>OXID</structfield> , <structfield>OID</structfield> and
+ <structfield>IPID</structfield> from the <structname>STDOBJREF</structname>, then reading
one or more RPC string bindings for the remote OXID resolver.
Then <function>RpcBindingFromStringBinding</function> is used
to convert this remote string binding into an RPC binding handle
@@ -941,7 +964,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
binding handle passed in earlier. The result of the query is
stored for future reference in the cache, and finally the
unmarshaling application gets back the apartment string binding,
- the IPID of that apartments <function>IRemUnknown</function>
+ the IPID of that apartments <classname>IRemUnknown</classname>
implementation, and a security hint (let's ignore this for now).
</para>
@@ -957,27 +980,28 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
</sect2>
<sect2>
- <title>Handling IUnknown</title>
+ <title>Handling <classname>IUnknown</classname></title>
<para>
- There are some subtleties here with respect to IUnknown. IUnknown
- itself is never marshaled directly: instead a version of it
- optimised for network usage is used. IRemUnknown is similar in
- concept to IUnknown except that it allows you to add and release
+ There are some subtleties here with respect to <classname>IUnknown</classname>.
+ <classname>IUnknown</classname> itself is never marshaled directly: instead a version of
+ it optimised for network usage is used. <classname>IRemUnknown</classname> is similar in
+ concept to <classname>IUnknown</classname> except that it allows you to add and release
arbitrary numbers of references at once, and it also allows you to
query for multiple interfaces at once.
</para>
<para>
- IRemUnknown is used for lifecycle management, and for marshaling
+ <classname>IRemUnknown</classname> is used for lifecycle management, and for marshaling
new interfaces on an object back to the client. Its definition can
- be seen in dcom.idl - basically the IRemUnknown::RemQueryInterface
- method takes an IPID and a list of IIDs, then returns STDOBJREFs
- of each new marshaled interface pointer.
+ be seen in <filename>dcom.idl</filename> - basically the
+ <function>IRemUnknown::RemQueryInterface</function> method takes an IPID and a list of
+ IIDs, then returns <structname>STDOBJREF</structname>s of each new marshaled interface
+ pointer.
</para>
<para>
- There is one IRemUnknown implementation per apartment, not per
+ There is one <classname>IRemUnknown</classname> implementation per apartment, not per
stub manager as you might expect. This is OK because IPIDs are
apartment not object scoped (in fact, according to the DCOM draft
spec, they are machine-scoped, but this implies apartment-scoped).
@@ -1005,7 +1029,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
however the stream does not hold a ref. If you unmarshal the
stream twice, once those two proxies have been released remote
object will also be released. Attempting to unmarshal the stream
- at this point will yield <function>CO_E_DISCONNECTED</function>.
+ at this point will yield <errorname>CO_E_DISCONNECTED</errorname>.
</para>
</sect2>
@@ -1082,22 +1106,16 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
There are still a lot of topics that have not been covered:
</para>
-
+
<itemizedlist>
<listitem><para> Format strings/MOPs</para></listitem>
-
- <listitem><para> IRemoteActivation</para></listitem>
-
+ <listitem><para> <classname>IRemoteActivation</classname></para></listitem>
<listitem><para> Complex/simple pings, distributed garbage collection</para></listitem>
-
- <listitem><para> Marshalling IDispatch</para></listitem>
-
- <listitem><para> ICallFrame</para></listitem>
-
+ <listitem><para> Marshalling <classname>IDispatch</classname></para></listitem>
+ <listitem><para> <classname>ICallFrame</classname></para></listitem>
<listitem><para> Interface pointer swizzling</para></listitem>
-
- <listitem><para> Runtime class object registration (CoRegisterClassObject), ROT</para></listitem>
-
+ <listitem><para> Runtime class object registration
+ (<function>CoRegisterClassObject</function>), <literal>ROT</literal></para></listitem>
<listitem><para> Exactly how InstallShield uses DCOM</para></listitem>
</itemizedlist>
--
1.8.4
More information about the wine-patches
mailing list