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