.TH Module_Interface 3erl "orber 3.8.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
Module_Interface \- Orber generated stubs/skeletons.
.SH DESCRIPTION
.LP
This module contains the stub/skeleton functions generated by IC\&.
.LP
Starting a Orber server can be done in three ways:
.RS 2
.TP 2
*
Normal - when the server dies Orber forgets all knowledge of the server\&.
.LP
.TP 2
*
Supervisor child - adding the configuration parameter \fI{sup_child, true}\fR\& the \fIoe_create_link/2\fR\& function returns \fI{ok, Pid, ObjRef}\fR\& which can be handled by the application \fIsupervisor/stdlib-1\&.7\fR\& or later\&. 
.LP
.TP 2
*
Persistent object reference - adding the configuration parameters \fI{persistent, true}\fR\& and \fI{regname, {global, term()}}\fR\& Orber will remember the object reference until the server terminates with reason \fInormal\fR\& or \fIshutdown\fR\&\&. Hence, if the server is started as a \fItransient\fR\& supervisor child we do not receive a \&'OBJECT_NOT_EXIST\&' exception when it has crashed and is being restarted\&.
.LP
.RE

.LP
The Orber stub can be used to start a \fIpseudo object\fR\&, which will create a non-server implementation\&. A pseudo object introduce some limitations:
.RS 2
.TP 2
*
The functions \fIoe_create_link/2\fR\& is equal to \fIoe_create/2\fR\&, i\&.e\&., no link can or will be created\&.
.LP
.TP 2
*
The \fIBIF:s self()\fR\& and \fIprocess_flag(trap_exit,true)\fR\& behaves incorrectly\&.
.LP
.TP 2
*
The \fIIC\fR\& option \fI{{impl, "M::I"}, "other_impl"}\fR\& has no effect\&. The call-back functions must be implemented in a file called \fIM_I_impl\&.erl\fR\&
.LP
.TP 2
*
The \fIIC\fR\& option \fIfrom\fR\& has no effect\&. 
.LP
.TP 2
*
The call-back functions must be implemented as if the \fIIC\fR\& option \fI{this, "M::I"}\fR\& was used\&.
.LP
.TP 2
*
Server \fIState\fR\& changes have no effect\&. The user can provide information via the \fIEnv\fR\& start parameter and the State returned from \fIinit/2\fR\& will be the State passed in following invocations\&.
.LP
.TP 2
*
If a call-back function replies with the \fITimeout\fR\& parameter set it have no effect\&.
.LP
.TP 2
*
Operations defined as \fIoneway\fR\& are blocking until the operation replies\&.
.LP
.TP 2
*
The option \fI{pseudo, true}\fR\& overrides all other start options\&.
.LP
.TP 2
*
Only the functions, besides own definitions, \fIinit/2\fR\& (called via oe_create*/2) and \fIterminate/2\fR\& (called via corba:dispose/1) must be implemented\&.
.LP
.RE

.LP
By adopting the rules for \fIpseudo\fR\& objects described above we can use \fIoe_create/2\fR\& to create \fIserver\fR\& or \fIpseudo\fR\& objects, by excluding or including the option \fI{pseudo, true}\fR\&, without changing the call-back module\&.
.LP
If you start a object without \fI{regname, RegName}\fR\& it can only be accessed through the returned object key\&. Started with a \fI{regname, RegName}\fR\& the name is registered locally or globally\&.
.LP

.RS -4
.B
Warning:
.RE
To avoid flooding Orber with old object references start erlang using the flag \fI-orber objectkeys_gc_time Time\fR\&, 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 \fIinfinity\fR\&\&. For more information, see the orber and corba documentation\&.

.SH EXPORTS
.LP
.B
Module_Interface:typeID() -> TypeId
.br
.RS
.LP
Types:

.RS 3
TypeId = string(), e\&.g\&., "IDL:Module/Interface:1\&.0"
.br
.RE
.RE
.RS
.LP
Returns the Type ID related to this stub/skeleton
.RE

.LP
.B
Module_Interface:oe_create() -> ObjRef
.br
.RS
.LP
Types:

.RS 3
ObjRef = #object reference
.br
.RE
.RE
.RS
.LP
Start a Orber server\&.
.RE

.LP
.B
Module_Interface:oe_create_link() -> ObjRef
.br
.RS
.LP
Types:

.RS 3
ObjRef = #object reference
.br
.RE
.RE
.RS
.LP
Start a linked Orber server\&.
.RE

.LP
.B
Module_Interface:oe_create(Env) -> ObjRef
.br
.RS
.LP
Types:

