.TH interceptors 3 "orber  3.6.9" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
interceptors \- Describe the functions which must be exported by any supplied Orber native interceptor\&.
.SH DESCRIPTION
.LP
This module contains the mandatory functions for user supplied native interceptors and their intended behavior\&. See also the User\&'s Guide\&.
.SS Warning:
.LP
Using \fIInterceptors\fR may reduce the through-put significantly if the supplied interceptors invoke expensive operations\&. Hence, one should always supply interceptors which cause as little overhead as possible\&.

.SS Warning:
.LP
It is possible to alter the \fIData\fR, \fIBin\fR and \fIArgs\fR parameter for the \fIin_reply\fR and \fIout_reply\fR, \fIin_reply_encoded\fR, \fIin_request_encoded\fR, \fIout_reply_encoded\fR and \fIout_request_encoded\fR, \fIin_request\fR and \fIout_request\fR respectively\&. But, if it is done incorrectly, the consequences can be serious\&.

.SS Note:
.LP
The \fIExtra\fR parameter is set to \&'undefined\&' by Orber when calling the first interceptor and may be set to any Erlang term\&. If an interceptor change this parameter it will be passed on to the next interceptor in the list uninterpreted\&.

.SS Note:
.LP
The \fIRef\fR parameter is set to \&'undefined\&' by Orber when calling \fInew_in_connection\fR or \fInew_out_connection\fR using the first interceptor\&. The user supplied interceptor may set \fINewRef\fR to any Erlang term\&. If an interceptor change this parameter it will be passed on to the next interceptor in the list uninterpreted\&.


.SH EXPORTS
.LP
.B
new_in_connection(Ref, PeerHost, PeerPort) -> NewRef
.br
.B
new_in_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef
.br
.RS
.TP
Types
Ref = term() | undefined
.br
PeerHost = SocketHost = string(), e\&.g\&., "myHost@myServer" or "192\&.0\&.0\&.10"
.br
PeerPort = SocketPort = integer()
.br
NewRef = term() | {\&'EXIT\&', Reason}
.br
.RE
.RS
.LP
When a new connection is requested by a client side ORB this operation is invoked\&. If more than one interceptor is supplied, e\&.g\&., \fI{native, [\&'myInterceptor1\&', \&'myInterceptor2\&']}\fR, the return value from \&'myInterceptor1\&' is passed to \&'myInterceptor2\&' as \fIRef\fR\&. Initially, Orber uses the atom \&'undefined\&' as \fIRef\fR parameter when calling the first interceptor\&. The return value from the last interceptor, in the example above \&'myInterceptor2\&', is passed to all other functions exported by the interceptors\&. Hence, the \fIRef\fR parameter can, for example, be used as a unique identifier to mnesia or ets where information/restrictions for this connection is stored\&.
.LP
The PeerHost and PeerPort variables supplied data of the client ORB which requested a new connection\&. SocketHost and SocketPort are the local interface and port the client connected to\&.
.LP
If, for some reason, we do not allow the client ORB to connect simply invoke \fIexit(Reason)\fR\&.
.RE
.LP
.B
new_out_connection(Ref, PeerHost, PeerPort) -> NewRef
.br
.B
new_out_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef
.br
.RS
.TP
Types
Ref = term() | undefined
.br
PeerHost = SocketHost = string(), e\&.g\&., "myHost@myServer" or "192\&.0\&.0\&.10"
.br
PeerPort = SocketPort = integer()
.br
NewRef = term() | {\&'EXIT\&', Reason}
.br
.RE
.RS
.LP
When a new connection is set up this function is invoked\&. Behaves just like \fInew_in_connection\fR; the only difference is that the PeerHost and PeerPort variables identifies the target ORB\&'s bootstrap data and SocketHost and SocketPort are the local interface and port the client ORB connected via\&.
.RE
.LP
.B
closed_in_connection(Ref) -> NewRef
.br
.RS
.TP
Types
Ref = term()
.br
NewRef = term()
.br
.RE
.RS
.LP
When an existing connection is terminated this operation is invoked\&. The main purpose of this function is to make it possible for a user to clean up all data associated with the associated connection\&.
.LP
The input parameter \fIRef\fR is the return value from \fInew_in_connection/3\fR\&.
.RE
.LP
.B
closed_out_connection(Ref) -> NewRef
.br
.RS
.TP
Types
Ref = term()
.br
NewRef = term()
.br
.RE
.RS
.LP
When an existing connection is terminated this operation is invoked\&. The main purpose of this function is to make it possible for a user to clean up all data associated with the associated connection\&.
.LP
The input parameter \fIRef\fR is the return value from \fInew_out_connection/3\fR\&.
.RE
.LP
.B
in_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Data = [Result, OutParameter1, \&.\&.\&., OutPramaterN]
.br
Reply = {NewData, NewExtra}
.br
.RE
.RS
.LP
When replies are delivered from the server side ORB to the client side ORB this operation is invoked\&. The \fIData\fR parameter is a list in which the first element is the return value value from the target object and the rest is a all parameters defined as \fIout\fR or \fIinout\fR in the IDL-specification\&.
.RE
.LP
.B
in_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Bin = #binary
.br
Reply = {NewBin, NewExtra}
.br
.RE
.RS
.LP
When replies are delivered from the server side ORB to the client side ORB this operation is invoked\&. The \fIBin\fR parameter is the reply body still uncoded\&.
.RE
.LP
.B
in_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Args = [Argument] - defined in the IDL-specification
.br
Reply = {NewArgs, NewExtra}
.br
.RE
.RS
.LP
When a new request arrives at the server side ORB this operation is invoked\&.
.RE
.LP
.B
in_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Bin = #binary
.br
Reply = {NewBin, NewExtra}
.br
.RE
.RS
.LP
When a new request arrives at the server side ORB this operation is invoked before decoding the request body\&.
.RE
.LP
.B
out_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Data = [Result, OutParameter1, \&.\&.\&., OutPramaterN]
.br
Reply = {NewData, NewExtra}
.br
.RE
.RS
.LP
After the target object have been invoked this operation is invoked with the result\&. The \fIData\fR parameter is a list in which the first element is the return value value from the target object and the rest is a all parameters defined as \fIout\fR or \fIinout\fR in the IDL-specification\&.
.RE
.LP
.B
out_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Bin = #binary
.br
Reply = {NewBin, NewExtra}
.br
.RE
.RS
.LP
This operation is similar to \fIout_reply\fR; the only difference is that the reply body have been encoded\&.
.RE
.LP
.B
out_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Args = [Argument] - defined in the IDL-specification
.br
Reply = {NewArgs, NewExtra}
.br
.RE
.RS
.LP
Before a request is sent to the server side ORB, \fIout_request\fR is invoked\&.
.RE
.LP
.B
out_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
.br
.RS
.TP
Types
Ref = term()
.br
Obj = #objref
.br
Ctx = [#\&'IOP_ServiceContext\&'{}]
.br
Op = atom()
.br
Bin = #binary
.br
Reply = {NewBin, NewExtra}
.br
.RE
.RS
.LP
This operation is similar to \fIout_request\fR; the only difference is that the request body have been encoded\&.
.RE