1 /* -------------------------------------------------------------------------
2 * libtcp-portmon.h: tcp port monitoring library.
4 * Copyright (C) 2005 Philip Kovacs kovacsp3@comcast.net
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.
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.
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 USA
21 * --------------------------------------------------------------------------- */
23 #ifndef LIBTCP_PORTMON_H
24 #define LIBTCP_PORTMON_H
26 #include <sys/types.h>
27 #include <sys/socket.h>
29 #include <arpa/inet.h>
30 #include <netinet/in.h>
31 #include <netinet/tcp.h>
41 #define TCP_CONNECTION_STARTING_AGE 1 /* connection deleted if unseen again after this # of refreshes */
42 #define TCP_CONNECTION_HASH_KEY_SIZE 28
43 #define TCP_PORT_MONITOR_HASH_KEY_SIZE 12
45 /* -------------------------------------------------------------------
46 * IMPLEMENTATION INTERFACE
48 * Implementation-specific interface begins here. Clients should not
49 * manipulate these structures directly, nor call the defined helper
50 * functions. Use the "Client interface" functions defined at bottom.
51 * ------------------------------------------------------------------- */
53 /* The inventory of peekable items within the port monitor. */
54 enum tcp_port_monitor_peekables {
66 /* ------------------------------------------------------------------------
67 * A single tcp connection
69 * The age variable provides the mechanism for removing connections if they
70 * are not seen again in subsequent update cycles.
71 * ------------------------------------------------------------------------ */
72 typedef struct _tcp_connection_t {
73 gchar key[TCP_CONNECTION_HASH_KEY_SIZE]; /* connection's key in monitor hash */
76 in_addr_t remote_addr;
77 in_port_t remote_port;
81 /* ----------------------------------
84 * Returns 0 on success, -1 otherwise
85 * ----------------------------------*/
86 int copy_tcp_connection(
87 tcp_connection_t * /* p_dest_connection */,
88 const tcp_connection_t * /* p_source_connection */
91 /* ------------------------------------------------------------------------
92 * A tcp connection node/list
94 * Connections within each monitor are stored in a double-linked list.
95 * ------------------------------------------------------------------------ */
96 typedef struct _tcp_connection_node_t {
97 tcp_connection_t connection;
98 struct _tcp_connection_node_t * p_prev;
99 struct _tcp_connection_node_t * p_next;
100 } tcp_connection_node_t;
102 typedef struct _tcp_connection_list_t {
103 tcp_connection_node_t * p_head;
104 tcp_connection_node_t * p_tail;
105 } tcp_connection_list_t;
110 typedef struct _tcp_port_monitor_t {
111 gchar key[TCP_PORT_MONITOR_HASH_KEY_SIZE]; /* monitor's key in collection hash */
112 in_port_t port_range_begin; /* start of monitor port range */
113 in_port_t port_range_end; /* begin = end to monitor a single port */
114 tcp_connection_list_t connection_list; /* list of connections for this monitor */
115 GHashTable *hash; /* hash table of pointers into connection list */
116 tcp_connection_t **p_peek; /* array of connection pointers for O(1) peeking */
117 unsigned int max_port_monitor_connections; /* max number of connections */
118 } tcp_port_monitor_t;
120 /* ------------------------
121 * A port monitor node/list
122 * ------------------------ */
123 typedef struct _tcp_port_monitor_node_t {
124 tcp_port_monitor_t * p_monitor;
125 struct _tcp_port_monitor_node_t *p_next;
126 } tcp_port_monitor_node_t;
128 typedef struct __tcp_port_monitor_list_t {
129 tcp_port_monitor_node_t * p_head;
130 tcp_port_monitor_node_t * p_tail;
131 } tcp_port_monitor_list_t;
133 /* ---------------------------------------
134 * A port monitor utility function typedef
135 * ---------------------------------------*/
136 typedef void (*tcp_port_monitor_function_ptr_t)( tcp_port_monitor_t * /* p_monitor */, void * /* p_void */ );
138 /* ---------------------------------------------------------------------------
139 * Port monitor utility functions implementing tcp_port_monitor_function_ptr_t
140 * ---------------------------------------------------------------------------*/
141 void destroy_tcp_port_monitor(
142 tcp_port_monitor_t * /* p_monitor */,
143 void * /* p_void (use NULL for this function) */
146 void age_tcp_port_monitor(
147 tcp_port_monitor_t * /* p_monitor */,
148 void * /* p_void (use NULL for this function) */
151 void rebuild_tcp_port_monitor_peek_table(
152 tcp_port_monitor_t * /* p_monitor */,
153 void * /* p_void (use NULL for this function) */
156 void show_connection_to_tcp_port_monitor(
157 tcp_port_monitor_t * /* p_monitor */,
158 void * /* p_connection (client should cast) */
161 /* -----------------------------
162 * A tcp port monitor collection
163 * -----------------------------*/
164 typedef struct _tcp_port_monitor_collection_t {
165 tcp_port_monitor_list_t monitor_list; /* list of monitors for this collection */
166 GHashTable *hash; /* hash table of pointers into collection's monitor list */
167 } tcp_port_monitor_collection_t;
169 /* ---------------------------------------------------------------------------------------
170 * Apply a tcp_port_monitor_function_ptr_t function to each port monitor in the collection.
171 * ---------------------------------------------------------------------------------------*/
172 void for_each_tcp_port_monitor_in_collection(
173 tcp_port_monitor_collection_t * /* p_collection */,
174 tcp_port_monitor_function_ptr_t /* p_function */,
175 void * /* p_function_args (for user arguments) */
178 /* ----------------------------------------------------------------------
181 * Clients should call only those functions below this line.
182 * ---------------------------------------------------------------------- */
184 /* struct to hold monitor creation arguments */
185 typedef struct _tcp_port_monitor_args_t {
186 int max_port_monitor_connections; /* monitor supports tracking at most this many connections */
187 } tcp_port_monitor_args_t;
190 /* ----------------------------------
191 * Client operations on port monitors
192 * ---------------------------------- */
194 /* Clients should first try to "find_tcp_port_monitor" before creating one
195 so that there are no redundant monitors. */
196 tcp_port_monitor_t * create_tcp_port_monitor(
197 in_port_t /* port_range_begin */,
198 in_port_t /* port_range_end */,
199 tcp_port_monitor_args_t * /* p_creation_args */
202 /* Clients use this function to get connection data from the indicated port monitor.
203 The requested monitor value is copied into a client-supplied char buffer.
204 Returns 0 on success, -1 otherwise. */
205 int peek_tcp_port_monitor(
206 const tcp_port_monitor_t * /* p_monitor */,
207 int /* item, ( item of interest, from tcp_port_monitor_peekables enum ) */,
208 int /* connection_index, ( 0 to number of connections in monitor - 1 )*/,
209 char * /* p_buffer, buffer to receive requested value */,
210 size_t /* buffer_size, size of p_buffer */
213 /* --------------------------------
214 * Client operations on collections
215 * -------------------------------- */
217 /* Create a monitor collection. Do this one first. */
218 tcp_port_monitor_collection_t * create_tcp_port_monitor_collection (void);
220 /* Destroy the monitor collection (and everything it contains). Do this one last. */
221 void destroy_tcp_port_monitor_collection(
222 tcp_port_monitor_collection_t * /* p_collection */
225 /* Updates the tcp statitics for all monitors within a collection */
226 void update_tcp_port_monitor_collection(
227 tcp_port_monitor_collection_t * /* p_collection */
230 /* After clients create a monitor, use this to add it to the collection.
231 Returns 0 on success, -1 otherwise. */
232 int insert_tcp_port_monitor_into_collection(
233 tcp_port_monitor_collection_t * /* p_collection */,
234 tcp_port_monitor_t * /* p_monitor */
237 /* Clients need a way to find monitors */
238 tcp_port_monitor_t * find_tcp_port_monitor(
239 const tcp_port_monitor_collection_t * /* p_collection */,
240 in_port_t /* port_range_begin */,
241 in_port_t /* port_range_end */