incubator-ooo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ksch...@apache.org
Subject svn commit: r1206895 [8/12] - in /incubator/ooo/ooo-site/trunk/content/udk/common: ./ man/ man/concept/ man/draft/ man/draft/scripting/ man/draft/scripting/DesignDoc/ man/images/ man/spec/ man/tasks/ man/tutorial/
Date Sun, 27 Nov 2011 22:50:08 GMT
Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/ole_bridge.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/ole_bridge.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/ole_bridge.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/ole_bridge.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,1262 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1" />
+	<TITLE>The OLE Bridge</TITLE>
+	<META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Win32)" />
+	<META NAME="AUTHOR" CONTENT="Joachim Lingner" />
+	<META NAME="CREATED" CONTENT="20001019;16275729" />
+	<META NAME="CHANGEDBY" CONTENT="Joachim Lingner" />
+	<META NAME="CHANGED" CONTENT="20001026;12595911" />
+	<STYLE type=text/css>
+	<!--
+		P { margin-bottom: 0.02in }
+		H1 { margin-bottom: 0.04in; font-family: "Arial", sans-serif; font-size: 20pt; color:#ffffff; text-align: center }
+		h2 { margin-bottom: 0.02in; font-family: "Arial", sans-serif; font-size: 14pt; color:#ffffff; background-color: #666699; padding-top: 0.2cm; padding-bottom: 0.2cm }
+		TD P { margin-bottom: 0.08in }
+		TH P { margin-bottom: 0.08in; font-style: italic }
+		P.source { margin-bottom: 0in; font-family: "Courier New", monospace; font-size: 10pt }
+		CODE { font-size: 11pt }
+		pre { background-color: #fffff0;}
+		li { margin-bottom: 0.2cm; }
+	-->
+	</STYLE>
+</HEAD>
+<BODY>
+<table border=0 cellPadding=12 bgColor=#666699 width=100% summary=header>
+<TR>
+  <TD>
+      <h1>The Ole Bridge</h1>
+	  </td><td width=200>
+	  <A
+            href="http://www.openoffice.org/"><IMG align=right alt=OpenOffice
+            border=0 name=Grafik1
+            src="../../../images/open_office_org_logo.gif" /></A>
+  </td>
+</tr>
+</table>
+
+<h2> Contents </h2>
+<ol>
+<li><a href="#a1">Introduction </a>
+<li><a href="#a2">Requirements </a>
+<li><a href="#a3">Parts of the bridge</a>
+<li><a href="#a4">Mapping of types</a>
+<li><a href="#a8">Using the bridge </a>
+<li><a href="#a5">Creation of types </a>
+<li><a href="#a6">JScript issues </a>
+<li><a href="#a7">Value Objects </a>
+<li><a href="#a9">Limitation of the dispatch objects</a>
+<li><a href="#a10">Implementing COM objects with UNO interfaces</a>
+</ol>
+
+<h2><a name="a1"> 1 Introduction </a></h2>
+
+<P>The  OLE bridge is a means to allow UNO
+objects to be accessed in a COM environment, that is to say a COM
+client can calls an UNO server without having do deal with UNO
+specific details. Conversely an UNO object can use COM objects and
+does not have to know anything about COM.
+
+<P>The bridge can be incorporated by
+different languages as long as the languages support OLE. So far the
+bridge has proved to work reliable with C++ and JScript. VBScript and
+Visual Basic still needs some testing and as for all other eligible
+languages they require testing from the ground up.
+<P> As the name "OLE" bridge implies the bridge deals with OLE objects
+  and not with COM objects generally. That means that only "dispatch objects"
+  can be mapped to UNO and UNO objects are only mapped to dispatch objects.
+</p>
+
+<h2><a name="a2"> 2 Requirements </a></h2>
+
+<p>
+First of all the system must be able to
+run both object models. As for COM, it runs on all Windows 95/98,
+Windows 3.51, Windows 2000 and Windows ME operating systems. There
+are also ports to Macintosh and Unix and since November 1999 there is
+a reference implementation for UNIX developed by the Open Group. UNO
+is available whenever the UDK is installed on a machine or indirectly
+when an Office is installed. As for the latter, the setup needs to be
+run to ensure that the initial UNO object is properly registered  at
+the system's registry. Simply copying the executables and
+libraries won't do.</p>
+
+<p>The bridge depends on some additional services. These are</p>
+<P STYLE="margin-bottom: 0in">com.sun.star.script.Invocation,<br/>
+com.sun.star.script.InvocationAdapterFactory,<br/>
+com.sun.star.script.Converter<br/>
+com.sun.star.reflection.CoreReflection,<br/>
+com.sun.star.beans.Introspection.</P>
+
+<h2><a name="a3"> 3 Parts of the Bridge </a></h2>
+
+<p>
+In contrast to other language bindings
+the OLE bridge is based on services. The following paragraphs give an
+overview of  the functionalities which are provided by them.
+</P>
+
+<h3>3.1 Service com.sun.star.bridge.OleBridgeSupplier2</h3>
+<P>Implementation name: com.sun.star.comp.ole.OleConverter2</P>
+
+<P>The service is able to bridge elements
+of one environment to elements of another environment. This feature
+is provided by exposing the interface
+<a href="http://api.openoffice.org/common/ref/com/sun/star/bridge/XBridgeSupplier2.html">
+com.sun.star.bridge.XBridgeSupplier2</a> which looks like
+</p>
+<pre>
+module com {  module sun {  module star {  module bridge {
+
+[ uik(5F97D2F0-50F8-11d4-83240050-04526AB4),
+	ident(&quot;XBridgeSupplier2&quot;, 1.0 ) ]
+interface XBridgeSupplier2: com::sun::star::uno::XInterface
+{
+    any createBridge( [in] any aModelDepObject,
+	              [in] sequence&lt; byte &gt; aProcessId,
+		      [in] short nSourceModelType,
+		      [in] short nDestModelType )
+	raises(	com::sun::star::lang::IllegalArgumentException );
+
+}; }; }; };
+</pre>
+
+
+<P STYLE="margin-bottom: 0in">As the parameter nSourceModelType and
+nDestModelType suggest this interface allows the bridging of element
+of very different models. The constant group <a href="http://api.openoffice.org/common/ref/com/sun/star/bridge/ModelDependent.html">
+ModelDependent</a> specifies
+the values which can be used with that interface.</P>
+
+<pre>
+module com {  module sun {  module star {  module bridge {
+constants ModelDependent
+{
+    const short UNO = 1;
+    const short OLE = 2;
+    const short JAVA = 3;
+    const short CORBA = 4;
+};
+}; }; }; };
+</pre>
+
+<P STYLE="margin-bottom: 0in">When using OleBridgeSupplier2 then only
+the constants UNO and OLE will have effect. The parameter
+aModelDepObject contains the element that is to be bridged and the
+return value contains the bridged element.
+</P>
+
+<h3>3.2 Service: com.sun.star.bridge.OleBridgeSupplierVar1</h3>
+
+<p>Implementation name:  com.sun.star.comp.ole.OleConverterVar1
+
+<P>The name OleBridgeSupplierVar1 is
+admittedly badly chosen and rather nondescript. Anyway, the "Var1"
+indicates that the service is a variation of the OleBridgeSupplier
+service. And in fact the functionality is the same but the way it is
+achieved is partly different. OleConverterVar1 was developed to
+optimize performance in a remote client server environment. A
+scenario could look like this:</p>
+
+<p>A remote UNO object object is to
+be converted into an OLE object. Because the bridge can only handle
+UNO objects which expose XInvocation it utilizes the
+com.sun.star.script.Invocation service that creates an invocation
+object out of every UNO object or struct. Invocation has to
+introspect the respective object which is very expensive in terms of
+function calls. Now consider Invocation to reside on the client and
+the actual object on a remote server. Obviously there would be a
+great many network round trips causing a negative performance impact.
+
+<p>OleBridgeSupplier2 is just doing that and hence it is
+inappropriate for this scenario. OleBridgeSupplierVar1 on the other
+hand allows the remote creation of Invocation. Since Invocation and
+the object now reside in the same process the process of creating
+invocation objects is a lot more efficient.</P>
+
+<P>Another issue concerns the way of how
+the bridge realizes the IDispatch interface for UNO wrapper objects.
+An UNO wrapper is an object that contains an UNO object and it
+implements IDispatch so that the wrapper can be used in an OLE
+environment. Calls on the wrapper's IDispatch are mapped to calls on
+the XInvocation of the wrapped object.</p>
+
+<p>OLE objects are used
+through their IDispatch interface. A function call or accessing a
+property is twofold. First IDispatch::GetIDsOfNames is called which
+basicly takes the function or property name and returns an id
+(DISPID). With the id at hand the IDispatch::Invoke can be called. The
+Invoke implementation knows by way of the DISPID exactly what
+function or property it has been called for.
+</P>
+<P>The OleBridgeSupplier2 UNO wrapper
+checks in GetIDsOfNames whether the object exists or not before it
+issues a DISPID. The caller knows immediately if the function or
+property exists. This check is not carried out by
+OleBridgeSupplierVar1 because it would cause at least one remote call
+(remember the object is remote). DISPIDs are blindly passed out
+whenever GetIDsOfNames is being called for a new name. If the DISPID
+produces an error during the Invoke call then the name is cached, so
+that the next time GetIDsOfNames is being called the caller receives
+an appropriate error code.</P>
+
+<P>The OleBridgeSupplierVar1 UNO wrapper has to do
+  some more work in IDispatch::Invoke because it has not obtained any type information
+  yet about the meaning of the current call. The wFlags parameter of IDispatch::Invoke
+  can e.g. consist of a combination of DISPATCH_METHOD and DISPATCH_PROPERTYPUT.
+  In this case the wrapper tries first to call a method on the wrapped UNO object
+  and when this fails it tries to access a property. Moreover after a call to
+  XInvocation failed the wrapper checks whether the name is correct by calling
+  XExactName::getExactName that is provided by the invocation object. During the
+  Invoke call information are gathered which are cached so that whenever the same
+  call is made again the cached information are used to fasten up the process.</P>
+
+<h3>3.3 com.sun.star.bridge.OleApplicationRegistration</h3>
+
+<P>Implementation name: com.sun.star.comp.ole.OleServer</P>
+
+<P>This service registers a COM class factory when the service is
+being instantiated and deregisteres it when the service is being
+destroyed. The class factory constructs an UNO multi service factory
+within the OLE environment. Services created by this factory are
+always created in that environment. That means that someone who is
+using the COM class factory as starting point for an application
+which incorporates UNO rarely has to deal with the OLE bridge
+themselves.</p>
+
+<p>The multi service factory which is mapped into the
+COM environment is the same factory which is passed into the
+component_getFactory function of the housing DLL.
+</P>
+
+<h3>3.4 com.sun.star.bridge.OleObjectFactory</h3>
+
+<P>Implementation name: com.sun.star.comp.ole.OleClient</P>
+
+<P>The OleObjectFactory represents itself as multi service factory by
+exposing the XMultiServiceFactory interface. It is used to create COM
+objects. The COM components are specified by their programmatic
+identifier (ProgId). The COM objects are created in the UNO
+environment, meaning they are wrapped by objects which implement
+XInvocation and map calls to IDispatch.</P>
+
+<P>To map an OLE object into the UNO environment you could create
+the object through any COM mechanism (e.g. CoCreateInstance) and
+then convert it by means of the service OleBridgeSupplier2. Actually
+the OleObjectFactory does not do otherwise.</P>
+
+<h2><a name="a4"> 4 Mapping of Types </a></h2>
+
+<P>The bridge maps data from UNO to OLE automation types and vice
+versa. Because the bridge can be used from different languages there
+are also some language specific issues to be considered; e.g. JScript
+has no out parameters. The problem is that the bridge cannot tell
+what language makes use of it, since on the binary level the
+communication between interfaces complies with the COM
+specification, regardless of the language. For more information about
+JScript and the issues involved see <a href=#a5>chapter 6</a>.</P>
+
+<P>The table 1 summarizes the possible conversions from  OLE
+Automation types to UNO types. (The names in italic letters are not
+idl types)</P>
+
+<TABLE WIDTH=72%  CELLPADDING=4 CELLSPACING=1 summary="OLE to UNO conversions">
+  <COL WIDTH=128* /> <COL WIDTH=128* /> <THEAD bgcolor=#eeeeee>
+  <TR>
+
+    <TH> OLE Automation (idl types) </TH>
+    <TH> UNO (idl types) </TH>
+	</TR>
+	</THEAD>
+	<TBODY bgcolor=#eeeeff>
+	<TR>
+    <TD> boolean </TD>
+    <TD> boolean </TD>
+	</TR>
+	<TR>
+    <TD> unsigned char </TD>
+    <TD> byte </TD>
+	</TR>
+	<TR>
+    <TD> [1] double </TD>
+    <TD> double, float </TD>
+	</TR>
+	<TR>
+    <TD> float </TD>
+    <TD> float </TD>
+	</TR>
+	<TR>
+    <TD> short </TD>
+    <TD> short </TD>
+	</TR>
+	<TR>
+    <TD> [1] long </TD>
+    <TD> long, short, byte </TD>
+	</TR>
+	<TR>
+    <TD> BSTR </TD>
+    <TD> string </TD>
+	</TR>
+	<TR>
+    <TD> SCODE </TD>
+    <TD> unsigned long </TD>
+	</TR>
+	<TR>
+    <TD> IUnknown* </TD>
+    <TD> com.sun.star.script.XInvocation </TD>
+	</TR>
+	<TR>
+    <TD> [2] IDispatch* </TD>
+    <TD> com.sun.star.script.XInvocation<br/>
+		<I>interface type, original type.</I><br/>
+		sequence&lt;<I>type</I>&gt;,<br/>
+		out parameter,<br/>
+        in/out parameter
+			</TD>
+	</TR>
+	<TR>
+    <TD> [3] SAFEARRAY(<I>type</I>) </TD>
+    <TD> sequence&lt;<I>type</I>&gt; </TD>
+	</TR>
+	<TR>
+    <TD> [4] <I>type</I> </TD>
+    <TD> any </TD>
+	</TR>
+</TBODY>
+</TABLE>
+
+<ol>
+<li>JScript does not use the types float, char and short. If the
+target UNO function takes one of those types then an appropriate
+conversion occurs.</li>
+
+<li><p>The default behaviour of the conversion routine is that
+dispatch objects are converted into invocation objects (objects
+implementing XInvocation). The actual COM object is wrapped by an UNO
+object that implements XInvocation. Calls on XInvocation are mapped
+to calls on IDispatch.</p>
+<p>If a dispatch object is actually a wrapped
+UNO object then the original UNO object is extracted. Consider the
+following JScript (COM environment) code:</p>
+
+<Pre>
+// obj is an uno object
+var obj2= obj.getSomeObject();
+//obj2 is an UNO object which is encapsulated by an UNO wrapper
+obj.putSomeObject( obj2);
+</Pre>
+
+<p>
+When obj2 is passed back into the UNO environment then "obj" receives
+the original UNO object instead of a COM wrapper object.
+
+<P>When an UNO object in a COM environment receives an dispatch
+object in an IDispatch::Invoke call then it acquires type information
+about the parameter. The information contains the type what the
+dispatch object should represent in the UNO environment. If an
+interface other than XInvocation is expected than that specific
+interface is created by way of the service
+com.sun.star.script.InvocationAdapterFactory.
+</P>
+<P>In JScript one uses Array objects for out or in/out parameters (see <a href="#a6">JScript issues
+ </a>). Those objects are dispatch objects which are converted into the expected
+  type. Besides, the Array objects are of course used for arrays. If so then
+  they are converted into a Sequence with the proper element type.</P>
+<P>A mapped COM object can only be successfully used through XInvocation if it
+  provides type information through IDispatch::GetTypeInfo.</P>
+
+<li>A SAFEARRAY is converted to sequence&lt;<I>type</I>&gt; where type is the
+  respective UNO type. If the SAFEARRAY has more than one dimension then the anys
+  contain sequences of sequences and so forth; e.g. sequence&lt;sequence&lt;long&gt;&gt;.</P>
+<li>Whenever an UNO function requires an any parameter then the caller in the
+  COM environment is not obliged to pass a VARIANT (actually VT_VARIANT | VT_BYREF).
+<p>Instead the actual type can be put into the respective VARIANT argument (DISPPARAMS::rgvarg).</p>
+  If the bridge receives an VT_DISPATCH then it depends of the type information
+  of the target UNO function or property what the dispatch object will be converted
+  into (see [2], <a href="#a6">JScript issues</a>).
+</P>
+</ol>
+<P>Table 2 shows the conversions from UNO types to OLE Automation
+types.</P>
+<TABLE WIDTH=77% CELLPADDING=4 CELLSPACING=1 STYLE="page-break-after: avoid" summary="UNO OLE conversions">
+  <COL WIDTH=128* /> <COL WIDTH=128* /> <THEAD bgcolor=#eeeeee>
+  <TR>
+    <TH> UNO </TH>
+    <TH> OLE Automation </TH>
+   </TR>
+	</THEAD>
+	<TBODY bgcolor=#eeeeff>
+	<TR>
+    <TD> boolean </TD>
+    <TD> boolean </TD>
+	</TR>
+	<TR>
+    <TD> byte </TD>
+    <TD> unsigned char </TD>
+	</TR>
+	<TR>
+    <TD> double </TD>
+    <TD> double </TD>
+	</TR>
+	<TR>
+    <TD> float </TD>
+    <TD> float </TD>
+	</TR>
+	<TR>
+    <TD> short </TD>
+    <TD> short </TD>
+	</TR>
+	<TR>
+    <TD> unsigned short </TD>
+    <TD> short </TD>
+	</TR>
+	<TR>
+    <TD> long </TD>
+    <TD> long </TD>
+	</TR>
+	<TR>
+    <TD> unsigned long </TD>
+    <TD> long </TD>
+	</TR>
+	<TR>
+    <TD> string </TD>
+    <TD> BSTR </TD>
+	</TR>
+	<TR>
+    <TD> <I>interfaces</I> </TD>
+    <TD> IDispatch* </TD>
+	</TR>
+	<TR>
+    <TD> [1] sequence&lt;<I>type</I>&gt; </TD>
+    <TD> SAFEARRAY(<I>type</I>),<br/>
+	     SAFEARRAY(VARIANT) </TD>
+	</TR>
+	<TR>
+    <TD> struct </TD>
+    <TD> IDispatch* </TD>
+	</TR>
+	<TR>
+    <TD> enum </TD>
+    <TD> long </TD>
+	</TR>
+	<TR>
+    <TD> char </TD>
+    <TD> short </TD>
+	</TR>
+	<TR>
+    <TD> [2] <I>type</I> </TD>
+    <TD> VARIANT </TD>
+	</TR>
+	</TBODY>
+</TABLE>
+
+<ol>
+<li>A Sequence which has as element
+type of a sequence could be regarded as two-dimensional array. The
+difference is that the element sequences could have varying lengths
+whereas the elements of a certain dimension of a  multidimensional
+array have the same length. To reflect that, sequences are converted
+into one-dimensional SAFEARRAYs with VARIANT elements which in turn
+can contain SAFEARRAYs. This conversion works fine with COM objects
+which expect those arrays, e.g. COM objects which implement UNO
+interfaces (see <a href="#a10">chapter 10</a>). But quite often this will not
+be the
+case and if a function argument is a SAFEARRAY of a certain element
+type and dimension then exactly this argument has to be provided.
+
+<p>Whenever the bridge determines that a COM object does not
+implement UNO interfaces then it converts a Sequence into a SAFEARRAY
+as described by the type information provided through the object's
+IDispatch interface.
+</P>
+<P>In case IDispatch::Invoke expects an
+argument of type SAFEARRAY(VARIANT) then the UNO clients can provide
+sequence&lt;any&gt; or just sequence&lt;<I>type</I>&gt;, where <I>type
+</I>means the actual UNO type.</P>
+<li>The XBridgeSupplier2::createInstance function returns an any that
+contains the converted element. If the target environment is OLE than
+the any contains an unsigned long that is actually a VARIANT*. The
+VARIANT then contains the converted element  and has never the
+VT_BYREF bit set. Hence it cannot contain another VARIANT.
+</P>
+<P>When a client uses the COM object in an
+UNO environment (through XInvocation) and calls a function that
+requires a VARIANT argument, then the bridge  creates the arguments
+for IDispatch::Invoke as needed.  In this case DISPPARAMS::rgvarg
+would contain a VARIANT with VARTYPE::vt= VT_VARIANT | VT_BYREF. To
+do this the bridge must use type information which is provided
+through IDispatch::Invoke.
+</P>
+</ol>
+
+<h2><a name="a8"> 5 Using the bridge </a></h2>
+
+<p>
+The bridge is automatically used when someone access the
+  Office through the COM mechanism. This is done by creating the service manager
+  component, that has the ProgId <font face="Courier New, monospace">&quot;com.sun.star.ServiceManager&quot;.
+  </font>The service manager can then be used to create additional UNO services.
+  There is no explicit mapping from COM to UNO or vice versa necessary. All objects
+  which have been obtained directly or indirectly from the service manager are
+  already COM objects.
+<p>The ServiceManager implements the <a
+href="http://api.openoffice.org/common/ref/com/sun/star/lang/XMultiServiceFactory.html">
+  XMultiServiceFactory</a> interface, that is used to create UNO services. Bear
+  in mind though, that ServiceManager is a COM object and hence it is to be accessed
+  through the IDispatch interface.</p>
+<p>Example C++:</p>
+
+<pre>
+// create the service manager of OpenOffice
+IDispatch* pdispFactory= NULL;
+CLSID clsFactory= {0x82154420,0x0FBF,0x11d4,{0x83, 0x13,0x00,0x50,0x04,0x52,0x6A,0xB4}};
+hr= CoCreateInstance( clsFactory, NULL, CLSCTX_ALL, __uuidof(IDispatch), (void**)&amp;pdispFactory);
+// create the CoreReflection service
+OLECHAR* funcName= L&quot;createInstance&quot;;
+DISPID id;
+pdispFactory-&gt;GetIDsOfNames( IID_NULL, &amp;funcName, 1, LOCALE_USER_DEFAULT, &amp;id);
+
+VARIANT param1;
+VariantInit( &amp;param1);
+param1.vt= VT_BSTR;
+param1.bstrVal=   SysAllocString( L&quot;com.sun.star.reflection.CoreReflection&quot;);
+DISPPARAMS dispparams= { &amp;param1, 0, 1, 0}; VARIANT result;
+VariantInit( &amp;result);
+hr= pdispFactory-&gt;Invoke( id, IID_NULL, LOCALE_USER_DEFAULT, DISPATCH_METHOD,
+			  &amp;dispparams, &amp;result, NULL, 0);
+IDispatch* pdispCoreReflection= result.pdispVal;
+pdispCoreReflection-&gt;AddRef();
+// do something with the CoreReflection service
+</pre>
+
+<p> Example JScript:</p>
+
+<pre>
+var factory= new ActiveAObject("com.sun.star.ServiceManager");
+var coreReflection= factory.createInstance("com.sun.star.reflection.CoreReflection");
+// do something with the CoreReflection service
+</pre>
+
+<p>Irrespective of the Office you can map every COM
+  or UNO elements directly by using the com.sun.star.bridge.OleBridgeSupplier2
+  service. The code to convert an UNO service could look like this:</p>
+
+<pre>
+// convert the service xIntServiceX to a dispatch object
+Any any;
+IDispatch* pdisp= NULL;
+any &lt;&lt;= xIntServiceX;
+sal_uInt8 arId[16];
+rtl_getGlobalProcessId( arId);
+Any target= xSuppl-&gt;createBridge( any, Sequence&lt;sal_Int8&gt;( (sal_Int8*)arId, 16), UNO, OLE);
+if (target.getValueTypeClass() == TypeClass_UNSIGNED_LONG) 
+{
+    VARIANT* pVariant = *(VARIANT**)target.getValue();
+    pdisp= pVariant-&gt;pdispVal;
+    pdisp-&gt;AddRef()
+    VariantClear(pVariant);
+    CoTaskMemFree(pVariant);
+}
+
+// do something with pdisp (IDispatch*)
+</pre>
+
+<p> COM objects can be converted as long as they support IDispatch:
+
+<pre>
+// create the COM object
+hr= CoCreateInstance( COMPONENTS_CLSID, NULL,CLSCTX_ALL,
+		      IID_Unknown, (void**) &amp;punk);
+
+// create the service factory
+Reference&lt;XInterface&gt;
+xint= createRegistryServiceFactory( OUString(L&quot;applicat.rdb&quot;));
+Reference&lt;XMultiServiceFactory&gt; factory=
+	Reference&lt;XMultiServiceFactory&gt;( xint, UNO_QUERY);
+
+// create the bridge service
+Reference&lt; XInterface &gt; xIntSupplier= mgr-&gt;createInstance(
+				OUString(L&quot;com.sun.star.bridge.OleBridgeSupplier2&quot;));
+Reference&lt; XBridgeSupplier2 &gt; xSuppl( xIntSupplier, UNO_QUERY);
+
+Any any;
+Variant var;
+VariantInit( &amp;var);
+var.vt= VT_UNKNOWN;
+var.punkVal= punk;
+any &lt;&lt;= ( sal_uInt32)&amp;var;
+sal_uInt8 arId[16];
+rtl_getGlobalProcessId( arId);
+Any target= xSuppl-&gt;createBridge( any, Sequence&lt;sal_Int8&gt;(
+				 (sal_Int8*)arId, 16), OLE, UNO );
+Reference&lt;XInvocation&gt; theObject;
+target&gt;&gt;= theObject;
+
+// theObject contains now the mapped COM object
+</pre>
+
+<p>Apart from objects one can map all the data types
+  as shown in table 1 and table 2.</p>
+
+<p>A "specialization" of the OleBridgeSupplier2
+  service is the OleObjectFactory service. It does basically what the above source
+  sample does; just mapping a COM object to XInvocation.</p>
+
+<h2><a name="a5"> 6 Creation of types </a></h2>
+
+<P>The creation of types of one environment within the same environment
+  is not an issue but it looks different if this is done in another environment.
+  Usually it is not necessary at all because types of one environment are automatically
+  mapped to types of the other environment. In other words, one creates a value
+  of a type which is native to the current environment and passes it to an object
+  function, where the object stems from the other environment. The bridge automatically
+  converts the type if necessary. This even works for UNO interfaces on COM side
+  (see <a href="#a10">chapter 10</a>). But it is a different matter with UNO structs. When a struct
+  is mapped from UNO to COM then it is encapsulated by an dispatch object and
+  when this object is passed back to UNO then the original struct is extracted.
+  If an UNO object function takes a struct as argument, then it it not possible
+  to create a dispatch object and pass it as the respective argument. This functionality
+  has not been implemented yet. Instead there are two ways of creating structs
+  in the COM environment. First one can make use of the com.sun.star.CoreReflection
+  service:</P>
+
+<pre>
+// create the service manager of OpenOffice
+IDispatch* pdispFactory= NULL;
+CLSID clsFactory= {0x82154420,0x0FBF,0x11d4,{0x83, 0x13,0x00,0x50,0x04,0x52,0x6A,0xB4}};
+hr= CoCreateInstance( clsFactory, NULL, CLSCTX_ALL, __uuidof(IDispatch), (void**)&amp;pdispFactory);
+
+// create the CoreReflection service
+OLECHAR* funcName= L&quot;createInstance&quot;;
+DISPID id;
+pdispFactory-&gt;GetIDsOfNames( IID_NULL, &amp;funcName, 1, LOCALE_USER_DEFAULT, &amp;id);
+
+VARIANT param1;
+VariantInit( &amp;param1);
+param1.vt= VT_BSTR;
+param1.bstrVal=   SysAllocString( L&quot;com.sun.star.reflection.CoreReflection&quot;);
+DISPPARAMS dispparams= { &amp;param1, 0, 1, 0}; VARIANT result;
+VariantInit( &amp;result);
+hr= pdispFactory-&gt;Invoke( id, IID_NULL, LOCALE_USER_DEFAULT, DISPATCH_METHOD,
+			  &amp;dispparams, &amp;result, NULL, 0);
+IDispatch* pdispCoreReflection= result.pdispVal;
+pdispCoreReflection-&gt;AddRef();
+VariantClear( &amp;result);
+
+// create the struct's idl class object
+OLECHAR* strforName= L&quot;forName&quot;;
+hr= pdispCoreReflection-&gt;GetIDsOfNames( IID_NULL, &amp;strforName, 1, LOCALE_USER_DEFAULT, &amp;id);
+VariantClear( &amp;param1);
+param1.vt= VT_BSTR;
+param1.bstrVal= SysAllocString(L&quot;com.sun.star.beans.PropertyValue&quot;);
+hr= pdispCoreReflection-&gt;Invoke( id, IID_NULL, LOCALE_USER_DEFAULT,
+				DISPATCH_METHOD, &amp;dispparams, &amp;result, NULL, 0);
+
+IDispatch* pdispClass= result.pdispVal;
+pdispClass-&gt;AddRef();
+VariantClear( &amp;result);
+
+// create the struct
+OLECHAR* strcreateObject= L&quot;createObject&quot;;
+hr= pdispClass-&gt;GetIDsOfNames( IID_NULL,&amp;strcreateObject, 1, LOCALE_USER_DEFAULT, &amp;id)
+
+IDispatch* pdispPropertyValue= NULL;
+VariantClear( &amp;param1);
+param1.vt= VT_DISPATCH | VT_BYREF;
+param1.ppdispVal= &amp;pdispPropertyValue;
+hr= pdispClass-&gt;Invoke( id, IID_NULL, LOCALE_USER_DEFAULT,
+		DISPATCH_METHOD, &amp;dispparams, NULL, NULL, 0);
+
+// do something with the struct pdispPropertyValue
+
+
+pdispPropertyValue-&gt;Release();
+pdispClass-&gt;Release();
+pdispCoreReflection-&gt;Release();
+pdispFactory-&gt;Release();
+</pre>
+
+<p>A simpler way is to use the _GetStruct function which every UNO
+object in a COM environment provides.
+</p>
+
+<pre>
+// object be some UNO object in a  COM environment
+OLECHAR* strstructFunc= L&quot;_GetStruct&quot;;
+hr= object-&gt;GetIDsOfNames( IID_NULL, &amp;strstructFunc, 1, LOCALE_USER_DEFAULT, &amp;id);
+
+VariantClear(&amp;result);
+VariantClear( &amp;param1);
+param1.vt= VT_BSTR;
+param1.bstrVal= SysAllocString(
+L&quot;com.sun.star.beans.PropertyValue&quot;);
+hr= object-&gt;Invoke( id, IID_NULL,LOCALE_USER_DEFAULT, DISPATCH_METHOD,
+			&amp;dispparams, &amp;result, NULL, 0);
+
+IDispatch* pdispPropertyValue= result.pdispVal;
+pdispPropertyValue-&gt;AddRef();
+
+// do something with the struct pdispPropertyValue
+</pre>
+
+<h2><a name="a6"> 7 JScript issues </a></h2>
+
+<P>
+JScript does not offer
+arrays in a way as C or C++ do. Instead it provides the Array object
+which acts as array but is actually a dispatch object. Therefore an
+UNO object in the COM environment receives an dispatch object when it
+is used in JScript and an Array object has been passed into a
+function of that object.
+</p>
+
+<pre>
+// JScript
+var param= new Array(1,2,3);
+// object is an UNO object
+object.function( param);
+</pre>
+
+<P>JScript does not has out or in/out parameter. To create those
+parameters we use Array objects. The value on index 0 (actually
+property "0") contains the out- value after return of the
+function.
+</p>
+
+<pre>
+var out= new Array();
+object.functionOut(out);
+var value= out[0];
+</pre>
+
+<P>If an in/out parameter is needed then the in-value is set at index[0].</P>
+
+<pre>
+var inout= new Array();
+inout[0]=123;
+object.functionInOut( inout);
+var value= inout[0];
+</pre>
+
+<P>Whenever the bridge has to convert a dispatch object
+  then it first has to find out what the object actually represents (object,
+  array, out parameter, in/out parameter) to do an appropriate conversion. This
+  is done by acquiring type information, which itself is not problematic but in
+  a remote environment it causes additional network traffic.To avoid this one
+  could use Value Objects (see <a href="#a6">chapter 7</a>). Such an object can be used in place
+  of every other parameter in a COM environment. The script programmer sets the
+  type and value of this object, so that the bridge implementation knows what
+  the value actually stands for. </P>
+
+<P>JScript always uses doubles whenever it
+encounters floating point values. When a UNO function is called which
+actually takes a float as parameter, then the bridge does a
+conversion by using the Windows function VariantChangeType. This
+could cause a change of the value depending on the format of the
+number used in the script.</p>
+
+<p>When a UNO function returns a float or
+has a float as out-parameter then the conversion is put off to
+JScript. The results of this conversion most certainly does not match
+the expected value. In a test a UNO function has been called with the
+number1.234567 where the function expected a float. The function then
+returned that value as float. JScript receives in this case a  value
+of 1.2345670461654663.</P>
+
+<P>A similar situation exist with integer values. JScript
+  exclusively uses 32 bit integer values. The bridge tries to convert to a smaller
+  type if necessary. This works fine as long as the numbers used in JScript correspond
+  to the value range of the parameter type of the respective UNO function argument.</P>
+
+<h2><a name="a7"> 8 Value Objects </a></h2>
+
+<h3>8.1 Motivation</h3>
+
+<P>An UNO object used in JavaScript is wrapped by an object that is COM compatible
+  in that it exposes <CODE>IDispatch</CODE>. Such wrapper may be referred to as
+  uno wrapper in this document. Every access on a uno wrapper within Java Script
+  causes ultimately a call to <CODE>IDispatch::GetIDsOfNames </CODE>and on success
+  <CODE>IDispatch::Invoke</CODE> is called. The parameters are passed as <CODE>VARIANT</CODE>
+  s and are converted into <CODE>Any</CODE> s and a <CODE>Sequence</CODE>, in
+  and in/out parameter are treated much differently in the process. The problem
+  now is how to recognise the kind of the parameter because they are all represented
+  by <CODE>IDispatch</CODE> objects (<CODE>VT_DISPATCH</CODE>). To solve this
+  problem every time an <CODE>IDispatch</CODE> is to be converted it is checked
+  what kind of parameter this parameter is expected to be and the conversion goes
+  accordingly. For this it is necessary to acquire type information that is usually
+  provided by the office application. In a remote scenario several network round trips
+  would be required to deliver those information to the client. To prevent a severe
+  performance impact it is desirable to dispense with type information. "ValueObjects"
+  are a means to come close to that requirement.</P>
+
+<h3>8.2 The Value Object</h3>
+<P>A ValueObject is an object that acts as a value of a certain type and can be
+  passed to UNO functions instead of the actual parameter. A ValueObject is passed
+  to the wrapper as <CODE>IDispatch</CODE>. The uno wrapper queries every <CODE>IDispatch</CODE>
+  parameter for the <CODE>IJScriptValueObject</CODE> interface and if that interface
+  is being returned than the wrapper has a means to find out the exact type by
+  using that interface and is not dependent on type information provided by the
+  office application. ValueObjects and other parameters can be used interchangeably.</p>
+<h3>8.3 Creation</h3>
+<P>Every UNO object used by JavaScript is capable of delivering
+ValueObjects. To obtain one imply call _GetValueObject:</P>
+
+<Pre>
+// object is some uno wrapper object
+var valueObject= object._GetValueObject();
+</pre>
+
+<h3>8.4 The Interface of the Value Object</h3>
+<P>A Value Object is actually an instance of class <CODE>JScriptValue</CODE> that
+  implements <CODE>IDispatch</CODE> and <CODE>IJScriptValueObject</CODE>. The
+  <CODE>IJScriptValueObject</CODE> looks like:</P>
+
+<pre>
+MIDL_INTERFACE(&quot;e40a2331-3bc1-11d4-8321-005004526ab4&quot;)
+IJScriptValueObject: public IUnknown
+{
+    STDMETHOD( Set)( VARIANT type,  VARIANT value)= 0;
+    STDMETHOD( Get)( /*out*/ VARIANT *val)= 0;
+    STDMETHOD( InitOutParam)()= 0;
+    STDMETHOD( InitInOutParam)( VARIANT type, VARIANT value)= 0;
+    STDMETHOD( IsOutParam)( /*out*/ VARIANT_BOOL* flag)= 0;
+    STDMETHOD( IsInOutParam)( /*out*/VARIANT_BOOL * flag)= 0;
+    STDMETHOD( GetValue)( /*out*/ BSTR* type,/*out*/ VARIANT *value)= 0;
+};
+</pre>
+
+<P><code>IJScriptValueObject::Set</code>: Sets
+a value and specifies its type. The param "<CODE>type</CODE>"
+specifies the type by a string and the parameter "<CODE>value</CODE>"
+contains the value. Usable in JavaScript.</P>
+<P><code>IJScriptValueObject::Get: </code>Delivers
+the value that is contained in the ValueObject. Usable in JavaScript.</P>
+<P><code>IJScriptValueObject::InitOutParam: </code>Stipulates
+the ValueObject to represent an out parameter. Usable in JavaScript.</P>
+
+<P><code>IJScriptValueObject::InitInOutParam:
+</code>Stipulates the ValueObject to
+represent an in/out parameter. Usable in JavaScript.</P>
+<P><code>IJScriptValueObject::IsOutParam:
+</code>Returns a boolean (as out
+parameter)indicating whether the ValueObject acts as out parameter or
+not. A return value of true means the object is an out parameter. Not
+for use in JavaScript.</P>
+<P><code>IJScriptValueObject::IsInOutParam: </code>Returns a boolean
+(as out parameter) indicating whether the ValueObject acts as
+in/out parameter or not. A return value of true means the objects is
+an in/out parameter. Not for use in JavaScript.</P>
+<p><code>IJScriptVal</code>v<code>ueObject::GetValue: </code> Returns the type
+and value of the ValueObject as out parameter. Not for use in JavaScript. As
+seen in the above function descriptions only <CODE>Get</CODE>,
+<CODE>Set</CODE>, <CODE>InitInOutParam</CODE>
+and <CODE>InitOutParam</CODE> can be used in JavaScript. To be more exact these
+functions are exposed by <CODE>IDispatch</CODE>.
+
+<h3>8.5 Supported Types</h3>
+
+<P>When setting the ValueObject to a value the type is determined by
+a string that is passed as first parameter in the Set function. The
+table below shows what strings are currently accepted (column name).</P>
+
+<TABLE WIDTH=100% CELLPADDING=4 CELLSPACING=1 summary="Table of supported types">
+  <COL WIDTH=85* /> <COL WIDTH=85* /> <COL WIDTH=85* /> <THEAD bgcolor=#eeeeee>
+  <TR>
+    <TH> Name </TH>
+    <TH> Type </TH>
+    <TH> TypeClass </TH>
+  </TR>
+  </THEAD> <TBODY bgcolor=#eeeeff>
+  <TR>
+    <TD> char </TD>
+    <TD> sal_Unicode </TD>
+    <TD> TypeClass_CHAR </TD>
+  </TR>
+  <TR>
+    <TD> boolean </TD>
+    <TD> sal_Bool </TD>
+    <TD> TypeClass_BOOL </TD>
+  </TR>
+  <TR>
+    <TD> byte </TD>
+    <TD> sal_Int8 </TD>
+    <TD> TypeClass_BYTE </TD>
+  </TR>
+  <TR>
+    <TD> short </TD>
+    <TD> sal_Int16 </TD>
+    <TD> TypeClass_SHORT </TD>
+  </TR>
+  <TR>
+    <TD> unsigned short </TD>
+    <TD> sal_uInt16 </TD>
+    <TD> TypeClass_UNSIGNED_SHORT </TD>
+  </TR>
+  <TR>
+    <TD> long </TD>
+    <TD> sal_Int32 </TD>
+    <TD> TypeClass_LONG </TD>
+  </TR>
+  <TR>
+    <TD> unsigned long </TD>
+    <TD> sal_uInt32 </TD>
+    <TD> TypeClass_UNSIGNED_LONG </TD>
+  </TR>
+  <TR>
+    <TD> string </TD>
+    <TD> OUString </TD>
+    <TD> TypeClass_STRING </TD>
+  </TR>
+  <TR>
+    <TD> float </TD>
+    <TD> float </TD>
+    <TD> TypeClass_FLOAT </TD>
+  </TR>
+  <TR>
+    <TD> double </TD>
+    <TD> double </TD>
+    <TD> TypeClass_DOUBLE </TD>
+  </TR>
+  <TR>
+    <TD> any </TD>
+    <TD> Any </TD>
+    <TD> TypeClass_ANY </TD>
+  </TR>
+  <TR>
+    <TD> object </TD>
+    <TD> XInterface </TD>
+    <TD> TypeClass_INTERFACE </TD>
+  </TR>
+  </TBODY>
+</TABLE>
+
+<P>Sequences are represented by prepending &quot;[]&quot;, e.g. []char, [][]byte,
+  [][][]object, etc.</P>
+
+<h3>8.6 Usage</h3>
+<OL>
+	<LI><P>Sequence:
+
+
+<pre>
+// object is an UNO object
+var value= object._GetValueObject();
+var array= new Array(1,2,3);
+value.Set(&quot;[]short&quot;,array);
+object.function( value);
+</pre>
+
+<p>The array could also contain ValueObjects if necessary:</p>
+
+<pre>
+var value1= object._GetValueObject();
+var value2= object._GetValueObject();
+value1.Set(&quot;short&quot;, 100);
+value2.Set(&quot;short&quot;, 111);
+var array= new Array();
+array[0]= value1;
+array[1]= value2;
+var allValue= object._GetValueObject();
+allValue.Set(&quot;[]short&quot;, array);
+object.function( allValue);
+</pre>
+
+<LI><P>Out parameter:
+
+<pre>
+// object is an UNO object
+var value= object._GetValueObject();
+value.InitOutParam();
+object.functionOut( value);
+var out= value.Get();
+</pre>
+
+	<LI><P>In / out parameter:
+
+<pre>
+// object is an UNO object
+var value= object._GetValueObject();
+value.InitInOutParam(&quot;long&quot;, 123);
+object.functionInOut( value);
+var out= value.Get();
+</Pre>
+
+</OL>
+
+<h2><a name="a9"> 9 Limitations of the dispatch objects </a></h2>
+
+<P>
+The dispatch objects provided by the bridge do not support type
+information. IDispatch::GetTypeInfoCount and IDispatch::GetTypeInfo
+return  E_NOTIMPL. Moreover there are no COM type libraries available
+and the dispatch objects do not implement IProvideClassInfo as well.
+<P>
+IDispatch::GetIDsOfName has to be called for every name separately.
+That this one cannot query the ids for several names at a time.
+<P>
+IDispatch::Invoke does not support named arguments nor the
+<I>pExcepInfo and puArgErr  </I>parameter.</P>
+
+<h2><a name="a10"> 10 Implementing COM objects with UNO interfaces </a></h2>
+
+<h3>10.1 Intention</h3>
+<P>It is desirable to be able to build COM components which implement
+UNO interfaces. Those components could be employed as listeners (COM:
+event sinks), for numerous broadcasters (COM: event source).</P>
+
+<h3>10.2 Terms and Conventions</h3>
+<P>When speaking of implementing UNO interfaces in COM components, we
+do not imply  the use of interfaces in terms of abstract C++ classes.
+Instead the components have  to implement IDispatch and dispatch
+method calls to functions that have the same names as the respective
+UNO interface functions.</P>
+<P>Basically all interfaces can be implemented as long as the data
+type used in the UNO interfaces can be mapped to OLE automation
+types. The mappings are shown in Table 3. One exception is the
+XInvocation interface. Because it is itself a scripting interface, it
+does not make sense to employ it within a COM component. Assuming
+that someone wants to build a COM component that represents some UNO
+XInvocation implementation then the properties and functions are to
+be directly implemented. That is, IDispatch::Invoke dispatches
+directly to those properties and methods.</P>
+<P>XInterface does not need to be implemented.</P>
+<P>Because the <CODE>queryInterface</CODE> mechanism
+  does not work for COM components with implemented UNO interface, they have to
+  supply a means to proclaim those interfaces. This is achieved by the property
+  &quot;<CODE>_implementedInterfaces</CODE>&quot; that holds an array of strings
+  which contain the fully qualified interface names. The property is not needed
+  when only one interface is supported.</p>
+
+<h3>10.3 Components in C++</h3>
+
+<P>To build a component with C++ one can write the component from
+scratch or use some kind of framework, where Microsoft's ATL comes
+in handy. 
+<p>A basic rule with implementing <CODE>IDispatch</CODE>
+is that all parameters (meaning the actual arguments to the function
+that is called in turn) are converted into the types that the
+component expects. Although the OLE Bridge does not just pass
+arguments with the type VT_VARIANT |VT_BYREF but instead the actual
+type (see mapping table) it is still good practice to convert
+parameters within the IDispatch::Invoke implementation.
+</P>
+<P>When using ATL there is no need to bother about this as long as
+one uses a dual interface. Then the parameters correspond to the
+types as shown in table ...</p>
+<p>A COM component is free to support as
+many UNO interfaces as it needs to but an ATL component just needs to
+implement one dual interface. All UNO interface functions have to be
+put in that dual. In fact there is no other way because ATL can only
+expose one <CODE>IDispatch</CODE>.</P>
+
+<TABLE WIDTH=100% CELLPADDING=4 CELLSPACING=1 summary="OLE to UNO type map">
+  <COL WIDTH=128* /> <COL WIDTH=128* /> <THEAD bgcolor=#eeeeee>
+  <TR>
+    <TH> UNO Type Class </TH>
+    <TH> OLE Automation Type as  VARTYPE </TH>
+  </TR>
+	</THEAD>
+	<TBODY bgcolor=#eeeeff>
+
+  <TR>
+    <TD> INTERFACE </TD>
+    <TD> VT_DISPATCH (IDispatch*) </TD>
+	</TR>
+
+  <TR>
+    <TD> STRUCT </TD>
+    <TD> VT_DISPATCH (IDispatch*) </TD>
+	</TR>
+
+  <TR>
+    <TD> ENUM </TD>
+    <TD> VT_I4 (long) </TD>
+	</TR>
+
+  <TR>
+    <TD> BOOLEAN </TD>
+    <TD> VT_BOOL (VARIANT_BOOL) </TD>
+	</TR>
+
+  <TR>
+    <TD> STRING </TD>
+    <TD> VT_BSTR (BSTR) </TD>
+	</TR>
+
+  <TR>
+    <TD> FLOAT </TD>
+    <TD> VT_R4 (float) </TD>
+	</TR>
+
+  <TR>
+    <TD> DOUBLE </TD>
+    <TD> VT_R8 (double) </TD>
+	</TR>
+
+  <TR>
+    <TD> CHAR </TD>
+
+    <TD> VT_I2 (short) </TD>
+	</TR>
+
+  <TR>
+    <TD> BYTE </TD>
+
+    <TD> VT_UI1 (unsigned char) </TD>
+	</TR>
+
+  <TR>
+    <TD> SHORT </TD>
+    <TD> VT_I2 (short) </TD>
+	</TR>
+
+  <TR>
+    <TD> UNSIGNED_SHORT </TD>
+    <TD> VT_I2 (short) </TD>
+	</TR>
+
+  <TR>
+    <TD> LONG </TD>
+    <TD> VT_I4 (long) </TD>
+	</TR>
+
+  <TR>
+    <TD> UNSIGNED_LONG </TD>
+    <TD> VT_I4 (long) </TD>
+	</TR>
+
+  <TR>
+    <TD> SEQUENCE </TD>
+    <TD> VT_ARRAY |  VT_VARIANT </TD>
+	</TR>
+
+  <TR>
+    <TD> ANY </TD>
+    <TD> VT_VARIANT </TD>
+	</TR>
+	</TBODY>
+</TABLE>
+
+<P STYLE="margin-top: 0.08in"><FONT SIZE=2><I>Table 3</I></FONT></P>
+
+<P>Whenever out or in/out parameter are used then the VARTYPEs above are or'd
+  with VT_BYREF.</P>
+<P>E.g. there is an UNO interface with this idl description:
+</p>
+
+<pre>
+interface XSimple : public com.sun.star.uno.XInterface
+{
+    void func1( [in] long val, [out] long outVal);
+    void func2( [in] sequence&lt; long &gt; val, [out] sequence&lt; long &gt; outVal);
+};
+</pre>
+
+<P>The MS IDL description (for an ATL
+component with a dual interface) would look like:
+</p>
+
+<pre>
+[
+    object,
+    uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx),
+    dual,
+    helpstring(&quot;ISimple Interface&quot;),
+    pointer_default(unique)
+]
+interface ISimple : IDispatch
+{
+    [id(1), helpstring(&quot;method func1&quot;)]
+		HRESULT func1( [in] long val, [out] long* outVal);
+    [id(2), helpstring(&quot;method func2&quot;)]
+		HRESULT func2([in] SAFEARRAY(VARIANT) val,
+			[out] SAFEARRAY(VARIANT) * outVal);
+};
+</pre>
+
+<p>
+The property  looks like this:
+</p>
+
+<pre>
+[propget, id(4), helpstring(&quot;property_implementedInterfaces&quot;)]
+	HRESULT	_implementedInterfaces([out, retval] SAFEARRAY(BSTR) *pVal);
+</pre>
+
+<h3>10.4 Components in JScript</h3>
+
+<P>In JScript one does not have to deal with types. Nevertheless it
+is important to know   how arrays, in/out and out parameter are used
+because the usage is rather different.
+</P>
+<P>For in/out and out parameter an object with a property   &quot;0&quot;
+is passed.
+
+<pre>
+function inoutFunction( val )
+{
+    var value= val[0];
+    val[0]= 123;
+}
+
+function outFunction( val)
+{
+    val[0]= 123;
+}
+</pre>
+
+<p>An Array is passed as out parameter:</p>
+
+<pre>
+function outArray( val )
+{
+    val[0]= new Array( 1,2,3);
+}
+</pre>
+
+<p>If a JScript object should implement several interfaces than the
+object has to have the property &quot;_<CODE>implementedInterfaces</CODE>&quot;.
+Additionally a JScript has to support the property &quot;_environment&quot;
+which must have the value &quot;JScript&quot;.
+</p>
+
+<pre>
+function AnObject()
+{
+    this._environment= &quot;JScript&quot;;
+    this._implementedInterfaces= new Array( &quot;XSimple1&quot;,
+				&quot;XSimple2&quot;,&quot;XSimple3&quot;);
+
+// the interface functions
+this.simple1Func= simple1Func;
+this.simple2Func= simple2Func;
+this.simple3Func= simple3Func;
+}
+// XSimple1
+function simpleFunc()
+{
+	...
+}
+// XSimple2
+function simple2Func()
+{
+	...
+}
+// XSimple3
+function simple3Func()
+{
+    ...
+}
+</pre>
+
+<table width=100% cellpadding=4 bgcolor=#666699 summary=footer>
+<tr>
+<TD>
+<FONT color=#ffffff>Author: <A href="mailto:joachim.lingner@germany.sun.com">
+<FONT color=#ffffff>Joachim Lingner</FONT></A>
+($Date: 2004/11/27 13:07:07 $)<br/>
+<I>Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</I></FONT>
+</td></tr></table>
+</BODY>
+</html>

Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/ole_bridge.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/remotebridge.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/remotebridge.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/remotebridge.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/remotebridge.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,285 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1" />
+	<TITLE>Interprocess bridges</TITLE>
+	<META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Win32)" />
+	<META NAME="CLASSIFICATION" CONTENT="Interprocess bridges" />
+	<META NAME="KEYWORDS" CONTENT="UNO,interprocess bridge" />
+	<style type="text/css">
+	<!--
+h1 { text-align:center; margin-top: 0.2cm; text-decoration: none; color: #ffffff; font-size: 6; margin-top: 0.2cm}
+h3 { margin-top: 0.2cm; margin-bottom=0.1cm; color: #ffffff;}
+dl {margin-bottom: 0.2cm;}
+dd {margin-bottom: 0.2cm;}
+dt {margin-bottom: 0.2cm;}
+-->
+</style>
+
+</HEAD>
+<BODY LINK="#444488" VLINK="#444488" BGCOLOR="#eeeeff">
+<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0 STYLE="page-break-before: always">
+	<TR>
+		<TD BGCOLOR="#666699">
+			<H1> Interprocess bridges </H1>
+			</td><td bgcolor="#666699" width=200>
+			<A HREF="http://www.openoffice.org/"><IMG SRC="../../../images/open_office_org_logo.gif" NAME="Grafik1" ALT="OpenOffice.org" ALIGN=right BORDER=0 /></A>
+		</TD>
+	</TR>
+</TABLE>
+<br/>
+<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0 STYLE="page-break-before: always">
+	<TR>
+		<TD WIDTH=100% BGCOLOR="#666699">
+			<h3> Contents </h3>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100%>
+		  <p style="Margin-left: 1cm">
+			<A HREF="#Overview">Overview</A><br/>
+			<A HREF="#Description">Description</A><br/>
+			<A HREF="#Technical_details">Technical details</A><br/>
+			<A HREF="#Profiling">Profiling OpenOffice.org</A><br/>
+		  </p>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100% BGCOLOR="#666699">
+			<h3><A NAME="Overview"></A> Overview </h3>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100%>
+			<P STYLE="margin-bottom: 0cm">Interprocess bridges
+			allow executing UNO-calls in a remote process via a
+			byte-stream-connection. Currently, two protocols are
+			available :  IIOP(<I>Internet inter-orb-protocol</I>) and
+			URP (<I>uno remote protocol</I>). The IIOP-protocol is still
+			under development, while URP is final.
+			After
+			bootstrapping the bridge and retrieving the first object, uno
+			programming becomes "remote transparent".</P>
+			<P>"Remote transparency" means that the caller does not
+			need to distinguish between remote and local UNO-calls ( and in
+			general, the caller has no way of knowing whether the call is
+			executed remotely or not).</P>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100% BGCOLOR="#666699">
+			<h3><A NAME="Description"></A> Description </h3>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100%>
+			<H4>Bootstrapping the bridge</H4>
+			<P><FONT SIZE=3><I>Fig. 1</I> shows all necessary services (and
+			their exported interfaces ) to create and use an interprocess bridge</FONT>.
+			An interprocess bridge can be instantiated via the service
+			com.sun.star.bridge.BridgeFactory using the call
+			XBridgeFactory.createBridge(). The caller needs to pass 4
+			Arguments to the bridge factory.</P>
+			<P>The first argument is the name of the bridge. When no name is
+			given, an exclusive bridge is created, which means that the bridge
+			cannot be retrieved via the getBridge() method. Giving the bridge
+			a certain name allows another component to reuse the bridge via
+			the getBridge() passing the same name. Unnamed bridges can be
+			safely disposed without bothering other possible users, while named
+			bridges can be reused.</P>
+			<P>The second argument is the protocol string. Up to now,
+			"iiop" and "urp" is supported.
+			Internally, the bridgefactory
+			searches for a service "com.sun.star.bridge.Bridge.protocolname "
+			and creates it. You may provide parameters, following the protocolname and
+			separated with comma(s), to the bridge (currently, there are no
+			parameters supported).</P>
+			<P>The third argument is a reference to an
+			XConnection-interface. The XConnection interface offers simple
+			read/write functions to exchange data with an arbitrary process.
+			The UDK supplies two services to build up a connection between two
+			processes (see acceptor/connector documentation), but one is
+			welcome to use their own implementation. Note that the
+			XConnection-interface does not have methods to initiate a
+			connection, it expects to receive a fully functional connection.
+			Note also, that the bridge expects to be the ONLY USER of the
+			connection, it can't cope with any, in between, read/write calls.</P>
+			<P>The createBridge()-caller may optionally pass an
+			XInstanceProvider-implementation. When the first request from the
+			remote process comes in, the bridge will call the
+			XInstanceProvider.getInstance() method to resolve the
+			first-object. At least one process must provide an
+			XInstanceProvider-implementation ( in general the
+			"server-process").</P>
+			<P>The resulting object, which is only a wrapper around a
+			C-Interface, exports an XBridge interface.
+			</P>
+			<P>The bridge has three methods, the getInstance() method is the
+			most important one. It allows the "client-process" to
+			retrieve the primary object from the remote process. The passed
+			string may be used to distinguish between different primary
+			objects. The bridge in the remote process will call
+			XInstanceProvider.getInstance( ) to resolve the requested object.</P>
+			<P>On client side, the bridge returns a proxy for the remote
+			object. The uno-programmer cannot distinguish between a proxy
+			object or an original object.</P>
+			<P>The primary object supports, in general, an interface that
+			allows for retrieving other objects (for instance
+			XMultiServiceFactory, XNamingService, or etc.)</P>
+			<P>The bridge also supports the XComponent interface. Calling
+			dispose immediately cancels all ongoing remote calls. See below
+			for further information.</P>
+			<P>Note that "client" and "server" is here
+			used only for convenience. In a distributed environment, one
+			process may act as client and as server at the same time.</P>
+
+			<H4> Lifetime of the bridge </H4>
+			<P>The bridge remains active as long as there are proxies or stubs
+			(which implicitly hold the bridge). When the last proxy dies, the
+			bridge will dispose itself and close the connection.</P>
+			<P>The bridge can be actively disposed by querying for the
+			XComponent-interface and calling a dispose. This will initiate the
+			shutdown procedure described below. The same procedure is done,
+			when the connection is closed for any external reason.</P>
+			<P>Hard shutdown procedure:</P>
+			<P>The connection is closed immediately. All pending requests
+			will receive a RuntimeException. After all threads have left the
+			bridge, the bridge explicitly deletes all stubs, so that original
+			objects held by the stubs are released. The bridge itself is
+			deleted when the last proxy dies.</P>
+			<P>Note that the main thread may need to synchronize with the
+			other threads in order to safely shutdown an application. Waiting
+			for a certain amount of time after disposing is a dirty but quick
+			solution for the problem.
+			</P>
+			<P>Note that all components must be able to cope with a
+			RuntimeException as a result of an arbitrary UNO-call to allow a
+			safe shutdown.</P>
+			<P ALIGN=center><IMG SRC="../images/iiopbridge.gif" NAME="Grafik2" ALIGN=middle WIDTH=642 HEIGHT=893 BORDER=0 alt="Interfaces for building a bridge" /></P>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100% BGCOLOR="#666699">
+			<h3><A NAME="Technical_details"></A> Technical details </h3>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100%>
+			<P STYLE="margin-bottom: 0cm">This section describes some
+			technical details about an interprocess bridge, that may be important to
+			know for remote programming.</P>
+			<H4>Multi-threading</H4>
+			<P STYLE="margin-bottom: 0cm">The whole bridge is threadsafe and
+			allows multiple threads to execute remote calls. The dispatcher
+			thread inside the bridge cannot block because it never executes
+			calls, instead it passes the requests to worker threads.</P>
+			<H4>Synchron/Asynchron calls</H4><!-- rh: In english: Synchronous/Asynchronous -->
+			<P STYLE="margin-bottom: 0cm">For a synchron call the bridge sends
+			the request via the connection and lets the requesting thread wait
+			for the reply. All calls that have a return value, an out
+			parameter, or throw exceptions different from the RuntimeException,
+			MUST be synchron.</P>
+			<P STYLE="margin-bottom: 0cm"><br/>
+			</P>
+			<P STYLE="margin-bottom: 0cm">An asynchron ( or oneway ) call
+			sends the request via the connection and immediately returns, not
+			waiting for a reply.It is currently specified at the
+			IDL-interface, whether a request is synchron or asynchron.</P>
+			<P STYLE="margin-bottom: 0cm"><br/>
+			</P>
+			<P STYLE="margin-bottom: 0cm">For <B>synchron</B> requests, <B>thread
+			identity</B> is guaranteed. When process A calls process B and
+			process B calls again process A, the same thread waiting in
+			process A will take over the new request. This avoids deadlocks
+			when the same mutex is locked again.</P>
+			<P STYLE="margin-bottom: 0cm"><br/>
+			</P>
+			<P>For <B>asynchron</B> requests, this is not possible because
+			there is no thread waiting in process A. Such requests are
+			executed in a new thread. The <B>series of calls</B> between two
+			processes is guaranteed. If two asynchron requests from process A
+			are sent to process B, the second request will wait until the
+			first request is finished.</P>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=100% BGCOLOR="#666699">
+			<h3><A NAME="Profiling"></A> Profiling OpenOffice.org </h3>
+		</TD>
+	</TR>
+
+	<TR>
+		<TD WIDTH=100%>
+		When your Java or C++ extension for OpenOffice.org is too slow, this can often be solved by reducing
+		redundant API calls. Each API call (Java-C++ inprocess, Java-C++ outofprocess,
+		C++-C++ outofprocess) involves a bridging overhead, which is about one milli second per call.
+		(Note that C++-C++ inprocess is not bridged at all and cannot be logged, but it is either way
+		very fast !).
+
+		<p>By using a specially built interprocess bridge, you can log the interprocess calls into a file,
+		in order to analyze them later. I have prepared for Linux,Solaris and windows a shared library,
+		which you simply should copy into the office-program directory (make sure, you have moved away
+		the original one before). They can be downloaded from the
+		<a href="http://udk.openoffice.org/servlets/ProjectDocumentList">files section</a>. They
+		have been built in a OpenOffice.org 1.0 source tree, but should also work in later OpenOffice.org builds and
+		in StarOffice builds.
+
+		<p>
+		In order to activate logging, you need to set the following environment variables :
+		<table summary="Environment variables">
+		<tr>
+		<td> PROT_REMOTE_ACTIVATE</td>
+		<td> 1 </td>
+		</tr>
+
+		<tr>
+		<td>PROT_REMOTE</td>
+		<td>/system-path/to/logfile</td>
+		</tr>
+		</table>
+
+		so e.g. on windows
+		<pre>
+		set PROT_REMOTE_ACTIVATE=1
+		set PROT_REMOTE=c:\mylog
+		</pre>
+
+		After you have started the office out of this shell, for each newly established bridge a file is
+		created, e.g. c:\mylog_pid1023_0 for an interprocess bridge and c:\mylog_pid1023_1 for the
+		Java-C++ inprocess. Note, that this is only an example, in fact, the last number in the
+		file name gives the order in which the bridges get used. E.g. when you connect from another
+		process to the office, the _0 file will be this interprocess bridge. When you then instantiate
+		a Java service in the office process, the _1 file will appear. In general, a quick look at the
+		methods names in the files tells you, which bridge belongs to which file.
+
+		<p>
+		Each log file contains the time of calling in milliseconds (since an arbitrary point of time), the bytesize of
+		each call, whether it was synchron or asynchron, and the name of the method, which has been called.
+
+		e.g.
+		<pre>
+		015572: calling [size=128(usedata=3)] [synchron=1] [name=queryInterface]
+		015743: getting reply [size=264(usedata=240)][name=queryInterface]
+		015752: serving request [size=125(usedata=31)] [synchron=1] [name=queryInterface]
+		015754: replying [size=93(usedata=59)] [name=queryInterface]
+		</pre>
+		The log is created in the C++ remote bridge. Therefor the output means e.g. for the Java-C++ inprocess
+		bridge : 'calling' means a call is initiated from the C++-office to an Java object, 'getting reply'
+		means that the call has returned from Java, 'serving request' means that from the Java side a call
+		to a C++ object has been initiated and replying means that this call is now going back to Java.
+
+		<p>
+		Happy profiling :o).
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=50% BGCOLOR="#666699">
+			<P ALIGN=left><FONT COLOR="#ffffff">
+			Author: <A HREF="mailto:joerg.budischewski@germany.sun.com"><FONT COLOR="#ffffff">Joerg Budischewski</FONT></A> ($Date: 2004/12/15 12:49:52 $)<br/>
+			<I>Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</I></FONT>
+			</P>
+		</TD>
+	</TR>
+</TABLE>
+</BODY>
+</html>

Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/remotebridge.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/transparentofficecomponents.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/transparentofficecomponents.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/transparentofficecomponents.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/transparentofficecomponents.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,319 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+<head>
+    <title>Transparent Use of Office UNO Components</title>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
+<style type="text/css">
+<!--
+h1 { text-align:center; margin-top: 0.2cm; text-decoration: none; color: #ffffff; background-color: #666699; font-size: 6; margin-top: 0.2cm; }
+h2 { margin-top: 0.2cm; margin-bottom=0.1cm; color: #ffffff; background-color: #666699 }
+li {margin-bottom: 0.2cm;}
+dl {margin-bottom: 0.2cm;}
+dd {margin-bottom: 0.2cm;}
+dt {margin-bottom: 0.2cm;}
+-->
+</style>
+</head>
+<body>
+
+
+<h1>Transparent Use of Office UNO Components</h1>
+
+<h2>Introduction</h2>
+
+<p>This document is about making the use of office UNO components transparent
+to the user.</p>
+
+<p>If some client code wants to use office UNO components, then the typical use 
+case is, that the client code is first looking for an existing office
+installation. If an installation is found, it is checked if the office process
+is already running. If no office process is running, an office process is
+started. After that the client code connects to the running office using remote
+UNO mechanisms in order to get the remote component context of that office.
+After this, the client code can use the remote component context to access
+arbitrary office UNO components. From the perspective of the client code there
+is no difference between local and remote components.</p>
+
+<p>The idea is, that the component context is provided in a more transparent
+way. Especially the location of an existing office installation and the
+detection of a running office process should be hidden from the user.</p>
+
+
+<h2>Transparent Use from Java</h2>
+	
+<p>The UNO component context is the root object for all UNO client applications.
+It must be passed to a component during its instantiation and therefore
+basically provides an environment for components. The component context also
+provides the service manager, which is used to create components. The idea is,
+that a bootstrap method is provided, which bootstraps the component context from
+a UNO installation. A simple client application may then look like:</p>
+
+<blockquote>
+<pre>
+// get the remote office component context
+XComponentContext xContext = 
+ com.sun.star.comp.helper.Bootstrap.bootstrap();
+
+// get the remote office service manager
+XMultiComponentFactory xServiceManager =
+ xContext.getServiceManager();
+
+// get an instance of the remote office desktop UNO service
+Object desktop = xServiceManager.createInstanceWithContext(
+  &quot;com.sun.star.frame.Desktop&quot;, xContext );
+
+// query the XComponentLoader interface from the desktop
+XComponentLoader xComponentLoader =
+  (XComponentLoader)UnoRuntime.queryInterface(
+    XComponentLoader.class, desktop );
+
+// load a spreadsheet document
+String loadURL = &quot;private:factory/scalc&quot;;
+PropertyValue[] loadProps = new PropertyValue[0];
+xComponentLoader.loadComponentFromURL(
+ loadURL, &quot;_blank&quot;, 0, loadProps);
+</pre>
+</blockquote>
+
+<p>One of the requirements for a Java client application is, that Java finds the
+<code>com.sun.star.comp.helper.Bootstrap</code> class and all the UNO types
+(e.g. UNO interfaces) and other Java UNO language binding classes (e.g.
+<code>com.sun.star.uno.AnyConverter</code>) used by the client code. A natural
+approach would be to add the UNO jar files to the Java CLASSPATH, but this
+requires the knowledge of the location of a UNO installation. Other approaches
+would be to use the Java extension mechanism or to deploy the jar files
+containing the UNO types in the client jar file. Both of those approaches have
+several drawbacks, the most important one is the problem of type conflicts, e.g.
+if a deployed component adds new UNO types. We therefore decided to use a more
+dynamic approach, namely to provide a customized class loader. The customized
+class loader will have an extended search path, which will also include the path
+to a UNO installation. The UNO installation will be auto-detected on the system
+by a provided search algorithm.</p>
+
+
+<h3>Customized Class Loader</h3>
+
+<p>The concept is based on the requirement that every class that uses UNO types
+or other classes that come with a office installation gets loaded by a
+customized class loader. This customized class loader knows the location of a
+UNO installation and loads every class from a jar or class file that belongs to
+the office installation. That means, the customized class loader must be
+instantiated and initialized before the first class that uses UNO is loaded.</p>
+
+<p>For convenience we will provide some tooling in the SDK, which allows to
+build a client jar file, which can be invoked by</p>
+
+<blockquote>
+<code>java -jar MyApplication.jar</code>
+</blockquote>
+
+<p>A client application created by using the SDK tooling will automatically load
+the class <code>com.sun.star.lib.loader.Loader</code>, which sets up the
+customized class loader for loading the application class. In order to achieve
+this, the SDK tooling creates a manifest file that contains the following
+<code>Main-Class</code> entry</p>
+
+<blockquote>
+<code>Main-Class: com.sun.star.lib.loader.Loader</code>
+</blockquote>
+
+<p>The customized loader needs a special entry in the manifest file that
+specifies the name of the class that contains the client application code:</p>
+
+<blockquote>
+<pre>
+Name: com/sun/star/lib/loader/Loader.class
+Application-Class: MyApplication
+</pre>
+</blockquote>
+
+<p>The implementation of <code>com.sun.star.lib.loader.Loader.main</code> will
+read this entry and call the main method of the application class after the
+customized class loader has been created and set up properly. The SDK tooling
+will take over the task to write the correct manifest entry for the application
+class.</p>
+
+
+<h3>Finding a UNO installation</h3>
+
+<p>The location of a UNO installation can be specified by the Java system
+property <code>com.sun.star.lib.loader.unopath</code>. The system property can
+be passed to the client application by using the <code>-D</code> flag, e.g</p> 
+
+<blockquote>
+<code>java -Dcom.sun.star.lib.loader.unopath=/opt/OpenOffice.org/program -jar
+MyApplication.jar</code>
+</blockquote>
+
+<p>In addition, it is possible to specify a UNO installation by setting the
+environment variable <code>UNO_PATH</code> to the program directory of a UNO
+installation, e.g.</p>
+
+<blockquote>
+<code>setenv UNO_PATH /opt/OpenOffice.org/program</code>
+</blockquote>
+
+<p>Note, that this is not working with Java 1.3.1 and Java 1.4, because
+environment variables are not supported in those Java versions.</p>
+
+<p>If no UNO installation is specified by the user, the default UNO installation
+on the system is searched for. The search algorithm is platform dependent.</p>
+
+<p>On the Windows platform, the UNO installation is found by reading the default
+value of the key &quot;Software\OpenOffice.org\UNO\InstallPath&quot; from the
+root key HKEY_CURRENT_USER in the Windows Registry. If this key is missing,
+the key is read from the root key HKEY_LOCAL_MACHINE. One of those keys is
+always written during the installation of an office. In a single user
+installation the key is written to HKEY_CURRENT_USER, in a multi-user
+installation of an administrator to HKEY_LOCAL_MACHINE. Note, that the default
+installation is the last installed office, but with the restriction, that
+HKEY_CURRENT_USER has a higher priority than HKEY_LOCAL_MACHINE. The reading
+from the Windows Registry requires, that the native library unowinreg.dll is
+part of the application jar file or can be found in the
+<code>java.library.path</code>. The SDK tooling automatically will put the
+native library into the jar file containing the client application.</p>
+
+<p>On the Unix/Linux platforms, the UNO installation is found from the
+<code>PATH</code> environment variable. Note, that for Java 1.3.1 and Java 1.4
+the installation is found by using the <code>which</code> command, because
+environment variables are not supported with those Java versions. Both methods
+require that the <code>soffice</code> executable or a symbolic link is in one of
+the directories listed in the <code>PATH</code> environment variable. For older
+versions than OOo 2.0 the above described methods may fail. In this case the UNO
+installation is taken from the .sversionrc file in the user's home directory.
+The default installation is the last entry in the .sversionrc file which points
+to a UNO installation. Note, that there won't be a .sversionrc file with OOo 2.0
+anymore.</p>
+
+
+<h3>The bootstrap method</h3>
+
+<p>The <code>com.sun.star.comp.helper.Bootstrap.bootstrap()</code> method is
+implemented in that way, that it first bootstraps a local component context by
+calling the method
+<code>com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null)</code>.
+Then it tries to establish a named pipe connection to a running
+office by using the <code>com.sun.star.bridge.UnoUrlResolver</code> service. If
+the connection fails, an office process is started. After that, it
+tries to connect to the running office again. If the connection
+succeeds, it gets the remote component context, which is returned.</p>
+
+<p>Note, that the office process can only be started, if the
+<code>juh.jar</code> file is located in the classes directory of an office
+installation. If the <code>juh.jar</code> file is copied to another location,
+the bootstrap method fails.</p>
+
+
+<h2>Transparent Use from C++</h2>
+
+<p>Also for C++ a bootstrap function is provided, which bootstraps the component
+context from a UNO installation. An example for a simple client application
+shows the following code snipplet:</p>
+
+<blockquote>
+<pre>
+// get the remote office component context
+Reference< XComponentContext > xContext( ::cppu::bootstrap() );
+
+// get the remote office service manager
+Reference< XMultiComponentFactory > xServiceManager(
+  xContext->getServiceManager() );
+
+// get an instance of the remote office desktop UNO service
+// and query the XComponentLoader interface
+Reference < XComponentLoader > xComponentLoader(
+  xServiceManager->createInstanceWithContext( OUString(
+  RTL_CONSTASCII_USTRINGPARAM( "com.sun.star.frame.Desktop" ) ),
+  xContext ), UNO_QUERY );
+
+// open a spreadsheet document
+Reference< XComponent > xComponent(
+  xComponentLoader->loadComponentFromURL(
+  OUString( RTL_CONSTASCII_USTRINGPARAM( "private:factory/scalc" ) ),
+  OUString( RTL_CONSTASCII_USTRINGPARAM( "_blank" ) ), 0,
+  Sequence &lt; ::com::sun::star::beans::PropertyValue >() ) );
+</pre>
+</blockquote>
+
+<p>A C++ client application which uses UNO is linked to the C++ UNO libraries,
+which can be found in the program directory of a UNO installation. When running
+the client application, the C++ UNO libraries are found only, if the UNO
+program directory is included in the <code>PATH</code> (Windows) or
+<code>LD_LIBRARY_PATH</code> (Unix/Linux) environment variable.</p>
+
+
+<h3>Application Loader</h3>
+
+<p>As this requires the knowledge of the location of a UNO installation, we
+will provide an application loader (<code>unoapploader.exe</code> for
+Windows, <code>unoapploader</code> for Unix/Linux), which detects
+a UNO installation on the system and adds the program directory of the UNO
+installation to the <code>PATH</code> / <code>LD_LIBRARY_PATH</code> environment
+variable. After that, the application process is loaded and started, whereby the
+new process inherits the environment of the calling process, including
+the modified <code>PATH</code> / <code>LD_LIBRARY_PATH</code> environment
+variable.</p>
+
+<p>For convenience we will provide some tooling in the SDK, which allows to
+build a client executable file (e.g. <code>myapplication</code> for
+Unix/Linux), which can be invoked by</p>
+
+<blockquote>
+<code>./myapplication</code>
+</blockquote>
+
+<p>In this case, the <code>myapplication</code> executable is simply the renamed
+<code>unoapploader</code> executable. All the application code is part of a
+second executable file, which must have the same name as the first executable,
+but prefixed by a underscore '_', that means in the example above the
+second executable is named <code>_myapplication</code>.</p>
+
+<p>On the Unix/Linux platforms the application loader writes error messages to
+the <code>stderr</code> stream. On the Windows platform error messages are
+written to the error file <code>&lt;application name&gt;-error.log</code> in
+the application's executable file directory. If this fails, the error file is
+written to the directory designated for temporary files.</p>
+
+<p>Note, that the C++ application loader is only available with OOo 2.0.</p>
+
+
+<h3>Finding a UNO installation</h3>
+
+<p>A UNO installation can be specified by the user by setting the
+<code>UNO_PATH</code> environment variable to the program directory of a UNO
+installation, e.g.</p>
+
+<blockquote>
+<code>setenv UNO_PATH /opt/OpenOffice.org/program</code>
+</blockquote>
+
+<p>If no UNO installation is specified by the user, the default installation
+on the system is taken.</p>
+
+<p>On the Windows platform, the default installation is read from the default
+value of the key &quot;Software\OpenOffice.org\UNO\InstallPath&quot; from the
+root key HKEY_CURRENT_USER in the Windows Registry. If this key is missing,
+the key is read from the root key HKEY_LOCAL_MACHINE.</p>
+
+<p>On the Unix/Linux platforms, the default installation is found from the
+<code>PATH</code> environment variable. This requires that the
+<code>soffice</code> executable or a symbolic link is in one of the directories
+listed in the <code>PATH</code> environment variable.</p>
+
+
+<h3>The bootstrap function</h3>
+
+<p>The <code>::cppu::bootstrap()</code> function is implemented in a similar
+way as the Java <code>com.sun.star.comp.helper.Bootstrap.bootstrap()</code>
+method. It first bootstraps a local component context by calling the
+<code>::cppu::defaultBootstrap_InitialComponentContext()</code> function and
+then tries to establish a named pipe connection to a running office by using
+the <code>com.sun.star.bridge.UnoUrlResolver</code> service. If the connection
+fails, an office process is started. After that, it tries to connect to the
+running office again. If the connection succeeds, it gets the remote component
+context, which is returned.</p>
+
+<p>Author: Thomas Benisch.  Last changed: $Date: 2004/12/05 13:42:29 $.</p>
+
+</body>
+</html>

Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/transparentofficecomponents.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/uno-url.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/uno-url.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/uno-url.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/uno-url.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,116 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+<HEAD>
+	<TITLE>UNO Url - Specification</TITLE>
+<meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8"/>
+<style type="text/css">
+	<!--
+h1 { text-align:center; margin-top: 0.2cm; text-decoration: none; color: #ffffff; font-size: 6; margin-top: 0.2cm}
+h2 { margin-top: 0.2cm; margin-bottom=0.1cm; color: #ffffff;
+     background-color: #666699 }
+li {margin-bottom: 0.2cm;}
+dl {margin-bottom: 0.2cm;}
+dd {margin-bottom: 0.2cm;}
+dt {margin-bottom: 0.2cm;}
+-->
+</style>
+</head>
+<BODY>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%" summary=header
+   bgcolor=#666699>
+<tr>
+<td>
+<h1> UNO Url - Specification </h1>
+</td><td>
+<a href="http://www.openoffice.org/">
+<img SRC="../../../images/open_office_org_logo.gif" ALT="OpenOffice" BORDER=0 height=54 width=114 align=right></img>
+</a>
+</td>
+</tr>
+</table>
+
+<h2> Specification </h2>
+<p>
+The UNO-Url is used to address a specific UNO object in a different process. It allows
+services such as the
+<a href="http://api.openoffice.org/common/ref/com/sun/star/bridge/UnoUrlResolver.html">
+com.sun.star.bridge.UnoUrlResolver</a> to map the addressed object from a remote process
+into the local process by setting  an interprocess connection and by using a certain
+kind of protocol on this connection.
+<p> 
+<img src="../images/uno-url.gif"></img>
+<p>
+
+The UNO-Url consists of four parts separated by colon and semicolon.
+<ol type=I>
+<li> The constant string 'uno:'. This identifies the url as UNO-Url and is needed to distinguish
+a uno-url e.g. from an http or ftp url.
+</li>
+<li> A string which characterizes the type of the connection, that shall be
+used to access
+the other process. Directly after this string can optionally follow a comma separated list
+of name-value pairs, where name and value are separated by a '='.
+
+<p>
+The connection-type-string and the names may only consist of ASCII letters and digits. They
+are not case sensitive. The value part is an arbitrary Unicode string, which is
+encoded in UTF8. Any character except letters, digits and <code>!$&'()*+-./:?@_~</code>
+must be converted to <code>%xx</code>, where xx is the hexadecimal representation of the UTF8
+byte. There are functions defined (see <a href="../../../cpp/ref/names/rtl/c-Uri.html">Uri</a> class) which
+support such conversions.
+
+<p>
+
+The <a href="connection_services.html">connection_services</a> document explains currently
+supported connection types and parameters and how the connection types can be extended.
+<p>
+The connection-type specifies the transport mechanism used to transfer a bytestream (e.g.
+tcp/ip-sockets or named pipes).
+</li>
+
+<li>
+A string which characterizes the type of protocol that is used to communicate over the
+established byte stream connection. The string can be followed by a comma separated list
+of name-value pairs, which can be used to customize the protocol to specific needs. The
+suggested protocol is urp (Uno Remote Protocol), have a look at the <a href="urp.html">
+specification</a> to see how it works and to get a list of possible properties.
+
+<p>
+The protocol-type-string and the names may only consist of ASCII letters and digits. They
+are interpreted case insensitive. The value part is an arbitrary Unicode string, which is
+encoded in UTF8. Any character except letters, digits and <code>!$&'()*+-./:?@_~</code>
+must be converted to <code>%xx</code>, where xx is the hexadecimal representation of the UTF8
+byte. There are functions defined (see <a href="../../../cpp/ref/names/rtl/c-Uri.html">Uri</a> class),
+which support such conversions.
+
+<p>
+The arrangement of connections and bridges is explained in detail in the
+<a href="remotebridge.html">remotebridge</a> document.
+
+<li>The object name of the object to be imported. A process
+must explicitly export a certain object by this distinct name, it is not possible
+to access an arbitrary UNO-object (for example as it would be possible in with CORBA's IOR).
+
+<p>Valid characters are letters, digits, and <code>!$&'()*+,-./:?=@_~</code>. Other characters
+are forbidden, such that this string can be taken as is (no conversion or escaping required).
+</li>
+</ol>
+
+<h2> <font color="#FFFFFF">Examples</font></h2>
+
+<ul>
+<li>uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager</li>
+<li>uno:pipe,name=mypipename;urp;MyObjectName</li>
+</ul>
+
+<table bgcolor=#666699 width=100%>
+<tr> <td>
+<font color="#FFFFFF">Author: <a href="mailto:joerg.budischewski@sun.com">
+<font color=#ffffff>J&ouml;rg Budischewski</font></a> ($Date: 2004/11/27 13:16:03 $)
+<br><I>Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</I></font>
+</td></tr>
+</table>
+</body>
+</html>
+

Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/uno-url.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/urp.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/urp.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/urp.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/urp.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,13 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+<HEAD>
+    <TITLE>UNO Remote Protocol Version 1.0 Specification</TITLE>
+    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"/>
+</HEAD>
+<BODY>
+
+<P>This document has been moved to <A HREF="http://wiki.services.openoffice.org/wiki/Uno/Remote/Specifications/Uno_Remote_Protocol">the wiki</A>.</P>
+
+</BODY>
+</HTML>

Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/urp.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message