<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html xmlns:fn="http://www.w3.org/2005/02/xpath-functions"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css"> <title>Erlang -- The C Server Back-end</title> </head> <body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container"> <script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript"> <!-- function getWinHeight() { var myHeight = 0; if( typeof( window.innerHeight ) == 'number' ) { //Non-IE myHeight = window.innerHeight; } else if( document.documentElement && ( document.documentElement.clientWidth || document.documentElement.clientHeight ) ) { //IE 6+ in 'standards compliant mode' myHeight = document.documentElement.clientHeight; } else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) { //IE 4 compatible myHeight = document.body.clientHeight; } return myHeight; } function setscrollpos() { var objf=document.getElementById('loadscrollpos'); document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2; } function addEvent(obj, evType, fn){ if (obj.addEventListener){ obj.addEventListener(evType, fn, true); return true; } else if (obj.attachEvent){ var r = obj.attachEvent("on"+evType, fn); return r; } else { return false; } } addEvent(window, 'load', setscrollpos); //--></script><div id="leftnav"><div class="innertube"> <img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/ic-4.2.24.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>ic</strong><br><strong>User's Guide</strong><br><small>Version 4.2.24</small></p> <br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p> <ul class="flipMenu" imagepath="../../../../doc/js/flipmenu"> <li id="no" title="Using the IC Compiler" expanded="false">Using the IC Compiler<ul> <li><a href="ch_introduction.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_introduction.html#id2258553">Introduction</a></li> <li title="Compilation of IDL Files"><a href="ch_introduction.html#id2252254">Compilation of IDL Files</a></li> </ul> </li> <li id="no" title="OMG IDL" expanded="false">OMG IDL<ul> <li><a href="ch_basic_idl.html"> Top of chapter </a></li> <li title="OMG IDL - Overview"><a href="ch_basic_idl.html#id2252467">OMG IDL - Overview</a></li> </ul> </li> <li id="no" title="IC Protocol" expanded="false">IC Protocol<ul> <li><a href="ch_ic_protocol.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_ic_protocol.html#id2259761">Introduction</a></li> <li title="Language mappings and IDL operations"><a href="ch_ic_protocol.html#id2259444">Language mappings and IDL operations</a></li> <li title="IC Protocol"><a href="ch_ic_protocol.html#id2258509">IC Protocol</a></li> <li title="Gen_server Protocol"><a href="ch_ic_protocol.html#id2260392">Gen_server Protocol</a></li> <li title="Erlang Distribution Protocol"><a href="ch_ic_protocol.html#id2260445">Erlang Distribution Protocol</a></li> </ul> </li> <li id="no" title="Using the Plain Erlang Back-end" expanded="false">Using the Plain Erlang Back-end<ul> <li><a href="ch_erl_plain.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_erl_plain.html#id2263852">Introduction</a></li> <li title="Compiling the Code"><a href="ch_erl_plain.html#id2263869">Compiling the Code</a></li> <li title="Writing the Implementation File"><a href="ch_erl_plain.html#id2263887">Writing the Implementation File</a></li> <li title="An Example"><a href="ch_erl_plain.html#id2263947">An Example</a></li> </ul> </li> <li id="no" title="Using the Erlang Generic Server Back-end" expanded="false">Using the Erlang Generic Server Back-end<ul> <li><a href="ch_erl_genserver.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_erl_genserver.html#id2266793">Introduction</a></li> <li title="Compiling the Code"><a href="ch_erl_genserver.html#id2266814">Compiling the Code</a></li> <li title="Writing the Implementation File"><a href="ch_erl_genserver.html#id2266839">Writing the Implementation File</a></li> <li title="An Example"><a href="ch_erl_genserver.html#id2266901">An Example</a></li> </ul> </li> <li id="no" title="IDL to C mapping" expanded="false">IDL to C mapping<ul> <li><a href="ch_c_mapping.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_c_mapping.html#id2266418">Introduction</a></li> <li title="C Mapping Characteristics"><a href="ch_c_mapping.html#id2266527">C Mapping Characteristics</a></li> <li title="Basic OMG IDL Types"><a href="ch_c_mapping.html#id2266704">Basic OMG IDL Types</a></li> <li title="Constructed OMG IDL Types"><a href="ch_c_mapping.html#id2267584">Constructed OMG IDL Types</a></li> <li title="OMG IDL Constants"><a href="ch_c_mapping.html#id2267811">OMG IDL Constants</a></li> <li title="OMG IDL Operations"><a href="ch_c_mapping.html#id2267845">OMG IDL Operations</a></li> <li title="Exceptions"><a href="ch_c_mapping.html#id2268532">Exceptions</a></li> <li title="Access to Attributes"><a href="ch_c_mapping.html#id2268547">Access to Attributes</a></li> <li title="Summary of Argument/Result Passing for the C-client"><a href="ch_c_mapping.html#id2268559">Summary of Argument/Result Passing for the C-client</a></li> <li title="Supported Memory Allocation Functions"><a href="ch_c_mapping.html#id2270185">Supported Memory Allocation Functions</a></li> <li title="Special Memory Deallocation Functions"><a href="ch_c_mapping.html#id2270320">Special Memory Deallocation Functions</a></li> <li title="Exception Access Functions"><a href="ch_c_mapping.html#id2270361">Exception Access Functions</a></li> <li title="Special Types"><a href="ch_c_mapping.html#id2270403">Special Types</a></li> <li title="A Mapping Example"><a href="ch_c_mapping.html#id2270537">A Mapping Example</a></li> </ul> </li> <li id="no" title="The C Client Back-end" expanded="false">The C Client Back-end<ul> <li><a href="ch_c_client.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_c_client.html#id2270691">Introduction</a></li> <li title="Generated Stub Files"><a href="ch_c_client.html#id2270721">Generated Stub Files</a></li> <li title="C Interface Functions"><a href="ch_c_client.html#id2270776">C Interface Functions</a></li> <li title="Generating, Compiling and Linking"><a href="ch_c_client.html#id2270858">Generating, Compiling and Linking</a></li> <li title="An Example"><a href="ch_c_client.html#id2270927">An Example</a></li> </ul> </li> <li id="loadscrollpos" title="The C Server Back-end" expanded="true">The C Server Back-end<ul> <li><a href="ch_c_server.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_c_server.html#id2271068">Introduction</a></li> <li title="Generated Stub Files"><a href="ch_c_server.html#id2271099">Generated Stub Files</a></li> <li title="C Skeleton Functions"><a href="ch_c_server.html#id2271154">C Skeleton Functions</a></li> <li title="The Server Loop"><a href="ch_c_server.html#id2271220">The Server Loop</a></li> <li title="Generating, Compiling and Linking"><a href="ch_c_server.html#id2271250">Generating, Compiling and Linking</a></li> <li title="An Example"><a href="ch_c_server.html#id2271320">An Example</a></li> </ul> </li> <li id="no" title="CORBA_Environment C Structure" expanded="false">CORBA_Environment C Structure<ul> <li><a href="ch_c_corba_env.html"> Top of chapter </a></li> <li title="C Structure"><a href="ch_c_corba_env.html#id2271466">C Structure</a></li> <li title="The CORBA Compatibility Part"><a href="ch_c_corba_env.html#id2271562">The CORBA Compatibility Part</a></li> <li title="The External Part"><a href="ch_c_corba_env.html#id2271620">The External Part</a></li> <li title="The Internal Part"><a href="ch_c_corba_env.html#id2271769">The Internal Part</a></li> <li title="Creating and Initiating the CORBA_Environment Structure"><a href="ch_c_corba_env.html#id2271900">Creating and Initiating the CORBA_Environment Structure</a></li> <li title="Setting System Exceptions"><a href="ch_c_corba_env.html#id2272229">Setting System Exceptions</a></li> </ul> </li> <li id="no" title="IDL to Java language Mapping" expanded="false">IDL to Java language Mapping<ul> <li><a href="ch_java.html"> Top of chapter </a></li> <li title="Introduction"><a href="ch_java.html#id2272363">Introduction</a></li> <li title="Specialties in the Mapping"><a href="ch_java.html#id2272427">Specialties in the Mapping</a></li> <li title="Basic OMG IDL Types"><a href="ch_java.html#id2272455">Basic OMG IDL Types</a></li> <li title="Constructed OMG IDL Types"><a href="ch_java.html#id2272864">Constructed OMG IDL Types</a></li> <li title="Mapping for Constants"><a href="ch_java.html#id2272934">Mapping for Constants</a></li> <li title="Invocations of Operations"><a href="ch_java.html#id2272946">Invocations of Operations</a></li> <li title="Exceptions"><a href="ch_java.html#id2273001">Exceptions</a></li> <li title="Access to Attributes"><a href="ch_java.html#id2273015">Access to Attributes</a></li> <li title="Summary of Argument/Result Passing for Java"><a href="ch_java.html#id2273027">Summary of Argument/Result Passing for Java</a></li> <li title="Communication Toolbox"><a href="ch_java.html#id2273090">Communication Toolbox</a></li> <li title="The Package com.ericsson.otp.ic"><a href="ch_java.html#id2273411">The Package com.ericsson.otp.ic</a></li> <li title="The Term Class"><a href="ch_java.html#id2273836">The Term Class</a></li> <li title="Stub File Types"><a href="ch_java.html#id2274123">Stub File Types</a></li> <li title="Client Stub Initialization, Methods Exported"><a href="ch_java.html#id2274190">Client Stub Initialization, Methods Exported</a></li> <li title="Server Skeleton Initialization, Server Stub Implementation, Methods Exported"><a href="ch_java.html#id2274383">Server Skeleton Initialization, Server Stub Implementation, Methods Exported</a></li> <li title="A Mapping Example"><a href="ch_java.html#id2274528">A Mapping Example</a></li> <li title="Running the Compiled Code"><a href="ch_java.html#id2274624">Running the Compiled Code</a></li> </ul> </li> </ul> </div></div> <div id="content"> <div class="innertube"> <h1>8 The C Server Back-end</h1> <h3><a name="id2271068">8.1 Introduction</a></h3> <p>With the option <span class="code">{be, c_server}</span> 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 <span class="code">erl_interface</span> functions for defining the hidden node and for establishing connections to other Erlang nodes.</p> <h3><a name="id2271099">8.2 Generated Stub Files</a></h3> <p>The generated stub files are:</p> <ul> <li> <p>For each IDL interface, a C source file, the name of which is <span class="code"><Scoped Interface Name>__s.c</span>. Each operation of the IDL interface is mapped to a C function (with scoped name) in that file;</p> </li> <li> <p>C source files that contain functions for type conversion, memory allocation, and data encoding/decoding;</p> </li> <li> <p>C header files that contain function prototypes and type definitions.</p> </li> </ul> <p>All C functions are exported (i.e. not declared static).</p> <h3><a name="id2271154">8.3 C Skeleton Functions</a></h3> <p>For each IDL operation a C skeleton function is generated, the prototype of which is <span class="code">int <Scoped Function Name>__exec(<Interface Object> oe_obj, CORBA_Environment *oe_env)</span>, where <span class="code"><Interface Object></span>, and <span class="code">CORBA_Environment</span> are of the same type as for the generated C client stubs code.</p> <p>Each <span class="code"><Scoped Function Name>__exec()</span> function calls the call-back function</p> <p><span class="code"><Scoped Function Name>_rs* <Scoped Function Name>__cb(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env)</span></p> <p>where the arguments are of the same type as those generated for C client stubs. </p> <p>The return value <span class="code"><Scoped Function Name>_rs* </span> is a pointer to a function with the same signature as the call-back function <span class="code"><Scoped Function Name>_cb</span>, and is called after the call-back function has been evaluated (provided that the pointer is not equal to <span class="code">NULL</span>). </p> <h3><a name="id2271220">8.4 The Server Loop</a></h3> <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 <span class="code">__exec</span> function. For that purpose the IC library function <span class="code">oe_server_receive()</span> function can be used.</p> <h3><a name="id2271250">8.5 Generating, Compiling and Linking</a></h3> <p>To generate the C server skeletons type the following in an appropriate shell:</p> <p><span class="code">erlc -I ICROOT/include "+{be, c_server}" File.idl</span>,</p> <p>where <span class="code">ICROOT</span> is the root of the IC application. The <span class="code">-I ICROOT/include</span> is only needed if <span class="code">File.idl</span> refers to <span class="code">erlang.idl</span>.</p> <p>When compiling a generated C skeleton file, the directories <span class="code">ICROOT/include</span> and <span class="code">EICROOT/include</span>, have to be specified as include directories, where <span class="code">EIROOT</span> is the root directory of the Erl_interface application.</p> <p>When linking object files the <span class="code">EIROOT/lib</span> and <span class="code">ICROOT/priv/lib</span> directories have to be specified. </p> <h3><a name="id2271320">8.6 An Example</a></h3> <p>In this example the IDL specification file "random.idl" is used for generating C server skeletons (the file is contained in the IC <span class="code">/examples/c-server</span> directory):</p> <div class="example"><pre> module rmod { interface random { double produce(); oneway void init(in long seed1, in long seed2, in long seed3); }; }; </pre></div> <p>Generate the C server skeletons:</p> <div class="example"><pre> erlc '+{be, c_server}' random.idl Erlang IDL compiler version X.Y.Z </pre></div> <p>Six files are generated. </p> <p>Compile the C server skeletons:</p> <p>Please read the <span class="code">ReadMe</span> file in the <span class="code">examples/c-server</span> directory.</p> <p>In the same directory you can find all the code for this example. In particular you will find the <span class="code">server.c</span> file that contains all the additional code that must be written to obtain a complete server.</p> <p>In the <span class="code">examples/c-server</span> directory you will also find source code for an Erlang client, which can be used for testing the C server.</p> </div> <div class="footer"> <hr> <p>Copyright © 1998-2010 Ericsson AB. All Rights Reserved.</p> </div> </div> </div></body> </html>