<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE cref SYSTEM "cref.dtd">

<cref>
  <header>
    <copyright>
      <year>2003</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>IC C Library Functions</title>
    <prepared></prepared>
    <docno></docno>
    <date>2003-12-16</date>
    <rev>PB1</rev>
  </header>
  <lib>ic_clib</lib>
  <libsummary>IC C Library Functions</libsummary>
  <description>
    <p>This manual page lists some of the functions in the IC C runtime
      library. </p>
  </description>

  <section>
    <title>Allocation and Deallocation Functions</title>
    <p>The following functions are used for allocating and
      deallocating a <em>CORBA_Environment</em> structure.</p>
  </section>
  <funcs>
    <func>
      <name><ret>CORBA_Environment*</ret><nametext>CORBA_Environment_alloc(int inbufsz, int outbufsz)</nametext></name>
      <fsummary>Allocate environment data.</fsummary>
      <desc>
        <p>This function is used to allocate and initiate the
          <c>CORBA_Environment</c> structure. In particular, it is used
          to dynamically allocate a CORBA_Environment structure and set
          the default values for the structure's fields.</p>
        <p><em>inbufsize</em> is the initial size of the input
          buffer.</p>
        <p><em>outbufsize</em> is the initial size of the output
          buffer.</p>
        <p><em>CORBA_Environment</em> is the CORBA 2.0 state structure
          used by the generated stub.</p>
        <p>This function will set all needed default values and
          allocate buffers the lengths of which are equal to the
          values passed, but will not allocate space for the _to_pid
          and _from_pid fields.</p>
        <p>To free the space allocated by CORBA_Environment_alloc() do
          as follows.</p>
        <list type="bulleted">
          <item>
            <p>First call CORBA_free for the input and output buffers.</p>
          </item>
          <item>
            <p>After freeing the buffer space, call CORBA_free for the
              CORBA_Environment space.</p>
          </item>
        </list>
      </desc>
    </func>
    <func>
      <name><ret>void</ret><nametext>CORBA_free(void *p)</nametext></name>
      <fsummary>Free any allocated data.</fsummary>
      <desc>
        <p>Frees allocated space pointed to by <c>p</c>.</p>
      </desc>
    </func>
    <func>
      <name><ret>CORBA_char*</ret><nametext>CORBA_string_alloc(CORBA_unsigned_long len)</nametext></name>
      <fsummary>Allocate a string.</fsummary>
      <desc>
        <p>Allocates a (simple) CORBA character string of length <c>len + 1</c>.</p>
      </desc>
    </func>
    <func>
      <name><ret>CORBA_wchar*</ret><nametext>CORBA_wstring_alloc(CORBA_unsigned_long len)</nametext></name>
      <fsummary>Allocate a wide string.</fsummary>
      <desc>
        <p>Allocates a CORBA wide string of length <c>len + 1</c>.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Exception Functions</title>
    <p>Functions for retrieving exception ids and values, and for setting
      exceptions. </p>
  </section>
  <funcs>
    <func>
      <name><ret>CORBA_char*</ret><nametext>CORBA_exception_id(CORBA_Environment *env)</nametext></name>
      <fsummary>Get exception identity.</fsummary>
      <desc>
        <p>Returns the exception identity if an exception is set, otherwise
          it returns <c>NULL</c>.</p>
      </desc>
    </func>
    <func>
      <name><ret>void*</ret><nametext>CORBA_exception_value(CORBA_Environment *env)</nametext></name>
      <fsummary>Get exception value.</fsummary>
      <desc>
        <p>Returns the exception value, if an exception is set, otherwise
          it returns <c>NULL</c>.</p>
      </desc>
    </func>
    <func>
      <name><ret>void</ret><nametext>CORBA_exc_set(CORBA_Environment *env, CORBA_exception_type Major, CORBA_char *Id, CORBA_char *Value)</nametext></name>
      <fsummary>Set exception.</fsummary>
      <desc>
        <p>Sets the exception type, exception identity, and exception value
          in the environment pointed to by <c>env</c>.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Server Reception</title>
    <p>The following function is provided for convenience. </p>
  </section>
  <funcs>
    <func>
      <name><ret>int</ret><nametext>oe_server_receive(CORBA_Environment *env, oe_map_t *map)</nametext></name>
      <name><ret>int</ret><nametext>oe_server_receive_tmo(CORBA_Environment *env, oe_map_t *map,  unsigned int send_ms, unsigned int recv_ms)</nametext></name>
      <fsummary>Server receive of notification or request, and sending of reply (in case of request).</fsummary>
      <desc>
        <p>Provides a loop that receives one message, executes the
          operation in question, and in case of a two-way operation
          sends a reply.</p>
        <p><c>send_ms</c> and <c>recv_ms</c> specify timeout values
          in milliseconds for send and receive, respectively.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Generic Execution Switch and Map Merging</title>
    <p>Function for searching for server operation function, and for
      calling it if found. Function for merging maps (see the include
      file <c>ic.h</c> for definitions). </p>
  </section>
  <funcs>
    <func>
      <name><ret>int</ret><nametext>oe_exec_switch(CORBA_Object obj, CORBA_Environment *env, oe_map_t *map)</nametext></name>
      <fsummary>Search for server operation and execute it.</fsummary>
      <desc>
        <p>Search for server operation and execute it.</p>
      </desc>
    </func>
    <func>
      <name><ret>oe_map_t*</ret><nametext>oe_merge_maps(oe_map_t *maps, int size)</nametext></name>
      <fsummary>Merge an array of server maps to one single map.</fsummary>
      <desc>
        <p>Merge an array of server maps to one single map.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>The CORBA_Environment structure</title>
    <p>Here is the complete definition of the CORBA_Environment structure,
      defined in file <em>ic.h</em>: </p>
    <code type="none">
      /* Environment definition */
      typedef struct {

      /*----- CORBA compatibility part ------------------------*/
      /* Exception tag, initially set to CORBA_NO_EXCEPTION ---*/
      CORBA_exception_type   _major;          

      /*----- External Implementation part - initiated by the user ---*/
      /* File descriptor                                              */
      int                    _fd;             
      /* Size of input buffer                                         */
      int                    _inbufsz;        
      /* Pointer to always dynamically allocated buffer for input     */
      char                  *_inbuf;         
      /* Size of output buffer                                        */
      int                    _outbufsz;       
      /* Pointer to always dynamically allocated buffer for output    */ 
      char                  *_outbuf;        
      /* Size of memory chunks in bytes, used for increasing the output
      buffer, set to >= 32, should be around >= 1024 for performance
      reasons                                                       */ 
      int                    _memchunk;       
      /* Pointer for registered name                                   */
      char                   _regname[256];   
      /* Process identity for caller                                   */
      erlang_pid            *_to_pid;         
      /* Process identity for callee                                  */ 
      erlang_pid            *_from_pid;      

      /*- Internal Implementation part - used by the server/client ---*/
      /* Index for input buffer                                       */
      int                    _iin;            
      /* Index for output buffer                                      */
      int                    _iout;          
      /* Pointer for operation name                                   */
      char                   _operation[256];
      /* Used to count parameters                                    */
      int                    _received;      
      /* Used to identify the caller                                  */
      erlang_pid             _caller;        
      /* Used to identify the call                                     */
      erlang_ref             _unique;         
      /* Exception id field                                           */
      CORBA_char            *_exc_id;        
      /* Exception value field                                        */
      void                  *_exc_value;           

      
      } CORBA_Environment; 
    </code>
    <note>
      <p>Always set the field values <em>_fd</em>, <em>_regname</em>,
        <em>_to_pid</em> and/or <em>*_from_pid</em> to appropriate
        application values. These are not automatically set by the
        stubs.</p>
    </note>
    <warning>
      <p>Never assign static buffers to the buffer pointers, and never
        set the <em>_memchunk</em> field to a value less than
        <em>32</em>.</p>
    </warning>
  </section>

  <section>
    <title>SEE ALSO</title>
    <p>ic(3), ic_c_protocol(3)
      </p>
  </section>
  
</cref>

