source: lib/libtrace.h @ 803ea87

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 803ea87 was 803ea87, checked in by Shane Alcock <salcock@…>, 16 years ago

Removed rt_protocol entirely as it was becoming a real nuisance.
Critical rt_protocol components have been moved to libtrace.h

  • Property mode set to 100644
File size: 23.4 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2004 The University of Waikato, Hamilton, New Zealand.
5 * Authors: Daniel Lawson
6 *          Perry Lorier
7 *         
8 * All rights reserved.
9 *
10 * This code has been developed by the University of Waikato WAND
11 * research group. For further information please see http://www.wand.net.nz/
12 *
13 * libtrace is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * libtrace is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with libtrace; if not, write to the Free Software
25 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 *
27 * $Id$
28 *
29 */
30
31#ifndef LIBTRACE_H
32#define LIBTRACE_H
33
34/** @file
35 *
36 * @brief Trace file processing library header
37 *
38 * @author Daniel Lawson
39 * @author Perry Lorier
40 *
41 * @version $Id$
42 *
43 * This library provides a per packet interface into a trace file, or a live
44 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
45 * pcap etc.
46 *
47 * @par Usage
48 * See the example/ directory in the source distribution for some simple examples
49 * @par Linking
50 * To use this library you need to link against libtrace by passing -ltrace
51 * to your linker. You may also need to link against a version of libpcap
52 * and of zlib which are compiled for largefile support (if you wish to access
53 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
54 * Woody, at least, does not support large file offsets.
55 *
56 */
57
58#include <sys/types.h>
59#include <netinet/in.h>
60/** API version as 2 byte hex digits, eg 0xXXYYZZ */
61#define LIBTRACE_API_VERSION 0x020017  /* 2.0.23 */
62
63#ifdef __cplusplus
64extern "C" { 
65#endif
66
67/* Function does not depend on anything but its
68 * parameters, used to hint gcc's optimisations
69 */
70#if __GNUC__ >= 3
71#  define SIMPLE_FUNCTION __attribute__((pure))
72#else
73#  define SIMPLE_FUNCTION
74#endif
75       
76#define RT_DATA 1
77#define RT_MSG 2
78
79       
80/** Opaque structure holding information about an output trace */
81struct libtrace_out_t;
82       
83/** Opaque structure holding information about a trace */
84struct libtrace_t;
85       
86/** Opaque structure holding information about a bpf filter */
87struct libtrace_filter_t;
88
89/** Structure holding information about a packet */
90#define LIBTRACE_PACKET_BUFSIZE 65536
91struct libtrace_packet_t {
92        struct libtrace_t *trace;
93        //void *buffer;
94        char buffer[LIBTRACE_PACKET_BUFSIZE];
95        size_t size;
96        struct {
97                uint8_t type;
98                uint8_t reserved;
99                uint16_t message;
100        } status;
101} __attribute__ ((packed));
102                     
103
104/** Enumeration of error codes */
105enum {E_NOERROR, E_BAD_FORMAT, E_NO_INIT, E_NO_INIT_OUT, E_URI_LONG, E_URI_NOCOLON, E_INIT_FAILED };
106
107/** Structure for dealing with IP packets */
108struct libtrace_ip
109{
110#if BYTE_ORDER == LITTLE_ENDIAN
111    unsigned int ip_hl:4;               /**< header length */
112    unsigned int ip_v:4;                /**< version */
113#elif BYTE_ORDER == BIG_ENDIAN
114    unsigned int ip_v:4;                /**< version */
115    unsigned int ip_hl:4;               /**< header length */
116#else
117#   error "Adjust your <bits/endian.h> defines"
118#endif
119    u_int8_t ip_tos;                    /**< type of service */
120    u_short ip_len;                     /**< total length */
121    u_short ip_id;                      /**< identification */
122    u_short ip_off;                     /**< fragment offset field */
123#define IP_RF 0x8000                    /**< reserved fragment flag */
124#define IP_DF 0x4000                    /**< dont fragment flag */
125#define IP_MF 0x2000                    /**< more fragments flag */
126#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
127    u_int8_t ip_ttl;                    /**< time to live */
128    u_int8_t ip_p;                      /**< protocol */
129    u_short ip_sum;                     /**< checksum */
130    struct in_addr ip_src;              /**< source address */
131    struct in_addr ip_dst;              /**< dest address */
132} __attribute__ ((packed));
133
134/** Structure for dealing with TCP packets */
135struct libtrace_tcp
136  {
137    u_int16_t source;           /**< Source Port */
138    u_int16_t dest;             /**< Destination port */
139    u_int32_t seq;              /**< Sequence number */
140    u_int32_t ack_seq;          /**< Acknowledgement Number */
141#  if BYTE_ORDER == LITTLE_ENDIAN
142    u_int16_t res1:4;           /**< Reserved bits */
143    u_int16_t doff:4;           
144    u_int16_t fin:1;            /**< FIN */
145    u_int16_t syn:1;            /**< SYN flag */
146    u_int16_t rst:1;            /**< RST flag */
147    u_int16_t psh:1;            /**< PuSH flag */
148    u_int16_t ack:1;            /**< ACK flag */
149    u_int16_t urg:1;            /**< URG flag */
150    u_int16_t res2:2;           /**< Reserved */
151#  elif BYTE_ORDER == BIG_ENDIAN
152    u_int16_t doff:4;           
153    u_int16_t res1:4;           /**< Reserved bits */
154    u_int16_t res2:2;           /**< Reserved */
155    u_int16_t urg:1;            /**< URG flag */
156    u_int16_t ack:1;            /**< ACK flag */
157    u_int16_t psh:1;            /**< PuSH flag */
158    u_int16_t rst:1;            /**< RST flag */
159    u_int16_t syn:1;            /**< SYN flag */
160    u_int16_t fin:1;            /**< FIN flag */
161#  else
162#   error "Adjust your <bits/endian.h> defines"
163#  endif
164    u_int16_t window;           /**< Window Size */
165    u_int16_t check;            /**< Checksum */
166    u_int16_t urg_ptr;          /**< Urgent Pointer */
167} __attribute__ ((packed));
168
169/** UDP Header for dealing with UDP packets */
170struct libtrace_udp {
171  u_int16_t     source;         /**< Source port */
172  u_int16_t     dest;           /**< Destination port */
173  u_int16_t     len;            /**< Length */
174  u_int16_t     check;          /**< Checksum */
175} __attribute__ ((packed));
176
177/** ICMP Header for dealing with icmp packets */
178struct libtrace_icmp
179{
180  u_int8_t type;                /**< message type */
181  u_int8_t code;                /**< type sub-code */
182  u_int16_t checksum;           /**< checksum */
183  union
184  {
185    struct
186    {
187      u_int16_t id;
188      u_int16_t sequence;
189    } echo;                     /**< echo datagram */
190    u_int32_t   gateway;        /**< gateway address */
191    struct
192    {
193      u_int16_t unused;
194      u_int16_t mtu;
195    } frag;                     /**< path mtu discovery */
196  } un;                         /**< Union for payloads of various icmp codes */
197} __attribute__ ((packed));
198
199/** 802.3 frame */
200struct libtrace_ether
201{
202  u_int8_t ether_dhost[6];      /* destination ether addr */
203  u_int8_t ether_shost[6];      /* source ether addr */
204  u_int16_t ether_type;         /* packet type ID field (next-header) */
205} __attribute__ ((packed));
206
207/** 802.1Q frame */
208struct libtrace_8021q
209{
210  u_int8_t  ether_dhost[6];      /* destination eth addr */
211  u_int8_t  ether_shost[6];      /* source ether addr    */
212  u_int16_t ether_type;          /* packet type ID field , 0x8100 for VLAN */
213  u_int16_t vlan_pri:3;          /* vlan user priority */
214  u_int16_t vlan_cfi:1;          /* vlan format indicator, 0 for ethernet, 1 for token ring */
215  u_int16_t vlan_id:12;          /* vlan id */
216  u_int16_t vlan_ether_type;     /* vlan sub-packet type ID field (next-header)*/
217} __attribute__ ((packed));
218
219/** ATM cell */
220struct libtrace_atm_cell
221{
222  u_int8_t gfc:4;
223  u_int8_t vpi;
224  u_int16_t vci;
225  u_int8_t pt:3;
226  u_int8_t clp:1;
227  u_int8_t hec;
228  u_int16_t ether_type;
229};
230
231/** POS header */
232struct libtrace_pos
233{
234 u_int16_t header;
235 u_int16_t ether_type;
236};
237
238/** Prints help information for libtrace
239 *
240 * Function prints out some basic help information regarding libtrace,
241 * and then prints out the help() function registered with each input module
242 */
243void trace_help();
244
245/** Gets the output format for a given output trace
246 *
247 * @param libtrace      the output trace to get the name of the format fo
248 * @returns callee-owned null-terminated char* containing the output format
249 *
250 */
251SIMPLE_FUNCTION
252char *trace_get_output_format(const struct libtrace_out_t *libtrace);
253
254/** Prints error information
255 *
256 * Prints out a descriptive error message for the currently set trace_err value
257 */
258void trace_perror(const char *caller);
259
260/** Create a trace file from a URI
261 *
262 * @param uri containing a valid libtrace URI
263 * @returns opaque pointer to a libtrace_t
264 *
265 * Valid URI's are:
266 *  - erf:/path/to/erf/file
267 *  - erf:/path/to/erf/file.gz
268 *  - erf:/path/to/rtclient/socket
269 *  - erf:-  (stdin)
270 *  - dag:/dev/dagcard                 
271 *  - pcapint:pcapinterface                (eg: pcap:eth0)
272 *  - pcap:/path/to/pcap/file
273 *  - pcap:-
274 *  - rtclient:hostname
275 *  - rtclient:hostname:port
276 *  - wag:-
277 *  - wag:/path/to/wag/file
278 *  - wag:/path/to/wag/file.gz
279 *  - wag:/path/to/wag/socket
280 *
281 *  If an error occured when attempting to open the trace file, NULL is returned
282 *  and trace_errno is set. Use trace_perror() to get more information
283 */
284struct libtrace_t *trace_create(const char *uri);
285
286/** Creates a "dummy" trace file that has only the format type set.
287 *
288 * @returns opaque pointer to a (sparsely initialised) libtrace_t
289 *
290 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
291 * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
292 * that are not associated with a libtrace_t structure.
293 */
294struct libtrace_t *trace_create_dead(const char *uri);
295
296/** Creates a trace output file from a URI.
297 *
298 * @param uri   the uri string describing the output format and destination
299 * @returns opaque pointer to a libtrace_output_t
300 * @author Shane Alcock
301 *
302 * Valid URI's are:
303 *  - gzerf:/path/to/erf/file.gz
304 *  - gzerf:/path/to/erf/file
305 *  - rtserver:hostname
306 *  - rtserver:hostname:port
307 *
308 *  If an error occured when attempting to open the output trace, NULL is returned
309 *  and trace_errno is set. Use trace_perror() to get more information
310 */
311struct libtrace_out_t *trace_output_create(const char *uri);
312
313/** Parses an output options string and calls the appropriate function to deal with output options.
314 *
315 * @param libtrace      the output trace object to apply the options to
316 * @param options       the options string
317 * @returns -1 if option configuration failed, 0 otherwise
318 *
319 * @author Shane Alcock
320 */
321int trace_output_config(struct libtrace_out_t *libtrace, char *options);
322
323/** Close a trace file, freeing up any resources it may have been using
324 *
325 */
326void trace_destroy(struct libtrace_t *trace);
327
328/** Close a trace file, freeing up any resources it may have been using
329 * @param trace         trace file to be destroyed
330 */
331void trace_destroy_dead(struct libtrace_t *trace);
332
333/** Close a trace output file, freeing up any resources it may have been using
334 *
335 * @param trace         the output trace file to be destroyed
336 *
337 * @author Shane Alcock
338 */
339void trace_output_destroy(struct libtrace_out_t *trace);
340
341/** Read one packet from the trace into buffer
342 *
343 * @param trace         the libtrace opaque pointer
344 * @param packet        the packet opaque pointer
345 * @returns 0 on EOF, negative value on error
346 *
347 */
348int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
349
350/** Write one packet out to the output trace
351 *
352 * @param trace         the libtrace_out opaque pointer
353 * @param packet        the packet opaque pointer
354 * @returns the number of bytes written out, if zero or negative then an error has occured.
355 */
356int trace_write_packet(struct libtrace_out_t *trace, const struct libtrace_packet_t *packet);
357
358/** get a pointer to the link layer
359 * @param packet        the packet opaque pointer
360 *
361 * @returns a pointer to the link layer, or NULL if there is no link layer
362 *
363 * @note you should call getLinkType() to find out what type of link layer
364 * this is
365 */
366SIMPLE_FUNCTION
367void *trace_get_link(const struct libtrace_packet_t *packet);
368
369/** get a pointer to the IP header (if any)
370 * @param packet        the packet opaque pointer
371 *
372 * @returns a pointer to the IP header, or NULL if there is not an IP packet
373 */
374SIMPLE_FUNCTION
375struct libtrace_ip *trace_get_ip(const struct libtrace_packet_t *packet);
376
377/** get a pointer to the TCP header (if any)
378 * @param packet        the packet opaque pointer
379 *
380 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
381 */
382SIMPLE_FUNCTION
383struct libtrace_tcp *trace_get_tcp(const struct libtrace_packet_t *packet);
384
385/** get a pointer to the TCP header (if any) given a pointer to the IP header
386 * @param ip            The IP header
387 * @param[out] skipped  An output variable of the number of bytes skipped
388 *
389 * @returns a pointer to the TCP header, or NULL if this is not a TCP packet
390 *
391 * Skipped can be NULL, in which case it will be ignored by the program.
392 *
393 * @author Perry Lorier
394 */
395SIMPLE_FUNCTION
396struct libtrace_tcp *trace_get_tcp_from_ip(const struct libtrace_ip *ip,int *skipped);
397
398/** get a pointer to the UDP header (if any)
399 * @param packet        the packet opaque pointer
400 *
401 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
402 */
403SIMPLE_FUNCTION
404struct libtrace_udp *trace_get_udp(const struct libtrace_packet_t *packet);
405
406/** get a pointer to the UDP header (if any) given a pointer to the IP header
407 * @param       ip      The IP header
408 * @param[out]  skipped An output variable of the number of bytes skipped
409 *
410 * @returns a pointer to the UDP header, or NULL if this is not an UDP packet
411 *
412 * Skipped may be NULL, in which case it will be ignored by this function.
413 */
414SIMPLE_FUNCTION
415struct libtrace_udp *trace_get_udp_from_ip(const struct libtrace_ip *ip,int *skipped);
416
417/** get a pointer to the ICMP header (if any)
418 * @param packet        the packet opaque pointer
419 *
420 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
421 */
422SIMPLE_FUNCTION
423struct libtrace_icmp *trace_get_icmp(const struct libtrace_packet_t *packet);
424
425/** get a pointer to the ICMP header (if any) given a pointer to the IP header
426 * @param ip            The IP header
427 * @param[out] skipped  An output variable of the number of bytes skipped
428 *
429 * @returns a pointer to the ICMP header, or NULL if this is not an ICMP packet
430 *
431 * Skipped may be NULL, in which case it will be ignored by this function
432 */
433SIMPLE_FUNCTION
434struct libtrace_icmp *trace_get_icmp_from_ip(const struct libtrace_ip *ip,int *skipped);
435
436/** parse an ip or tcp option
437 * @param[in,out] ptr   the pointer to the current option
438 * @param[in,out] len   the length of the remaining buffer
439 * @param[out] type     the type of the option
440 * @param[out] optlen   the length of the option
441 * @param[out] data     the data of the option
442 *
443 * @returns bool true if there is another option (and the fields are filled in)
444 *               or false if this was the last option.
445 *
446 * This updates ptr to point to the next option after this one, and updates
447 * len to be the number of bytes remaining in the options area.  Type is updated
448 * to be the code of this option, and data points to the data of this option,
449 * with optlen saying how many bytes there are.
450 *
451 * @note Beware of fragmented packets.
452 */
453int trace_get_next_option(unsigned char **ptr,int *len,
454                        unsigned char *type,
455                        unsigned char *optlen,
456                        unsigned char **data);
457
458
459/** Get the current time in DAG time format
460 * @param packet        the packet opaque pointer
461 *
462 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
463 * past 1970-01-01, the lower 32bits are partial seconds)
464 * @author Daniel Lawson
465 */
466SIMPLE_FUNCTION
467uint64_t trace_get_erf_timestamp(const struct libtrace_packet_t *packet);
468
469/** Get the current time in struct timeval
470 * @param packet        the packet opaque pointer
471 *
472 * @returns time that this packet was seen in a struct timeval
473 * @author Daniel Lawson
474 * @author Perry Lorier
475 */ 
476SIMPLE_FUNCTION
477struct timeval trace_get_timeval(const struct libtrace_packet_t *packet);
478
479/** Get the current time in floating point seconds
480 * @param packet        the packet opaque pointer
481 *
482 * @returns time that this packet was seen in 64bit floating point seconds
483 * @author Daniel Lawson
484 * @author Perry Lorier
485 */
486SIMPLE_FUNCTION
487double trace_get_seconds(const struct libtrace_packet_t *packet);
488
489/** Get the size of the packet in the trace
490 * @param packet        the packet opaque pointer
491 * @returns the size of the packet in the trace
492 * @author Perry Lorier
493 * @note Due to this being a header capture, or anonymisation, this may not
494 * be the same size as the original packet.  See get_wire_length() for the original
495 * size of the packet.
496 * @note This can (and often is) different for different packets in a trace!
497 * @par
498 *  This is sometimes called the "snaplen".
499 */
500SIMPLE_FUNCTION
501int trace_get_capture_length(const struct libtrace_packet_t *packet);
502
503/** Get the size of the packet as it was seen on the wire.
504 * @param packet        the packet opaque pointer
505 * @returns the size of the packet as it was on the wire.
506 * @author Perry Lorier
507 * @author Daniel Lawson
508 * @note Due to the trace being a header capture, or anonymisation this may
509 * not be the same as the Capture Len.
510 */ 
511SIMPLE_FUNCTION
512int trace_get_wire_length(const struct libtrace_packet_t *packet);
513
514/** Get the length of the capture framing headers.
515 * @param packet        the packet opaque pointer
516 * @returns the size of the packet as it was on the wire.
517 * @author Perry Lorier
518 * @author Daniel Lawson
519 * @note this length corresponds to the difference between the size of a
520 * captured packet in memory, and the captured length of the packet
521 */ 
522SIMPLE_FUNCTION
523int trace_get_framing_length(const struct libtrace_packet_t *packet);
524
525
526/** Link layer types
527 * This enumates the various different link types that libtrace understands
528 */
529typedef enum { 
530       TRACE_TYPE_LEGACY,       
531       TRACE_TYPE_HDLC_POS, 
532       TRACE_TYPE_ETH,                  /**< 802.3 style Ethernet */
533       TRACE_TYPE_ATM,
534       TRACE_TYPE_80211,                /**< 802.11 frames */
535       TRACE_TYPE_NONE,
536       TRACE_TYPE_LINUX_SLL,            /**< Linux "null" framing */
537       TRACE_TYPE_PFLOG,                /**< FreeBSD's PFlug */
538       TRACE_TYPE_LEGACY_DEFAULT,
539       TRACE_TYPE_LEGACY_POS,
540       TRACE_TYPE_LEGACY_ATM,
541       TRACE_TYPE_LEGACY_ETH
542     } libtrace_linktype_t;
543
544/** Get the type of the link layer
545 * @param packet        the packet opaque pointer
546 * @returns libtrace_linktype_t
547 * @author Perry Lorier
548 * @author Daniel Lawson
549 */
550SIMPLE_FUNCTION
551inline libtrace_linktype_t trace_get_link_type(const struct libtrace_packet_t *packet);
552
553/** Get the destination MAC addres
554 * @param packet        the packet opaque pointer
555 * @returns a pointer to the destination mac, (or NULL if there is no
556 * destination MAC)
557 * @author Perry Lorier
558 */
559SIMPLE_FUNCTION
560uint8_t *trace_get_destination_mac(const struct libtrace_packet_t *packet);
561
562/** Get the source MAC addres
563 * @param packet        the packet opaque pointer
564 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
565 * @author Perry Lorier
566 */
567SIMPLE_FUNCTION
568uint8_t *trace_get_source_mac(const struct libtrace_packet_t *packet);
569
570/** Truncate the packet at the suggested length
571 * @param packet        the packet opaque pointer
572 * @param size          the new length of the packet
573 * @returns the new length of the packet, or the original length of the
574 * packet if unchanged
575 * @author Daniel Lawson
576 */
577size_t trace_set_capture_length(struct libtrace_packet_t *packet, size_t size);
578
579/** Set the direction flag, if it has one
580 * @param packet        the packet opaque pointer
581 * @param direction     the new direction (0,1,2,3)
582 * @returns a signed value containing the direction flag, or -1 if this is not supported
583 * @author Daniel Lawson
584 */
585int8_t trace_set_direction(struct libtrace_packet_t *packet, int8_t direction);
586
587/** Get the direction flag, if it has one
588 * @param packet        the packet opaque pointer
589 * @returns a signed value containing the direction flag, or -1 if this is not supported
590 * The direction is defined as 0 for packets originating locally (ie, outbound)
591 * and 1 for packets originating remotely (ie, inbound).
592 * Other values are possible, which might be overloaded to mean special things
593 * for a special trace.
594 * @author Daniel Lawson
595 */
596SIMPLE_FUNCTION
597int8_t trace_get_direction(const struct libtrace_packet_t *packet);
598
599/** Event types
600 * see \ref libtrace_eventobj_t and \ref trace_event
601 */
602typedef enum {
603        TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
604        TRACE_EVENT_SLEEP,      /**< Sleep for some time */
605        TRACE_EVENT_PACKET,     /**< packet has arrived */
606        TRACE_EVENT_TERMINATE   /**< End of trace */
607} libtrace_event_t;
608
609/** structure returned by libtrace_event explaining what the current event is */
610struct libtrace_eventobj_t {
611        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
612        int fd;                /**< if IOWAIT, the fd to sleep on */
613        double seconds;        /**< if SLEEP, the amount of time to sleep for */
614        int size;              /**< if PACKET, the value returned from trace_read_packet */
615};
616
617/** process a libtrace event
618 * @param trace the libtrace opaque pointer
619 * @param packet the libtrace_packet opaque pointer
620 * @returns libtrace_event struct containing the type, and potential
621 *      fd or seconds to sleep on
622 *
623 * Type can be:
624 *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
625 *  TRACE_EVENT_SLEEP   Next event in seconds
626 *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
627 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
628 */
629struct libtrace_eventobj_t trace_event(struct libtrace_t *trace,
630                struct libtrace_packet_t *packet);
631
632/** setup a BPF filter
633 * @param filterstring a char * containing the bpf filter string
634 * @returns opaque pointer pointer to a libtrace_filter_t object
635 * @author Daniel Lawson
636 * @note The filter is not actually compiled at this point, so no correctness
637 * tests are performed here. trace_bpf_setfilter will always return ok, but
638 * if the filter is poorly constructed an error will be generated when the
639 * filter is actually used
640 */
641SIMPLE_FUNCTION
642struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
643
644/** apply a BPF filter
645 * @param filter        the filter opaque pointer
646 * @param packet        the packet opaque pointer
647 * @returns 0 if the filter fails, 1 if it succeeds
648 * @author Daniel Lawson
649 * @note Due to the way BPF filters are built, the filter is not actually compiled
650 * until the first time trace_bpf_filter is called. If your filter is incorrect, it will generate an error message and assert, exiting the program. This behaviour may change to more graceful handling of this error in the future.
651 */
652int trace_bpf_filter(struct libtrace_filter_t *filter,
653                const struct libtrace_packet_t *packet);
654
655
656/** Which port is the server port */
657typedef enum {
658        USE_DEST,       /**< Destination port is the server port */
659        USE_SOURCE      /**< Source port is the server port */
660} serverport_t;
661
662/** Get the source port
663 * @param packet        the packet to read from
664 * @returns a port in \em HOST byte order, or equivilent to ports for this
665 * protocol, or 0 if this protocol has no ports.
666 * @author Perry Lorier
667 */
668SIMPLE_FUNCTION
669uint16_t trace_get_source_port(const struct libtrace_packet_t *packet);
670
671/** Get the destination port
672 * @param packet        the packet to read from
673 * @returns a port in \em HOST byte order, or equivilent to ports for this
674 * protocol, or 0 if this protocol has no ports.
675 * @author Perry Lorier
676 */
677SIMPLE_FUNCTION
678uint16_t trace_get_destination_port(const struct libtrace_packet_t *packet);
679
680/** hint at the server port in specified protocol
681 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
682 * @param source        the source port from the packet
683 * @param dest          the destination port from the packet
684 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
685 * @note ports must be in \em HOST byte order!
686 * @author Daniel Lawson
687 */
688SIMPLE_FUNCTION
689int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
690
691/** Takes a uri and splits it into a format and uridata component.
692 * Primarily for internal use but made available for external use.
693 * @param uri           the uri to be parsed
694 * @param format        destination location for the format component of the uri
695 * @returns 0 if an error occured, otherwise returns the uridata component
696 * @author Shane Alcock
697 */
698const char *trace_parse_uri(const char *uri, char **format);
699#ifdef __cplusplus
700} // extern "C"
701#endif // #ifdef __cplusplus
702#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.