1*91df013fSAsim Jamshed<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2*91df013fSAsim Jamshed<HTML><HEAD><TITLE>Man page of mtcp_register_callback</TITLE> 3*91df013fSAsim Jamshed<link rel="stylesheet" href="./common.css"> 4*91df013fSAsim Jamshed</HEAD><BODY> 5*91df013fSAsim Jamshed<div class="main"> 6*91df013fSAsim Jamshed<H1 align="center">mtcp_register_callback</H1> 7*91df013fSAsim Jamshed 8*91df013fSAsim Jamshed<H2>NAME</H2> 9*91df013fSAsim Jamshed 10*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">mtcp_register_callback - register/de-register a callback function on a specified hook point</p> 11*91df013fSAsim Jamshed<A NAME="lbAC"> </A> 12*91df013fSAsim Jamshed<H2>SYNOPSIS</H2> 13*91df013fSAsim Jamshed 14*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 15*91df013fSAsim Jamshed<B>#include <<A HREF="file:///usr/include/mos_api.h">mos_api.h</A>></B></P> 16*91df013fSAsim Jamshed 17*91df013fSAsim 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> 18*91df013fSAsim Jamshed 19*91df013fSAsim Jamshed<P> 20*91df013fSAsim Jamshed<A NAME="lbAD"> </A> 21*91df013fSAsim Jamshed<H2>DESCRIPTION</H2> 22*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 23*91df013fSAsim Jamshed<B>mtcp_register_callback</B>() 24*91df013fSAsim Jamshed 25*91df013fSAsim Jamshedregisters a callback handler, 26*91df013fSAsim Jamshed<I>cb,</I> 27*91df013fSAsim Jamshed 28*91df013fSAsim Jamshedfor a monitoring socket referred to by the 29*91df013fSAsim Jamshed<I>sockid</I> 30*91df013fSAsim Jamshed 31*91df013fSAsim Jamsheddescriptor. A user can register the callback handler 32*91df013fSAsim Jamshedin any one of the three available hook points as shown 33*91df013fSAsim Jamshedbelow: 34*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 35*91df013fSAsim Jamshed 36*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 37*91df013fSAsim Jamshed<TABLE BORDER> 38*91df013fSAsim Jamshed<TR VALIGN=top><TD ALIGN=center COLSPAN=2>Hook points<BR></TD></TR> 39*91df013fSAsim Jamshed<TR VALIGN=top><TD>Type</TD><TD>Description<BR></TD></TR> 40*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_HK_RCV</TD><TD> 41*91df013fSAsim JamshedTrigger point right after receiver side stack update. 42*91df013fSAsim Jamshed<BR></TD></TR> 43*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_HK_SND</TD><TD> 44*91df013fSAsim JamshedTrigger point right after sender side stack update 45*91df013fSAsim Jamshed<BR></TD></TR> 46*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_NULL</TD><TD> 47*91df013fSAsim JamshedTrigger point for connection-less IP traffic 48*91df013fSAsim Jamshed<BR></TD></TR> 49*91df013fSAsim Jamshed</TABLE> 50*91df013fSAsim Jamshed 51*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 52*91df013fSAsim Jamshed 53*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 54*91df013fSAsim JamshedA user can register for relevant built-in or custom user-defined 55*91df013fSAsim Jamshedevents (see 56*91df013fSAsim Jamshed<B>mtcp_define_event())</B> 57*91df013fSAsim Jamshed 58*91df013fSAsim Jamshedof interest. The 59*91df013fSAsim Jamshed<I>event</I> 60*91df013fSAsim Jamshed 61*91df013fSAsim Jamshedargument is a typedef'ed uint64_t integer. mOS provides the following 62*91df013fSAsim Jamshedbuilt-in events that a user can employ: 63*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 64*91df013fSAsim Jamshed<TABLE BORDER> 65*91df013fSAsim Jamshed<TR VALIGN=top><TD ALIGN=center COLSPAN=2>Events<BR></TD></TR> 66*91df013fSAsim Jamshed<TR VALIGN=top><TD>Type</TD><TD>Description<BR></TD></TR> 67*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_PKT_IN</TD><TD> 68*91df013fSAsim JamshedPacket arrival. 69*91df013fSAsim Jamshed<BR></TD></TR> 70*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_CONN_START</TD><TD> 71*91df013fSAsim JamshedConnection initiation (the first SYN packet). 72*91df013fSAsim Jamshed<BR></TD></TR> 73*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_REXMIT</TD><TD> 74*91df013fSAsim JamshedTCP packet retransmission. 75*91df013fSAsim Jamshed<BR></TD></TR> 76*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_TCP_STATE_CHANGE</TD><TD> 77*91df013fSAsim JamshedTCP state transition. 78*91df013fSAsim Jamshed<BR></TD></TR> 79*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_CONN_END</TD><TD> 80*91df013fSAsim JamshedConnection termination. 81*91df013fSAsim Jamshed<BR></TD></TR> 82*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_CONN_NEW_DATA</TD><TD> 83*91df013fSAsim JamshedNew flow data. 84*91df013fSAsim Jamshed<BR></TD></TR> 85*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_ORPHAN</TD><TD> 86*91df013fSAsim JamshedOut-of-flow (or non-TCP) packet arrival. 87*91df013fSAsim Jamshed<BR></TD></TR> 88*91df013fSAsim Jamshed<TR VALIGN=top><TD>MOS_ON_ERROR</TD><TD> 89*91df013fSAsim JamshedError report (e.g. receive buffer full (see 90*91df013fSAsim Jamshed<B>mtcp_peek())).</B> 91*91df013fSAsim Jamshed 92*91df013fSAsim Jamshed<BR></TD></TR> 93*91df013fSAsim Jamshed</TABLE> 94*91df013fSAsim Jamshed 95*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 96*91df013fSAsim Jamshed 97*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 98*91df013fSAsim JamshedAll events, with the exception of MOS_ON_ORPHAN, can be used for stream monitoring sockets. 99*91df013fSAsim JamshedThe mOS stack internally manages the client and the server networking stacks 100*91df013fSAsim Jamshedas the ongoing traffic passes through the middlebox. A user-registered callback, 101*91df013fSAsim Jamshed<I>cb,</I> 102*91df013fSAsim Jamshed 103*91df013fSAsim Jamshedis invoked whenever a relevant network event is detected by the underlying stack. The 104*91df013fSAsim Jamsheduser is expected to define the callback handler and is expected to add monitoring 105*91df013fSAsim Jamshedapplication logic pertaining to the triggered event. The 106*91df013fSAsim Jamshedcallback handler is a function pointer of type: 107*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 108*91df013fSAsim 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> 109*91df013fSAsim Jamshed 110*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 111*91df013fSAsim JamshedThe 112*91df013fSAsim Jamshed<I>side</I> 113*91df013fSAsim Jamshed 114*91df013fSAsim Jamshedvariable informs the user exactly 115*91df013fSAsim Jamshedwhich flow of the connection is currently in context. This can 116*91df013fSAsim Jamshedeither be MOS_SIDE_CLI (the client side) or MOS_SIDE_SVR (the 117*91df013fSAsim Jamshedserver side). Callback functions generated from raw monitoring 118*91df013fSAsim Jamshedsockets (MOS_SOCK_MONITOR_RAW) only provide MOS_NULL as the 119*91df013fSAsim Jamshedvalue of the side argument, while the only available event 120*91df013fSAsim Jamshedfor such sockets is MOS_ON_ORPHAN. 121*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 122*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 123*91df013fSAsim Jamshed 124*91df013fSAsim JamshedA user can dynamically de-register the event callback handler 125*91df013fSAsim Jamshedfrom any monitoring socket, during the life time of the connection, 126*91df013fSAsim Jamshedby calling 127*91df013fSAsim Jamshed<B>mtcp_register_callback()</B> 128*91df013fSAsim Jamshed 129*91df013fSAsim Jamshedwith the 130*91df013fSAsim Jamshed<I>cb</I> 131*91df013fSAsim Jamshed 132*91df013fSAsim Jamshedargument set as NULL. 133*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 134*91df013fSAsim JamshedA typical usage of 135*91df013fSAsim Jamshed<B>mtcp_register_callback()</B> 136*91df013fSAsim Jamshed 137*91df013fSAsim Jamshedis illustrated below: 138*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 139*91df013fSAsim Jamshed 140*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 141*91df013fSAsim Jamshed<BR> /*************************************************/ 142*91df013fSAsim Jamshed<BR> monitor_filter_t ft = {0}; 143*91df013fSAsim Jamshed<BR> int s; 144*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 145*91df013fSAsim Jamshed<BR> // create a passive monitoring socket with its scope 146*91df013fSAsim Jamshed<BR> s = mtcp_socket(m, AF_INET, MOS_SOCK_MONITOR_STREAM, 0); 147*91df013fSAsim Jamshed<BR> ft.stream_syn_filter = "dst net 216.58 and dst port 80"; 148*91df013fSAsim Jamshed<BR> mtcp_bind_monitor_filter(m, s, &ft); 149*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 150*91df013fSAsim Jamshed<BR> // sets up an event handler for MOS_ON_REXMIT 151*91df013fSAsim Jamshed<BR> mtcp_register_callback(m, s, MOS_ON_REXMIT, MOS_HK_RCV, OnRexmitPkt); 152*91df013fSAsim Jamshed<BR> /*************************************************/ 153*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 154*91df013fSAsim Jamshed 155*91df013fSAsim Jamshed<A NAME="lbAE"> </A> 156*91df013fSAsim Jamshed<H2>RETURN VALUE</H2> 157*91df013fSAsim Jamshed 158*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 159*91df013fSAsim JamshedReturns 0 on success; -1 on failure. 160*91df013fSAsim Jamshed 161*91df013fSAsim Jamshed 162*91df013fSAsim Jamshed 163*91df013fSAsim Jamshed 164*91df013fSAsim Jamshed<A NAME="lbAF"> </A> 165*91df013fSAsim Jamshed<H2>ERRORS</H2> 166*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 167*91df013fSAsim Jamshed<DL> 168*91df013fSAsim Jamshed<DT><B>EINVAL </B> 169*91df013fSAsim Jamshed 170*91df013fSAsim Jamshed<DD> 171*91df013fSAsim JamshedThe socket descriptor, 172*91df013fSAsim Jamshed<I>sockid</I> 173*91df013fSAsim Jamshed 174*91df013fSAsim Jamshedis invalid. 175*91df013fSAsim Jamshed 176*91df013fSAsim Jamshed</DL> 177*91df013fSAsim Jamshed<A NAME="lbAG"> </A> 178*91df013fSAsim Jamshed<H2>AUTHORS</H2> 179*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 180*91df013fSAsim JamshedmOS development team <<A HREF="mailto:[email protected]">[email protected]</A>> 181*91df013fSAsim Jamshed 182*91df013fSAsim Jamshed<A NAME="lbAH"> </A> 183*91df013fSAsim Jamshed<H2>SEE ALSO</H2> 184*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 185*91df013fSAsim Jamshed<B>mtcp_socket</B>(), 186*91df013fSAsim Jamshed 187*91df013fSAsim Jamshed<B>mtcp_bind_monitor_filter</B>(), 188*91df013fSAsim Jamshed 189*91df013fSAsim Jamshed<B>mtcp_register_callback</B>() 190*91df013fSAsim Jamshed 191*91df013fSAsim Jamshed 192*91df013fSAsim Jamshed<A NAME="lbAI"> </A> 193*91df013fSAsim Jamshed<H2>COLOPHON</H2> 194*91df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"> 195*91df013fSAsim JamshedThis page is part of mOS release 0.3 196*91df013fSAsim Jamshed<I>docs</I> 197*91df013fSAsim Jamshed 198*91df013fSAsim Jamshedsection. A description of the project, and information 199*91df013fSAsim Jamshedabout reporting bugs, can be found at 200*91df013fSAsim Jamshed<A HREF="http://mos.kaist.edu/.">http://mos.kaist.edu/.</A> 201*91df013fSAsim Jamshed 202*91df013fSAsim Jamshed<!-- 203*91df013fSAsim Jamshed<HR> 204*91df013fSAsim Jamshed<A NAME="index"> </A><H2>Index</H2> 205*91df013fSAsim Jamshed<DL> 206*91df013fSAsim Jamshed<DT><A HREF="#lbAB">NAME</A><DD> 207*91df013fSAsim Jamshed<DT><A HREF="#lbAC">SYNOPSIS</A><DD> 208*91df013fSAsim Jamshed<DT><A HREF="#lbAD">DESCRIPTION</A><DD> 209*91df013fSAsim Jamshed<DT><A HREF="#lbAE">RETURN VALUE</A><DD> 210*91df013fSAsim Jamshed<DT><A HREF="#lbAF">ERRORS</A><DD> 211*91df013fSAsim Jamshed<DT><A HREF="#lbAG">AUTHORS</A><DD> 212*91df013fSAsim Jamshed<DT><A HREF="#lbAH">SEE ALSO</A><DD> 213*91df013fSAsim Jamshed<DT><A HREF="#lbAI">COLOPHON</A><DD> 214*91df013fSAsim Jamshed</DL> 215*91df013fSAsim Jamshed<!-- <HR> --> 216*91df013fSAsim Jamshed<div class="footer"> 217*91df013fSAsim Jamshed <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 218*91df013fSAsim Jamshed</div> 219*91df013fSAsim Jamshed</div> 220*91df013fSAsim Jamshed</BODY> 221*91df013fSAsim Jamshed</HTML> 222
