aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/doc/src/ic_c_protocol.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ic/doc/src/ic_c_protocol.xml')
-rw-r--r--lib/ic/doc/src/ic_c_protocol.xml158
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>
+