source: lib/libtrace.h @ 5a67294

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 5a67294 was 5a67294, checked in by Perry Lorier <perry@…>, 16 years ago

Add typedef's

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