Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all bug

NAME

       Module_Interface - Orber generated stubs/skeletons.

DESCRIPTION

       This module contains the stub/skeleton functions generated by IC.

       Starting a Orber server can be done in three ways:

         * Normal - when the server dies Orber forgets all knowledge of the server.

         * Supervisor   child   -  adding  the  configuration  parameter  {sup_child,  true}  the
           oe_create_link/2 function returns {ok, Pid,  ObjRef}  which  can  be  handled  by  the
           application supervisor/stdlib-1.7 or later.

         * Persistent  object  reference - adding the configuration parameters {persistent, true}
           and {regname, {global, term()}} Orber will remember the  object  reference  until  the
           server terminates with reason normal or shutdown. Hence, if the server is started as a
           transient supervisor child we do not receive a 'OBJECT_NOT_EXIST'  exception  when  it
           has crashed and is being restarted.

       The  Orber  stub  can  be  used  to  start a pseudo object, which will create a non-server
       implementation. A pseudo object introduce some limitations:

         * The functions oe_create_link/2 is equal to oe_create/2, i.e., no link can or  will  be
           created.

         * The BIF:s self() and process_flag(trap_exit,true) behaves incorrectly.

         * The  IC  option  {{impl, "M::I"}, "other_impl"} has no effect. The call-back functions
           must be implemented in a file called M_I_impl.erl

         * The IC option from has no effect.

         * The call-back functions must be implemented as if the IC  option  {this,  "M::I"}  was
           used.

         * Server  State  changes  have  no  effect. The user can provide information via the Env
           start parameter and the State returned  from  init/2  will  be  the  State  passed  in
           following invocations.

         * If a call-back function replies with the Timeout parameter set it have no effect.

         * Operations defined as oneway are blocking until the operation replies.

         * The option {pseudo, true} overrides all other start options.

         * Only  the  functions,  besides  own  definitions, init/2 (called via oe_create*/2) and
           terminate/2 (called via corba:dispose/1) must be implemented.

       By adopting the rules for pseudo objects described above we can use oe_create/2 to  create
       server  or  pseudo  objects,  by excluding or including the option {pseudo, true}, without
       changing the call-back module.

       If you start a object without {regname, RegName} it  can  only  be  accessed  through  the
       returned  object  key. Started with a {regname, RegName} the name is registered locally or
       globally.

   Warning:
       To avoid flooding Orber with old object references start  erlang  using  the  flag  -orber
       objectkeys_gc_time  Time, 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 infinity. For more
       information, see the orber and corba documentation.

EXPORTS

       Module_Interface:typeID() -> TypeId

              Types:

                 TypeId = string(), e.g., "IDL:Module/Interface:1.0"

              Returns the Type ID related to this stub/skeleton

       Module_Interface:oe_create() -> ObjRef

              Types:

                 ObjRef = #object reference

              Start a Orber server.

       Module_Interface:oe_create_link() -> ObjRef

              Types:

                 ObjRef = #object reference

              Start a linked Orber server.

       Module_Interface:oe_create(Env) -> ObjRef

              Types:

                 Env = term()
                 ObjRef = #object reference

              Start a Orber server passing Env to init/1.

       Module_Interface:oe_create_link(Env) -> ObjRef

              Types:

                 Env = term()
                 ObjRef = #object reference

              Start a linked Orber server passing Env to init/1.

       Module_Interface:oe_create(Env, Options) -> ObjRef

              Types:

                 Env = term()
                 ObjRef = #object reference
                 Options = [{sup_child, false}  |  {persistent,  Bool}  |  {regname,  RegName}  |
                 {pseudo,   Bool}   |   {local_typecheck,   Bool}   |   {survive_exit,   Bool}  |
                 {create_options, [CreateOpts]}]
                 Bool = true | false
                 RegName = {global, term()} | {local, atom()}
                 CreateOpts = {debug, [Dbg]} | {timeout, Time}
                 Dbg = trace | log | statistics | {log_to_file, FileName}

              Start a Orber server passing Env to init/1.

              If the option {pseudo, true} is used, all other options are overridden. As default,
              this option is set to false.

              This  function cannot be used for starting a server as supervisor child. If started
              as persistent, the options [{persistent, true}, {regname, {global,  term()}}]  must
              be  used  and  Orber  will  only  forget the object reference if it terminates with
              reason normal or shutdown.

              The option {local_typecheck, boolean()}, which  overrides  the  Local  Typechecking
              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 MAY ONLY be used during testing and development.

              {survive_exit,  boolean()}  overrides  the  EXIT  Tolerance  environment  flag.  If
              activated,  the server will not terminate, even though the call-back module returns
              EXIT.

              Time specifies how long time, in milliseconds,  the  server  is  allowed  to  spend
              initializing. For more information about the Dbg options, see the sys module.

       Module_Interface:oe_create_link(Env, Options) -> Return

              Types:

                 Env = term()
                 Return = ObjRef | {ok, Pid, ObjRef}
                 ObjRef = #object reference
                 Options  =  [{sup_child,  Bool}  |  {persistent,  Bool}  |  {regname, RegName} |
                 {pseudo,  Bool}   |   {local_typecheck,   Bool}   |   {survive_exit,   Bool}   |
                 {create_options, [CreateOpts]}]
                 Bool = true | false
                 RegName = {global, term()} | {local, atom()}
                 CreateOpts = {debug, [Dbg]} | {timeout, Time}
                 Dbg = trace | log | statistics | {log_to_file, FileName}

              Start a linked Orber server passing Env to init/1.

              If  the option {pseudo, true} is used, all other options are overridden and no link
              will be created. As default, this option is set to false.

              This function can be used for starting a server as persistent or supervisor  child.
              At  the  moment  [{persistent,  true}, {regname, {global, term()}}] 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 'OBJECT_NOT_EXIST' exception. Orber
              will only forget the object reference  if  it  terminates  with  reason  normal  or
              shutdown,  hence, the server must be started as transient (for more information see
              the supervisor documentation).

              The options {local_typecheck, boolean()} and {survive_exit, boolean()}  behaves  in
              the same way as for oe_create/2.

              Time  specifies  how  long  time,  in  milliseconds, the server is allowed to spend
              initializing. For more information about the Dbg options, see the sys module.

       Module_Interface:own_functions(ObjRef, Arg1, ..., ArgN) -> Reply
       Module_Interface:own_functions(ObjRef, Options, Arg1, ..., ArgN) -> Reply

              Types:

                 ObjRef = #object reference
                 Options = [Option] | Timeout
                 Option = {timeout, Timeout} | {context, [Context]}
                 Timeout = infinity | integer(milliseconds)
                 Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}
                 CtxId = ?ORBER_GENERIC_CTX_ID
                 CtxData = {interface, Interface}  |  {userspecific,  term()}  |  {configuration,
                 Options}
                 Interface = string()
                 Options = [{Key, Value}]
                 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
                 Value = allowed value associated with the given key
                 ArgX = specified in the IDL-code.
                 Reply = specified in the IDL-code.

              The  default  value  for the Timeout option is infinity. IPv4 or IPv6 addresses are
              accepted as local Interface.

              The  configuration  context  is  used  to  override  the  global  SSL  client  side
              configuration.

              To  gain  access  to  #'IOP_ServiceContext'{}  record and the ?ORBER_GENERIC_CTX_ID
              macro, you must add -include_lib("orber/include/corba.hrl"). to your module.

