git.maemo.org Git - monky/blob - src/libtcp-portmon.h

   1 /* $Id$ */
   2
   3 /*
   4  * libtcp-portmon.h:  tcp port monitoring library.
   5  *
   6  * Copyright (C) 2005-2007 Philip Kovacs pkovacs@users.sourceforge.net
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  21  * USA.
  22  *
  23  */
  24
  25 #ifndef LIBTCP_PORTMON_H
  26 #define LIBTCP_PORTMON_H
  27
  28 #include <sys/types.h>
  29 #include <sys/socket.h>
  30
  31 #include <arpa/inet.h>
  32 #include <netinet/in.h>
  33 #include <netinet/tcp.h>
  34
  35 #include <math.h>
  36 #include <netdb.h>
  37 #include <stdlib.h>
  38 #include <stdio.h>
  39 #include <string.h>
  40
  41 #include <glib.h>
  42
  43 #define TCP_CONNECTION_STARTING_AGE 1   /* connection deleted if unseen again after this # of refreshes */
  44 #define TCP_CONNECTION_HASH_KEY_SIZE 28
  45 #define TCP_PORT_MONITOR_HASH_KEY_SIZE 12
  46
  47 /* -------------------------------------------------------------------
  48  * IMPLEMENTATION INTERFACE
  49  *
  50  * Implementation-specific interface begins here.  Clients should not
  51  * manipulate these structures directly, nor call the defined helper
  52  * functions.  Use the "Client interface" functions defined at bottom.
  53  * ------------------------------------------------------------------- */
  54
  55 /* The inventory of peekable items within the port monitor. */
  56 enum tcp_port_monitor_peekables {
  57         COUNT=0,
  58         REMOTEIP,
  59         REMOTEHOST,
  60         REMOTEPORT,
  61         REMOTESERVICE,
  62         LOCALIP,
  63         LOCALHOST,
  64         LOCALPORT,
  65         LOCALSERVICE
  66 };
  67
  68 /* ------------------------------------------------------------------------
  69  * A single tcp connection
  70  *
  71  * The age variable provides the mechanism for removing connections if they
  72  * are not seen again in subsequent update cycles.
  73  * ------------------------------------------------------------------------ */
  74 typedef struct _tcp_connection_t {
  75         gchar key[TCP_CONNECTION_HASH_KEY_SIZE];        /* connection's key in monitor hash */
  76         in_addr_t local_addr;
  77         in_port_t local_port;
  78         in_addr_t remote_addr;
  79         in_port_t remote_port;
  80         int age;
  81 } tcp_connection_t;
  82
  83 /* ----------------------------------
  84  * Copy a connection
  85  *
  86  * Returns 0 on success, -1 otherwise
  87  * ----------------------------------*/
  88 int copy_tcp_connection(
  89         tcp_connection_t *                      /* p_dest_connection */,
  90         const tcp_connection_t *                /* p_source_connection */
  91         );
  92
  93 /* ------------------------------------------------------------------------
  94  * A tcp connection node/list
  95  *
  96  * Connections within each monitor are stored in a double-linked list.
  97  * ------------------------------------------------------------------------ */
  98 typedef struct _tcp_connection_node_t {
  99         tcp_connection_t connection;
 100         struct _tcp_connection_node_t * p_prev;
 101         struct _tcp_connection_node_t * p_next;
 102 } tcp_connection_node_t;
 103
 104 typedef struct _tcp_connection_list_t {
 105         tcp_connection_node_t * p_head;
 106         tcp_connection_node_t * p_tail;
 107 } tcp_connection_list_t;
 108
 109 /* --------------
 110  * A port monitor
 111  * -------------- */
 112 typedef struct _tcp_port_monitor_t {
 113         gchar key[TCP_PORT_MONITOR_HASH_KEY_SIZE];      /* monitor's key in collection hash */
 114         in_port_t port_range_begin;                     /* start of monitor port range */
 115         in_port_t port_range_end;                       /* begin = end to monitor a single port */
 116         tcp_connection_list_t connection_list;          /* list of connections for this monitor */
 117         GHashTable *hash;                               /* hash table of pointers into connection list */
 118         tcp_connection_t **p_peek;                      /* array of connection pointers for O(1) peeking */
 119         unsigned int max_port_monitor_connections;      /* max number of connections */
 120 } tcp_port_monitor_t;
 121
 122 /* ------------------------
 123  * A port monitor node/list
 124  * ------------------------ */
 125 typedef struct _tcp_port_monitor_node_t {
 126         tcp_port_monitor_t * p_monitor;
 127         struct _tcp_port_monitor_node_t *p_next;
 128 } tcp_port_monitor_node_t;
 129
 130 typedef struct __tcp_port_monitor_list_t {
 131         tcp_port_monitor_node_t * p_head;
 132         tcp_port_monitor_node_t * p_tail;
 133 } tcp_port_monitor_list_t;
 134
 135 /* ---------------------------------------
 136  * A port monitor utility function typedef
 137  * ---------------------------------------*/
 138 typedef void (*tcp_port_monitor_function_ptr_t)( tcp_port_monitor_t * /* p_monitor */, void * /* p_void */ );
 139
 140 /* ---------------------------------------------------------------------------
 141  * Port monitor utility functions implementing tcp_port_monitor_function_ptr_t
 142  * ---------------------------------------------------------------------------*/
 143 void destroy_tcp_port_monitor(
 144         tcp_port_monitor_t *                    /* p_monitor */,
 145         void *                                  /* p_void (use NULL for this function) */
 146         );
 147
 148 void age_tcp_port_monitor(
 149         tcp_port_monitor_t *                    /* p_monitor */,
 150         void *                                  /* p_void (use NULL for this function) */
 151         );
 152
 153 void rebuild_tcp_port_monitor_peek_table(
 154         tcp_port_monitor_t *                    /* p_monitor */,
 155         void *                                  /* p_void (use NULL for this function) */
 156         );
 157
 158 void show_connection_to_tcp_port_monitor(
 159         tcp_port_monitor_t *                    /* p_monitor */,
 160         void *                                  /* p_connection (client should cast) */
 161         );
 162
 163 /* -----------------------------
 164  * A tcp port monitor collection
 165  * -----------------------------*/
 166 typedef struct _tcp_port_monitor_collection_t {
 167         tcp_port_monitor_list_t monitor_list;   /* list of monitors for this collection */
 168         GHashTable *hash;                       /* hash table of pointers into collection's monitor list */
 169 } tcp_port_monitor_collection_t;
 170
 171 /* ---------------------------------------------------------------------------------------
 172  * Apply a tcp_port_monitor_function_ptr_t function to each port monitor in the collection.
 173  * ---------------------------------------------------------------------------------------*/
 174 void for_each_tcp_port_monitor_in_collection(
 175         tcp_port_monitor_collection_t *         /* p_collection */,
 176         tcp_port_monitor_function_ptr_t         /* p_function */,
 177         void *                                  /* p_function_args (for user arguments) */
 178         );
 179
 180 /* ----------------------------------------------------------------------
 181  * CLIENT INTERFACE
 182  *
 183  * Clients should call only those functions below this line.
 184  * ---------------------------------------------------------------------- */
 185
 186 /* struct to hold monitor creation arguments */
 187 typedef struct _tcp_port_monitor_args_t {
 188         int     max_port_monitor_connections;   /* monitor supports tracking at most this many connections */
 189 } tcp_port_monitor_args_t;
 190
 191
 192 /* ----------------------------------
 193  * Client operations on port monitors
 194  * ---------------------------------- */
 195
 196 /* Clients should first try to "find_tcp_port_monitor" before creating one
 197    so that there are no redundant monitors. */
 198 tcp_port_monitor_t * create_tcp_port_monitor(
 199         in_port_t                       /* port_range_begin */,
 200         in_port_t                       /* port_range_end */,
 201         tcp_port_monitor_args_t *       /* p_creation_args */
 202         );
 203
 204 /* Clients use this function to get connection data from the indicated port monitor.
 205    The requested monitor value is copied into a client-supplied char buffer.
 206    Returns 0 on success, -1 otherwise. */
 207 int peek_tcp_port_monitor(
 208         const tcp_port_monitor_t *      /* p_monitor */,
 209         int                             /* item, ( item of interest, from tcp_port_monitor_peekables enum ) */,
 210         int                             /* connection_index, ( 0 to number of connections in monitor - 1 )*/,
 211         char *                          /* p_buffer, buffer to receive requested value */,
 212         size_t                          /* buffer_size, size of p_buffer */
 213         );
 214
 215 /* --------------------------------
 216  * Client operations on collections
 217  * -------------------------------- */
 218
 219 /* Create a monitor collection.  Do this one first. */
 220 tcp_port_monitor_collection_t * create_tcp_port_monitor_collection (void);
 221
 222 /* Destroy the monitor collection (and everything it contains).  Do this one last. */
 223 void destroy_tcp_port_monitor_collection(
 224         tcp_port_monitor_collection_t *         /* p_collection */
 225         );
 226
 227 /* Updates the tcp statitics for all monitors within a collection */
 228 void update_tcp_port_monitor_collection(
 229         tcp_port_monitor_collection_t *         /* p_collection */
 230         );
 231
 232 /* After clients create a monitor, use this to add it to the collection.
 233    Returns 0 on success, -1 otherwise. */
 234 int insert_tcp_port_monitor_into_collection(
 235         tcp_port_monitor_collection_t *         /* p_collection */,
 236         tcp_port_monitor_t *                    /* p_monitor */
 237         );
 238
 239 /* Clients need a way to find monitors */
 240 tcp_port_monitor_t * find_tcp_port_monitor(
 241         const tcp_port_monitor_collection_t *   /* p_collection */,
 242         in_port_t                               /* port_range_begin */,
 243         in_port_t                               /* port_range_end */
 244         );
 245
 246 #endif