191df013fSAsim Jamshed<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 291df013fSAsim Jamshed<HTML><HEAD><TITLE>Man page of mtcp_register_callback</TITLE> 391df013fSAsim Jamshed<link rel="stylesheet" href="./common.css"> 491df013fSAsim Jamshed</HEAD><BODY> 591df013fSAsim Jamshed<div class="main"> 691df013fSAsim Jamshed<H1 align="center">mtcp_register_callback</H1> 791df013fSAsim Jamshed 891df013fSAsim Jamshed<H2>NAME</H2> 991df013fSAsim Jamshed 1091df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">mtcp_register_callback - register/de-register a callback function on a specified hook point</p> 1191df013fSAsim Jamshed<A NAME="lbAC"> </A> 1291df013fSAsim Jamshed<H2>SYNOPSIS</H2> 1391df013fSAsim Jamshed 1491df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 1591df013fSAsim Jamshed<B>#include <<A HREF="file:///usr/include/mos_api.h">mos_api.h</A>></B></P> 1691df013fSAsim Jamshed 1791df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"><B>int mtcp_register_callback(mctx_t </B><I>mctx</I><B>, int </B><I>sockid</I><B>, event_t </B><I>event</I><B>, int </B><I>hook_point</I><B>, callback_t </B><I>cb</I><B>);</B> </P> 1891df013fSAsim Jamshed 1991df013fSAsim Jamshed<P> 2091df013fSAsim Jamshed<A NAME="lbAD"> </A> 2191df013fSAsim Jamshed<H2>DESCRIPTION</H2> 2291df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 2391df013fSAsim Jamshed<B>mtcp_register_callback</B>() 2491df013fSAsim Jamshed 2591df013fSAsim Jamshedregisters a callback handler, 2691df013fSAsim Jamshed<I>cb,</I> 2791df013fSAsim Jamshed 2891df013fSAsim Jamshedfor a monitoring socket referred to by the 2991df013fSAsim Jamshed<I>sockid</I> 3091df013fSAsim Jamshed 3191df013fSAsim Jamsheddescriptor. A user can register the callback handler 3291df013fSAsim Jamshedin any one of the three available hook points as shown 3391df013fSAsim Jamshedbelow: 3491df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 3591df013fSAsim Jamshed 3691df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 3791df013fSAsim Jamshed<TABLE BORDER> 3891df013fSAsim Jamshed<TR VALIGN=top><TD ALIGN=center COLSPAN=2>Hook points<BR></TD></TR> 3991df013fSAsim Jamshed<TR VALIGN=top><TD>Type</TD><TD>Description<BR></TD></TR> 4091df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_HK_RCV</TD><TD> 4191df013fSAsim JamshedTrigger point right after receiver side stack update. 4291df013fSAsim Jamshed<BR></TD></TR> 4391df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_HK_SND</TD><TD> 4491df013fSAsim JamshedTrigger point right after sender side stack update 4591df013fSAsim Jamshed<BR></TD></TR> 4691df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_NULL</TD><TD> 4791df013fSAsim JamshedTrigger point for connection-less IP traffic 4891df013fSAsim Jamshed<BR></TD></TR> 4991df013fSAsim Jamshed</TABLE> 5091df013fSAsim Jamshed 5191df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 5291df013fSAsim Jamshed 5391df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 5491df013fSAsim JamshedA user can register for relevant built-in or custom user-defined 5591df013fSAsim Jamshedevents (see 5691df013fSAsim Jamshed<B>mtcp_define_event())</B> 5791df013fSAsim Jamshed 5891df013fSAsim Jamshedof interest. The 5991df013fSAsim Jamshed<I>event</I> 6091df013fSAsim Jamshed 6191df013fSAsim Jamshedargument is a typedef'ed uint64_t integer. mOS provides the following 6291df013fSAsim Jamshedbuilt-in events that a user can employ: 6391df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 6491df013fSAsim Jamshed<TABLE BORDER> 6591df013fSAsim Jamshed<TR VALIGN=top><TD ALIGN=center COLSPAN=2>Events<BR></TD></TR> 6691df013fSAsim Jamshed<TR VALIGN=top><TD>Type</TD><TD>Description<BR></TD></TR> 6791df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_PKT_IN</TD><TD> 6891df013fSAsim JamshedPacket arrival. 6991df013fSAsim Jamshed<BR></TD></TR> 7091df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_CONN_START</TD><TD> 7191df013fSAsim JamshedConnection initiation (the first SYN packet). 7291df013fSAsim Jamshed<BR></TD></TR> 7391df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_REXMIT</TD><TD> 7491df013fSAsim JamshedTCP packet retransmission. 7591df013fSAsim Jamshed<BR></TD></TR> 7691df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_TCP_STATE_CHANGE</TD><TD> 7791df013fSAsim JamshedTCP state transition. 7891df013fSAsim Jamshed<BR></TD></TR> 7991df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_CONN_END</TD><TD> 8091df013fSAsim JamshedConnection termination. 8191df013fSAsim Jamshed<BR></TD></TR> 8291df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_CONN_NEW_DATA</TD><TD> 8391df013fSAsim JamshedNew flow data. 8491df013fSAsim Jamshed<BR></TD></TR> 8591df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_ORPHAN</TD><TD> 8691df013fSAsim JamshedOut-of-flow (or non-TCP) packet arrival. 8791df013fSAsim Jamshed<BR></TD></TR> 8891df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_ERROR</TD><TD> 8991df013fSAsim JamshedError report (e.g. receive buffer full (see 9091df013fSAsim Jamshed<B>mtcp_peek())).</B> 9191df013fSAsim Jamshed 9291df013fSAsim Jamshed<BR></TD></TR> 9391df013fSAsim Jamshed</TABLE> 9491df013fSAsim Jamshed 9591df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 9691df013fSAsim Jamshed 9791df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 9891df013fSAsim JamshedAll events, with the exception of MOS_ON_ORPHAN, can be used for stream monitoring sockets. 9991df013fSAsim JamshedThe mOS stack internally manages the client and the server networking stacks 10091df013fSAsim Jamshedas the ongoing traffic passes through the middlebox. A user-registered callback, 10191df013fSAsim Jamshed<I>cb,</I> 10291df013fSAsim Jamshed 10391df013fSAsim Jamshedis invoked whenever a relevant network event is detected by the underlying stack. The 10491df013fSAsim Jamsheduser is expected to define the callback handler and is expected to add monitoring 10591df013fSAsim Jamshedapplication logic pertaining to the triggered event. The 10691df013fSAsim Jamshedcallback handler is a function pointer of type: 10791df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 10891df013fSAsim Jamshed<B>typedef void (*callback_t)(mctx_t </B><I>mctx</I><B>, int </B><I>sock</I><B>, int </B><I>side</I><B>, event_t </B><I>event</I><B>);</B> 10991df013fSAsim Jamshed 11091df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 11191df013fSAsim JamshedThe 11291df013fSAsim Jamshed<I>side</I> 11391df013fSAsim Jamshed 11491df013fSAsim Jamshedvariable informs the user exactly 11591df013fSAsim Jamshedwhich flow of the connection is currently in context. This can 11691df013fSAsim Jamshedeither be MOS_SIDE_CLI (the client side) or MOS_SIDE_SVR (the 11791df013fSAsim Jamshedserver side). Callback functions generated from raw monitoring 11891df013fSAsim Jamshedsockets (MOS_SOCK_MONITOR_RAW) only provide MOS_NULL as the 11991df013fSAsim Jamshedvalue of the side argument, while the only available event 12091df013fSAsim Jamshedfor such sockets is MOS_ON_ORPHAN. 12191df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 12291df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 12391df013fSAsim Jamshed 12491df013fSAsim JamshedA user can dynamically de-register the event callback handler 12591df013fSAsim Jamshedfrom any monitoring socket, during the life time of the connection, 12691df013fSAsim Jamshedby calling 12791df013fSAsim Jamshed<B>mtcp_register_callback()</B> 12891df013fSAsim Jamshed 12991df013fSAsim Jamshedwith the 13091df013fSAsim Jamshed<I>cb</I> 13191df013fSAsim Jamshed 13291df013fSAsim Jamshedargument set as NULL. 13391df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 13491df013fSAsim JamshedA typical usage of 13591df013fSAsim Jamshed<B>mtcp_register_callback()</B> 13691df013fSAsim Jamshed 13791df013fSAsim Jamshedis illustrated below: 13891df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 13991df013fSAsim Jamshed 14091df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 14191df013fSAsim Jamshed<BR> /*************************************************/ 14291df013fSAsim Jamshed<BR> monitor_filter_t ft = {0}; 14391df013fSAsim Jamshed<BR> int s; 14491df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 14591df013fSAsim Jamshed<BR> // create a passive monitoring socket with its scope 14691df013fSAsim Jamshed<BR> s = mtcp_socket(m, AF_INET, MOS_SOCK_MONITOR_STREAM, 0); 14791df013fSAsim Jamshed<BR> ft.stream_syn_filter = "dst net 216.58 and dst port 80"; 14891df013fSAsim Jamshed<BR> mtcp_bind_monitor_filter(m, s, &ft); 14991df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 15091df013fSAsim Jamshed<BR> // sets up an event handler for MOS_ON_REXMIT 15191df013fSAsim Jamshed<BR> mtcp_register_callback(m, s, MOS_ON_REXMIT, MOS_HK_RCV, OnRexmitPkt); 15291df013fSAsim Jamshed<BR> /*************************************************/ 15391df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 15491df013fSAsim Jamshed 15591df013fSAsim Jamshed<A NAME="lbAE"> </A> 15691df013fSAsim Jamshed<H2>RETURN VALUE</H2> 15791df013fSAsim Jamshed 15891df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 15991df013fSAsim JamshedReturns 0 on success; -1 on failure. 16091df013fSAsim Jamshed 16191df013fSAsim Jamshed 16291df013fSAsim Jamshed 16391df013fSAsim Jamshed 16491df013fSAsim Jamshed<A NAME="lbAF"> </A> 16591df013fSAsim Jamshed<H2>ERRORS</H2> 16691df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 16791df013fSAsim Jamshed<DL> 16891df013fSAsim Jamshed<DT><B>EINVAL </B> 16991df013fSAsim Jamshed 17091df013fSAsim Jamshed<DD> 17191df013fSAsim JamshedThe socket descriptor, 17291df013fSAsim Jamshed<I>sockid</I> 17391df013fSAsim Jamshed 17491df013fSAsim Jamshedis invalid. 17591df013fSAsim Jamshed 17691df013fSAsim Jamshed</DL> 17791df013fSAsim Jamshed<A NAME="lbAG"> </A> 17891df013fSAsim Jamshed<H2>AUTHORS</H2> 17991df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 18091df013fSAsim JamshedmOS development team <<A HREF="mailto:[email protected]">[email protected]</A>> 18191df013fSAsim Jamshed 182*e5df9dc1SAsim Jamshed<!-----------------------------------------------------------> 183*e5df9dc1SAsim Jamshed<h2>EXAMPLES 184*e5df9dc1SAsim Jamshed<a name="EXAMPLES"></a> 185*e5df9dc1SAsim Jamshed</h2> 186*e5df9dc1SAsim Jamshed 187*e5df9dc1SAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 188*e5df9dc1SAsim Jamshed <a href="http://mos.kaist.edu/guide/programmer/05_api_example.html#registering-for-built-in-events"> 189*e5df9dc1SAsim Jamshed http://mos.kaist.edu/guide/programmer/05_api_example.html#registering-for-built-in-events 190*e5df9dc1SAsim Jamshed </a> 191*e5df9dc1SAsim Jamshed</p> 192*e5df9dc1SAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 193*e5df9dc1SAsim Jamshed <a href="http://mos.kaist.edu/guide/programmer/05_api_example.html#registering-for-user-defined-events-udes"> 194*e5df9dc1SAsim Jamshed http://mos.kaist.edu/guide/programmer/05_api_example.html#registering-for-user-defined-events-udes 195*e5df9dc1SAsim Jamshed </a> 196*e5df9dc1SAsim Jamshed</p> 197*e5df9dc1SAsim Jamshed<!-----------------------------------------------------------> 198*e5df9dc1SAsim Jamshed 19991df013fSAsim Jamshed<A NAME="lbAH"> </A> 20091df013fSAsim Jamshed<H2>SEE ALSO</H2> 20191df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 20291df013fSAsim Jamshed<B>mtcp_socket</B>(), 20391df013fSAsim Jamshed 20491df013fSAsim Jamshed<B>mtcp_bind_monitor_filter</B>(), 20591df013fSAsim Jamshed 20691df013fSAsim Jamshed<B>mtcp_register_callback</B>() 20791df013fSAsim Jamshed 20891df013fSAsim Jamshed 20991df013fSAsim Jamshed<A NAME="lbAI"> </A> 21091df013fSAsim Jamshed<H2>COLOPHON</H2> 21191df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 21291df013fSAsim JamshedThis page is part of mOS release 0.3 21391df013fSAsim Jamshed<I>docs</I> 21491df013fSAsim Jamshed 21591df013fSAsim Jamshedsection. A description of the project, and information 21691df013fSAsim Jamshedabout reporting bugs, can be found at 21791df013fSAsim Jamshed<A HREF="http://mos.kaist.edu/.">http://mos.kaist.edu/.</A> 21891df013fSAsim Jamshed 21991df013fSAsim Jamshed<!-- 22091df013fSAsim Jamshed<HR> 22191df013fSAsim Jamshed<A NAME="index"> </A><H2>Index</H2> 22291df013fSAsim Jamshed<DL> 22391df013fSAsim Jamshed<DT><A HREF="#lbAB">NAME</A><DD> 22491df013fSAsim Jamshed<DT><A HREF="#lbAC">SYNOPSIS</A><DD> 22591df013fSAsim Jamshed<DT><A HREF="#lbAD">DESCRIPTION</A><DD> 22691df013fSAsim Jamshed<DT><A HREF="#lbAE">RETURN VALUE</A><DD> 22791df013fSAsim Jamshed<DT><A HREF="#lbAF">ERRORS</A><DD> 22891df013fSAsim Jamshed<DT><A HREF="#lbAG">AUTHORS</A><DD> 22991df013fSAsim Jamshed<DT><A HREF="#lbAH">SEE ALSO</A><DD> 23091df013fSAsim Jamshed<DT><A HREF="#lbAI">COLOPHON</A><DD> 23191df013fSAsim Jamshed</DL> 23291df013fSAsim Jamshed<!-- <HR> --> 23391df013fSAsim Jamshed<div class="footer"> 23491df013fSAsim Jamshed <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 23591df013fSAsim Jamshed</div> 23691df013fSAsim Jamshed</div> 23791df013fSAsim Jamshed</BODY> 23891df013fSAsim Jamshed</HTML> 239
