diff options
Diffstat (limited to 'lib/orber/doc/src/Module_Interface.xml')
| -rw-r--r-- | lib/orber/doc/src/Module_Interface.xml | 356 |
1 files changed, 0 insertions, 356 deletions
diff --git a/lib/orber/doc/src/Module_Interface.xml b/lib/orber/doc/src/Module_Interface.xml deleted file mode 100644 index a809bcf02f..0000000000 --- a/lib/orber/doc/src/Module_Interface.xml +++ /dev/null @@ -1,356 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>1999</year> - <year>2016</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. - - The Initial Developer of the Original Code is Ericsson AB. - </legalnotice> - - <title>Module_Interface</title> - <prepared></prepared> - <docno></docno> - <checked></checked> - <date>1999-09-03</date> - <rev>A</rev> - </header> - <module>Module_Interface</module> - <modulesummary>Orber generated stubs/skeletons.</modulesummary> - <description> - <p>This module contains the stub/skeleton functions generated by IC.</p> - <p>Starting a Orber server can be done in three ways:</p> - <list type="bulleted"> - <item>Normal - when the server dies Orber forgets all knowledge of the server.</item> - <item>Supervisor child - adding the configuration parameter <c>{sup_child, true}</c> - the <c>oe_create_link/2</c> function returns <c>{ok, Pid, ObjRef}</c> which - can be handled by the application <em>supervisor/stdlib-1.7</em> or later. </item> - <item>Persistent object reference - adding the configuration parameters <c>{persistent, true}</c> - and <c>{regname, {global, term()}}</c> Orber will remember the object reference until the - server terminates with reason <em>normal</em> or <em>shutdown</em>. Hence, - if the server is started as a <em>transient</em> supervisor child we do not - receive a 'OBJECT_NOT_EXIST' exception when it has crashed and is being restarted.</item> - </list> - <p>The Orber stub can be used to start a <c>pseudo object</c>, which will create a non-server implementation. - A pseudo object introduce some limitations:</p> - <list type="bulleted"> - <item>The functions <c>oe_create_link/2</c> is equal to <c>oe_create/2</c>, i.e., - no link can or will be created.</item> - <item>The <c>BIF:s self()</c> and <c>process_flag(trap_exit,true)</c> behaves incorrectly.</item> - <item>The <c>IC</c> option <c>{{impl, "M::I"}, "other_impl"}</c> has no effect. The call-back - functions must be implemented in a file called <c>M_I_impl.erl</c></item> - <item>The <c>IC</c> option <c>from</c> has no effect. </item> - <item>The call-back functions must be implemented as if the <c>IC</c> option - <c>{this, "M::I"}</c> was used.</item> - <item>Server <c>State</c> changes have no effect. The user can provide information via - the <c>Env</c> start parameter and the State returned from <c>init/2</c> will be the State - passed in following invocations.</item> - <item>If a call-back function replies with the <c>Timeout</c> parameter set it have no effect.</item> - <item>Operations defined as <c>oneway</c> are blocking until the operation replies.</item> - <item>The option <c>{pseudo, true}</c> overrides all other start options.</item> - <item>Only the functions, besides own definitions, <c>init/2</c> (called via oe_create*/2) and - <c>terminate/2</c> (called via corba:dispose/1) must be implemented.</item> - </list> - <p>By adopting the rules for <c>pseudo</c> objects described above we can use <c>oe_create/2</c> - to create <c>server</c> or <c>pseudo</c> objects, by excluding or including the - option <c>{pseudo, true}</c>, without changing the call-back module. - </p> - <p>If you start a object without <c>{regname, RegName}</c> it can only be accessed through the returned object key. - Started with a <c>{regname, RegName}</c> the name is registered locally or globally. - </p> - <warning> - <p>To avoid flooding Orber with old object references start erlang using the flag - <em>-orber objectkeys_gc_time Time</em>, which will remove all object references - related to servers being dead for Time seconds. To avoid extra overhead, i.e., performing - garbage collect if no persistent objects are started, the objectkeys_gc_time default value - is <em>infinity</em>. For more information, see the orber and corba documentation.</p> - </warning> - </description> - <funcs> - <func> - <name>Module_Interface:typeID() -> TypeId</name> - <fsummary>Return the Type ID related to this stub/skeleton</fsummary> - <type> - <v>TypeId = string(), e.g., "IDL:Module/Interface:1.0"</v> - </type> - <desc> - <p>Returns the Type ID related to this stub/skeleton</p> - </desc> - </func> - <func> - <name>Module_Interface:oe_create() -> ObjRef</name> - <fsummary>Start a Orber server.</fsummary> - <type> - <v>ObjRef = #object reference</v> - </type> - <desc> - <p>Start a Orber server.</p> - </desc> - </func> - <func> - <name>Module_Interface:oe_create_link() -> ObjRef</name> - <fsummary>Start a linked Orber server.</fsummary> - <type> - <v>ObjRef = #object reference</v> - </type> - <desc> - <p>Start a linked Orber server.</p> - </desc> - </func> - <func> - <name>Module_Interface:oe_create(Env) -> ObjRef</name> - <fsummary>Start a Orber server.</fsummary> - <type> - <v>Env = term()</v> - <v>ObjRef = #object reference</v> - </type> - <desc> - <p>Start a Orber server passing Env to <c>init/1</c>.</p> - </desc> - </func> - <func> - <name>Module_Interface:oe_create_link(Env) -> ObjRef</name> - <fsummary>Start a linked Orber server.</fsummary> - <type> - <v>Env = term()</v> - <v>ObjRef = #object reference</v> - </type> - <desc> - <p>Start a linked Orber server passing Env to <c>init/1</c>.</p> - </desc> - </func> - <func> - <name>Module_Interface:oe_create(Env, Options) -> ObjRef</name> - <fsummary>Start a Orber stub/skeleton</fsummary> - <type> - <v>Env = term()</v> - <v>ObjRef = #object reference</v> - <v>Options = [{sup_child, false} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]</v> - <v>Bool = true | false</v> - <v>RegName = {global, term()} | {local, atom()}</v> - <v>CreateOpts = {debug, [Dbg]} | {timeout, Time}</v> - <v>Dbg = trace | log | statistics | {log_to_file, FileName}</v> - </type> - <desc> - <p>Start a Orber server passing Env to <c>init/1</c>.</p> - <p>If the option <c>{pseudo, true}</c> is used, all other options are overridden. - As default, this option is set to false.</p> - <p>This function cannot be used for starting a server as supervisor child. - If started as <c>persistent</c>, the options <c>[{persistent, true}, {regname, {global, term()}}]</c> must be used and - Orber will only forget the object reference if it terminates with reason <em>normal</em> or <em>shutdown</em>.</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> - <p><c>{survive_exit, boolean()}</c> overrides the - <seealso marker="ch_install#flags">EXIT Tolerance</seealso> - environment flag. If activated, the server will not terminate, even though - the call-back module returns EXIT.</p> - <p><c>Time</c> specifies how long time, in milliseconds, the server is allowed to - spend initializing. For more information about the <c>Dbg</c> options, - see the <c>sys</c> module.</p> - </desc> - </func> - <func> - <name>Module_Interface:oe_create_link(Env, Options) -> Return</name> - <fsummary>Start a Orber stub/skeleton</fsummary> - <type> - <v>Env = term()</v> - <v>Return = ObjRef | {ok, Pid, ObjRef}</v> - <v>ObjRef = #object reference</v> - <v>Options = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]</v> - <v>Bool = true | false</v> - <v>RegName = {global, term()} | {local, atom()}</v> - <v>CreateOpts = {debug, [Dbg]} | {timeout, Time}</v> - <v>Dbg = trace | log | statistics | {log_to_file, FileName}</v> - <v></v> - <v></v> - <v></v> - </type> - <desc> - <p>Start a linked Orber server passing Env to <c>init/1</c>.</p> - <p>If the option <c>{pseudo, true}</c> is used, all other options are overridden and no link will be created. - As default, this option is set to false.</p> - <p>This function can be used for starting a server as persistent or supervisor child. At the moment - <c>[{persistent, true}, {regname, {global, term()}}]</c> must be used to start - a server as persistent, i.e., if a server died and is in the process of being restarted - a call to the server will not raise <c>'OBJECT_NOT_EXIST'</c> exception. - Orber will only forget the object reference if it terminates with reason <em>normal</em> or <em>shutdown</em>, - hence, the server must be started as <em>transient</em> (for more information see the - supervisor documentation).</p> - <p>The options <c>{local_typecheck, boolean()}</c> and <c>{survive_exit, boolean()}</c> - behaves in the same way as for <c>oe_create/2</c>.</p> - <p><c>Time</c> specifies how long time, in milliseconds, the server is allowed to - spend initializing. For more information about the <c>Dbg</c> options, - see the <c>sys</c> module.</p> - </desc> - </func> - <func> - <name>Module_Interface:own_functions(ObjRef, Arg1, ..., ArgN) -> Reply</name> - <name>Module_Interface:own_functions(ObjRef, Options, Arg1, ..., ArgN) -> Reply</name> - <fsummary>User defined function which is not a part of Orber</fsummary> - <type> - <v>ObjRef = #object reference</v> - <v>Options = [Option] | Timeout</v> - <v>Option = {timeout, Timeout} | {context, [Context]}</v> - <v>Timeout = infinity | integer(milliseconds)</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_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile | - ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout</v> - <v>Value = allowed value associated with the given key</v> - <v>ArgX = specified in the IDL-code.</v> - <v>Reply = specified in the IDL-code.</v> - </type> - <desc> - <p>The default value for the <c>Timeout</c> option is <c>infinity</c>. - IPv4 or IPv6 addresses are accepted as local Interface.</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>To gain access to <c>#'IOP_ServiceContext'{}</c> record and the - <c>?ORBER_GENERIC_CTX_ID</c> macro, you must add - <c>-include_lib("orber/include/corba.hrl").</c> to your module.</p> - </desc> - </func> - </funcs> - - <section> - <title>CALLBACK FUNCTIONS</title> - <p>The following functions should be exported from a <c>CORBA</c> - callback module. Note, a complete template of the call-back module can - be generated automatically by compiling the IDL-file with the IC option - <c>{be,erl_template}</c>. One should also add - the same compile options, for example <c>this</c> or <c>from</c>, - used when generating the stub/skeleton modules.</p> - </section> - <funcs> - <func> - <name>Module_Interface_impl:init(Env) -> CallReply</name> - <fsummary>User defined function which is not a part of Orber</fsummary> - <type> - <v>Env = term()</v> - <v>CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}</v> - <v>State = term()</v> - <v>Timeout = int() >= 0 | infinity</v> - <v>StopReason = term()</v> - </type> - <desc> - <p>Whenever a new server is started, <em>init/1</em> is the first function called in the specified call-back module.</p> - </desc> - </func> - <func> - <name>Module_Interface_impl:terminate(Reason, State) -> ok</name> - <fsummary>User defined function which is not a part of Orber</fsummary> - <type> - <v>Reason = term()</v> - <v>State = term()</v> - </type> - <desc> - <p>This call-back function is called whenever the server is about to terminate.</p> - </desc> - </func> - <func> - <name>Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply</name> - <fsummary>User defined function which is not a part of Orber</fsummary> - <type> - <v>OldVsn = undefined | term()</v> - <v>State = term()</v> - <v>Extra = term()</v> - <v>CallReply = {ok, NewState}</v> - <v>NewState = term()</v> - </type> - <desc> - <p>Update the internal <c>State</c>.</p> - </desc> - </func> - <func> - <name>Module_Interface_impl:handle_info(Info, State) -> CallReply</name> - <fsummary>User defined function which is not a part of Orber</fsummary> - <type> - <v>Info = term()</v> - <v>State = term()</v> - <v>CallReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}</v> - <v>Timeout = int() >= 0 | infinity</v> - <v>StopReason = normal | shutdown | term()</v> - </type> - <desc> - <p>If the configuration parameter <em>{{handle_info, "Module::Interface"}, true}</em> - is passed to IC and <em>process_flag(trap_exit,true)</em> is set in the <em>init()</em> - call-back this function must be exported. </p> - <note> - <p>To be able to handle the <c>Timeout</c> option in <c>CallReply</c> in the call-back - module the configuration parameter <em>{{handle_info, "Module::Interface"}, true}</em> must - be passed to IC. </p> - </note> - </desc> - </func> - <func> - <name>Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CallReply</name> - <name>Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CallReply</name> - <name>Module_Interface_impl:own_functions(This, From, State, Arg1, ..., ArgN) -> ExtCallReply</name> - <name>Module_Interface_impl:own_functions(From, State, Arg1, ..., ArgN) -> ExtCallReply</name> - <fsummary>User defined function which is not a part of Orber</fsummary> - <type> - <v>This = the servers #object reference</v> - <v>State = term()</v> - <v>ArgX = specified in the IDL-code.</v> - <v>CallReply = {reply, Reply, State} | {reply, Reply, State, Timeout} | {stop, StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)</v> - <v>ExtCallReply = CallReply | corba:reply(From, Reply), {noreply, State} | corba:reply(From, Reply), {noreply, State, Timeout}</v> - <v>Reply = specified in the IDL-code.</v> - <v>Timeout = int() >= 0 | infinity</v> - <v>StopReason = normal | shutdown | term()</v> - </type> - <desc> - <p>All two-way functions must return one of the listed replies or raise any of - the exceptions listed in the IDL code (i.e. raises(...)). - If the IC compile options <em>this</em> and/or <em>from</em> are used, - the implementation must accept the <em>This</em> and/or <em>From</em> - parameters.</p> - </desc> - </func> - <func> - <name>Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CastReply</name> - <name>Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CastReply</name> - <fsummary>User defined function which is not a part of Orber</fsummary> - <type> - <v>This = the servers #object reference</v> - <v>State = term()</v> - <v>CastReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}</v> - <v>ArgX = specified in the IDL-code.</v> - <v>Reply = specified in the IDL-code.</v> - <v>Timeout = int() >= 0 | infinity</v> - <v>StopReason = normal | shutdown | term()</v> - </type> - <desc> - <p>All one-way functions must return one of the listed replies. - If the IC compile option <em>this</em> is used, - the implementation must accept the <em>This</em> parameter.</p> - </desc> - </func> - </funcs> - -</erlref> - |