The C Client Back-end

## 7 The C Client Back-end

### 7.1 Introduction

With the option `{be, c_client}` the IDL Compiler generates C client stubs according to the IDL to C mapping, on top of the Erlang distribution and gen_server protocols.

The developer has to write additional code, that together with the generated C client stubs, form a hidden Erlang node. That additional code uses `erl_interface` functions for defining the hidden node, and for establishing connections to other Erlang nodes.

### 7.2 Generated Stub Files

The generated stub files are:

- For each IDL interface, a C source file, the name of which is `<Scoped Interface Name>.c`. Each operation of the IDL interface is mapped to a C function (with scoped name) in that file;
- C source files that contain functions for type conversion, memory allocation, and data encoding/decoding;
- C header files that contain function prototypes and type definitions.

All C functions are exported (i.e. not declared static).

### 7.3 C Interface Functions

For each IDL operation a C interface function is generated, the prototype of which is:

`<Return Value> <Scoped Function Name>(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env);`

where

- `<Return Value>` is the value to be returned as defined by the IDL specification;
- `<Interface Object> oe_obj` is the client interface object;
- `<Parameters>` is a list of parameters of the operation, defined in the same order as defined by the IDL specdication;
- `CORBA_Environment *oe_env` is a pointer to the current client environment. It contains the current file descriptor, the current input and output buffers, etc. For details see CORBA_Environment C Structure.

### 7.4 Generating, Compiling and Linking

To generate the C client stubs type the following in an appropriate shell:

`erlc -I ICROOT/include "+{be, c_client}" File.idl`,

where `ICROOT` is the root of the IC application. The `-I ICROOT/include` is only needed if `File.idl` refers to `erlang.idl`.

When compiling a generated C stub file, the directories `ICROOT/include` and `EICROOT/include`, have to be specified as include directories, where `EIROOT` is the root directory of the Erl_interface application.

When linking object files the `EIROOT/lib` and `ICROOT/priv/lib` directories have to be specified.

### 7.5 An Example

In this example the IDL specification file "random.idl" is used for generating C client stubs (the file is contained in the IC `/examples/c-client` directory):

    module rmod {

      interface random {

        double produce();

        oneway void init(in long seed1, in long seed2, in long seed3);

      };

    };

Generate the C client stubs:

    erlc '+{be, c_client}' random.idl
    Erlang IDL compiler version X.Y.Z

Six files are generated.

Compile the C client stubs:

Please read the `ReadMe` file att the `examples/c-client` directory

In the same directory you can find all the code for this example.

In particular you will find the `client.c` file that contains all the additional code that must be written to obtain a complete client.

In the `examples/c-client` directory you will also find source code for an Erlang server, which can be used for testing the C client.

Copyright © 1991-2007 Ericsson AB