.RS 3
Env = term()
.br
ObjRef = #object reference
.br
.RE
.RE
.RS
.LP
Start a Orber server passing Env to \fIinit/1\fR\&\&.
.RE

.LP
.B
Module_Interface:oe_create_link(Env) -> ObjRef
.br
.RS
.LP
Types:

.RS 3
Env = term()
.br
ObjRef = #object reference
.br
.RE
.RE
.RS
.LP
Start a linked Orber server passing Env to \fIinit/1\fR\&\&.
.RE

.LP
.B
Module_Interface:oe_create(Env, Options) -> ObjRef
.br
.RS
.LP
Types:

.RS 3
Env = term()
.br
ObjRef = #object reference
.br
Options = [{sup_child, false} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]
.br
Bool = true | false
.br
RegName = {global, term()} | {local, atom()}
.br
CreateOpts = {debug, [Dbg]} | {timeout, Time}
.br
Dbg = trace | log | statistics | {log_to_file, FileName}
.br
.RE
.RE
.RS
.LP
Start a Orber server passing Env to \fIinit/1\fR\&\&.
.LP
If the option \fI{pseudo, true}\fR\& is used, all other options are overridden\&. As default, this option is set to false\&.
.LP
This function cannot be used for starting a server as supervisor child\&. If started as \fIpersistent\fR\&, the options \fI[{persistent, true}, {regname, {global, term()}}]\fR\& must be used and Orber will only forget the object reference if it terminates with reason \fInormal\fR\& or \fIshutdown\fR\&\&.
.LP
The option \fI{local_typecheck, boolean()}\fR\&, which overrides the \fBLocal Typechecking\fR\& 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 \fIMAY ONLY\fR\& be used during testing and development\&.
.LP
\fI{survive_exit, boolean()}\fR\& overrides the \fBEXIT Tolerance\fR\& environment flag\&. If activated, the server will not terminate, even though the call-back module returns EXIT\&.
.LP
\fITime\fR\& specifies how long time, in milliseconds, the server is allowed to spend initializing\&. For more information about the \fIDbg\fR\& options, see the \fIsys\fR\& module\&.
.RE

.LP
.B
Module_Interface:oe_create_link(Env, Options) -> Return
.br
.RS
.LP
Types:

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

.br

.br

.br
.RE
.RE
.RS
.LP
Start a linked Orber server passing Env to \fIinit/1\fR\&\&.
.LP
If the option \fI{pseudo, true}\fR\& is used, all other options are overridden and no link will be created\&. As default, this option is set to false\&.
.LP
This function can be used for starting a server as persistent or supervisor child\&. At the moment \fI[{persistent, true}, {regname, {global, term()}}]\fR\& 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 \fI\&'OBJECT_NOT_EXIST\&'\fR\& exception\&. Orber will only forget the object reference if it terminates with reason \fInormal\fR\& or \fIshutdown\fR\&, hence, the server must be started as \fItransient\fR\& (for more information see the supervisor documentation)\&.
.LP
The options \fI{local_typecheck, boolean()}\fR\& and \fI{survive_exit, boolean()}\fR\& behaves in the same way as for \fIoe_create/2\fR\&\&.
.LP
\fITime\fR\& specifies how long time, in milliseconds, the server is allowed to spend initializing\&. For more information about the \fIDbg\fR\& options, see the \fIsys\fR\& module\&.
.RE

.LP
.B
Module_Interface:own_functions(ObjRef, Arg1, \&.\&.\&., ArgN) -> Reply
.br
.B
Module_Interface:own_functions(ObjRef, Options, Arg1, \&.\&.\&., ArgN) -> Reply
.br
.RS
.LP
Types:

.RS 3
ObjRef = #object reference
.br
Options = [Option] | Timeout
.br
Option = {timeout, Timeout} | {context, [Context]}
.br
Timeout = infinity | integer(milliseconds)
.br
Context = #\&'IOP_ServiceContext\&'{context_id = CtxId, context_data = CtxData}
.br
CtxId = ?ORBER_GENERIC_CTX_ID
.br
CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}
.br
Interface = string()
.br
Options = [{Key, Value}]
.br
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
.br
Value = allowed value associated with the given key
.br
ArgX = specified in the IDL-code\&.
.br
Reply = specified in the IDL-code\&.
.br
.RE
.RE
.RS
.LP
The default value for the \fITimeout\fR\& option is \fIinfinity\fR\&\&. IPv4 or IPv6 addresses are accepted as local Interface\&.
.LP
The \fIconfiguration\fR\& context is used to override the global SSL client side \fBconfiguration\fR\&\&.
.LP
To gain access to \fI#\&'IOP_ServiceContext\&'{}\fR\& record and the \fI?ORBER_GENERIC_CTX_ID\fR\& macro, you must add \fI-include_lib("orber/include/corba\&.hrl")\&.\fR\& to your module\&.
.RE

