← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/ic/doc/src/ic_clib.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/ic/doc/src/ic_clib.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE cref SYSTEM "cref.dtd">
 
3
 
 
4
<cref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2003</year>
 
8
      <year>2008</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>IC C Library Functions</title>
 
27
    <prepared></prepared>
 
28
    <docno></docno>
 
29
    <date>2003-12-16</date>
 
30
    <rev>PB1</rev>
 
31
  </header>
 
32
  <lib>ic_clib</lib>
 
33
  <libsummary>IC C Library Functions</libsummary>
 
34
  <description>
 
35
    <p>This manual page lists some of the functions in the IC C runtime
 
36
      library. </p>
 
37
  </description>
 
38
 
 
39
  <section>
 
40
    <title>Allocation and Deallocation Functions</title>
 
41
    <p>The following functions are used for allocating and
 
42
      deallocating a <em>CORBA_Environment</em> structure.</p>
 
43
  </section>
 
44
  <funcs>
 
45
    <func>
 
46
      <name><ret>CORBA_Environment*</ret><nametext>CORBA_Environment_alloc(int inbufsz, int outbufsz)</nametext></name>
 
47
      <fsummary>Allocate environment data.</fsummary>
 
48
      <desc>
 
49
        <p>This function is used to allocate and initiate the
 
50
          <c>CORBA_Environment</c> structure. In particular, it is used
 
51
          to dynamically allocate a CORBA_Environment structure and set
 
52
          the default values for the structure's fields.</p>
 
53
        <p><em>inbufsize</em> is the initial size of the input
 
54
          buffer.</p>
 
55
        <p><em>outbufsize</em> is the initial size of the output
 
56
          buffer.</p>
 
57
        <p><em>CORBA_Environment</em> is the CORBA 2.0 state structure
 
58
          used by the generated stub.</p>
 
59
        <p>This function will set all needed default values and
 
60
          allocate buffers the lengths of which are equal to the
 
61
          values passed, but will not allocate space for the _to_pid
 
62
          and _from_pid fields.</p>
 
63
        <p>To free the space allocated by CORBA_Environment_alloc() do
 
64
          as follows.</p>
 
65
        <list type="bulleted">
 
66
          <item>
 
67
            <p>First call CORBA_free for the input and output buffers.</p>
 
68
          </item>
 
69
          <item>
 
70
            <p>After freeing the buffer space, call CORBA_free for the
 
71
              CORBA_Environment space.</p>
 
72
          </item>
 
73
        </list>
 
74
      </desc>
 
75
    </func>
 
76
    <func>
 
77
      <name><ret>void</ret><nametext>CORBA_free(void *p)</nametext></name>
 
78
      <fsummary>Free any allocated data.</fsummary>
 
79
      <desc>
 
80
        <p>Frees allocated space pointed to by <c>p</c>.</p>
 
81
      </desc>
 
82
    </func>
 
83
    <func>
 
84
      <name><ret>CORBA_char*</ret><nametext>CORBA_string_alloc(CORBA_unsigned_long len)</nametext></name>
 
85
      <fsummary>Allocate a string.</fsummary>
 
86
      <desc>
 
87
        <p>Allocates a (simple) CORBA character string of length <c>len + 1</c>.</p>
 
88
      </desc>
 
89
    </func>
 
90
    <func>
 
91
      <name><ret>CORBA_wchar*</ret><nametext>CORBA_wstring_alloc(CORBA_unsigned_long len)</nametext></name>
 
92
      <fsummary>Allocate a wide string.</fsummary>
 
93
      <desc>
 
94
        <p>Allocates a CORBA wide string of length <c>len + 1</c>.</p>
 
95
      </desc>
 
96
    </func>
 
97
  </funcs>
 
98
 
 
99
  <section>
 
100
    <title>Exception Functions</title>
 
101
    <p>Functions for retrieving exception ids and values, and for setting
 
102
      exceptions. </p>
 
103
  </section>
 
104
  <funcs>
 
105
    <func>
 
106
      <name><ret>CORBA_char*</ret><nametext>CORBA_exception_id(CORBA_Environment *env)</nametext></name>
 
107
      <fsummary>Get exception identity.</fsummary>
 
108
      <desc>
 
109
        <p>Returns the exception identity if an exception is set, otherwise
 
110
          it returns <c>NULL</c>.</p>
 
111
      </desc>
 
112
    </func>
 
113
    <func>
 
114
      <name><ret>void*</ret><nametext>CORBA_exception_value(CORBA_Environment *env)</nametext></name>
 
115
      <fsummary>Get exception value.</fsummary>
 
116
      <desc>
 
117
        <p>Returns the exception value, if an exception is set, otherwise
 
118
          it returns <c>NULL</c>.</p>
 
119
      </desc>
 
120
    </func>
 
121
    <func>
 
122
      <name><ret>void</ret><nametext>CORBA_exc_set(CORBA_Environment *env, CORBA_exception_type Major, CORBA_char *Id, CORBA_char *Value)</nametext></name>
 
123
      <fsummary>Set exception.</fsummary>
 
124
      <desc>
 
125
        <p>Sets the exception type, exception identity, and exception value
 
126
          in the environment pointed to by <c>env</c>.</p>
 
127
      </desc>
 
128
    </func>
 
129
  </funcs>
 
