The R13B03 release.OTP_R13B03

1 files changed, 149 insertions, 0 deletions

diff --git a/lib/ic/doc/src/ch_c_client.xml b/lib/ic/doc/src/ch_c_client.xml
new file mode 100644
index 0000000000..7d4f8ec91a
--- /dev/null
+++ b/lib/ic/doc/src/ch_c_client.xml
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1998</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>The C Client Back-end</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date>2004-01-14</date>
+    <rev>C</rev>
+    <file>ch_c_client.xml</file>
+  </header>
+
+  <section>
+    <title>Introduction</title>
+    <p>With the option <c>{be, c_client}</c> the IDL Compiler generates
+      C client stubs according to the IDL to C mapping, on top of the
+      Erlang distribution and gen_server protocols.</p>
+    <p>The developer has to write additional code, that together with
+      the generated C client stubs, form a hidden Erlang node. That
+      additional code uses <c>erl_interface</c> functions for defining
+      the hidden node, and for establishing connections to other
+      Erlang nodes.</p>
+  </section>
+
+  <section>
+    <title>Generated Stub Files</title>
+    <p>The generated stub files are:</p>
+    <list type="bulleted">
+      <item>
+        <p>For each IDL interface, a C source file, the name of which
+          is <c><![CDATA[<Scoped Interface Name>.c]]></c>. Each operation of the
+          IDL interface is mapped to a C function (with scoped name)
+          in that file;</p>
+      </item>
+      <item>
+        <p>C source files that contain functions for type conversion,
+          memory allocation, and data encoding/decoding;</p>
+      </item>
+      <item>
+        <p>C header files that contain function prototypes and type
+          definitions.</p>
+      </item>
+    </list>
+    <p>All C functions are exported (i.e. not declared static).</p>
+  </section>
+
+  <section>
+    <title>C Interface Functions</title>
+    <p>For each IDL operation a C interface function is 
+      generated, the prototype of which is:</p>
+    <p><c><![CDATA[<Return Value> <Scoped Function Name>(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env);]]></c></p>
+    <p>where</p>
+    <list type="bulleted">
+      <item>
+        <p><c><![CDATA[<Return Value>]]></c> is the value to be returned as defined
+          by the IDL specification;</p>
+      </item>
+      <item>
+        <p><c><![CDATA[<Interface Object> oe_obj]]></c> is the client interface
+          object;</p>
+      </item>
+      <item>
+        <p><c><![CDATA[<Parameters>]]></c> is a list of parameters of the
+          operation, defined in the same order as defined by the IDL
+          specification;</p>
+      </item>
+      <item>
+        <p><c>CORBA_Environment *oe_env</c> is a pointer to the current
+          client environment. It contains the current file descriptor,
+          the current input and output buffers, etc. For details see
+          <seealso marker="ch_c_corba_env#corbaenv">CORBA_Environment C Structure</seealso>.</p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>Generating, Compiling and Linking</title>
+    <p>To generate the C client stubs type the following in an
+      appropriate shell:</p>
+    <p><c><![CDATA[erlc -I ICROOT/include "+{be, c_client}"  File.idl]]></c>,</p>
+    <p>where <c>ICROOT</c> is the root of the IC application. The
+      <c>-I ICROOT/include</c> is only needed if <c>File.idl</c>
+      refers to <c>erlang.idl</c>.</p>
+    <p>When compiling a generated C stub file, the directories
+      <c>ICROOT/include</c> and <c>EICROOT/include</c>, have to be
+      specified as include directories, where <c>EIROOT</c> is the
+      root directory of the Erl_interface application.</p>
+    <p>When linking object files the <c>EIROOT/lib</c> and
+      <c>ICROOT/priv/lib</c> directories have to be specified. </p>
+  </section>
+
+  <section>
+    <title>An Example</title>
+    <p>In this example the IDL specification file "random.idl" is used
+      for generating C client stubs (the file is contained in the IC
+      <c>/examples/c-client</c> directory):</p>
+    <code type="none"><![CDATA[
+module rmod {
+ 
+  interface random {
+ 
+    double produce();
+ 
+    oneway void init(in long seed1, in long seed2, in long seed3);
+ 
+  };
+ 
+};        ]]></code>
+    <p>Generate the C client stubs:</p>
+
+    <code type="none"><![CDATA[
+erlc '+{be, c_client}' random.idl
+Erlang IDL compiler version X.Y.Z        ]]></code>
+
+    <p>Six files are generated. </p>
+    <p>Compile the C client stubs:</p>
+    <p>Please read the <c>ReadMe</c> file att the
+      <c>examples/c-client</c> directory</p>
+    <p>In the same
+      directory you can find all the code for this example.</p>
+    <p>In particular you will find the <c>client.c</c> file that contains
+      all the additional code that must be written to obtain a complete
+      client. </p>
+    <p>In the <c>examples/c-client</c> directory you will also find
+      source code for an Erlang server, which can be used for testing
+      the C client.</p>
+  </section>
+</chapter>
+
+