mtcp_register_callback

NAME

mtcp_register_callback - register/de-register a callback function on a specified hook point

 

SYNOPSIS

#include <mos_api.h>

int mtcp_register_callback(mctx_t mctx, int sockid, event_t event, int hook_point, callback_t cb);

 

DESCRIPTION

mtcp_register_callback() registers a callback handler, cb, for a monitoring socket referred to by the sockid descriptor. A user can register the callback handler in any one of the three available hook points as shown below:

Hook points
TypeDescription
MOS_HK_RCV Trigger point right after receiver side stack update.
MOS_HK_SND Trigger point right after sender side stack update
MOS_NULL Trigger point for connection-less IP traffic

A user can register for relevant built-in or custom user-defined events (see mtcp_define_event()) of interest. The event argument is a typedef'ed uint64_t integer. mOS provides the following built-in events that a user can employ:

Events
TypeDescription
MOS_ON_PKT_IN Packet arrival.
MOS_ON_CONN_START Connection initiation (the first SYN packet).
MOS_ON_REXMIT TCP packet retransmission.
MOS_ON_TCP_STATE_CHANGE TCP state transition.
MOS_ON_CONN_END Connection termination.
MOS_ON_CONN_NEW_DATA New flow data.
MOS_ON_ORPHAN Out-of-flow (or non-TCP) packet arrival.
MOS_ON_ERROR Error report (e.g. receive buffer full (see mtcp_peek())).

All events, with the exception of MOS_ON_ORPHAN, can be used for stream monitoring sockets. The mOS stack internally manages the client and the server networking stacks as the ongoing traffic passes through the middlebox. A user-registered callback, cb, is invoked whenever a relevant network event is detected by the underlying stack. The user is expected to define the callback handler and is expected to add monitoring application logic pertaining to the triggered event. The callback handler is a function pointer of type:

typedef void (*callback_t)(mctx_t mctx, int sock, int side, event_t event);

The side variable informs the user exactly which flow of the connection is currently in context. This can either be MOS_SIDE_CLI (the client side) or MOS_SIDE_SVR (the server side). Callback functions generated from raw monitoring sockets (MOS_SOCK_MONITOR_RAW) only provide MOS_NULL as the value of the side argument, while the only available event for such sockets is MOS_ON_ORPHAN.

A user can dynamically de-register the event callback handler from any monitoring socket, during the life time of the connection, by calling mtcp_register_callback() with the cb argument set as NULL.

A typical usage of mtcp_register_callback() is illustrated below:


 /*************************************************/
 monitor_filter_t ft = {0};
 int s;


 // create a passive monitoring socket with its scope
 s = mtcp_socket(m, AF_INET, MOS_SOCK_MONITOR_STREAM, 0);
 ft.stream_syn_filter = "dst net 216.58 and dst port 80";
 mtcp_bind_monitor_filter(m, s, &ft);


 // sets up an event handler for MOS_ON_REXMIT
 mtcp_register_callback(m, s, MOS_ON_REXMIT, MOS_HK_RCV, OnRexmitPkt);
 /*************************************************/

 

RETURN VALUE

Returns 0 on success; -1 on failure.  

ERRORS

EINVAL    
The socket descriptor, sockid is invalid.
 

AUTHORS

mOS development team <mtcp-user@list.ndsl.kaist.edu>

EXAMPLES

http://mos.kaist.edu/guide/programmer/05_api_example.html#registering-for-built-in-events

http://mos.kaist.edu/guide/programmer/05_api_example.html#registering-for-user-defined-events-udes

 

SEE ALSO

mtcp_socket(), mtcp_bind_monitor_filter(), mtcp_register_callback()  

COLOPHON

This page is part of mOS release 0.3 docs section. A description of the project, and information about reporting bugs, can be found at http://mos.kaist.edu/.

Back to Index