diff options
Diffstat (limited to 'lib/ic/doc/src/ch_c_server.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_c_server.xml | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/lib/ic/doc/src/ch_c_server.xml b/lib/ic/doc/src/ch_c_server.xml new file mode 100644 index 0000000000..c66ae85fa3 --- /dev/null +++ b/lib/ic/doc/src/ch_c_server.xml @@ -0,0 +1,148 @@ +<?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 Server Back-end</title> + <prepared></prepared> + <docno></docno> + <date>2004-01-14</date> + <rev>C</rev> + <file>ch_c_server.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>With the option <c>{be, c_server}</c> the IDL Compiler generates + C server skeletons 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 server skeletons, form a hidden Erlang + node. That additional code contains implementations of call-back + functions that implement the true server functionality, and also + 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>__s.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 Skeleton Functions</title> + <p>For each IDL operation a C skeleton function is generated, the + prototype of which is <c><![CDATA[int <Scoped Function Name>__exec(<Interface Object> oe_obj, CORBA_Environment *oe_env)]]></c>, where <c><![CDATA[<Interface Object>]]></c>, and + <c>CORBA_Environment</c> are of the same type as for the + generated C client stubs code.</p> + <p>Each <c><![CDATA[<Scoped Function Name>__exec()]]></c> function calls the + call-back function</p> + <p><c><![CDATA[<Scoped Function Name>_rs* <Scoped Function Name>__cb(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env)]]></c></p> + <p>where the arguments are of the same type as those generated for + C client stubs. </p> + <p>The return value <c><![CDATA[<Scoped Function Name>_rs* ]]></c> is a pointer + to a function with the same signature as the call-back function + <c><![CDATA[<Scoped Function Name>_cb]]></c>, and is called after the call-back + function has been evaluated (provided that the pointer is not equal + to <c>NULL</c>). </p> + </section> + + <section> + <title>The Server Loop</title> + <p>The developer has to implement code for establishing connections + with other Erlang nodes, code for call-back functions and restore + functions. </p> + <p></p> + <p>In addition, the developer also has to implement code for a + server loop, that receives messages and calls the relevant + <c>__exec</c> function. For that purpose the IC library function + <c>oe_server_receive()</c> function can be used.</p> + </section> + + <section> + <title>Generating, Compiling and Linking</title> + <p>To generate the C server skeletons type the following in an + appropriate shell:</p> + <p><c>erlc -I ICROOT/include "+{be, c_server}" 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 skeleton 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 server skeletons (the file is contained in the IC + <c>/examples/c-server</c> directory):</p> + <code type="none"> +module rmod { + + interface random { + + double produce(); + + oneway void init(in long seed1, in long seed2, in long seed3); + + }; + +}; </code> + <p>Generate the C server skeletons:</p> + <code type="none"> +erlc '+{be, c_server}' random.idl +Erlang IDL compiler version X.Y.Z </code> + <p>Six files are generated. </p> + <p>Compile the C server skeletons:</p> + <p>Please read the <c>ReadMe</c> file in the + <c>examples/c-server</c> directory.</p> + <p>In the same directory you can find all the code for this + example. In particular you will find the <c>server.c</c> file + that contains all the additional code that must be written to + obtain a complete server.</p> + <p>In the <c>examples/c-server</c> directory you will also find + source code for an Erlang client, which can be used for testing + the C server.</p> + </section> +</chapter> + + |