---
name: "Module_Interface"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:19.2.1+dfsg-2+deb9u3"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/Module_Interface"
---

# Module\_Interface(3erl)

Orber generated stubs/skeletons.

## 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.