diff options
Diffstat (limited to 'lib/ic/doc/src/ic_c_protocol.xml')
| -rw-r--r-- | lib/ic/doc/src/ic_c_protocol.xml | 158 |
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> + |