diff options
Diffstat (limited to 'lib/orber/doc/src/corba.xml')
| -rw-r--r-- | lib/orber/doc/src/corba.xml | 454 |
1 files changed, 0 insertions, 454 deletions
diff --git a/lib/orber/doc/src/corba.xml b/lib/orber/doc/src/corba.xml deleted file mode 100644 index fbfb55f2f2..0000000000 --- a/lib/orber/doc/src/corba.xml +++ /dev/null @@ -1,454 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>1997</year><year>2017</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>corba</title> - <prepared></prepared> - <responsible></responsible> - <docno></docno> - <approved></approved> - <checked></checked> - <date>1997-06-10</date> - <rev>A</rev> - </header> - <module>corba</module> - <modulesummary>The functions on CORBA module level</modulesummary> - <description> - <p>This module contains functions that are specified on the CORBA module - level. It also contains some functions for creating and disposing - objects.</p> - </description> - <funcs> - <func> - <name>create(Module, TypeID) -> Object</name> - <name>create(Module, TypeID, Env) -> Object</name> - <name>create(Module, TypeID, Env, Optons1) -> Object</name> - <name>create_link(Module, TypeID) -> Object</name> - <name>create_link(Module, TypeID, Env) -> Object</name> - <name>create_link(Module, TypeID, Env, Options2) -> Reply</name> - <fsummary>Create and start a new server object</fsummary> - <type> - <v>Module = atom()</v> - <v>TypeID = string()</v> - <v>Env = term()</v> - <v>Options1 = [{persistent, Bool} | {regname, RegName} | {local_typecheck, Bool}]</v> - <v>Options2 = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool}]</v> - <v>RegName = {local, atom()} | {global, term()}</v> - <v>Reply = #objref | {ok, Pid, #objref}</v> - <v>Bool = true | false</v> - <v>Object = #objref</v> - </type> - <desc> - <p>These functions start a new server object. If you start it - without <em>RegName</em> it can only be accessed through the - returned object key. Started with a <em>RegName</em> the name is - registered locally or globally. </p> - <p><em>TypeID</em> is the repository ID of the server object type and - could for example look like "IDL:StackModule/Stack:1.0". </p> - <p><em>Module</em> is the name of the interface API module. </p> - <p><em>Env</em> is the arguments passed which will be passed to the - implementations <em>init</em> call-back function.</p> - <p>A server started with create/2, create/3 or create/4 does not care - about the parent, which means that the parent is not handled - explicitly in the generic process part. </p> - <p>A server started with create_link2, create_link/3 or create_link/4 - is initially linked to the caller, the parent, and it will - terminate whenever the parent process terminates, and with the same - reason as the parent. If the server traps exits, the terminate/2 - call-back function is called in order to clean up before the - termination. These functions should be used if the server is a - worker in a supervision tree.</p> - <p>If you use the option <c>{sup_child, true}</c> create_link/4 will return - <c>{ok, Pid, #objref}</c>, otherwise <c>#objref</c>, and make it possible - to start a server as a supervisor child (stdlib-1.7 or later).</p> - <p>If you use the option <c>{persistent, true}</c> you also must use the option - <c>{regname, {global, Name}}</c>. This combination makes it possible to tell - the difference between a server permanently terminated or in the process of restarting.</p> - <p>The option <c>{pseudo, true}</c>, allow us to create an object which is not a - server. Using <c>{pseudo, true}</c> overrides all other start options. - For more information see section <c>Module_Interface</c>.</p> - <p>If a server is started using the option <c>{persistent, true}</c> the object key - will not be removed unless it terminates with reason <em>normal</em> or <em>shutdown</em>. - Hence, if persistent servers is used as supervisor children they should be <em>transient</em> - and the <em>objectkeys_gc_time</em> should be modified (default equals <c>infinity</c>).</p> - <p>The option <c>{local_typecheck, boolean()}</c>, which overrides the - <seealso marker="ch_install#flags">Local Typechecking</seealso> - environment flag, turns on or off typechecking. If activated, - parameters, replies and raised exceptions will be checked to ensure that - the data is correct, when invoking operations on CORBA Objects within - the same Orber domain. Due to the extra overhead, this option - <em>MAY ONLY</em> be used during testing and development.</p> - <code type="none"> -Example: - - corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", {10, test}) - </code> - </desc> - </func> - <func> - <name>dispose(Object) -> ok</name> - <fsummary>Stop a server object</fsummary> - <type> - <v>Object = #objref</v> - </type> - <desc> - <p>This function is used for terminating the execution of a - server object. Invoking this operation on a NIL object reference, - e.g., the return value of <c>corba:create_nil_objref/0</c>, always - return ok. For valid object references, invoking this operation - more than once, will result in a system exception.</p> - </desc> - </func> - <func> - <name>create_nil_objref() -> Object</name> - <fsummary>Stop a server object</fsummary> - <type> - <v>Object = #objref representing NIL.</v> - </type> - <desc> - <p>Creates an object reference that represents the NIL value. - Attempts to invoke operations using the returned object reference - will return a system exception.</p> - </desc> - </func> - <func> - <name>create_subobject_key(Object, Key) -> Result</name> - <fsummary>Add an Erlang term to a private key field</fsummary> - <type> - <v>Object = #objref</v> - <v>Key = term()</v> - <v>Result = #objref</v> - </type> - <desc> - <p>This function is used to create a subobject in a server object. - It can for example be useful when one wants unique access to - separate rows in a mnesia or an ETS table. The <em>Result</em> is - an object reference that will be seen as a unique reference to - the outside world but will access the same server object where one - can use the <em>get_subobject_key/1</em> function to get the private - key value.</p> - <p><em>Key</em> is stored in the object reference <em>Object</em>. - If it is a binary it will be stored as is and otherwise it is - converted to a binary before storage.</p> - </desc> - </func> - <func> - <name>get_subobject_key(Object) -> Result</name> - <fsummary>Fetch the contents of the private key field</fsummary> - <type> - <v>Object = #objref</v> - <v>Result = #binary</v> - </type> - <desc> - <p>This function is used to fetch a subobject key from the object - reference <em>Object</em>. The result is a always a binary, if it - was an Erlang term that was stored with <em>create_subobject_key/2</em> - one can to do <em>binary_to_term/1</em> to get the real value. </p> - </desc> - </func> - <func> - <name>get_pid(Object) -> Result</name> - <fsummary>Get the process id from an object key</fsummary> - <type> - <v>Object = #objref</v> - <v>Result = #pid | {error, Reason} | {'EXCEPTION',E}</v> - </type> - <desc> - <p>This function is to get the process id from an object, which is a - must when CORBA objects is started/handled in a supervisor tree. - The function will throw exceptions if the key is not found or - some other error occurs.</p> - </desc> - </func> - <func> - <name>raise(Exception)</name> - <fsummary>Generate an Erlang throw</fsummary> - <type> - <v>Exception = record()</v> - </type> - <desc> - <p>This function is used for raising corba exceptions as an - Erlang user generated exit signal. It will throw the tuple - <c>{'EXCEPTION', </c><em>Exception</em><c>}</c>.</p> - </desc> - </func> - <func> - <name>reply(To, Reply) -> true</name> - <fsummary>Send explicit reply to client</fsummary> - <type> - <v>To = client reference</v> - <v>Reply = IDL type</v> - </type> - <desc> - <p>This function can be used by a CORBA object to explicitly send - a reply to a client that invoked a two-way operation. If this operation - is used, it is <em>not</em> possible to return a reply in the call-back - module. - <br></br> -<em>To</em> must be the <em>From</em> argument provided to the - callback function, which requires that the IC option <em>from</em> - was used when compiling the IDL-file.</p> - </desc> - </func> - <func> - <name>resolve_initial_references(ObjectId) -> Object</name> - <name>resolve_initial_references(ObjectId, Contexts) -> Object</name> - <fsummary>Return the object reference for the given object id</fsummary> - <type> - <v>ObjectId = string()</v> - <v>Contexts = [Context]</v> - <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v> - <v>CtxId = ?ORBER_GENERIC_CTX_ID</v> - <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v> - <v>Interface = string()</v> - <v>Options = [{Key, Value}]</v> - <v>Key = ssl_client_options</v> - <v>Value = allowed value associated with the given key</v> - <v>Object = #objref</v> - </type> - <desc> - <p>This function returns the object reference associated with the given - object id. Initially, only <c>"NameService"</c> is available. To add or remove - services use <c>add_initial_service/2</c> or <c>remove_initial_service/1</c>.</p> - <p>The <em>configuration</em> context is used to override the global - SSL client side - <seealso marker="ch_install#config">configuration</seealso>.</p> - </desc> - </func> - <func> - <name>add_initial_service(ObjectId, Object) -> boolean()</name> - <fsummary>Add a new initial service and associate it with the given id</fsummary> - <type> - <v>ObjectId = string()</v> - <v>Object = #objref</v> - </type> - <desc> - <p>This operation allows us to add initial services, which can be accessed by - using <c>resolve_initial_references/1</c> or the <c>corbaloc</c> schema. - If using an Id defined by the OMG, the given object must be of the - correct type; for more information see the - <seealso marker="ch_naming_service#interop_ns">Interoperable Naming Service</seealso>. - Returns <c>false</c> if the given id already exists.</p> - </desc> - </func> - <func> - <name>remove_initial_service(ObjectId) -> boolean()</name> - <fsummary>Remove association between the given id and service</fsummary> - <type> - <v>ObjectId = string()</v> - </type> - <desc> - <p>If we don not want a certain service to be accessible, invoking this function - will remove the association. Returns <c>true</c> if able to terminate the - binding. If no such binding existed <c>false</c> is returned.</p> - </desc> - </func> - <func> - <name>list_initial_services() -> [ObjectId]</name> - <fsummary>Return a list of supported object id's</fsummary> - <type> - <v>ObjectId = string()</v> - </type> - <desc> - <p>This function returns a list of allowed object id's.</p> - </desc> - </func> - <func> - <name>resolve_initial_references_remote(ObjectId, Address) -> Object</name> - <name>resolve_initial_references_remote(ObjectId, Address, Contexts) -> Object</name> - <fsummary>Return the object reference for the given object id</fsummary> - <type> - <v>ObjectId = string()</v> - <v>Address = [RemoteModifier]</v> - <v>RemoteModifier = string()</v> - <v>Contexts = [Context]</v> - <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v> - <v>CtxId = ?ORBER_GENERIC_CTX_ID</v> - <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v> - <v>Interface = string()</v> - <v>Options = [{Key, Value}]</v> - <v>Key = ssl_client_options</v> - <v>Value = allowed value associated with the given key</v> - <v>Object = #objref</v> - </type> - <desc> - <p>This function returns the object reference for the object id asked - for. - The remote modifier string has the following format: - <c>"iiop://"<host>":"<port></c> where <c><host> = <DNS hostname> | - <IPv4 address> | "["<IPv6 address>"]"</c>. - </p> - <p>The <em>configuration</em> context is used to override the global - SSL client side - <seealso marker="ch_install#config">configuration</seealso>.</p> - <warning> - <p>This operation is not supported by most ORB's. Hence, use - <c>corba:string_to_object/1</c> instead.</p> - </warning> - </desc> - </func> - <func> - <name>list_initial_services_remote(Address) -> [ObjectId]</name> - <name>list_initial_services_remote(Address, Contexts) -> [ObjectId]</name> - <fsummary>Return a list of supported object id's</fsummary> - <type> - <v>Address = [RemoteModifier]</v> - <v>RemoteModifier = string()</v> - <v>Contexts = [Context]</v> - <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v> - <v>CtxId = ?ORBER_GENERIC_CTX_ID</v> - <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v> - <v>Interface = string()</v> - <v>Options = [{Key, Value}]</v> - <v>Key = ssl_client_options</v> - <v>Value = allowed value associated with the given key</v> - <v>ObjectId = string()</v> - </type> - <desc> - <p>This function returns a list of allowed object id's. - The remote modifier string has the following format: - <c>"iiop://"<host>":"<port></c> where <c><host> = <DNS hostname> | - <IPv4 address> | "["<IPv6 address>"]"</c>. - </p> - <p>The <em>configuration</em> context is used to override the global - SSL client side - <seealso marker="ch_install#config">configuration</seealso>.</p> - <warning> - <p>This operation is not supported by most ORB's. Hence, avoid - using it.</p> - </warning> - </desc> - </func> - <func> - <name>object_to_string(Object) -> IOR_string</name> - <fsummary>Convert the object reference to the external string representation</fsummary> - <type> - <v>Object = #objref</v> - <v>IOR_string = string()</v> - </type> - <desc> - <p>This function returns the object reference as the external string - representation of an IOR.</p> - </desc> - </func> - <func> - <name>string_to_object(IOR_string) -> Object</name> - <name>string_to_object(IOR_string, Contexts) -> Object</name> - <fsummary>Convert the external string representation to an object reference</fsummary> - <type> - <v>IOR_string = string()</v> - <v>Contexts = [Context]</v> - <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v> - <v>CtxId = ?ORBER_GENERIC_CTX_ID</v> - <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v> - <v>Interface = string()</v> - <v>Options = [{Key, Value}]</v> - <v>Key = ssl_client_options</v> - <v>Value = allowed value associated with the given key</v> - <v>Object = #objref</v> - </type> - <desc> - <p>This function takes a <c>corbaname</c>, <c>corbaloc</c> or an IOR on the - external string representation and returns the object reference.</p> - <p>To lookup the NameService reference, simply use:</p> - <code>corbaloc:iiop:[email protected]:4001/NameService</code> - <p>We can also resolve an object from the NameService by using:</p> - <code>corbaname:iiop:[email protected]:4001/NameService#org/Erlang/MyObj</code> - <p>To lookup the NameService reference with an IPv6 address, simply use:</p> - <code>corbaloc:iiop:1.2@[FEC1:0:3:0:0312:44AF:FAB1:3D01]:4001/NameService</code> - <p>For more information about <c>corbaname</c> and <c>corbaloc</c>, see - the User's Guide (Interoperable Naming Service).</p> - <p>The <em>configuration</em> context is used to override the global - SSL client side - <seealso marker="ch_install#config">configuration</seealso>.</p> - <p>How to handle the interface context is further described in the User's Guide.</p> - </desc> - </func> - <func> - <name>print_object(Data [, Type]) -> ok | {'EXCEPTION', E} | {'EXIT', R} | string()</name> - <fsummary>Print the supplied object</fsummary> - <type> - <v>Data = IOR_string | #objref (local or external) | corbaloc/corbaname string</v> - <v>Type = IoDevice | error_report | {error_report, Reason} | info_msg | {info_msg, Comment} | string</v> - <v>IoDevice = see the io-module</v> - <v>Reason = Comment = string()</v> - </type> - <desc> - <p>The object represented by the supplied data is dissected and presented - in a more readable form. The Type parameter is optional; if not supplied - standard output is used. For <c>error_report</c> and <c>info_msg</c> - the <c>error_logger</c> module is used, with or without Reason or Comment. - If the atom <c>string</c> is supplied this function will return a flat - list. The <c>IoDevice</c> is passed to the operation <c>io:format/2</c>.</p> - <p>If the supplied object is a local reference, the output is equivalent - to an object exported from the node this function is invoked on.</p> - </desc> - </func> - <func> - <name>add_alternate_iiop_address(Object, Host, Port) -> NewObject | {'EXCEPTION', E}</name> - <fsummary>Add ALTERNATE_IIOP_ADDRESS component to the supplied local object</fsummary> - <type> - <v>Object = NewObject = local #objref</v> - <v>Host = string()</v> - <v>Port = integer()</v> - </type> - <desc> - <p>This operation creates a new instance of the supplied object - containing an ALTERNATE_IIOP_ADDRESS component. Only the new instance - contains the new component. When this object is passed to another - ORB, which supports the ALTERNATE_IIOP_ADDRESS, requests will be routed - to the alternate address if it is not possible to communicate with - the main address.</p> - <p>The ALTERNATE_IIOP_ADDRESS component requires that IIOP-1.2 is used. - Hence, make sure both Orber and the other ORB is correctly configured.</p> - <p></p> - <note> - <p>Make sure that the given <c>Object</c> is accessible via the - alternate Host/port. For example, if the object is correctly started as - <c>local</c> or <c>pseudo</c>, the object should be available on all - nodes within a multi-node Orber installation. Since only one instance - exists for other object types, it will not be possible to access it - if the node it was started on terminates.</p> - </note> - </desc> - </func> - <func> - <name>orb_init(KeyValueList) -> ok | {'EXIT', Reason}</name> - <fsummary>Configure Orber before starting it</fsummary> - <type> - <v>KeyValueList = [{Key, Value}]</v> - <v>Key = any key listed in the configuration chapter</v> - <v>Value = allowed value associated with the given key</v> - </type> - <desc> - <p>This function allows the user to configure Orber in, for example, - an Erlang shell. Orber may <em>NOT</em> be started prior to invoking - this operation. For more information, see - <seealso marker="ch_install#config">configuration settings</seealso> - in the User's Guide.</p> - </desc> - </func> - </funcs> - -</erlref> - |