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

<cref>
  <header>
    <copyright>
      <year>2004</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 Protocol Functions</title>
    <prepared></prepared>
    <docno></docno>
    <date>2004-04-06</date>
    <rev>A</rev>
  </header>
  <lib>ic_c_protocol</lib>
  <libsummary>IC C Protocol Functions</libsummary>
  <description>
    <p>This manual page lists some of the functions of the IC C runtime
      library that are used internally for the IC protocol.
      </p>
    <p>The listed functions are used internally by generated C client
      and server code. They are documented here for <em>the advanced user</em> that want to replace the default protocol (Erlang
      distribution + gen_server) by his own protocol, For each set of
      client or sever functions below with prefix <c>oe</c>, the user
      has to implement his own set of functions, the names of which
      are obtained by replacing the <c>oe</c> prefix by <c>Prefix</c>.
      The <c>Prefix</c> has to be set with the option
      <c>{user_protocol, Prefix}</c> at compile time.</p>
    <p>The following terminology is used (reflected in names of
      functions): a <em>notification</em> is a message send from
      client to server, without any reply back (i.e.  a
      <em>oneway</em> operation); a <em>request</em> is a message sent
      from client to server, and where a <em>reply</em> message is
      sent back from the server to the client.</p>
    <p>In order to understand how the functions work and what they do
      the user <em>must</em> study their implementation in the IC C
      library (source file is <c>ic.c</c>), and also consider how they
      are used in the C code of ordinary generated client stubs or
      server skeletons.</p>
    <p></p>
  </description>

  <section>
    <title>Client Protocol Functions</title>
    <p>The following functions are used internally by generated C
      client code.</p>
  </section>
  <funcs>
    <func>
      <name><ret>int</ret><nametext>oe_prepare_notification_encoding(CORBA_Environment *env)</nametext></name>
      <fsummary>Prepare client notification encoding.</fsummary>
      <desc>
        <p>The result of this function is the beginning of a binary of
          in external format of the tuple <c>{'$gen_cast', X}</c> where
          <c>X</c> is not yet filled in. </p>
        <p>In generated client code this function is the first to be called
          in the encoding function for each oneway operation.</p>
      </desc>
    </func>
    <func>
      <name><ret>int</ret><nametext>oe_send_notification(CORBA_Environment *env)</nametext></name>
      <name><ret>int</ret><nametext>oe_send_notification_tmo(CORBA_Environment *env,  unsigned int send_ms)</nametext></name>
      <fsummary>Send client notification.</fsummary>
      <desc>
        <p>Sends a client notification to a server according to the
          Erlang distribution + gen_server protocol.</p>
        <p>The <c>send_ms</c> parameter specified a timeout in milliseconds.</p>
      </desc>
    </func>
    <func>
      <name><ret>int</ret><nametext>oe_prepare_request_encoding(CORBA_Environment *env)</nametext></name>
      <fsummary>Prepare client request encoding.</fsummary>
      <desc>
        <p>The result of this function is the beginning of a binary in
          the external format of the tuple <c>{'$gen_call', {Pid, Ref}, X}</c> where <c>X</c> is not yet filled in.</p>
        <p>In generated client code this function is the first to be called
          in the encoding function for each twoway operation.</p>
      </desc>
    </func>
    <func>
      <name><ret>int</ret><nametext>oe_send_request_and_receive_reply(CORBA_Environment *env)</nametext></name>
      <name><ret>int</ret><nametext>oe_send_request_and_receive_reply_tmo(CORBA_Environment *env, unsigned int send_ms, unsigned int recv_ms)</nametext></name>
      <fsummary>Send client request and receive reply.</fsummary>
      <desc>
        <p>Sends a client request and receives the reply according to
          the Erlang distribution + gen_server protocol. This function
          calls the <c>oe_prepare_reply_decoding</c> function in order
          to obtain the gen_server reply.
          </p>
        <p><c>send_ms</c> and <c>recv_ms</c> specify timeouts for send
          and receive, respectively, in milliseconds.</p>
      </desc>
    </func>
    <func>
      <name><ret>int</ret><nametext>oe_prepare_reply_decoding(CORBA_Environment *env)</nametext></name>
      <fsummary>Prepare client decoding of reply.</fsummary>
      <desc>
        <p>Decodes the binary version of the tuple <c>{Ref, X}</c>,
          where <c>X</c> is to be decoded later by the specific client
          decoding function.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Server Protocol Functions</title>
    <p>The following functions are used internally by generated C
      server code.</p>
  </section>
  <funcs>
    <func>
      <name><ret>int</ret><nametext>oe_prepare_request_decoding(CORBA_Environment *env)</nametext></name>
      <fsummary>Prepare server decoding of request.</fsummary>
      <desc>
        <p>Decodes the binary version of the tuple <c>{'$gen_cast', Op}</c> (<c>Op</c> an atom), or the tuple <c>{'$gen_cast', {Op, X}}</c>, where <c>Op</c> is the operation name, and
          where <c>X</c> is to be decoded later by the specific
          operation decoding function; or</p>
        <p>decodes the binary version of the tuple <c>{'$gen_call', {Pid, Ref}, Op}</c> (<c>Op</c> an atom), or the tuple
          <c>{'$gen_call', {Pid, Ref}, {Op, X}}</c>, where <c>Op></c>
          is the operation name, and <c>X</c> is to be decode later by
          the specific operation decoding function.</p>
      </desc>
    </func>
    <func>
      <name><ret>int</ret><nametext>oe_prepare_reply_encoding(CORBA_Environment *env)</nametext></name>
      <fsummary>Prepare server encoding of reply.</fsummary>
      <desc>
        <p>Encodes the beginning of the binary version of the tuple
          <c>{{Ref,X}</c>, where <c>X</c> is to be filled in by the
          specific server encoding function.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>SEE ALSO</title>
    <p>ic(3), ic_clib(3), <seealso marker="ch_ic_protocol">IC Protocol</seealso></p>
  </section>
  
</cref>

