interceptors(3)

📦
version 5.2.2 · 2 versions
, in fedora 43, fedora 44

💖 interceptors(3) 💖

okay so bestie, gather round, because this is interceptors(3) — an Erlang module definition, and it's literally about Orber native interceptors and the functions you have to export if you're supplying one. no cap. 🦋

✨ NAME ✨

interceptors — describes the functions which must be exported by any supplied Orber native interceptor. periodt. 💅

🌸 DESCRIPTION 🌸

okay so this module is basically the whole rulebook: it holds the mandatory functions for user-supplied native interceptors, plus what those functions are supposed to do. also go check the User's Guide, bestie, it's right there. 📖

⚠️ Warning: using Interceptors may reduce the through-put significantly if the interceptors you supply go and invoke expensive operations. so like… one should always supply interceptors which cause as little overhead as possible. keep it light, keep it breezy, keep it cheap. 😭
⚠️ Warning: it is possible to alter the Data, Bin and Args parameter for the in_reply and out_reply, in_reply_encoded, in_request_encoded, out_reply_encoded and out_request_encoded, in_request and out_request respectively. but — and this is the important part, bestie — if it is done incorrectly, the consequences can be serious. like, do-not-pass-go serious. 💀
📝 Note: the Extra parameter is set to 'undefined' by Orber when calling the first interceptor and may be set to any Erlang term. if an interceptor changes this parameter it will be passed on to the next interceptor in the list uninterpreted. it just vibes on through, no commentary. 🫶
📝 Note: the Ref parameter is set to 'undefined' by Orber when calling new_in_connection or new_out_connection using the first interceptor. the user supplied interceptor may set NewRef to any Erlang term. if an interceptor changes this parameter it will be passed on to the next interceptor in the list uninterpreted. same energy, different parameter. ✨

👑 EXPORTS 👑

🧚 new_in_connection

new_in_connection(Ref, PeerHost, PeerPort) -> NewRef
new_in_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef

Types:

Ref = term() | undefined
PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10"
PeerPort = SocketPort = integer()
NewRef = term() | {'EXIT', Reason}

so when a new connection is requested by a client side ORB, this operation gets invoked. that's it, that's the moment. 🌈

if more than one interceptor is supplied — like, say, {native, ['myInterceptor1', 'myInterceptor2']} — the return value from 'myInterceptor1' is passed to 'myInterceptor2' as Ref. initially, Orber uses the atom 'undefined' as the Ref parameter when calling the first interceptor. and then the return value from the last interceptor — in the example above, 'myInterceptor2' — is passed to all other functions exported by the interceptors. so basically the Ref parameter can, for example, be used as a unique identifier to mnesia or ets where information/restrictions for this connection is stored. iconic little handoff, honestly. 🎀

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.

and if, for some reason, we do not allow the client ORB to connect? simply invoke exit(Reason). bye bestie, not today. 🙈

🦋 new_out_connection

new_out_connection(Ref, PeerHost, PeerPort) -> NewRef
new_out_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef

Types:

Ref = term() | undefined
PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10"
PeerPort = SocketPort = integer()
NewRef = term() | {'EXIT', Reason}

when a new connection is set up, this function is invoked. it behaves just like new_in_connection — the only difference is that the PeerHost and PeerPort variables identify the target ORB's bootstrap data, and SocketHost and SocketPort are the local interface and port the client ORB connected via. same girl, different outfit. 💅

🍓 closed_in_connection

closed_in_connection(Ref) -> NewRef

Types:

Ref = term()
NewRef = term()

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. tidy up, bestie. 🧹

the input parameter Ref is the return value from new_in_connection/3.

🌸 closed_out_connection

closed_out_connection(Ref) -> NewRef

Types:

Ref = term()
NewRef = term()

when an existing connection is terminated, this operation is invoked. (yes, again — this is the out twin.) the main purpose of this function is to make it possible for a user to clean up all data associated with the associated connection.

the input parameter Ref is the return value from new_out_connection/3.

💜 in_reply

in_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Data = [Result, OutParameter1, ..., OutPramaterN]
Reply = {NewData, NewExtra}

when replies are delivered from the server side ORB to the client side ORB, this operation is invoked. the Data 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 out or inout in the IDL-specification. 🎀

⭐ in_reply_encoded

in_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Bin = #binary
Reply = {NewBin, NewExtra}

when replies are delivered from the server side ORB to the client side ORB, this operation is invoked. the Bin parameter is the reply body still uncoded. raw. untouched. ✨

🔥 in_request

in_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Args = [Argument] - defined in the IDL-specification
Reply = {NewArgs, NewExtra}

when a new request arrives at the server side ORB, this operation is invoked. that's the whole thing. 😌

🌈 in_request_encoded

in_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Bin = #binary
Reply = {NewBin, NewExtra}

when a new request arrives at the server side ORB, this operation is invoked before decoding the request body. catching it early, like a true main character. 👑

🎀 out_reply

out_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Data = [Result, OutParameter1, ..., OutPramaterN]
Reply = {NewData, NewExtra}

after the target object have been invoked, this operation is invoked with the result. the Data 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 out or inout in the IDL-specification. 🫶

🧚 out_reply_encoded

out_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Bin = #binary
Reply = {NewBin, NewExtra}

this operation is similar to out_reply; the only difference is that the reply body have been encoded. so it's the same vibe, just already wrapped up. 🎁

💖 out_request

out_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Args = [Argument] - defined in the IDL-specification
Reply = {NewArgs, NewExtra}

before a request is sent to the server side ORB, out_request is invoked. sending it off, bestie. ✈️

🌸 out_request_encoded

out_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply

Types:

Ref = term()
Obj = #objref
Ctx = [#'IOP_ServiceContext'{}]
Op = atom()
Bin = #binary
Reply = {NewBin, NewExtra}

this operation is similar to out_request; the only difference is that the request body have been encoded. yes girl, same but encoded. 💅

🦋 SEE ALSO 🦋

aw wait, there's no SEE ALSO section in this one — but the DESCRIPTION did point you at the User's Guide, so go read that if you want the full lore. iykyk. 📚

and that's the whole page, bestie!! this gem was brought to you by Ericsson AB, from orber 5.2.2, and it's the interceptors(3) page — so go forth, write those interceptors, keep the overhead tiny, and remember: alter Data, Bin and Args incorrectly and the consequences can be serious. slay responsibly. 💜✨

📦 where this page comes from