path: root/lib/ic/doc/src/ch_c_client.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1998</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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>