1interceptors(3)            Erlang Module Definition            interceptors(3)
2
3
4

NAME

6       interceptors  -  Describe  the  functions which must be exported by any
7       supplied Orber native interceptor.
8

DESCRIPTION

10       This module contains the mandatory functions for user  supplied  native
11       interceptors and their intended behavior. See also the User's Guide.
12
13   Warning:
14       Using Interceptors may reduce the through-put significantly if the sup‐
15       plied interceptors  invoke  expensive  operations.  Hence,  one  should
16       always supply interceptors which cause as little overhead as possible.
17
18
19   Warning:
20       It  is  possible  to  alter  the  Data,  Bin and Args parameter for the
21       in_reply   and   out_reply,    in_reply_encoded,    in_request_encoded,
22       out_reply_encoded  and  out_request_encoded, in_request and out_request
23       respectively. But, if it is done incorrectly, the consequences  can  be
24       serious.
25
26
27   Note:
28       The  Extra  parameter  is  set to 'undefined' by Orber when calling the
29       first interceptor and may be set to any Erlang term. If an  interceptor
30       change  this  parameter it will be passed on to the next interceptor in
31       the list uninterpreted.
32
33
34   Note:
35       The  Ref  parameter  is  set  to  'undefined'  by  Orber  when  calling
36       new_in_connection  or  new_out_connection  using the first interceptor.
37       The user supplied interceptor may set NewRef to any Erlang term. If  an
38       interceptor  change  this  parameter  it  will be passed on to the next
39       interceptor in the list uninterpreted.
40
41

EXPORTS

