source: lib/libtrace.h @ 9c87732

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

Added trace_get_transport and trace_get_transport_from_ip functions to
do generic transport layer header grabbing.
Changed all the various get_tcp, get_udp and get_icmp functions to
act as wrappers around trace_get_transport_from_ip.

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