diff options
Diffstat (limited to 'lib/orber/doc/src/interceptors.xml')
| -rw-r--r-- | lib/orber/doc/src/interceptors.xml | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/lib/orber/doc/src/interceptors.xml b/lib/orber/doc/src/interceptors.xml new file mode 100644 index 0000000000..8d1f97d5a2 --- /dev/null +++ b/lib/orber/doc/src/interceptors.xml @@ -0,0 +1,283 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2001</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>interceptors</title> + <prepared></prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>1999-09-03</date> + <rev>A</rev> + </header> + <module>interceptors</module> + <modulesummary>Describe the functions which must be exported by any supplied Orber native interceptor.</modulesummary> + <description> + <p>This module contains the mandatory functions for user supplied native + interceptors and their intended behavior. See also the User's Guide.</p> + <warning> + <p>Using <c>Interceptors</c> 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.</p> + </warning> + <warning> + <p>It is possible to alter the <c>Data</c>, <c>Bin</c> and <c>Args</c> + parameter for the <c>in_reply</c> and <c>out_reply</c>, + <c>in_reply_encoded</c>, <c>in_request_encoded</c>, + <c>out_reply_encoded</c> and <c>out_request_encoded</c>, + <c>in_request</c> and <c>out_request</c> respectively. But, + if it is done incorrectly, the consequences can be serious.</p> + </warning> + <note> + <p>The <c>Extra</c> 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.</p> + </note> + <note> + <p>The <c>Ref</c> parameter is set to 'undefined' by Orber when calling + <c>new_in_connection</c> or <c>new_out_connection</c> using + the first interceptor. The user supplied interceptor may set <c>NewRef</c> + to any Erlang term. If an interceptor change this parameter it will be + passed on to the next interceptor in the list uninterpreted.</p> + </note> + </description> + <funcs> + <func> + <name>new_in_connection(Ref, PeerHost, PeerPort) -> NewRef</name> + <name>new_in_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef</name> + <fsummary>Invoke when a new client ORB wants to setup a connection</fsummary> + <type> + <v>Ref = term() | undefined</v> + <v>PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10"</v> + <v>PeerPort = SocketPort = integer()</v> + <v>NewRef = term() | {'EXIT', Reason}</v> + </type> + <desc> + <p>When a new connection is requested by a client side ORB this operation + is invoked. If more than one interceptor is supplied, e.g., + <c>{native, ['myInterceptor1', 'myInterceptor2']}</c>, the return value + from 'myInterceptor1' is passed to 'myInterceptor2' as <c>Ref</c>. + Initially, Orber uses the atom 'undefined' as <c>Ref</c> 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 <c>Ref</c> parameter can, for example, be used as a unique + identifier to mnesia or ets where information/restrictions for + this connection is stored.</p> + <p>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.</p> + <p>If, for some reason, we do not allow the client ORB to connect + simply invoke <c>exit(Reason)</c>.</p> + </desc> + </func> + <func> + <name>new_out_connection(Ref, PeerHost, PeerPort) -> NewRef</name> + <name>new_out_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef</name> + <fsummary>Invoke when setting up a new connection to a server side ORB</fsummary> + <type> + <v>Ref = term() | undefined</v> + <v>PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10"</v> + <v>PeerPort = SocketPort = integer()</v> + <v>NewRef = term() | {'EXIT', Reason}</v> + </type> + <desc> + <p>When a new connection is set up this function is invoked. Behaves + just like <c>new_in_connection</c>; 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.</p> + </desc> + </func> + <func> + <name>closed_in_connection(Ref) -> NewRef</name> + <fsummary>Invoke when an existing connection to a client side ORB have been terminated</fsummary> + <type> + <v>Ref = term()</v> + <v>NewRef = term()</v> + </type> + <desc> + <p>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.</p> + <p>The input parameter <c>Ref</c> is the return value from + <c>new_in_connection/3</c>.</p> + </desc> + </func> + <func> + <name>closed_out_connection(Ref) -> NewRef</name> + <fsummary>Invoke when an existing connection to a server side ORB have been terminated</fsummary> + <type> + <v>Ref = term()</v> + <v>NewRef = term()</v> + </type> + <desc> + <p>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.</p> + <p>The input parameter <c>Ref</c> is the return value from + <c>new_out_connection/3</c>.</p> + </desc> + </func> + <func> + <name>in_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply</name> + <fsummary>Invoke when replies arrives at the client side ORB</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Data = [Result, OutParameter1, ..., OutPramaterN]</v> + <v>Reply = {NewData, NewExtra}</v> + </type> + <desc> + <p>When replies are delivered from the server side ORB to the client side + ORB this operation is invoked. The <c>Data</c> 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 <c>out</c> or <c>inout</c> in + the IDL-specification.</p> + </desc> + </func> + <func> + <name>in_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name> + <fsummary>Invoke when replies arrives at the client side ORB with undecoded reply body</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Bin = #binary</v> + <v>Reply = {NewBin, NewExtra}</v> + </type> + <desc> + <p>When replies are delivered from the server side ORB to the client side + ORB this operation is invoked. The <c>Bin</c> parameter is the reply + body still uncoded.</p> + </desc> + </func> + <func> + <name>in_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply</name> + <fsummary>Invoke when requests arrive at the server side ORB</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Args = [Argument] - defined in the IDL-specification</v> + <v>Reply = {NewArgs, NewExtra}</v> + </type> + <desc> + <p>When a new request arrives at the server side ORB this operation is + invoked.</p> + </desc> + </func> + <func> + <name>in_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name> + <fsummary>Invoke when requests arrive at the server side ORB with undecoded request body</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Bin = #binary</v> + <v>Reply = {NewBin, NewExtra}</v> + </type> + <desc> + <p>When a new request arrives at the server side ORB this operation is + invoked before decoding the request body.</p> + </desc> + </func> + <func> + <name>out_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply</name> + <fsummary>Invoke after the target object replied</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Data = [Result, OutParameter1, ..., OutPramaterN]</v> + <v>Reply = {NewData, NewExtra}</v> + </type> + <desc> + <p>After the target object have been invoked this operation is invoked + with the result. The <c>Data</c> 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 <c>out</c> or <c>inout</c> in + the IDL-specification.</p> + </desc> + </func> + <func> + <name>out_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name> + <fsummary>Invoke after the target object replied with the reply encoded</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Bin = #binary</v> + <v>Reply = {NewBin, NewExtra}</v> + </type> + <desc> + <p>This operation is similar to <c>out_reply</c>; the only difference is + that the reply body have been encoded.</p> + </desc> + </func> + <func> + <name>out_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply</name> + <fsummary>Invoke on the client side ORB before encoding and sending the request</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Args = [Argument] - defined in the IDL-specification</v> + <v>Reply = {NewArgs, NewExtra}</v> + </type> + <desc> + <p>Before a request is sent to the server side ORB, <c>out_request</c> is + invoked.</p> + </desc> + </func> + <func> + <name>out_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name> + <fsummary>Invoke on the client side ORB before sending the request</fsummary> + <type> + <v>Ref = term()</v> + <v>Obj = #objref</v> + <v>Ctx = [#'IOP_ServiceContext'{}]</v> + <v>Op = atom()</v> + <v>Bin = #binary</v> + <v>Reply = {NewBin, NewExtra}</v> + </type> + <desc> + <p>This operation is similar to <c>out_request</c>; the only + difference is that the request body have been encoded.</p> + </desc> + </func> + </funcs> + +</erlref> + |