aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/doc/src/ic_clib.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/ic/doc/src/ic_clib.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/ic/doc/src/ic_clib.xml')
-rw-r--r--lib/ic/doc/src/ic_clib.xml246
1 files changed, 246 insertions, 0 deletions
diff --git a/lib/ic/doc/src/ic_clib.xml b/lib/ic/doc/src/ic_clib.xml
new file mode 100644
index 0000000000..b557c4b5f6
--- /dev/null
+++ b/lib/ic/doc/src/ic_clib.xml
@@ -0,0 +1,246 @@
+<?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>
+