[1/2] [docs] winedev: Use 'interfacename' tags for interfaces
Frédéric Delanoy
frederic.delanoy at gmail.com
Wed Sep 4 17:15:48 CDT 2013
---
en/winedev-documentation.sgml | 2 +-
en/winedev-ole.sgml | 109 ++++++++++++++++++++++--------------------
2 files changed, 58 insertions(+), 53 deletions(-)
diff --git a/en/winedev-documentation.sgml b/en/winedev-documentation.sgml
index c15cef3..09ee273 100644
--- a/en/winedev-documentation.sgml
+++ b/en/winedev-documentation.sgml
@@ -488,7 +488,7 @@
<para>
Let's assume you have implemented a COM interface that you want to document; we'll
- use the name <classname>IExample</classname> as an example here. Your comment would
+ use the name <interfacename>IExample</interfacename> as an example here. Your comment would
look like the following (assuming you are exporting this object from
<filename class="libraryfile">EXAMPLE.DLL</filename>):
<programlisting>
diff --git a/en/winedev-ole.sgml b/en/winedev-ole.sgml
index 4e0bfde..235a04b 100644
--- a/en/winedev-ole.sgml
+++ b/en/winedev-ole.sgml
@@ -26,8 +26,8 @@
<itemizedlist>
<listitem>
<para>
- all COM interfaces derive from <classname>IUnknown</classname>, this should not
- be a problem.
+ all COM interfaces derive from <interfacename>IUnknown</interfacename>, this should
+ not be a problem.
</para>
</listitem>
<listitem>
@@ -140,7 +140,8 @@ ICOM_DEFINE(IDirect3D,IUnknown)
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 <classname>IDirect3D2</classname>), I left them blank.
+ (I could only find doc about <interfacename>IDirect3D2</interfacename>), I left them
+ blank.
</para>
<para>
Finally the set of <symbol>IDirect3D_<replaceable>Xxx</replaceable></symbol> macros is
@@ -201,7 +202,7 @@ struct IDirect3DVtbl {
Comments:
</para>
<para>
- <classname>IDirect3D</classname> only contains a pointer to the
+ <interfacename>IDirect3D</interfacename> 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
@@ -214,7 +215,7 @@ struct IDirect3DVtbl {
<systemitem class="macro"><replaceable>Xxx_</replaceable>IMETHODS</systemitem> macro to
automatically repeat the prototypes of all the inherited
methods and then uses <symbol>IDirect3D_METHODS</symbol> to define the
- <classname>IDirect3D</classname> methods.
+ <interfacename>IDirect3D</interfacename> methods.
</para>
<para>
Each method is declared as a pointer to function field in
@@ -263,26 +264,26 @@ struct IDirect3DVtbl {
Comments:
</para>
<para>
- In C++ <classname>IDirect3D</classname> does double duty as both the virtual/jump
+ In C++ <interfacename>IDirect3D</interfacename> 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,
- <structfield>t.lpVtbl</structfield> defined in <classname>IUnknown</classname>, must be
- interpreted as the jump table pointer if we interpret the structure as the
+ <structfield>t.lpVtbl</structfield> defined in <interfacename>IUnknown</interfacename>,
+ must be interpreted as the jump table pointer if we interpret the structure as the
interface class, and as the function pointer to the
<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>.
+ is entirely taken care of in the header of <interfacename>IUnknown</interfacename>.
</para>
<para>
Of course in C++ we use inheritance so that we don't have to
duplicate the method definitions.
</para>
<para>
- Since <classname>IDirect3D</classname> does double duty, each
+ Since <interfacename>IDirect3D</interfacename> 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
@@ -585,8 +586,8 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
objects in the first place, and where they came from. You can use the
<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.
+ stuff is involved to do this (like <interfacename>IRemoteActivation</interfacename>,
+ <interfacename>IOXIDResolver</interfacename> and so on) but let's gloss over that for now.
</para>
<para>
@@ -610,9 +611,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
COM proxies are objects that implement both the interfaces needing to be
- proxied and also <classname>IRpcProxyBuffer</classname>. Likewise, COM stubs implement
- <classname>IRpcStubBuffer</classname> and understand how to invoke the methods of the
- requested interface.
+ proxied and also <interfacename>IRpcProxyBuffer</interfacename>. Likewise, COM stubs
+ implement <interfacename>IRpcStubBuffer</interfacename> and understand how to invoke the
+ methods of the requested interface.
</para>
<para>
@@ -624,7 +625,8 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
</para>
<para>
- The <classname>IRpc[Proxy/Stub]Buffer</classname> interfaces are used to control the
+ The <interfacename>IRpcProxyBuffer</interfacename> and
+ <interfacename>IRpcStubBuffer</interfacename> interfaces are used to control the
proxy/stub objects and are one of the many semi-public interfaces used in DCOM.
</para>
@@ -654,9 +656,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<listitem> <para> COM looks in
<literal>HKEY_CLASSES_ROOT/Interface/<replaceable>whatever-iid</replaceable>/ProxyStubClsId32</literal>
to retrieve the CLSID of another COM object, which
- implements <classname>IPSFactoryBuffer</classname>. </para> </listitem>
+ implements <interfacename>IPSFactoryBuffer</interfacename>. </para> </listitem>
- <listitem> <para> <classname>IPSFactoryBuffer</classname> has only two methods,
+ <listitem> <para> <interfacename>IPSFactoryBuffer</interfacename> 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>
@@ -668,18 +670,18 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<para>
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.
+ <function>QueryInterface</function>d to <interfacename>IRpcProxyBuffer</interfacename>,
+ which only has one method, <function>IRpcProxyBuffer::Connect</function>.
+ This method only takes one parameter, the <interfacename>IRpcChannelBuffer</interfacename>
+ 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
<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.
+ <interfacename>IRpcStubBuffer</interfacename>, and
+ <function>IRpcStubBuffer::Connect</function> is used to link it to the RPC channel.
</para>
</sect2>
@@ -692,12 +694,12 @@ 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
- <classname>IRpcChannelBuffer</classname>, and it's basically an abstraction of different
- RPC methods. For instance, in the case of inter-thread marshalling (not
+ <interfacename>IRpcChannelBuffer</interfacename>, 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 <classname>IRpcChannelBuffer</classname> in that case isn't actually
- implemented by <filename class="libraryfile">RPCRT4</filename> but rather just by the
- COM/OLE DLLS.
+ marshallers are, so <interfacename>IRpcChannelBuffer</interfacename> in that case isn't
+ actually implemented by <filename class="libraryfile">RPCRT4</filename> but rather just by
+ the COM/OLE DLLS.
</para>
<para>
@@ -749,9 +751,10 @@ 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 <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.
+ thinking <quote>but we use <interfacename>IRpcStubBuffer</interfacename> 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>
@@ -908,14 +911,14 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
OXIDs are generated and registered with the OXID resolver by performing local RPCs
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.
+ <interfacename>ILocalOxidResolver</interfacename> 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 (<classname>IRpcStubBuffer</classname>
+ therefore multiple interface stubs (<interfacename>IRpcStubBuffer</interfacename>
implementations). OIDs are apartment scoped. Each interface stub is identified by an
IPID, which identifies a marshaled interface pointer. IPIDs are apartment scoped.
</para>
@@ -925,8 +928,9 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
object exporter (the apartment holding the marshaled interface pointer) and being
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 <function>RpcBindingSetObject</function>. <classname>IRemUnknown</classname>,
- discussed below, uses a reserved IPID. Please note that this is true only in the current
+ call using <function>RpcBindingSetObject</function>.
+ <interfacename>IRemUnknown</interfacename>, 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>
@@ -947,7 +951,7 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
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>.
+ called <interfacename>IOXIDResolver</interfacename>.
Despite the identical naming convention this is not a COM interface.
</para>
@@ -966,7 +970,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 <classname>IRemUnknown</classname>
+ the IPID of that apartments <interfacename>IRemUnknown</interfacename>
implementation, and a security hint (let's ignore this for now).
</para>
@@ -975,27 +979,28 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
unmarshalling process constructs an RPC Channel Buffer
implementation with the connection handle and the IPID of the
needed interface, loads and constructs the
- <function>IRpcProxyBuffer</function> implementation for that
+ <interfacename>IRpcProxyBuffer</interfacename> implementation for that
IID and connects it to the channel. Finally the proxy is passed
back to the application.
</para>
</sect2>
<sect2>
- <title>Handling <classname>IUnknown</classname></title>
+ <title>Handling <interfacename>IUnknown</interfacename></title>
<para>
- 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
+ There are some subtleties here with respect to <interfacename>IUnknown</interfacename>.
+ <interfacename>IUnknown</interfacename> itself is never marshaled directly: instead a
+ version of it optimised for network usage is used.
+ <interfacename>IRemUnknown</interfacename> is similar in concept to
+ <interfacename>IUnknown</interfacename> 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>
- <classname>IRemUnknown</classname> is used for lifecycle management, and for marshaling
- new interfaces on an object back to the client. Its definition can
+ <interfacename>IRemUnknown</interfacename> is used for lifecycle management, and for
+ marshaling new interfaces on an object back to the client. Its definition can
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
@@ -1003,8 +1008,8 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
</para>
<para>
- There is one <classname>IRemUnknown</classname> implementation per apartment, not per
- stub manager as you might expect. This is OK because IPIDs are
+ There is one <interfacename>IRemUnknown</interfacename> 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).
</para>
@@ -1111,10 +1116,10 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
<itemizedlist>
<listitem><para> Format strings/MOPs</para></listitem>
- <listitem><para> <classname>IRemoteActivation</classname></para></listitem>
+ <listitem><para> <interfacename>IRemoteActivation</interfacename></para></listitem>
<listitem><para> Complex/simple pings, distributed garbage collection</para></listitem>
- <listitem><para> Marshalling <classname>IDispatch</classname></para></listitem>
- <listitem><para> <classname>ICallFrame</classname></para></listitem>
+ <listitem><para> Marshalling <interfacename>IDispatch</interfacename></para></listitem>
+ <listitem><para> <interfacename>ICallFrame</interfacename></para></listitem>
<listitem><para> Interface pointer swizzling</para></listitem>
<listitem><para> Runtime class object registration
(<function>CoRegisterClassObject</function>), <literal>ROT</literal></para></listitem>
--
1.8.4
More information about the wine-patches
mailing list