source: lib/libtrace.h @ a8a9355

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

updated changelog
added trace_get_framing_length() to return the capture-format framing (eg, ERF or pcap headers).

  • Property mode set to 100644
File size: 23.1 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/* HAVE_ATTR_PURE is replaced by autoconf */
45#define HAVE_ATTR_PURE 1
46
47/* Function does not depend on anything but its
48 * parameters, used to hint gcc's optimisations
49 */
50#if HAVE_ATTR_PURE
51#  define SIMPLE_FUNCTION __attribute__((pure))
52#else
53#  define SIMPLE_FUNCTION
54#endif
55       
56
57/** @file
58 *
59 * @brief Trace file processing library header
60 *
61 * @author Daniel Lawson
62 * @author Perry Lorier
63 *
64 * @version $Id$
65 *
66 * This library provides a per packet interface into a trace file, or a live
67 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
68 * pcap etc.
69 *
70 * @par Usage
71 * See the example/ directory in the source distribution for some simple examples
72 * @par Linking
73 * To use this library you need to link against libtrace by passing -ltrace
74 * to your linker. You may also need to link against a version of libpcap
75 * and of zlib which are compiled for largefile support (if you wish to access
76 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
77 * Woody, at least, does not support large file offsets.
78 *
79 */
80
81#define COLLECTOR_PORT 3435
82
83       
84/** Opaque structure holding information about an output trace */
85struct libtrace_out_t;
86       
87/** Opaque structure holding information about a trace */
88struct libtrace_t;
89       
90/** Opaque structure holding information about a bpf filter */
91struct libtrace_filter_t;
92
93/** Structure holding information about a packet */
94#define LIBTRACE_PACKET_BUFSIZE 65536
95struct libtrace_packet_t {
96        struct libtrace_t *trace;
97        //void *buffer;
98        char buffer[LIBTRACE_PACKET_BUFSIZE];
99        size_t size;
100        uint32_t status;
101};
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/** Prints help information for libtrace
220 *
221 * Function prints out some basic help information regarding libtrace,
222 * and then prints out the help() function registered with each input module
223 */
224void trace_help();
225
226/** Gets the output format for a given output trace
227 *
228 * @param libtrace      the output trace to get the name of the format fo
229 * @returns callee-owned null-terminated char* containing the output format
230 *
231 */
232SIMPLE_FUNCTION
233char *trace_get_output_format(const struct libtrace_out_t *libtrace);
234
235/** Prints error information
236 *
237 * Prints out a descriptive error message for the currently set trace_err value
238 */
239void trace_perror(const char *caller);
240
241/** Create a trace file from a URI
242 *
243 * @param uri containing a valid libtrace URI
244 * @returns opaque pointer to a libtrace_t
245 *
246 * Valid URI's are:
247 *  - erf:/path/to/erf/file
248 *  - erf:/path/to/erf/file.gz
249 *  - erf:/path/to/rtclient/socket
250 *  - erf:-  (stdin)
251 *  - dag:/dev/dagcard                 
252 *  - pcapint:pcapinterface                (eg: pcap:eth0)
253 *  - pcap:/path/to/pcap/file
254 *  - pcap:-
255 *  - rtclient:hostname
256 *  - rtclient:hostname:port
257 *  - wag:-
258 *  - wag:/path/to/wag/file
259 *  - wag:/path/to/wag/file.gz
260 *  - wag:/path/to/wag/socket
261 *
262 *  If an error occured when attempting to open the trace file, NULL is returned
263 *  and trace_errno is set. Use trace_perror() to get more information
264 */
265struct libtrace_t *trace_create(const char *uri);
266
267/** Creates a "dummy" trace file that has only the format type set.
268 *
269 * @returns opaque pointer to a (sparsely initialised) libtrace_t
270 *
271 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
272 * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
273 * that are not associated with a libtrace_t structure.
274 */
275struct libtrace_t *trace_create_dead(const char *uri);
276
277/** Creates a trace output file from a URI.
278 *
279 * @param uri   the uri string describing the output format and destination
280 * @returns opaque pointer to a libtrace_output_t
281 * @author Shane Alcock
282 *
283 * Valid URI's are:
284 *  - gzerf:/path/to/erf/file.gz
285 *  - gzerf:/path/to/erf/file
286 *  - rtserver:hostname
287 *  - rtserver:hostname:port
288 *
289 *  If an error occured when attempting to open the output trace, NULL is returned
290 *  and trace_errno is set. Use trace_perror() to get more information
291 */
292struct libtrace_out_t *trace_output_create(const char *uri);
293
294/** Parses an output options string and calls the appropriate function to deal with output options.
295 *
296 * @param libtrace      the output trace object to apply the options to
297 * @param options       the options string
298 * @returns -1 if option configuration failed, 0 otherwise
299 *
300 * @author Shane Alcock
301 */
302int trace_output_config(struct libtrace_out_t *libtrace, char *options);
303
304/** Close a trace file, freeing up any resources it may have been using
305 *
306 */
307void trace_destroy(struct libtrace_t *trace);
308
309/** Close a trace file, freeing up any resources it may have been using
310 * @param trace         trace file to be destroyed
311 */
312void trace_destroy_dead(struct libtrace_t *trace);
313
314/** Close a trace output file, freeing up any resources it may have been using
315 *
316 * @param trace         the output trace file to be destroyed
317 *
318 * @author Shane Alcock
319 */
320void trace_output_destroy(struct libtrace_out_t *trace);
321
322/** Read one packet from the trace into buffer
323 *
324 * @param trace         the libtrace opaque pointer
325 * @param packet        the packet opaque pointer
326 * @returns 0 on EOF, negative value on error
327 *
328 */
329int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
330
331/** Write one packet out to the output trace
332 *
333 * @param trace         the libtrace_out opaque pointer
334 * @param packet        the packet opaque pointer
335 * @returns the number of bytes written out, if zero or negative then an error has occured.
336 */
337int trace_write_packet(struct libtrace_out_t *trace, const struct libtrace_packet_t *packet);
338
339/** get a pointer to the link layer
340 * @param packet        the packet opaque pointer
341 *
342 * @returns a pointer to the link layer, or NULL if there is no link layer
343 *
344 * @note you should call getLinkType() to find out what type of link layer
345 * this is
346 */
347SIMPLE_FUNCTION
348void *trace_get_link(const struct libtrace_packet_t *packet);
349
350/** get a pointer to the IP header (if any)
351 * @param packet        the packet opaque pointer
352 *
353 * @returns a pointer to the IP header, or NULL if there is not an IP packet
354 */
355SIMPLE_FUNCTION
356struct libtrace_ip *trace_get_ip(const struct libtrace_packet_t *packet);
357
358/** get a pointer to the TCP header (if any)
359 * @param packet        the packet opaque pointer
360 *
361 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
362 */
363SIMPLE_FUNCTION
364struct libtrace_tcp *trace_get_tcp(const struct libtrace_packet_t *packet);
365
366/** get a pointer to the TCP header (if any) given a pointer to the IP header
367 * @param ip            The IP header
368 * @param[out] skipped  An output variable of the number of bytes skipped
369 *
370 * @returns a pointer to the TCP header, or NULL if this is not a TCP packet
371 *
372 * Skipped can be NULL, in which case it will be ignored by the program.
373 *
374 * @author Perry Lorier
375 */
376SIMPLE_FUNCTION
377struct libtrace_tcp *trace_get_tcp_from_ip(const struct libtrace_ip *ip,int *skipped);
378
379/** get a pointer to the UDP header (if any)
380 * @param packet        the packet opaque pointer
381 *
382 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
383 */
384SIMPLE_FUNCTION
385struct libtrace_udp *trace_get_udp(const struct libtrace_packet_t *packet);
386
387/** get a pointer to the UDP header (if any) given a pointer to the IP header
388 * @param       ip      The IP header
389 * @param[out]  skipped An output variable of the number of bytes skipped
390 *
391 * @returns a pointer to the UDP header, or NULL if this is not an UDP packet
392 *
393 * Skipped may be NULL, in which case it will be ignored by this function.
394 */
395SIMPLE_FUNCTION
396struct libtrace_udp *trace_get_udp_from_ip(const struct libtrace_ip *ip,int *skipped);
397
398/** get a pointer to the ICMP header (if any)
399 * @param packet        the packet opaque pointer
400 *
401 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
402 */
403SIMPLE_FUNCTION
404struct libtrace_icmp *trace_get_icmp(const struct libtrace_packet_t *packet);
405
406/** get a pointer to the ICMP 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 ICMP header, or NULL if this is not an ICMP packet
411 *
412 * Skipped may be NULL, in which case it will be ignored by this function
413 */
414SIMPLE_FUNCTION
415struct libtrace_icmp *trace_get_icmp_from_ip(const struct libtrace_ip *ip,int *skipped);
416
417/** parse an ip or tcp option
418 * @param[in,out] ptr   the pointer to the current option
419 * @param[in,out] len   the length of the remaining buffer
420 * @param[out] type     the type of the option
421 * @param[out] optlen   the length of the option
422 * @param[out] data     the data of the option
423 *
424 * @returns bool true if there is another option (and the fields are filled in)
425 *               or false if this was the last option.
426 *
427 * This updates ptr to point to the next option after this one, and updates
428 * len to be the number of bytes remaining in the options area.  Type is updated
429 * to be the code of this option, and data points to the data of this option,
430 * with optlen saying how many bytes there are.
431 *
432 * @note Beware of fragmented packets.
433 */
434int trace_get_next_option(unsigned char **ptr,int *len,
435                        unsigned char *type,
436                        unsigned char *optlen,
437                        unsigned char **data);
438
439
440/** Get the current time in DAG time format
441 * @param packet        the packet opaque pointer
442 *
443 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
444 * past 1970-01-01, the lower 32bits are partial seconds)
445 * @author Daniel Lawson
446 */
447SIMPLE_FUNCTION
448uint64_t trace_get_erf_timestamp(const struct libtrace_packet_t *packet);
449
450/** Get the current time in struct timeval
451 * @param packet        the packet opaque pointer
452 *
453 * @returns time that this packet was seen in a struct timeval
454 * @author Daniel Lawson
455 * @author Perry Lorier
456 */ 
457SIMPLE_FUNCTION
458struct timeval trace_get_timeval(const struct libtrace_packet_t *packet);
459
460/** Get the current time in floating point seconds
461 * @param packet        the packet opaque pointer
462 *
463 * @returns time that this packet was seen in 64bit floating point seconds
464 * @author Daniel Lawson
465 * @author Perry Lorier
466 */
467SIMPLE_FUNCTION
468double trace_get_seconds(const struct libtrace_packet_t *packet);
469
470/** Get the size of the packet in the trace
471 * @param packet        the packet opaque pointer
472 * @returns the size of the packet in the trace
473 * @author Perry Lorier
474 * @note Due to this being a header capture, or anonymisation, this may not
475 * be the same size as the original packet.  See get_wire_length() for the original
476 * size of the packet.
477 * @note This can (and often is) different for different packets in a trace!
478 * @par
479 *  This is sometimes called the "snaplen".
480 */
481SIMPLE_FUNCTION
482int trace_get_capture_length(const struct libtrace_packet_t *packet);
483
484/** Get the size of the packet as it was seen on the wire.
485 * @param packet        the packet opaque pointer
486 * @returns the size of the packet as it was on the wire.
487 * @author Perry Lorier
488 * @author Daniel Lawson
489 * @note Due to the trace being a header capture, or anonymisation this may
490 * not be the same as the Capture Len.
491 */ 
492SIMPLE_FUNCTION
493int trace_get_wire_length(const struct libtrace_packet_t *packet);
494
495/** Get the length of the capture framing headers.
496 * @param packet        the packet opaque pointer
497 * @returns the size of the packet as it was on the wire.
498 * @author Perry Lorier
499 * @author Daniel Lawson
500 * @note this length corresponds to the difference between the size of a
501 * captured packet in memory, and the captured length of the packet
502 */ 
503SIMPLE_FUNCTION
504int trace_get_framing_length(const struct libtrace_packet_t *packet);
505
506
507/** Link layer types
508 * This enumates the various different link types that libtrace understands
509 */
510typedef enum { 
511       TRACE_TYPE_LEGACY,       
512       TRACE_TYPE_HDLC_POS, 
513       TRACE_TYPE_ETH,                  /**< 802.3 style Ethernet */
514       TRACE_TYPE_ATM,
515       TRACE_TYPE_80211,                /**< 802.11 frames */
516       TRACE_TYPE_NONE,
517       TRACE_TYPE_LINUX_SLL,            /**< Linux "null" framing */
518       TRACE_TYPE_PFLOG,                /**< FreeBSD's PFlug */
519       TRACE_TYPE_LEGACY_DEFAULT,
520       TRACE_TYPE_LEGACY_POS,
521       TRACE_TYPE_LEGACY_ATM,
522       TRACE_TYPE_LEGACY_ETH
523     } libtrace_linktype_t;
524
525/** Get the type of the link layer
526 * @param packet        the packet opaque pointer
527 * @returns libtrace_linktype_t
528 * @author Perry Lorier
529 * @author Daniel Lawson
530 */
531SIMPLE_FUNCTION
532inline libtrace_linktype_t trace_get_link_type(const struct libtrace_packet_t *packet);
533
534/** Get the destination MAC addres
535 * @param packet        the packet opaque pointer
536 * @returns a pointer to the destination mac, (or NULL if there is no
537 * destination MAC)
538 * @author Perry Lorier
539 */
540SIMPLE_FUNCTION
541uint8_t *trace_get_destination_mac(const struct libtrace_packet_t *packet);
542
543/** Get the source MAC addres
544 * @param packet        the packet opaque pointer
545 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
546 * @author Perry Lorier
547 */
548SIMPLE_FUNCTION
549uint8_t *trace_get_source_mac(const struct libtrace_packet_t *packet);
550
551/** Truncate the packet at the suggested length
552 * @param packet        the packet opaque pointer
553 * @param size          the new length of the packet
554 * @returns the new length of the packet, or the original length of the
555 * packet if unchanged
556 * @author Daniel Lawson
557 */
558size_t trace_set_capture_length(struct libtrace_packet_t *packet, size_t size);
559
560/** Set the direction flag, if it has one
561 * @param packet        the packet opaque pointer
562 * @param direction     the new direction (0,1,2,3)
563 * @returns a signed value containing the direction flag, or -1 if this is not supported
564 * @author Daniel Lawson
565 */
566int8_t trace_set_direction(struct libtrace_packet_t *packet, int8_t direction);
567
568/** Get the direction flag, if it has one
569 * @param packet        the packet opaque pointer
570 * @returns a signed value containing the direction flag, or -1 if this is not supported
571 * The direction is defined as 0 for packets originating locally (ie, outbound)
572 * and 1 for packets originating remotely (ie, inbound).
573 * Other values are possible, which might be overloaded to mean special things
574 * for a special trace.
575 * @author Daniel Lawson
576 */
577SIMPLE_FUNCTION
578int8_t trace_get_direction(const struct libtrace_packet_t *packet);
579
580/** Event types
581 * see \ref libtrace_eventobj_t and \ref trace_event
582 */
583typedef enum {
584        TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
585        TRACE_EVENT_SLEEP,      /**< Sleep for some time */
586        TRACE_EVENT_PACKET,     /**< packet has arrived */
587        TRACE_EVENT_TERMINATE   /**< End of trace */
588} libtrace_event_t;
589
590/** structure returned by libtrace_event explaining what the current event is */
591struct libtrace_eventobj_t {
592        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
593        int fd;                /**< if IOWAIT, the fd to sleep on */
594        double seconds;        /**< if SLEEP, the amount of time to sleep for */
595        int size;              /**< if PACKET, the value returned from trace_read_packet */
596};
597
598/** process a libtrace event
599 * @param trace the libtrace opaque pointer
600 * @param packet the libtrace_packet opaque pointer
601 * @returns libtrace_event struct containing the type, and potential
602 *      fd or seconds to sleep on
603 *
604 * Type can be:
605 *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
606 *  TRACE_EVENT_SLEEP   Next event in seconds
607 *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
608 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
609 */
610struct libtrace_eventobj_t trace_event(struct libtrace_t *trace,
611                struct libtrace_packet_t *packet);
612
613/** setup a BPF filter
614 * @param filterstring a char * containing the bpf filter string
615 * @returns opaque pointer pointer to a libtrace_filter_t object
616 * @author Daniel Lawson
617 * @note The filter is not actually compiled at this point, so no correctness
618 * tests are performed here. trace_bpf_setfilter will always return ok, but
619 * if the filter is poorly constructed an error will be generated when the
620 * filter is actually used
621 */
622SIMPLE_FUNCTION
623struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
624
625/** apply a BPF filter
626 * @param filter        the filter opaque pointer
627 * @param packet        the packet opaque pointer
628 * @returns 0 if the filter fails, 1 if it succeeds
629 * @author Daniel Lawson
630 * @note Due to the way BPF filters are built, the filter is not actually compiled
631 * 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.
632 */
633int trace_bpf_filter(struct libtrace_filter_t *filter,
634                const struct libtrace_packet_t *packet);
635
636
637/** Which port is the server port */
638typedef enum {
639        USE_DEST,       /**< Destination port is the server port */
640        USE_SOURCE      /**< Source port is the server port */
641} serverport_t;
642
643/** Get the source port
644 * @param packet        the packet to read from
645 * @returns a port in \em HOST byte order, or equivilent to ports for this
646 * protocol, or 0 if this protocol has no ports.
647 * @author Perry Lorier
648 */
649SIMPLE_FUNCTION
650uint16_t trace_get_source_port(const struct libtrace_packet_t *packet);
651
652/** Get the destination port
653 * @param packet        the packet to read from
654 * @returns a port in \em HOST byte order, or equivilent to ports for this
655 * protocol, or 0 if this protocol has no ports.
656 * @author Perry Lorier
657 */
658SIMPLE_FUNCTION
659uint16_t trace_get_destination_port(const struct libtrace_packet_t *packet);
660
661/** hint at the server port in specified protocol
662 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
663 * @param source        the source port from the packet
664 * @param dest          the destination port from the packet
665 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
666 * @note ports must be in \em HOST byte order!
667 * @author Daniel Lawson
668 */
669SIMPLE_FUNCTION
670int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
671
672/** Takes a uri and splits it into a format and uridata component.
673 * Primarily for internal use but made available for external use.
674 * @param uri           the uri to be parsed
675 * @param format        destination location for the format component of the uri
676 * @returns 0 if an error occured, otherwise returns the uridata component
677 * @author Shane Alcock
678 */
679const char *trace_parse_uri(const char *uri, char **format);
680#ifdef __cplusplus
681} // extern "C"
682#endif // #ifdef __cplusplus
683#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.