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