CALLBACK FUNCTIONS

       The following functions should be exported from a CORBA callback module. Note, a  complete
       template  of the call-back module can be generated automatically by compiling the IDL-file
       with the IC option {be,erl_template}. One should also add the same  compile  options,  for
       example this or from, used when generating the stub/skeleton modules.

EXPORTS

       Module_Interface_impl:init(Env) -> CallReply

              Types:

                 Env = term()
                 CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}
                 State = term()
                 Timeout = int() >= 0 | infinity
                 StopReason = term()

              Whenever  a  new  server  is  started,  init/1  is the first function called in the
              specified call-back module.

       Module_Interface_impl:terminate(Reason, State) -> ok

              Types:

                 Reason = term()
                 State = term()

              This call-back function is called whenever the server is about to terminate.

       Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply

              Types:

                 OldVsn = undefined | term()
                 State = term()
                 Extra = term()
                 CallReply = {ok, NewState}
                 NewState = term()

              Update the internal State.

       Module_Interface_impl:handle_info(Info, State) -> CallReply

              Types:

                 Info = term()
                 State = term()
                 CallReply = {noreply, State} | {noreply, State, Timeout}  |  {stop,  StopReason,
                 State}
                 Timeout = int() >= 0 | infinity
                 StopReason = normal | shutdown | term()

              If the configuration parameter {{handle_info, "Module::Interface"}, true} is passed
              to IC and process_flag(trap_exit,true) is set in the init() call-back this function
              must be exported.

          Note:
              To  be  able  to handle the Timeout option in CallReply in the call-back module the
              configuration parameter {{handle_info, "Module::Interface"}, true} must  be  passed
              to IC.

       Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CallReply
       Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CallReply
       Module_Interface_impl:own_functions(This, From, State, Arg1, ..., ArgN) -> ExtCallReply
       Module_Interface_impl:own_functions(From, State, Arg1, ..., ArgN) -> ExtCallReply

              Types:

                 This = the servers #object reference
                 State = term()
                 ArgX = specified in the IDL-code.
                 CallReply  =  {reply,  Reply,  State}  | {reply, Reply, State, Timeout} | {stop,
                 StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)
                 ExtCallReply  =  CallReply  |  corba:reply(From,  Reply),  {noreply,  State}   |
                 corba:reply(From, Reply), {noreply, State, Timeout}
                 Reply = specified in the IDL-code.
                 Timeout = int() >= 0 | infinity
                 StopReason = normal | shutdown | term()

              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
              this  and/or  from  are  used,  the implementation must accept the This and/or From
              parameters.

       Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CastReply
       Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CastReply

              Types:

                 This = the servers #object reference
                 State = term()
                 CastReply = {noreply, State} | {noreply, State, Timeout}  |  {stop,  StopReason,
                 State}
                 ArgX = specified in the IDL-code.
                 Reply = specified in the IDL-code.
                 Timeout = int() >= 0 | infinity
                 StopReason = normal | shutdown | term()

              All  one-way  functions  must  return  one of the listed replies. If the IC compile
              option this is used, the implementation must accept the This parameter.