source: lib/libtrace.h @ 61ecfb6

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 61ecfb6 was 61ecfb6, checked in by Daniel Lawson <dlawson@…>, 16 years ago

added libpacketdump:

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