.SH "CALLBACK FUNCTIONS"

.LP
The following functions should be exported from a \fICORBA\fR\& callback module\&. Note, a complete template of the call-back module can be generated automatically by compiling the IDL-file with the IC option \fI{be,erl_template}\fR\&\&. One should also add the same compile options, for example \fIthis\fR\& or \fIfrom\fR\&, used when generating the stub/skeleton modules\&.
.SH EXPORTS
.LP
.B
Module_Interface_impl:init(Env) -> CallReply
.br
.RS
.LP
Types:

.RS 3
Env = term()
.br
CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}
.br
State = term()
.br
Timeout = int() >= 0 | infinity
.br
StopReason = term()
.br
.RE
.RE
.RS
.LP
Whenever a new server is started, \fIinit/1\fR\& is the first function called in the specified call-back module\&.
.RE

.LP
.B
Module_Interface_impl:terminate(Reason, State) -> ok
.br
.RS
.LP
Types:

.RS 3
Reason = term()
.br
State = term()
.br
.RE
.RE
.RS
.LP
This call-back function is called whenever the server is about to terminate\&.
.RE

.LP
.B
Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply
.br
.RS
.LP
Types:

.RS 3
OldVsn = undefined | term()
.br
State = term()
.br
Extra = term()
.br
CallReply = {ok, NewState}
.br
NewState = term()
.br
.RE
.RE
.RS
.LP
Update the internal \fIState\fR\&\&.
.RE

.LP
.B
Module_Interface_impl:handle_info(Info, State) -> CallReply
.br
.RS
.LP
Types:

.RS 3
Info = term()
.br
State = term()
.br
CallReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}
.br
Timeout = int() >= 0 | infinity
.br
StopReason = normal | shutdown | term()
.br
.RE
.RE
.RS
.LP
If the configuration parameter \fI{{handle_info, "Module::Interface"}, true}\fR\& is passed to IC and \fIprocess_flag(trap_exit,true)\fR\& is set in the \fIinit()\fR\& call-back this function must be exported\&.
.LP

.RS -4
.B
Note:
.RE
To be able to handle the \fITimeout\fR\& option in \fICallReply\fR\& in the call-back module the configuration parameter \fI{{handle_info, "Module::Interface"}, true}\fR\& must be passed to IC\&.

.RE

.LP
.B
Module_Interface_impl:own_functions(State, Arg1, \&.\&.\&., ArgN) -> CallReply
.br
.B
Module_Interface_impl:own_functions(This, State, Arg1, \&.\&.\&., ArgN) -> CallReply
.br
.B
Module_Interface_impl:own_functions(This, From, State, Arg1, \&.\&.\&., ArgN) -> ExtCallReply
.br
.B
Module_Interface_impl:own_functions(From, State, Arg1, \&.\&.\&., ArgN) -> ExtCallReply
.br
.RS
.LP
Types:

.RS 3
This = the servers #object reference
.br
State = term()
.br
ArgX = specified in the IDL-code\&.
.br
CallReply = {reply, Reply, State} | {reply, Reply, State, Timeout} | {stop, StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)
.br
ExtCallReply = CallReply | corba:reply(From, Reply), {noreply, State} | corba:reply(From, Reply), {noreply, State, Timeout}
.br
Reply = specified in the IDL-code\&.
.br
Timeout = int() >= 0 | infinity
.br
StopReason = normal | shutdown | term()
.br
.RE
.RE
.RS
.LP
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 \fIthis\fR\& and/or \fIfrom\fR\& are used, the implementation must accept the \fIThis\fR\& and/or \fIFrom\fR\& parameters\&.
.RE

.LP
.B
Module_Interface_impl:own_functions(State, Arg1, \&.\&.\&., ArgN) -> CastReply
.br
.B
Module_Interface_impl:own_functions(This, State, Arg1, \&.\&.\&., ArgN) -> CastReply
.br
.RS
.LP
Types:

.RS 3
This = the servers #object reference
.br
State = term()
.br
CastReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}
.br
ArgX = specified in the IDL-code\&.
.br
Reply = specified in the IDL-code\&.
.br
Timeout = int() >= 0 | infinity
.br
StopReason = normal | shutdown | term()
.br
.RE
.RE
.RS
.LP
All one-way functions must return one of the listed replies\&. If the IC compile option \fIthis\fR\& is used, the implementation must accept the \fIThis\fR\& parameter\&.
.RE