The R13B03 release.OTP_R13B03

1 files changed, 158 insertions, 0 deletions

diff --git a/lib/ic/doc/src/ic_c_protocol.xml b/lib/ic/doc/src/ic_c_protocol.xml
new file mode 100644
index 0000000000..f895fe0723
--- /dev/null
+++ b/lib/ic/doc/src/ic_c_protocol.xml
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE cref SYSTEM "cref.dtd">
+
+<cref>
+  <header>
+    <copyright>
+      <year>2004</year>
+      <year>2007</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.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </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>
+