130
 
 
131
  <section>
 
132
    <title>Server Reception</title>
 
133
    <p>The following function is provided for convenience. </p>
 
134
  </section>
 
135
  <funcs>
 
136
    <func>
 
137
      <name><ret>int</ret><nametext>oe_server_receive(CORBA_Environment *env, oe_map_t *map)</nametext></name>
 
138
      <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>
 
139
      <fsummary>Server receive of notification or request, and sending of reply (in case of request).</fsummary>
 
140
      <desc>
 
141
        <p>Provides a loop that receives one message, executes the
 
142
          operation in question, and in case of a two-way operation
 
143
          sends a reply.</p>
 
144
        <p><c>send_ms</c> and <c>recv_ms</c> specify timeout values
 
145
          in milliseconds for send and receive, respectively.</p>
 
146
      </desc>
 
147
    </func>
 
148
  </funcs>
 
149
 
 
150
  <section>
 
151
    <title>Generic Execution Switch and Map Merging</title>
 
152
    <p>Function for searching for server operation function, and for
 
153
      calling it if found. Function for merging maps (see the include
 
154
      file <c>ic.h</c> for definitions). </p>
 
155
  </section>
 
156
  <funcs>
 
157
    <func>
 
158
      <name><ret>int</ret><nametext>oe_exec_switch(CORBA_Object obj, CORBA_Environment *env, oe_map_t *map)</nametext></name>
 
159
      <fsummary>Search for server operation and execute it.</fsummary>
 
160
      <desc>
 
161
        <p>Search for server operation and execute it.</p>
 
162
      </desc>
 
163
    </func>
 
164
    <func>
 
165
      <name><ret>oe_map_t*</ret><nametext>oe_merge_maps(oe_map_t *maps, int size)</nametext></name>
 
166
      <fsummary>Merge an array of server maps to one single map.</fsummary>
 
167
      <desc>
 
168
        <p>Merge an array of server maps to one single map.</p>
 
169
      </desc>
 
170
    </func>
 
171
  </funcs>
 
172
 
 
173
  <section>
 
174
    <title>The CORBA_Environment structure</title>
 
175
    <p>Here is the complete definition of the CORBA_Environment structure,
 
176
      defined in file <em>ic.h</em>: </p>
 
177
    <code type="none">
 
178
      /* Environment definition */
 
179
      typedef struct {
 
180
 
 
181
      /*----- CORBA compatibility part ------------------------*/
 
182
      /* Exception tag, initially set to CORBA_NO_EXCEPTION ---*/
 
183
      CORBA_exception_type   _major;          
 
184
 
 
185
      /*----- External Implementation part - initiated by the user ---*/
 
186
      /* File descriptor                                              */
 
187
      int                    _fd;             
 
188
      /* Size of input buffer                                         */
 
189
      int                    _inbufsz;        
 
190
      /* Pointer to always dynamically allocated buffer for input     */
 
191
      char                  *_inbuf;         
 
192
      /* Size of output buffer                                        */
 
193
      int                    _outbufsz;       
 
194
      /* Pointer to always dynamically allocated buffer for output    */ 
 
195
      char                  *_outbuf;        
 
196
      /* Size of memory chunks in bytes, used for increasing the output
 
197
      buffer, set to >= 32, should be around >= 1024 for performance
 
198
      reasons                                                       */ 
 
199
      int                    _memchunk;       
 
200
      /* Pointer for registered name                                   */
 
201
      char                   _regname[256];   
 
202
      /* Process identity for caller                                   */
 
203
      erlang_pid            *_to_pid;         
 
204
      /* Process identity for callee                                  */ 
 
205
      erlang_pid            *_from_pid;      
 
206
 
 
207
      /*- Internal Implementation part - used by the server/client ---*/
 
208
      /* Index for input buffer                                       */
 
209
      int                    _iin;            
 
210
      /* Index for output buffer                                      */
 
211
      int                    _iout;          
 
212
      /* Pointer for operation name                                   */
 
213
      char                   _operation[256];
 
214
      /* Used to count parameters                                    */
 
215
      int                    _received;      
 
216
      /* Used to identify the caller                                  */
 
217
      erlang_pid             _caller;        
 
218
      /* Used to identify the call                                     */
 
219
      erlang_ref             _unique;         
 
220
      /* Exception id field                                           */
 
221
      CORBA_char            *_exc_id;        
 
222
      /* Exception value field                                        */
 
223
      void                  *_exc_value;           
 
224
 
 
225
      
 
226
      } CORBA_Environment; 
 
227
    </code>
 
228
    <note>
 
229
      <p>Always set the field values <em>_fd</em>, <em>_regname</em>,
 
230
        <em>_to_pid</em> and/or <em>*_from_pid</em> to appropriate
 
231
        application values. These are not automatically set by the
 
232
        stubs.</p>
 
233
    </note>
 
234
    <warning>
 
235
      <p>Never assign static buffers to the buffer pointers, and never
 
236
        set the <em>_memchunk</em> field to a value less than
 
237
        <em>32</em>.</p>
 
238
    </warning>
 
239
  </section>
 
240
 
 
241
  <section>
 
242
    <title>SEE ALSO</title>
 
243
    <p>ic(3), ic_c_protocol(3)
 
244
      </p>
 
245
  </section>
 
246
  
 
247
</cref>
 
248