43       new_in_connection(Ref, PeerHost, PeerPort) -> NewRef
44       new_in_connection(Ref, PeerHost, PeerPort, SocketHost,  SocketPort)  ->
45       NewRef
46
47              Types:
48
49                 Ref = term() | undefined
50                 PeerHost  = SocketHost = string(), e.g., "myHost@myServer" or
51                 "192.0.0.10"
52                 PeerPort = SocketPort = integer()
53                 NewRef = term() | {'EXIT', Reason}
54
55              When a new connection is requested by a  client  side  ORB  this
56              operation  is invoked. If more than one interceptor is supplied,
57              e.g., {native, ['myInterceptor1', 'myInterceptor2']}, the return
58              value  from  'myInterceptor1'  is  passed to 'myInterceptor2' as
59              Ref. Initially, Orber uses the atom 'undefined' as Ref parameter
60              when  calling  the  first interceptor. The return value from the
61              last interceptor, in  the  example  above  'myInterceptor2',  is
62              passed  to  all  other  functions  exported by the interceptors.
63              Hence, the Ref parameter can, for example, be used as  a  unique
64              identifier  to  mnesia or ets where information/restrictions for
65              this connection is stored.
66
67              The PeerHost and PeerPort variables supplied data of the  client
68              ORB  which requested a new connection. SocketHost and SocketPort
69              are the local interface and port the client connected to.
70
71              If, for some reason, we do not allow the client ORB  to  connect
72              simply invoke exit(Reason).
73
74       new_out_connection(Ref, PeerHost, PeerPort) -> NewRef
75       new_out_connection(Ref,  PeerHost, PeerPort, SocketHost, SocketPort) ->
76       NewRef
77
78              Types:
79
80                 Ref = term() | undefined
81                 PeerHost = SocketHost = string(), e.g., "myHost@myServer"  or
82                 "192.0.0.10"
83                 PeerPort = SocketPort = integer()
84                 NewRef = term() | {'EXIT', Reason}
85
86              When  a  new  connection  is  set  up  this function is invoked.
87              Behaves just like new_in_connection; the only difference is that
88              the  PeerHost and PeerPort variables identifies the target ORB's
89              bootstrap data and  SocketHost  and  SocketPort  are  the  local
90              interface and port the client ORB connected via.
91
92       closed_in_connection(Ref) -> NewRef
93
94              Types:
95
96                 Ref = term()
97                 NewRef = term()
98
99              When  an  existing  connection  is  terminated this operation is
100              invoked. The main purpose of this function is to make it  possi‐
101              ble  for a user to clean up all data associated with the associ‐
102              ated connection.
103
104              The input parameter Ref is the return value from  new_in_connec‐
105              tion/3.
106
107       closed_out_connection(Ref) -> NewRef
108
109              Types:
110
111                 Ref = term()
112                 NewRef = term()
113
114              When  an  existing  connection  is  terminated this operation is
115              invoked. The main purpose of this function is to make it  possi‐
116              ble  for a user to clean up all data associated with the associ‐
117              ated connection.
118
119              The input parameter Ref is the return value from new_out_connec‐
120              tion/3.
121
122       in_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply
123
124              Types:
125
126                 Ref = term()
127                 Obj = #objref
128                 Ctx = [#'IOP_ServiceContext'{}]
129                 Op = atom()
130                 Data = [Result, OutParameter1, ..., OutPramaterN]
131                 Reply = {NewData, NewExtra}
132
133              When  replies  are  delivered  from  the  server side ORB to the
134              client side ORB this operation is invoked. The Data parameter is
135              a list in which the first element is the return value value from
136              the target object and the rest is a all  parameters  defined  as
137              out or inout in the IDL-specification.
138
139       in_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
140
141              Types:
142
143                 Ref = term()
144                 Obj = #objref
145                 Ctx = [#'IOP_ServiceContext'{}]
146                 Op = atom()
147                 Bin = #binary
148                 Reply = {NewBin, NewExtra}
149
150              When  replies  are  delivered  from  the  server side ORB to the
151              client side ORB this operation is invoked. The Bin parameter  is
152              the reply body still uncoded.
153
154       in_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply
155
156              Types:
157
158                 Ref = term()
159                 Obj = #objref
160                 Ctx = [#'IOP_ServiceContext'{}]
161                 Op = atom()
162                 Args = [Argument] - defined in the IDL-specification
163                 Reply = {NewArgs, NewExtra}
164
165              When a new request arrives at the server side ORB this operation
166              is invoked.
167
168       in_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
169
170              Types:
171
172                 Ref = term()
173                 Obj = #objref
174                 Ctx = [#'IOP_ServiceContext'{}]
175                 Op = atom()
176                 Bin = #binary
177                 Reply = {NewBin, NewExtra}
178
179              When a new request arrives at the server side ORB this operation
180              is invoked before decoding the request body.
181
182       out_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply
183
184              Types:
185
186                 Ref = term()
187                 Obj = #objref
188                 Ctx = [#'IOP_ServiceContext'{}]
189                 Op = atom()
190                 Data = [Result, OutParameter1, ..., OutPramaterN]
191                 Reply = {NewData, NewExtra}
192
193              After  the  target  object  have  been invoked this operation is
194              invoked with the result. The Data parameter is a list  in  which
195              the  first  element  is  the  return value value from the target
196              object and the rest is a all parameters defined as out or  inout
197              in the IDL-specification.
198
199       out_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
200
201              Types:
202
203                 Ref = term()
204                 Obj = #objref
205                 Ctx = [#'IOP_ServiceContext'{}]
206                 Op = atom()
207                 Bin = #binary
208                 Reply = {NewBin, NewExtra}
209
210              This  operation  is similar to out_reply; the only difference is
211              that the reply body have been encoded.
212
213       out_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply
214
215              Types:
216
217                 Ref = term()
218                 Obj = #objref
219                 Ctx = [#'IOP_ServiceContext'{}]
220                 Op = atom()
221                 Args = [Argument] - defined in the IDL-specification
222                 Reply = {NewArgs, NewExtra}
223
224              Before a request is sent to the server side ORB, out_request  is
225              invoked.
226
227       out_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply
228
229              Types:
230
231                 Ref = term()
232                 Obj = #objref
233                 Ctx = [#'IOP_ServiceContext'{}]
234                 Op = atom()
235                 Bin = #binary
236                 Reply = {NewBin, NewExtra}
237
238              This operation is similar to out_request; the only difference is
239              that the request body have been encoded.
240
241
242
243Ericsson AB                        orber 5.0                   interceptors(3)
Impressum