1corba(3)                   Erlang Module Definition                   corba(3)
2
3
4

NAME

6       corba - The functions on CORBA module level
7

DESCRIPTION

9       This  module  contains functions that are specified on the CORBA module
10       level. It also contains some functions for creating and  disposing  ob‐
11       jects.
12

EXPORTS

14       create(Module, TypeID) -> Object
15       create(Module, TypeID, Env) -> Object
16       create(Module, TypeID, Env, Optons1) -> Object
17       create_link(Module, TypeID) -> Object
18       create_link(Module, TypeID, Env) -> Object
19       create_link(Module, TypeID, Env, Options2) -> Reply
20
21              Types:
22
23                 Module = atom()
24                 TypeID = string()
25                 Env = term()
26                 Options1  =  [{persistent,  Bool} | {regname, RegName} | {lo‐
27                 cal_typecheck, Bool}]
28                 Options2 = [{sup_child, Bool} | {persistent,  Bool}  |  {reg‐
29                 name, RegName} | {pseudo, Bool} | {local_typecheck, Bool}]
30                 RegName = {local, atom()} | {global, term()}
31                 Reply = #objref | {ok, Pid, #objref}
32                 Bool = true | false
33                 Object = #objref
34
35              These functions start a new server object. If you start it with‐
36              out RegName it can only be accessed through the returned  object
37              key.  Started  with  a RegName the name is registered locally or
38              globally.
39
40              TypeID is the repository ID of the server object type and  could
41              for example look like "IDL:StackModule/Stack:1.0".
42
43              Module is the name of the interface API module.
44
45              Env  is  the arguments passed which will be passed to the imple‐
46              mentations init call-back function.
47
48              A server started with create/2, create/3 or  create/4  does  not
49              care  about  the parent, which means that the parent is not han‐
50              dled explicitly in the generic process part.
51
52              A  server  started  with  create_link2,  create_link/3  or  cre‐
53              ate_link/4 is initially linked to the caller, the parent, and it
54              will terminate whenever the parent process terminates, and  with
55              the  same  reason  as the parent. If the server traps exits, the
56              terminate/2 call-back function is called in order  to  clean  up
57              before  the  termination.  These functions should be used if the
58              server is a worker in a supervision tree.
59
60              If you use the option {sup_child, true} create_link/4  will  re‐
61              turn {ok, Pid, #objref}, otherwise #objref, and make it possible
62              to start a server as a supervisor child (stdlib-1.7 or later).
63
64              If you use the option {persistent, true} you also must  use  the
65              option {regname, {global, Name}}. This combination makes it pos‐
66              sible to tell the difference between a server permanently termi‐
67              nated or in the process of restarting.
68
69              The option {pseudo, true}, allow us to create an object which is
70              not a server. Using {pseudo, true} overrides all other start op‐
71              tions. For more information see section Module_Interface.
72
73              If  a  server is started using the option {persistent, true} the
74              object key will not be removed unless it terminates with  reason
75              normal  or shutdown. Hence, if persistent servers is used as su‐
76              pervisor children  they  should  be  transient  and  the  objec‐
77              tkeys_gc_time should be modified (default equals infinity).
78
79              The option {local_typecheck, boolean()}, which overrides the Lo‐
80              cal Typechecking environment flag, turns on or off typechecking.
81              If  activated, parameters, replies and raised exceptions will be
82              checked to ensure that the data is correct, when invoking opera‐
83              tions  on CORBA Objects within the same Orber domain. Due to the
84              extra overhead, this option MAY ONLY be used during testing  and
85              development.
86
87              Example:
88
89                corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", {10, test})
90
91
92       dispose(Object) -> ok
93
94              Types:
95
96                 Object = #objref
97
98              This  function is used for terminating the execution of a server
99              object. Invoking this operation on a NIL object reference, e.g.,
100              the return value of corba:create_nil_objref/0, always return ok.
101              For valid object references, invoking this operation  more  than
102              once, will result in a system exception.
103
104       create_nil_objref() -> Object
105
106              Types:
107
108                 Object = #objref representing NIL.
109
110              Creates  an  object reference that represents the NIL value. At‐
111              tempts to invoke operations using the returned object  reference
112              will return a system exception.
113
114       create_subobject_key(Object, Key) -> Result
115
116              Types:
117
118                 Object = #objref
119                 Key = term()
120                 Result = #objref
121
122              This  function is used to create a subobject in a server object.
123              It can for example be useful when one  wants  unique  access  to
124              separate  rows in a mnesia or an ETS table. The Result is an ob‐
125              ject reference that will be seen as a unique  reference  to  the
126              outside  world  but will access the same server object where one
127              can use the get_subobject_key/1 function to get the private  key
128              value.
129
130              Key  is stored in the object reference Object. If it is a binary
131              it will be stored as is and otherwise it is converted to  a  bi‐
132              nary before storage.
133
134       get_subobject_key(Object) -> Result
135
136              Types:
137
138                 Object = #objref
139                 Result = #binary
140
141              This  function  is used to fetch a subobject key from the object
142              reference Object. The result is a always a binary, if it was  an
143              Erlang  term that was stored with create_subobject_key/2 one can
144              to do binary_to_term/1 to get the real value.
145
146       get_pid(Object) -> Result
147
148              Types:
149
150                 Object = #objref
151                 Result = #pid | {error, Reason} | {'EXCEPTION',E}
152
153              This function is to get the process id from an object, which  is
154              a  must  when  CORBA  objects is started/handled in a supervisor
155              tree. The function will throw exceptions if the key is not found
156              or some other error occurs.
157
158       raise(Exception)
159
160              Types:
161
162                 Exception = record()
163
164              This  function is used for raising corba exceptions as an Erlang
165              user generated exit signal. It will  throw  the  tuple  {'EXCEP‐
166              TION', Exception}.
167
168       reply(To, Reply) -> true
169
170              Types:
171
172                 To = client reference
173                 Reply = IDL type
174
175              This function can be used by a CORBA object to explicitly send a
176              reply to a client that invoked a two-way operation. If this  op‐
177              eration  is  used,  it  is not possible to return a reply in the
178              call-back module.
179              To must be the From argument provided to the callback  function,
180              which  requires  that the IC option from was used when compiling
181              the IDL-file.
182
183       resolve_initial_references(ObjectId) -> Object
184       resolve_initial_references(ObjectId, Contexts) -> Object
185
186              Types:
187
188                 ObjectId = string()
189                 Contexts = [Context]
190                 Context  =  #'IOP_ServiceContext'{context_id  =  CtxId,  con‐
191                 text_data = CtxData}
192                 CtxId = ?ORBER_GENERIC_CTX_ID
193                 CtxData  =  {interface, Interface} | {userspecific, term()} |
194                 {configuration, Options}
195                 Interface = string()
196                 Options = [{Key, Value}]
197                 Key = ssl_client_options
198                 Value = allowed value associated with the given key
199                 Object = #objref
200
201              This function returns the object reference associated  with  the
202              given  object id. Initially, only "NameService" is available. To
203              add or remove services use add_initial_service/2 or  remove_ini‐
204              tial_service/1.
205
206              The  configuration  context  is  used to override the global SSL
207              client side configuration.
208
209       add_initial_service(ObjectId, Object) -> boolean()
210
211              Types:
212
213                 ObjectId = string()
214                 Object = #objref
215
216              This operation allows us to add initial services, which  can  be
217              accessed  by  using resolve_initial_references/1 or the corbaloc
218              schema. If using an Id defined by the OMG, the given object must
219              be of the correct type; for more information see the Interopera‐
220              ble Naming Service. Returns false if the given  id  already  ex‐
221              ists.
222
223       remove_initial_service(ObjectId) -> boolean()
224
225              Types:
226
227                 ObjectId = string()
228
229              If  we don not want a certain service to be accessible, invoking
230              this function will remove the association. Returns true if  able
231              to  terminate  the  binding. If no such binding existed false is
232              returned.
233
234       list_initial_services() -> [ObjectId]
235
236              Types:
237
238                 ObjectId = string()
239
240              This function returns a list of allowed object id's.
241
242       resolve_initial_references_remote(ObjectId, Address) -> Object
243       resolve_initial_references_remote(ObjectId, Address, Contexts)  ->  Ob‐
244       ject
245
246              Types:
247
248                 ObjectId = string()
249                 Address = [RemoteModifier]
250                 RemoteModifier = string()
251                 Contexts = [Context]
252                 Context  =  #'IOP_ServiceContext'{context_id  =  CtxId,  con‐
253                 text_data = CtxData}
254                 CtxId = ?ORBER_GENERIC_CTX_ID
255                 CtxData = {interface, Interface} | {userspecific,  term()}  |
256                 {configuration, Options}
257                 Interface = string()
258                 Options = [{Key, Value}]
259                 Key = ssl_client_options
260                 Value = allowed value associated with the given key
261                 Object = #objref
262
263              This  function  returns  the  object reference for the object id
264              asked for. The remote modifier string has the following  format:
265              "iiop://"<host>":"<port>  where  <host> = <DNS hostname> | <IPv4
266              address> | "["<IPv6 address>"]".
267
268              The configuration context is used to  override  the  global  SSL
269              client side configuration.
270
271          Warning:
272              This  operation  is  not  supported  by  most  ORB's. Hence, use
273              corba:string_to_object/1 instead.
274
275
276       list_initial_services_remote(Address) -> [ObjectId]
277       list_initial_services_remote(Address, Contexts) -> [ObjectId]
278
279              Types:
280
281                 Address = [RemoteModifier]
282                 RemoteModifier = string()
283                 Contexts = [Context]
284                 Context  =  #'IOP_ServiceContext'{context_id  =  CtxId,  con‐
285                 text_data = CtxData}
286                 CtxId = ?ORBER_GENERIC_CTX_ID
287                 CtxData  =  {interface, Interface} | {userspecific, term()} |
288                 {configuration, Options}
289                 Interface = string()
290                 Options = [{Key, Value}]
291                 Key = ssl_client_options
292                 Value = allowed value associated with the given key
293                 ObjectId = string()
294
295              This function returns a list of allowed object id's. The  remote
296              modifier      string      has      the     following     format:
297              "iiop://"<host>":"<port> where <host> = <DNS hostname>  |  <IPv4
298              address> | "["<IPv6 address>"]".
299
300              The  configuration  context  is  used to override the global SSL
301              client side configuration.
302
303          Warning:
304              This operation is not supported by most ORB's. Hence, avoid  us‐
305              ing it.
306
307
308       object_to_string(Object) -> IOR_string
309
310              Types:
311
312                 Object = #objref
313                 IOR_string = string()
314
315              This  function  returns  the  object  reference  as the external
316              string representation of an IOR.
317
318       string_to_object(IOR_string) -> Object
319       string_to_object(IOR_string, Contexts) -> Object
320
321              Types:
322
323                 IOR_string = string()
324                 Contexts = [Context]
325                 Context  =  #'IOP_ServiceContext'{context_id  =  CtxId,  con‐
326                 text_data = CtxData}
327                 CtxId = ?ORBER_GENERIC_CTX_ID
328                 CtxData  =  {interface, Interface} | {userspecific, term()} |
329                 {configuration, Options}
330                 Interface = string()
331                 Options = [{Key, Value}]
332                 Key = ssl_client_options
333                 Value = allowed value associated with the given key
334                 Object = #objref
335
336              This function takes a corbaname, corbaloc or an IOR on  the  ex‐
337              ternal string representation and returns the object reference.
338
339              To lookup the NameService reference, simply use:
340
341              corbaloc:iiop:1.2@123.0.0.12:4001/NameService
342
343              We can also resolve an object from the NameService by using:
344
345              corbaname:iiop:1.2@123.0.0.12:4001/NameService#org/Erlang/MyObj
346
347              To lookup the NameService reference with an IPv6 address, simply
348              use:
349
350              corbaloc:iiop:1.2@[FEC1:0:3:0:0312:44AF:FAB1:3D01]:4001/NameService
351
352              For more information  about  corbaname  and  corbaloc,  see  the
353              User's Guide (Interoperable Naming Service).
354
355              The  configuration  context  is  used to override the global SSL
356              client side configuration.
357
358              How to handle the interface context is further described in  the
359              User's Guide.
360
361       print_object(Data  [,  Type])  -> ok | {'EXCEPTION', E} | {'EXIT', R} |
362       string()
363
364              Types:
365
366                 Data = IOR_string  |  #objref  (local  or  external)  |  cor‐
367                 baloc/corbaname string
368                 Type  =  IoDevice  |  error_report | {error_report, Reason} |
369                 info_msg | {info_msg, Comment} | string
370                 IoDevice = see the io-module
371                 Reason = Comment = string()
372
373              The object represented by the supplied  data  is  dissected  and
374              presented  in  a  more  readable form. The Type parameter is op‐
375              tional; if not supplied standard output is used.  For  error_re‐
376              port and info_msg the error_logger module is used, with or with‐
377              out Reason or Comment. If the atom string is supplied this func‐
378              tion  will return a flat list. The IoDevice is passed to the op‐
379              eration io:format/2.
380
381              If the supplied object is  a  local  reference,  the  output  is
382              equivalent  to an object exported from the node this function is
383              invoked on.
384
385       add_alternate_iiop_address(Object, Host, Port) -> NewObject |  {'EXCEP‐
386       TION', E}
387
388              Types:
389
390                 Object = NewObject = local #objref
391                 Host = string()
392                 Port = integer()
393
394              This  operation  creates  a  new instance of the supplied object
395              containing an ALTERNATE_IIOP_ADDRESS component. Only the new in‐
396              stance contains the new component. When this object is passed to
397              another ORB, which supports the ALTERNATE_IIOP_ADDRESS, requests
398              will be routed to the alternate address if it is not possible to
399              communicate with the main address.
400
401              The ALTERNATE_IIOP_ADDRESS component requires that  IIOP-1.2  is
402              used. Hence, make sure both Orber and the other ORB is correctly
403              configured.
404
405          Note:
406              Make sure that the given Object is accessible via the  alternate
407              Host/port.  For  example,  if the object is correctly started as
408              local or pseudo, the object should be  available  on  all  nodes
409              within  a multi-node Orber installation. Since only one instance
410              exists for other object types, it will not be possible to access
411              it if the node it was started on terminates.
412
413
414       orb_init(KeyValueList) -> ok | {'EXIT', Reason}
415
416              Types:
417
418                 KeyValueList = [{Key, Value}]
419                 Key = any key listed in the configuration chapter
420                 Value = allowed value associated with the given key
421
422              This  function  allows the user to configure Orber in, for exam‐
423              ple, an Erlang shell. Orber may NOT be started prior to invoking
424              this operation. For more information, see configuration settings
425              in the User's Guide.
426
427
428
429Ericsson AB                       orber 5.0.2                         corba(3)
Impressum