source: lib/libtrace.h.in @ 82facc5

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 82facc5 was 82facc5, checked in by Richard Sanger <rsangerarj@…>, 7 years ago

Adds a thread keepalive that sends a messages to the perpkt threads every second(still todo make this configurable)
Updated tracertstats to use this rather than the temporary result system which has been removed
Also fixes a handful of compile warnings

  • Property mode set to 100644
File size: 133.0 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
7 * Authors: Daniel Lawson
8 *          Perry Lorier
9 *          Shane Alcock
10 *         
11 * All rights reserved.
12 *
13 * This code has been developed by the University of Waikato WAND
14 * research group. For further information please see http://www.wand.net.nz/
15 *
16 * libtrace is free software; you can redistribute it and/or modify
17 * it under the terms of the GNU General Public License as published by
18 * the Free Software Foundation; either version 2 of the License, or
19 * (at your option) any later version.
20 *
21 * libtrace is distributed in the hope that it will be useful,
22 * but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24 * GNU General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with libtrace; if not, write to the Free Software
28 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29 *
30 * $Id$
31 *
32 */
33
34#ifndef LIBTRACE_H
35#define LIBTRACE_H
36
37/** @file
38 *
39 * @brief Trace file processing library header
40 *
41 * @author Daniel Lawson
42 * @author Perry Lorier
43 * @author Shane Alcock
44 *
45 * @version $Id$
46 *
47 * This library provides a per packet interface into a trace file, or a live
48 * captures.  It supports ERF, DAG cards, PCAP, Linux and BSD native sockets,
49 * legacy ERF formats etc.
50 *
51 * @par Usage
52 * See the example/ directory in the source distribution for some simple
53 * examples
54 *
55 * @par Linking
56 * To use this library you need to link against libtrace by passing -ltrace
57 * to your linker. You may also need to link against a version of libpcap
58 * and of zlib which are compiled for largefile support (if you wish to access
59 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
60 * Woody, at least, does not support large file offsets.
61 *
62 */
63
64#include <sys/types.h>
65#ifndef WIN32
66#include <sys/time.h>
67#endif
68
69/* Deal with missing byte order macros */
70#include <sys/param.h>
71
72#if defined(BYTE_ORDER) && !defined(__BYTE_ORDER)
73#define __BYTE_ORDER    BYTE_ORDER
74#endif
75
76#if defined(BIG_ENDIAN) && !defined(__BIG_ENDIAN)
77#define __BIG_ENDIAN    BIG_ENDIAN
78#endif
79
80#if defined(LITTLE_ENDIAN) && !defined(__LITTLE_ENDIAN)
81#define __LITTLE_ENDIAN LITTLE_ENDIAN
82#endif
83
84#ifdef _MSC_VER
85    /* define the following from MSVC's internal types */
86    typedef             __int8  int8_t;
87    typedef             __int16 int16_t;
88    typedef             __int32 int32_t;
89    typedef             __int64 int64_t;
90    typedef unsigned    __int8  uint8_t;
91    typedef unsigned    __int16 uint16_t;
92    typedef unsigned    __int32 uint32_t;
93    typedef unsigned    __int64 uint64_t;
94    #ifdef LT_BUILDING_DLL
95        #define DLLEXPORT __declspec(dllexport)
96    #else
97        #define DLLEXPORT __declspec(dllimport)
98    #endif
99    #define DLLLOCAL
100    /* Windows pads bitfields out to to the size of their parent type
101     * however gcc warns that this doesn't meet with the iso C specification
102     * so produces warnings for this behaviour.  sigh.
103     */
104    #define LT_BITFIELD8        uint8_t
105    #define LT_BITFIELD16       uint16_t
106    #define LT_BITFIELD32       uint32_t
107    #define LT_BITFIELD64       uint64_t
108#else
109    #ifdef HAVE_STDINT_H
110        #   include <stdint.h>
111    #endif
112    #if __GNUC__ >= 4
113        #ifdef LT_BUILDING_DLL
114                #define DLLEXPORT __attribute__ ((visibility("default")))
115                #define DLLLOCAL __attribute__ ((visibility("hidden")))
116        #else
117                #define DLLEXPORT
118                #define DLLLOCAL
119        #endif
120    #else
121        #define DLLEXPORT
122        #define DLLLOCAL
123    #endif
124    /* GCC warns if the bitfield type is not "unsigned int", however windows
125     * generates incorrect code for this (see above), so we define these
126     * macros.  How Hideous.  So much for C's portability.
127     */
128    #define LT_BITFIELD8        unsigned int
129    #define LT_BITFIELD16       unsigned int
130    #define LT_BITFIELD32       unsigned int
131    #define LT_BITFIELD64       unsigned int
132#endif
133
134#ifdef WIN32
135#   include <winsock2.h>
136#   include <ws2tcpip.h>
137    typedef short sa_family_t;
138    /* Make up for a lack of stdbool.h */
139#    define bool signed char
140#    define false 0
141#    define true 1
142#    if !defined(ssize_t)
143     /* XXX: Not 64-bit safe! */
144#    define ssize_t int
145#    endif   
146#else
147#    include <netinet/in.h>
148
149#ifndef __cplusplus
150#    include <stdbool.h>
151#endif
152
153#    include <sys/types.h>
154#    include <sys/socket.h>
155#endif
156
157/** API version as 2 byte hex digits, eg 0xXXYYZZ */
158#define LIBTRACE_API_VERSION \
159            ((@LIBTRACE_MAJOR@<<16)|(@LIBTRACE_MID@<<8)|(@LIBTRACE_MINOR@))
160
161/** Replaced with the current SVN revision number when 'make dist' is invoked
162 *  to create a distributable tarball */
163#define LIBTRACE_SVN_REVISION 0
164
165/** DAG driver version installed on the current system */
166#define DAG_DRIVER_V "@DAG_VERSION_NUM@"
167   
168#ifdef __cplusplus
169extern "C" {
170#endif
171
172/* Function does not depend on anything but its
173 * parameters, used to hint gcc's optimisations
174 */
175#if __GNUC__ >= 3
176#  define DEPRECATED __attribute__((deprecated))
177#  define SIMPLE_FUNCTION __attribute__((pure))
178#  define UNUSED __attribute__((unused))
179#  define PACKED __attribute__((packed))
180#  define PRINTF(formatpos,argpos) __attribute__((format(printf,formatpos,argpos)))
181#else
182#  define DEPRECATED
183#  define SIMPLE_FUNCTION
184#  define UNUSED
185#  define PACKED
186#  define PRINTF(formatpos,argpos)
187#endif
188       
189/** Opaque structure holding information about an output trace */
190typedef struct libtrace_out_t libtrace_out_t;
191       
192/** Opaque structure holding information about a trace */
193typedef struct libtrace_t libtrace_t;
194       
195/** Opaque structure holding information about a bpf filter */
196typedef struct libtrace_filter_t libtrace_filter_t;
197
198/** Structure holding information about a result */
199typedef struct libtrace_result_t {
200        uint64_t key;
201        void * value;
202        int is_packet;
203} libtrace_result_t;
204
205typedef struct libtrace_message_t libtrace_message_t;
206
207typedef struct libtrace_thread_t libtrace_thread_t;
208
209/** If the packet has allocated its own memory the buffer_control should be
210 * set to TRACE_CTRL_PACKET, so that the memory will be freed when the packet
211 * is destroyed. If the packet has been zerocopied out of memory owned by
212 * something else, e.g. a DAG card, it should be TRACE_CTRL_EXTERNAL.
213 *
214 * @note The letters p and e are magic numbers used to detect if the packet
215 * wasn't created properly.
216 */
217typedef enum {
218        TRACE_CTRL_PACKET='p',  /**< Buffer memory is owned by the packet */
219        TRACE_CTRL_EXTERNAL='e' /**< Buffer memory is owned by an external source */
220} buf_control_t;
221
222/** The size of a packet's buffer when managed by libtrace */
223#define LIBTRACE_PACKET_BUFSIZE 65536
224
225/** Libtrace error information */
226typedef struct trace_err_t{
227        int err_num;            /**< error code */
228        char problem[255];      /**< the format, uri etc that caused the error for reporting purposes */
229} libtrace_err_t;
230
231/** Enumeration of error codes */
232enum {
233        /** No Error has occured.... yet. */
234        TRACE_ERR_NOERROR       = 0,
235        /** The URI passed to trace_create() is unsupported, or badly formed */
236        TRACE_ERR_BAD_FORMAT    = -1,
237        /** The trace failed to initialise */
238        TRACE_ERR_INIT_FAILED   = -2,
239        /** Unknown config option */
240        TRACE_ERR_UNKNOWN_OPTION= -3,
241        /** This output uri cannot write packets of this type */
242        TRACE_ERR_NO_CONVERSION = -4,
243        /** This packet is corrupt, or unusable for the action required */
244        TRACE_ERR_BAD_PACKET    = -5,
245        /** Option known, but unsupported by this format */
246        TRACE_ERR_OPTION_UNAVAIL= -6,
247        /** This feature is unsupported */
248        TRACE_ERR_UNSUPPORTED   = -7,
249        /** Illegal use of the API */
250        TRACE_ERR_BAD_STATE     = -8,
251        /** Failed to compile a BPF filter */
252        TRACE_ERR_BAD_FILTER    = -9,
253        /** RT communication breakdown */
254        TRACE_ERR_RT_FAILURE    = -10,
255        /** Compression format unsupported */
256        TRACE_ERR_UNSUPPORTED_COMPRESS  = -11
257};
258
259/** Enumeration of DLTs supported by libtrace
260 */
261typedef enum {
262        /* Special value used to indicate a failure to convert to libtrace
263         * DLT */
264        TRACE_DLT_ERROR = -1,
265       
266        /** pcap documents this as having the Address Family value in host byte order as the
267          * framing.  Ugly? Yes.
268          */
269        TRACE_DLT_NULL = 0,
270        TRACE_DLT_EN10MB = 1,
271        TRACE_DLT_PPP = 9,
272        TRACE_DLT_ATM_RFC1483 = 11,
273       
274        /** Ok, so OpenBSD has a different value for DLT_RAW as the rest of the planet, so detect
275          * this.  When reading to/from files we should be using TRACE_DLT_LINKTYPE_RAW instead.
276          * When talking about DLT's inside libtrace tho, we should be using /these/ DLT's.
277          */
278#ifdef __OpenBSD__
279        TRACE_DLT_OPENBSD_LOOP=12,
280        TRACE_DLT_RAW = 14,     
281#else
282        TRACE_DLT_RAW = 12,
283        TRACE_DLT_OPENBSD_LOOP = 108,
284#endif
285        TRACE_DLT_PPP_SERIAL = 50,
286        TRACE_DLT_LINKTYPE_RAW = 101, /**< See TRACE_DLT_RAW for explainations of pain. */
287        TRACE_DLT_C_HDLC = 104,
288        TRACE_DLT_IEEE802_11 = 105,
289        TRACE_DLT_LINUX_SLL = 113,
290        TRACE_DLT_PFLOG = 117,
291        TRACE_DLT_IEEE802_11_RADIO = 127 /**< Radiotap */
292} libtrace_dlt_t ;
293
294/** Enumeration of link layer types supported by libtrace */
295typedef enum {
296       TRACE_TYPE_UNKNOWN = -1,         /**< Unable to determine link type */
297    /* TRACE_TYPE_LEGACY = 0            Obsolete */
298       TRACE_TYPE_HDLC_POS = 1,         /**< HDLC over POS */
299       TRACE_TYPE_ETH = 2,              /**< 802.3 style Ethernet */
300       TRACE_TYPE_ATM = 3,              /**< ATM frame */
301       TRACE_TYPE_80211 = 4,            /**< 802.11 frames */
302       TRACE_TYPE_NONE = 5,             /**< Raw IP frames */
303       TRACE_TYPE_LINUX_SLL = 6,        /**< Linux "null" framing */
304       TRACE_TYPE_PFLOG = 7,            /**< FreeBSD's PFlog */
305    /* TRACE_TYPE_LEGACY_DEFAULT        Obsolete */
306       TRACE_TYPE_POS = 9,              /**< Packet-over-SONET */
307    /* TRACE_TYPE_LEGACY_ATM            Obsolete */
308    /* TRACE_TYPE_LEGACY_ETH            Obsolete */
309       TRACE_TYPE_80211_PRISM = 12,     /**< 802.11 Prism frames */
310       TRACE_TYPE_AAL5 = 13,            /**< ATM Adaptation Layer 5 frames */
311       TRACE_TYPE_DUCK = 14,         /**< Pseudo link layer for DUCK packets */
312       TRACE_TYPE_80211_RADIO = 15,  /**< Radiotap + 802.11 */
313       TRACE_TYPE_LLCSNAP = 16,      /**< Raw LLC/SNAP */
314       TRACE_TYPE_PPP = 17,          /**< PPP frames */
315       TRACE_TYPE_METADATA = 18,        /**< WDCAP-style meta-data */
316       TRACE_TYPE_NONDATA = 19,         /**< Not a data packet */
317       TRACE_TYPE_OPENBSD_LOOP = 20     /**< OpenBSD loopback */
318} libtrace_linktype_t;
319
320/** RT protocol base format identifiers.
321 * This is used to describe the capture format of the packet is being sent
322 * using the RT protocol.
323 */
324enum base_format_t {
325        TRACE_FORMAT_ERF          =1,   /**< ERF (DAG capture format) */
326        TRACE_FORMAT_PCAP         =2,   /**< Live PCAP capture */
327        TRACE_FORMAT_PCAPFILE     =3,   /**< PCAP trace file */
328        TRACE_FORMAT_WAG          =4,   /**< WAG live capture (Obsolete) */
329        TRACE_FORMAT_RT           =5,   /**< RT network protocol */
330        TRACE_FORMAT_LEGACY_ATM   =6,   /**< Legacy ERF for ATM capture */
331        TRACE_FORMAT_LEGACY_POS   =7,   /**< Legacy ERF for POS capture */
332        TRACE_FORMAT_LEGACY_ETH   =8,   /**< Legacy ERF for ETH capture */
333        TRACE_FORMAT_LINUX_NATIVE =9,   /**< Linux native interface capture */
334        TRACE_FORMAT_DUCK         =10,  /**< DAG Clock information */
335        TRACE_FORMAT_BPF          =11,  /**< BSD native interface capture */
336        TRACE_FORMAT_TSH          =12,  /**< TSH trace format */
337        TRACE_FORMAT_ATMHDR       =13,  /**< Legacy ATM header capture */
338        TRACE_FORMAT_LEGACY_NZIX  =14,  /**< Legacy format used for NZIX traces */
339        TRACE_FORMAT_LINUX_RING   =15,  /**< Linux native interface capture PACKET_MMAP */
340        TRACE_FORMAT_RAWERF       =16,  /**< Special format for reading uncompressed ERF traces without checking for compression */
341    TRACE_FORMAT_DPDK     =17, /**< The Intel Data Plane Development Kit format */
342};
343
344/** RT protocol packet types */
345typedef enum {
346        TRACE_RT_HELLO          =1, /**< Connection accepted */
347        TRACE_RT_START          =2, /**< Request for data transmission to begin
348                                    */
349        TRACE_RT_ACK            =3, /**< Data acknowledgement */
350        TRACE_RT_STATUS         =4, /**< Fifo status packet */
351        TRACE_RT_DUCK           =5, /**< Dag duck info packet */
352        TRACE_RT_END_DATA       =6, /**< Server is exiting message */
353        TRACE_RT_CLOSE          =7, /**< Client is exiting message */
354        TRACE_RT_DENY_CONN      =8, /**< Connection has been denied */
355        TRACE_RT_PAUSE          =9, /**< Request server to suspend sending data
356                                     */
357        TRACE_RT_PAUSE_ACK      =10,/**< Server is paused message */
358        TRACE_RT_OPTION         =11,/**< Option request */
359        TRACE_RT_KEYCHANGE      =12,/**< Anonymisation key has changed */
360        TRACE_RT_DUCK_2_4       =13,/**< Dag 2.4 Duck */
361        TRACE_RT_DUCK_2_5       =14,/**< Dag 2.5 Duck */
362        TRACE_RT_LOSTCONN       =15,/**< Lost connection to server */
363        TRACE_RT_SERVERSTART    =16,/**< Reliable server has been restarted */
364        TRACE_RT_CLIENTDROP     =17,/**< Reliable client was lost */
365        TRACE_RT_METADATA       =18,/**< Packet contains server meta-data */
366
367        /** Not actually used - all DATA types begin from this value */
368        TRACE_RT_DATA_SIMPLE    = 1000,
369       
370        /** RT is encapsulating an ERF capture record */
371        TRACE_RT_DATA_ERF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_ERF,
372        /** RT is encapsulating a WAG capture record */
373        TRACE_RT_DATA_WAG       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_WAG,
374        /** RT is encapsulating a Legacy ATM capture record */
375        TRACE_RT_DATA_LEGACY_ATM=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ATM,
376        /** RT is encapsulating a Legacy POS capture record */
377        TRACE_RT_DATA_LEGACY_POS=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_POS,
378        /** RT is encapsulating a Legacy ETH capture record */
379        TRACE_RT_DATA_LEGACY_ETH=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ETH,
380        /** RT is encapsulating a Linux native capture record */
381        TRACE_RT_DATA_LINUX_NATIVE=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_NATIVE,
382        /** RT is encapsulating a BSD native capture record */
383        //TRACE_RT_DATA_BPF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_BPF,
384        /** RT is encapsulating a TSH capture record */
385        TRACE_RT_DATA_TSH       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_TSH,
386        /** RT is encapsulating an ATM header capture record */
387        TRACE_RT_DATA_ATMHDR = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_ATMHDR,
388        /** RT is encapsulating a Legacy NZIX capture record */
389        TRACE_RT_DATA_LEGACY_NZIX=TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_LEGACY_NZIX,
390        /** RT is encapsulating a Linux native PACKET_MMAP capture record */
391        TRACE_RT_DATA_LINUX_RING=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_RING,
392    /** RT is encapsulating a Intel DPDK capture record */
393        TRACE_RT_DATA_DPDK=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_DPDK,
394
395        /** As PCAP does not store the linktype with the packet, we need to
396         * create a separate RT type for each supported DLT, starting from
397         * this value */
398        TRACE_RT_DATA_DLT               = 2000,
399        /** RT is encapsulating a PCAP capture record with a NULL linktype */
400        TRACE_RT_DLT_NULL               =TRACE_RT_DATA_DLT+TRACE_DLT_NULL,
401        /** RT is encapsulating a PCAP capture record with an Ethernet
402         * linktype */
403        TRACE_RT_DLT_EN10MB             =TRACE_RT_DATA_DLT+TRACE_DLT_EN10MB,
404        /** RT is encapsulating a PCAP capture record with an 802.11
405         * linktype */
406        TRACE_RT_DLT_IEEE802_11         =TRACE_RT_DATA_DLT+TRACE_DLT_IEEE802_11,
407        /** RT is encapsulating a PCAP capture record with a Linux SLL
408         * linktype */
409        TRACE_RT_DLT_LINUX_SLL          =TRACE_RT_DATA_DLT+TRACE_DLT_LINUX_SLL,
410        /** RT is encapsulating a PCAP capture record with a PFlog linktype */
411        TRACE_RT_DLT_PFLOG              =TRACE_RT_DATA_DLT+TRACE_DLT_PFLOG,
412        /** RT is encapsulating a PCAP capture record with an AAL5 linktype */
413        TRACE_RT_DLT_ATM_RFC1483        =TRACE_RT_DATA_DLT+TRACE_DLT_ATM_RFC1483,
414        /** Unused value marking the end of the valid range for PCAP RT
415         * encapsulation */
416        TRACE_RT_DATA_DLT_END           = 2999,
417        /** BPF does not store the linktype with the packet, so we need a
418         * separate RT type for each supported DLT. This value represents the
419         * starting point */
420        TRACE_RT_DATA_BPF               = 3000,
421
422        TRACE_RT_BPF_NULL               = TRACE_RT_DATA_BPF+TRACE_DLT_NULL,
423        TRACE_RT_BPF_EN10MB             = TRACE_RT_DATA_BPF+TRACE_DLT_EN10MB,
424        TRACE_RT_BPF_IEEE802_11         = TRACE_RT_DATA_BPF+TRACE_DLT_IEEE802_11,
425        TRACE_RT_BPF_PFLOG              =TRACE_RT_DATA_BPF+TRACE_DLT_PFLOG,
426        TRACE_RT_BPF_ATM_RFC1483        =TRACE_RT_DATA_BPF+TRACE_DLT_ATM_RFC1483,
427
428        TRACE_RT_DATA_BPF_END           = 3999,
429        /** Unused value marking the end of the valid range for all RT packet
430         * types */
431        TRACE_RT_LAST                   = 4000
432} libtrace_rt_types_t;
433
434/** IP Protocol values */
435typedef enum {
436        TRACE_IPPROTO_IP        = 0,    /**< IP pseudo protocol number */
437        TRACE_IPPROTO_ICMP      = 1,    /**< Internet Control Message protocol */
438        TRACE_IPPROTO_IGMP      = 2,    /**< Internet Group Management Protocol */
439        TRACE_IPPROTO_IPIP      = 4,    /**< IP encapsulated in IP */
440        TRACE_IPPROTO_TCP       = 6,    /**< Transmission Control Protocol */
441        TRACE_IPPROTO_UDP       = 17,   /**< User Datagram Protocol */
442        TRACE_IPPROTO_IPV6      = 41,   /**< IPv6 over IPv4 */
443        TRACE_IPPROTO_ROUTING   = 43,   /**< IPv6 Routing header */
444        TRACE_IPPROTO_FRAGMENT  = 44,   /**< IPv6 Fragmentation header */
445        TRACE_IPPROTO_RSVP      = 46,   /**< Resource Reservation Protocol */
446        TRACE_IPPROTO_GRE       = 47,   /**< General Routing Encapsulation */
447        TRACE_IPPROTO_ESP       = 50,   /**< Encapsulated Security Payload [RFC2406] */
448        TRACE_IPPROTO_AH        = 51,   /**< Authentication Header [RFC2402] */
449        TRACE_IPPROTO_ICMPV6    = 58,   /**< ICMPv6 */
450        TRACE_IPPROTO_NONE      = 59,   /**< IPv6 no next header */
451        TRACE_IPPROTO_DSTOPTS   = 60,   /**< IPv6 destination options */
452        TRACE_IPPROTO_OSPF      = 89,   /**< Open Shortest Path First routing protocol */
453        TRACE_IPPROTO_PIM       = 103,  /**< Protocol Independant Multicast */
454        TRACE_IPPROTO_SCTP      = 132   /**< Stream Control Transmission Protocol */
455} libtrace_ipproto_t;
456
457/** Ethertypes supported by Libtrace */
458typedef enum {
459        /* Numbers <=1500 are of course, LLC/SNAP */
460        TRACE_ETHERTYPE_LOOPBACK= 0x0060,       /**< Ethernet Loopback */
461        TRACE_ETHERTYPE_IP      = 0x0800,       /**< IPv4 */
462        TRACE_ETHERTYPE_ARP     = 0x0806,       /**< Address resolution protocol */
463        TRACE_ETHERTYPE_RARP    = 0x8035,       /**< Reverse ARP */
464        TRACE_ETHERTYPE_8021Q   = 0x8100,       /**< 802.1q VLAN Extended Header */
465        TRACE_ETHERTYPE_IPV6    = 0x86DD,       /**< IPv6 */
466        TRACE_ETHERTYPE_MPLS    = 0x8847,       /**< MPLS Unicast traffic */
467        TRACE_ETHERTYPE_MPLS_MC = 0x8848,       /**< MPLS Multicast traffic */
468        TRACE_ETHERTYPE_PPP_DISC= 0x8863,       /**< PPPoE Service Discovery */
469        TRACE_ETHERTYPE_PPP_SES = 0x8864        /**< PPPoE Session Messages */
470} libtrace_ethertype_t;
471
472/** The libtrace packet structure. Applications shouldn't be
473 * meddling around in here
474 */
475typedef struct libtrace_packet_t {
476        struct libtrace_t *trace;       /**< Pointer to the trace */
477        void *header;                   /**< Pointer to the framing header */
478        void *payload;                  /**< Pointer to the link layer */
479        void *buffer;                   /**< Allocated buffer */
480        libtrace_rt_types_t  type;      /**< RT protocol type for the packet */
481        buf_control_t buf_control;      /**< Describes memory ownership */
482        int capture_length;             /**< Cached capture length */
483        int wire_length;                /**< Cached wire length */
484        int payload_length;             /**< Cached payload length */
485        void *l2_header;                /**< Cached link header */
486        libtrace_linktype_t link_type;  /**< Cached link type */
487        uint32_t l2_remaining;          /**< Cached link remaining */
488        void *l3_header;                /**< Cached l3 header */
489        uint16_t l3_ethertype;          /**< Cached l3 ethertype */
490        uint32_t l3_remaining;          /**< Cached l3 remaining */
491        void *l4_header;                /**< Cached transport header */
492        uint8_t transport_proto;        /**< Cached transport protocol */
493        uint32_t l4_remaining;          /**< Cached transport remaining */
494        uint64_t order; /**< Notes the order of this packet in relation to the input */
495        uint64_t hash; /**< A hash of the packet as supplied by the user */
496        int error; /**< The error status of pread_packet */
497} libtrace_packet_t;
498
499
500/** Trace directions.
501 * Note that these are the directions used by convention. More directions
502 * are possible, not just these 3, and that they may not conform to this
503 * convention.
504 */
505typedef enum {
506        TRACE_DIR_OUTGOING = 0,         /**< Packets originating "inside" */
507        TRACE_DIR_INCOMING = 1,         /**< Packets originating "outside" */
508        TRACE_DIR_OTHER    = 2,         /**< Packets with an unknown direction, or one that's unknown */
509        TRACE_DIR_UNKNOWN = -1,         /**< No direction information available */
510} libtrace_direction_t;
511
512/** Enumeration of Radiotap fields */
513typedef enum {
514    TRACE_RADIOTAP_TSFT = 0, /**< Timer synchronisation function, in microseconds (uint64) */
515    TRACE_RADIOTAP_FLAGS = 1, /**< Wireless flags (uint8) */
516    TRACE_RADIOTAP_RATE = 2, /**< Bitrate in units of 500kbps (uint8) */
517    TRACE_RADIOTAP_CHANNEL = 3, /**< Frequency in MHz (uint16) and channel flags (uint16) */
518    TRACE_RADIOTAP_FHSS = 4, /**< FHSS hop set (uint8) and hopping pattern (uint8) */
519    TRACE_RADIOTAP_DBM_ANTSIGNAL = 5, /**< Signal power in dBm (int8) */
520    TRACE_RADIOTAP_DBM_ANTNOISE = 6, /**< Noise power in dBm (int8) */
521    TRACE_RADIOTAP_LOCK_QUALITY = 7, /**< Barker Code lock quality (uint16) */
522    TRACE_RADIOTAP_TX_ATTENUATION = 8, /**< TX attenuation as unitless distance from max power (uint16) */
523    TRACE_RADIOTAP_DB_TX_ATTENUATION = 9, /**< TX attenutation as dB from max power (uint16) */
524    TRACE_RADIOTAP_DBM_TX_POWER = 10, /**< TX Power in dBm (int8) */
525    TRACE_RADIOTAP_ANTENNA = 11, /**< Antenna frame was rx'd or tx'd on (uint8) */
526    TRACE_RADIOTAP_DB_ANTSIGNAL = 12, /**< Signal power in dB from a fixed reference (uint8) */
527    TRACE_RADIOTAP_DB_ANTNOISE = 13, /**< Noise power in dB from a fixed reference (uint8) */
528    TRACE_RADIOTAP_RX_FLAGS = 14, /** Properties of received frame (uint16) */
529    TRACE_RADIOTAP_TX_FLAGS = 15, /** Properties of transmitted frame (uint16) */
530    TRACE_RADIOTAP_RTS_RETRIES = 16, /** Number of rts retries frame used (uint8) */
531    TRACE_RADIOTAP_DATA_RETRIES = 17, /** Number of unicast retries a transmitted frame used (uint8) */
532    TRACE_RADIOTAP_EXT = 31
533} libtrace_radiotap_field_t;
534
535
536/** @name Protocol structures
537 * These convenience structures provide portable versions of the headers
538 * for a variety of protocols.
539 * @{
540 */
541
542#ifdef WIN32
543#pragma pack(push)
544#pragma pack(1)
545#endif
546
547/** Generic IP header structure */
548typedef struct libtrace_ip
549{
550#if __BYTE_ORDER == __LITTLE_ENDIAN
551    LT_BITFIELD8 ip_hl:4;               /**< Header Length */
552    LT_BITFIELD8 ip_v:4;                /**< Version */
553#elif __BYTE_ORDER == __BIG_ENDIAN
554    LT_BITFIELD8 ip_v:4;                /**< Version */
555    LT_BITFIELD8 ip_hl:4;               /**< Header Length */
556#else
557#   error "Adjust your <bits/endian.h> defines"
558#endif
559    uint8_t  ip_tos;                    /**< Type of Service */
560    uint16_t ip_len;                    /**< Total Length */
561    int16_t  ip_id;                     /**< Identification */
562    uint16_t ip_off;                    /**< IP Fragment offset (and flags) */
563    uint8_t  ip_ttl;                    /**< Time to Live */
564    uint8_t  ip_p;                      /**< Protocol */
565    uint16_t ip_sum;                    /**< Checksum */
566    struct in_addr ip_src;              /**< Source Address */
567    struct in_addr ip_dst;              /**< Destination Address */
568} PACKED libtrace_ip_t;
569
570/** IPv6 header extension structure */
571typedef struct libtrace_ip6_ext
572{
573        uint8_t nxt;    /**< Next header */
574        uint8_t len;    /**< Length of the current header */
575} PACKED libtrace_ip6_ext_t;
576
577typedef struct libtrace_ip6_frag
578{
579        uint8_t nxt;    /**< Next header */
580        uint8_t res;    /**< Reserved */
581        uint16_t frag_off;      /**< Fragment Offset (includes M flag) */
582        uint32_t ident; /** Fragment identification */
583} PACKED libtrace_ip6_frag_t;
584
585/** Generic IPv6 header structure
586 *
587 * @note The flow label field also includes the Version and Traffic Class
588 * fields, because we haven't figured out a nice way to deal with fields
589 * crossing byte boundaries on both Big and Little Endian machines */
590typedef struct libtrace_ip6
591{
592    uint32_t flow;                      /**< Flow label */
593    uint16_t plen;                      /**< Payload length */
594    uint8_t nxt;                        /**< Next header */
595    uint8_t hlim;                       /**< Hop limit */
596    struct in6_addr ip_src;             /**< Source address */
597    struct in6_addr ip_dst;             /**< Destination address */
598} PACKED libtrace_ip6_t;
599
600/** Generic TCP header structure */
601typedef struct libtrace_tcp
602  {
603    uint16_t source;            /**< Source Port */
604    uint16_t dest;              /**< Destination port */
605    uint32_t seq;               /**< Sequence number */
606    uint32_t ack_seq;           /**< Acknowledgement Number */
607#  if __BYTE_ORDER == __LITTLE_ENDIAN
608    LT_BITFIELD8 ecn_ns:1;      /**< ECN Nonce Sum */
609    LT_BITFIELD8 res1:3;        /**< Reserved bits */
610    LT_BITFIELD8 doff:4;        /**< Data Offset */
611    LT_BITFIELD8 fin:1;         /**< FIN */
612    LT_BITFIELD8 syn:1;         /**< SYN flag */
613    LT_BITFIELD8 rst:1;         /**< RST flag */
614    LT_BITFIELD8 psh:1;         /**< PuSH flag */
615    LT_BITFIELD8 ack:1;         /**< ACK flag */
616    LT_BITFIELD8 urg:1;         /**< URG flag */
617    LT_BITFIELD8 ece:1;         /**< ECN Echo */
618    LT_BITFIELD8 cwr:1;         /**< ECN CWR */
619#  elif __BYTE_ORDER == __BIG_ENDIAN
620    LT_BITFIELD8 doff:4;        /**< Data offset */
621    LT_BITFIELD8 res1:3;        /**< Reserved bits */
622    LT_BITFIELD8 ecn_ns:1;      /**< ECN Nonce Sum */
623    LT_BITFIELD8 cwr:1;         /**< ECN CWR */
624    LT_BITFIELD8 ece:1;         /**< ECN Echo */
625    LT_BITFIELD8 urg:1;         /**< URG flag */
626    LT_BITFIELD8 ack:1;         /**< ACK flag */
627    LT_BITFIELD8 psh:1;         /**< PuSH flag */
628    LT_BITFIELD8 rst:1;         /**< RST flag */
629    LT_BITFIELD8 syn:1;         /**< SYN flag */
630    LT_BITFIELD8 fin:1;         /**< FIN flag */
631#  else
632#   error "Adjust your <bits/endian.h> defines"
633#  endif
634    uint16_t window;            /**< Window Size */
635    uint16_t check;             /**< Checksum */
636    uint16_t urg_ptr;           /**< Urgent Pointer */
637} PACKED libtrace_tcp_t;
638
639/** Generic UDP header structure */
640typedef struct libtrace_udp {
641  uint16_t      source;         /**< Source port */
642  uint16_t      dest;           /**< Destination port */
643  uint16_t      len;            /**< Length */
644  uint16_t      check;          /**< Checksum */
645} PACKED libtrace_udp_t;
646
647/** Generic ICMP header structure */
648typedef struct libtrace_icmp
649{
650  uint8_t type;         /**< Message Type */
651  uint8_t code;         /**< Type Sub-code */
652  uint16_t checksum;            /**< Checksum */
653  union
654  {
655    struct
656    {
657      uint16_t  id;             /**< ID of the Echo request */
658      uint16_t  sequence;       /**< Sequence number of the Echo request */
659    } echo;                     /**< Echo Datagram */
660    uint32_t    gateway;        /**< Gateway Address */
661    struct
662    {
663      uint16_t  unused;         /**< Unused */
664      uint16_t  mtu;            /**< Next-hop MTU */
665    } frag;                     /**< Path MTU Discovery */
666  } un;                         /**< Union for Payloads of Various ICMP Codes */
667} PACKED libtrace_icmp_t;
668
669typedef struct libtrace_icmp6 {
670  uint8_t type;         /**< Message Type */
671  uint8_t code;         /**< Type Sub-code */
672  uint16_t checksum;    /**< Checksum */
673
674  union {
675    struct {
676        uint8_t length;   /**< Length of original datagram content in 64 bit words */
677        uint8_t unused;   /**< Unused */       
678        uint8_t unused1;  /**< Unused */
679    } extend;   /**< Extensions added in RFC 4884 for Time Exceeded and Destination Unreachable Messages */
680
681    uint32_t mtu;       /**< MTU from Packet Too Big Message */
682    uint32_t pointer;   /**< Pointer from Parameter Problem Message */
683    struct {
684        uint16_t id;    /**< Echo Identifier */
685        uint16_t sequence; /**< Echo Sequence Number */
686    } echo; /**< Data required for Echo Request and Reply messages */
687  } un;
688} PACKED libtrace_icmp6_t;
689
690/** Generic LLC/SNAP header structure */
691typedef struct libtrace_llcsnap
692{
693/* LLC */
694  uint8_t dsap;                 /**< Destination Service Access Point */
695  uint8_t ssap;                 /**< Source Service Access Point */
696  uint8_t control;              /**< Control field */
697/* SNAP */
698  LT_BITFIELD32 oui:24;         /**< Organisationally Unique Identifier (scope)*/
699  uint16_t type;                /**< Protocol within OUI */
700} PACKED libtrace_llcsnap_t;
701
702/** 802.3 frame */
703typedef struct libtrace_ether
704{
705  uint8_t ether_dhost[6];       /**< Destination Ether Addr */
706  uint8_t ether_shost[6];       /**< Source Ether Addr */
707  uint16_t ether_type;          /**< Packet Type ID Field (next-header) */
708} PACKED libtrace_ether_t;
709
710/** 802.1Q frame */
711typedef struct libtrace_8021q
712{
713  LT_BITFIELD16 vlan_pri:3;      /**< VLAN User Priority */
714  LT_BITFIELD16 vlan_cfi:1;      /**< VLAN Format Indicator,
715                                   * 0 for ethernet, 1 for token ring */
716  LT_BITFIELD16 vlan_id:12;      /**< VLAN Id */
717  uint16_t vlan_ether_type;      /**< VLAN Sub-packet Type ID Field
718                                   * (next-header)*/
719} PACKED libtrace_8021q_t;
720
721/** ATM User Network Interface (UNI) Cell. */
722typedef struct libtrace_atm_cell
723{
724  LT_BITFIELD32 gfc:4;          /**< Generic Flow Control */
725  LT_BITFIELD32 vpi:8;          /**< Virtual Path Identifier */
726  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
727  LT_BITFIELD32 pt:3;           /**< Payload Type */
728  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
729  LT_BITFIELD32 hec:8;          /**< Header Error Control */
730} PACKED libtrace_atm_cell_t;
731
732/** ATM Network Node/Network Interface (NNI) Cell. */
733typedef struct libtrace_atm_nni_cell
734{
735  LT_BITFIELD32 vpi:12;         /**< Virtual Path Identifier */
736  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
737  LT_BITFIELD32 pt:3;           /**< Payload Type */
738  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
739  LT_BITFIELD32 hec:8;          /**< Header Error Control */
740} PACKED libtrace_atm_nni_cell_t;
741
742/** Captured UNI cell.
743 *
744 * Endace don't capture the HEC, presumably to keep alignment.  This
745 * version of the \ref libtrace_atm_cell is used when dealing with DAG
746 * captures of uni cells.
747 *
748 */
749typedef struct libtrace_atm_capture_cell
750{
751  LT_BITFIELD32 gfc:4;          /**< Generic Flow Control */
752  LT_BITFIELD32 vpi:8;          /**< Virtual Path Identifier */
753  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
754  LT_BITFIELD32 pt:3;           /**< Payload Type */
755  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
756} PACKED libtrace_atm_capture_cell_t;
757
758/** Captured NNI cell.
759 *
760 * Endace don't capture the HEC, presumably to keep alignment.  This
761 * version of the \ref libtrace_atm_nni_cell is used when dealing with DAG
762 * captures of nni cells.
763 *
764 */
765typedef struct libtrace_atm_nni_capture_cell
766{
767  LT_BITFIELD32 vpi:12;         /**< Virtual Path Identifier */
768  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
769  LT_BITFIELD32 pt:3;           /**< Payload Type */
770  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
771  LT_BITFIELD32 hec:8;          /**< Header Error Control */
772} PACKED libtrace_atm_nni_capture_cell_t;
773
774/** PPP header */
775typedef struct libtrace_ppp
776{
777 /* I can't figure out where the hell these two variables come from. They're
778  * definitely not in RFC 1661 which defines PPP. Probably some weird thing
779  * relating to the lack of distinction between PPP, HDLC and CHDLC */
780       
781/* uint8_t address; */          /**< PPP Address (0xFF - All stations) */
782/* uint8_t header;  */          /**< PPP Control (0x03 - Unnumbered info) */
783 uint16_t protocol;             /**< PPP Protocol (htons(0x0021) - IPv4 */
784} PACKED libtrace_ppp_t;
785
786/** PPPoE header */
787typedef struct libtrace_pppoe
788{
789 LT_BITFIELD8 version:4;        /**< Protocol version number */
790 LT_BITFIELD8 type:4;           /**< PPPoE Type */
791 uint8_t code;                  /**< PPPoE Code */
792 uint16_t session_id;           /**< Session Identifier */
793 uint16_t length;               /**< Total Length of the PPP packet */
794} PACKED libtrace_pppoe_t;
795
796/** 802.11 header */
797typedef struct libtrace_80211_t {
798#if __BYTE_ORDER == __LITTLE_ENDIAN
799        LT_BITFIELD32      protocol:2;  /**< Protocol Version */
800        LT_BITFIELD32      type:2;      /**< Frame Type */
801        LT_BITFIELD32      subtype:4;   /**< Frame Subtype */
802#else
803        LT_BITFIELD32      subtype:4;   /**< Frame Subtype */
804        LT_BITFIELD32      type:2;      /**< Frame Type */
805        LT_BITFIELD32      protocol:2;  /**< Protocol Version */
806#endif
807
808#if __BYTE_ORDER == __LITTLE_ENDIAN
809        LT_BITFIELD32      to_ds:1;     /**< Packet to Distribution Service */
810        LT_BITFIELD32      from_ds:1;   /**< Packet from Distribution Service */
811        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
812        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
813        LT_BITFIELD32      power:1;     /**< Power Management mode */
814        LT_BITFIELD32      more_data:1; /**< More data is buffered at station */
815        LT_BITFIELD32      wep:1;       /**< WEP encryption indicator */
816        LT_BITFIELD32      order:1;     /**< Strictly-Ordered class indicator */
817#else
818        LT_BITFIELD32      order:1;     /**< Strictly-Ordered class indicator */
819        LT_BITFIELD32      wep:1;       /**< WEP encryption indicator */
820        LT_BITFIELD32      more_data:1; /**< More data is buffered at station */
821        LT_BITFIELD32      power:1;     /**< Power Management mode */
822        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
823        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
824        LT_BITFIELD32      from_ds:1;   /**< Packet from Distribution Service */
825        LT_BITFIELD32      to_ds:1;     /**< Packet to Distribution Service */
826#endif
827       
828        uint16_t     duration;  /**< Duration value for NAV calculation */
829        uint8_t      mac1[6];   /**< MAC Address 1 */
830        uint8_t      mac2[6];   /**< MAC Address 2 */
831        uint8_t      mac3[6];   /**< MAC Address 3 */
832        uint16_t     SeqCtl;    /**< Sequence Control */       
833        uint8_t      mac4[6];   /**< MAC Address 4 */
834} PACKED libtrace_80211_t;
835
836/** The Radiotap header pre-amble
837 *
838 * All Radiotap headers start with this pre-amble, followed by the fields
839 * specified in the it_present bitmask. If bit 31 of it_present is set, then
840 * another bitmask follows.
841 * @note All of the radiotap data fields are in little-endian byte-order.
842 */
843typedef struct libtrace_radiotap_t {
844    uint8_t     it_version; /**< Radiotap version */
845    uint8_t     it_pad; /**< Padding for natural alignment */
846    uint16_t    it_len; /**< Length in bytes of the entire Radiotap header */
847    uint32_t    it_present; /**< Which Radiotap fields are present */
848} PACKED libtrace_radiotap_t;
849
850/** OSPF header */
851typedef struct libtrace_ospf_v2_t
852{
853        uint8_t ospf_v;         /**< OSPF Version, should be 2 */
854        uint8_t type;           /**< OSPF Packet Type */
855        uint16_t len;           /**< Packet length, including OSPF header */
856        struct in_addr router;  /**< Router ID of the packet source */
857        struct in_addr area;    /**< Area the packet belongs to */
858        uint16_t sum;           /**< Checksum */
859        uint16_t au_type;       /**< Authentication procedure */
860        uint16_t zero;          /**< Always zero */
861        uint8_t au_key_id;      /**< Authentication Key ID */
862        uint8_t au_data_len;    /**< Authentication Data Length */
863        uint32_t au_seq_num;    /**< Cryptographic Sequence Number */
864} PACKED libtrace_ospf_v2_t;
865
866/** Options Field present in some OSPFv2 packets */
867typedef struct libtrace_ospf_options_t {
868#if __BYTE_ORDER == __LITTLE_ENDIAN
869        LT_BITFIELD8 unused1:1;
870        LT_BITFIELD8 e_bit:1;
871        LT_BITFIELD8 mc_bit:1;
872        LT_BITFIELD8 np_bit:1;
873        LT_BITFIELD8 ea_bit:1;
874        LT_BITFIELD8 dc_bit:1;
875        LT_BITFIELD8 unused2:2;
876#elif __BYTE_ORDER == __BIG_ENDIAN
877        LT_BITFIELD8 unused2:2;
878        LT_BITFIELD8 dc_bit:1;
879        LT_BITFIELD8 ea_bit:1;
880        LT_BITFIELD8 np_bit:1;
881        LT_BITFIELD8 mc_bit:1;
882        LT_BITFIELD8 e_bit:1;
883        LT_BITFIELD8 unused1:1;
884#endif
885} PACKED libtrace_ospf_options_t;
886
887/** LSA Header for OSPFv2 */
888typedef struct libtrace_ospf_lsa_v2_t
889{
890        uint16_t age;           /**< Time in seconds since LSA originated */
891        libtrace_ospf_options_t lsa_options;    /**< Options */
892        uint8_t lsa_type;       /**< LSA type */
893        struct in_addr ls_id;   /**< Link State ID */
894        struct in_addr adv_router; /**< Router that originated this LSA */
895        uint32_t seq;           /**< LS sequence number */
896        uint16_t checksum;      /**< Checksum */
897        uint16_t length;        /**< Length of the LSA including LSA header */
898} PACKED libtrace_ospf_lsa_v2_t;
899
900/** OSPFv2 Hello Packet */
901typedef struct libtrace_ospf_hello_v2_t
902{
903        struct in_addr mask;    /**< Network mask for this interface */
904        uint16_t interval;      /**< Interval between Hello packets (secs) */
905        libtrace_ospf_options_t hello_options;  /**< Options */
906        uint8_t priority;       /**< Router Priority */
907        uint32_t deadint;       /**< Interval before declaring a router down */
908        struct in_addr designated;      /**< Designated router for the network */
909        struct in_addr backup;  /**< Backup designated router */
910
911        /** Neighbors follow from here, but there can be anywhere from 1 to N
912         * neighbors so I can't include that here */
913} PACKED libtrace_ospf_hello_v2_t;
914
915/** OSPFv2 Database Description packet */
916typedef struct libtrace_ospf_db_desc_v2_t
917{
918        uint16_t mtu;           /**< Interface MTU */
919        libtrace_ospf_options_t db_desc_options;        /**< Options */
920#if __BYTE_ORDER == __LITTLE_ENDIAN
921        LT_BITFIELD8 db_desc_ms:1;      /**< If set, this router is the master */
922        LT_BITFIELD8 db_desc_m:1;       /**< If set, more packets to follow */
923        LT_BITFIELD8 db_desc_i:1;       /**< If set, this is the first packet in sequence */
924        LT_BITFIELD8 zero:5;
925#elif __BYTE_ORDER == __BIG_ENDIAN
926        LT_BITFIELD8 zero:5;
927        LT_BITFIELD8 db_desc_i:1;       /**< If set, this is the first packet in sequence */
928        LT_BITFIELD8 db_desc_m:1;       /**< If set, more packets to follow */
929        LT_BITFIELD8 db_desc_ms:1;      /**< If set, this router is the master */
930#endif
931        uint32_t seq;           /**< Sequence number for DD packets */
932} PACKED libtrace_ospf_db_desc_v2_t;
933
934/** OSPF Link State Request Packet */
935typedef struct libtrace_ospf_ls_req_t
936{
937        uint32_t ls_type;       /**< Link State Type */
938        uint32_t ls_id;         /**< Link State Id */
939        uint32_t advertising_router;    /**< Advertising Router */
940} PACKED libtrace_ospf_ls_req_t;
941
942/** OSPF Link State Update Packet */
943typedef struct libtrace_ospf_ls_update_t
944{
945        uint32_t ls_num_adv;    /**< Number of LSAs in this packet */
946
947        /* Followed by LSAs, use API functions to access these */
948} PACKED libtrace_ospf_ls_update_t;
949
950/** OSPFv2 AS External LSA Body */
951typedef struct libtrace_ospf_as_external_lsa_t
952{
953        struct in_addr netmask; /**< Netmask for the destination */
954#if __BYTE_ORDER == __LITTLE_ENDIAN
955        LT_BITFIELD8 tos:7;
956        LT_BITFIELD8 e:1;       /**< If set, metric is Type 2. Else, Type 1 */
957#elif __BYTE_ORDER == __BIG_ENDIAN
958        LT_BITFIELD8 e:1;       /**< If set, metric is Type 2. Else, Type 1 */
959        LT_BITFIELD8 tos:7;
960#endif
961        uint8_t metric_a;       /**< Byte 1 of the Metric field */
962        uint8_t metric_b;       /**< Byte 2 of the Metric field */
963        uint8_t metric_c;       /**< Byte 3 of the Metric field */
964        struct in_addr forwarding;      /**< Forwarding address */
965        uint32_t external_tag;          /**< External Route Tag */
966} PACKED libtrace_ospf_as_external_lsa_v2_t;
967
968/** OSPFv2 Summary LSA Body */
969typedef struct libtrace_ospf_summary_lsa
970{
971        struct in_addr netmask; /**< Netmask for the destination */
972        uint8_t zero;           /**< Always zero */
973        uint8_t metric_a;       /**< Byte 1 of the Metric field */
974        uint8_t metric_b;       /**< Byte 2 of the Metric field */
975        uint8_t metric_c;       /**< Byte 3 of the Metric field */
976       
977} PACKED libtrace_ospf_summary_lsa_v2_t;
978
979/** OSPFv2 Network LSA Body */
980typedef struct libtrace_ospf_network_lsa_t
981{
982        struct in_addr netmask; /**< Netmask for the network */
983        /* Followed by IDs of attached routers */
984} PACKED libtrace_ospf_network_lsa_v2_t;
985
986/** OSPFv2 Router Link structure */
987typedef struct libtrace_ospf_link_t
988{
989        struct in_addr link_id;         /**< Object that link connects to */
990        struct in_addr link_data;       /**< Link Data field */
991        uint8_t type;                   /**< Link Type */
992        uint8_t num_tos;                /**< Number of TOS metrics */
993        uint16_t tos_metric;            /**< Cost of router link */
994} PACKED libtrace_ospf_link_v2_t;
995
996/** OSPFv2 Router LSA */
997typedef struct libtrace_ospf_router_lsa_t
998{
999#if __BYTE_ORDER == __LITTLE_ENDIAN
1000        LT_BITFIELD8 b:1;       /**< Area Border Router Flag */
1001        LT_BITFIELD8 e:1;       /**< External Router Flag */
1002        LT_BITFIELD8 v:1;       /**< Virtual Endpoint Flag */
1003        LT_BITFIELD8 zero:5;
1004#elif __BYTE_ORDER == __BIG_ENDIAN
1005        LT_BITFIELD8 zero:5;
1006        LT_BITFIELD8 v:1;       /**< Virtual Endpoint Flag */
1007        LT_BITFIELD8 e:1;       /**< External Router Flag */
1008        LT_BITFIELD8 b:1;       /**< Area Border Router Flag */
1009#endif
1010        uint8_t zero2;          /**< Always zero */
1011        uint16_t num_links;     /**< Number of links in LSA */
1012} PACKED libtrace_ospf_router_lsa_v2_t;
1013
1014typedef enum {
1015        TRACE_OSPF_HELLO = 1,           /**< OSPF Hello */
1016        TRACE_OSPF_DATADESC = 2,        /**< OSPF Database Description */
1017        TRACE_OSPF_LSREQ = 3,           /**< OSPF Link State Request */
1018        TRACE_OSPF_LSUPDATE = 4,        /**< OSPF Link State Update */
1019        TRACE_OSPF_LSACK = 5            /**< OSPF Link State Acknowledgement */
1020} libtrace_ospf_types_t;
1021
1022typedef enum {
1023        TRACE_OSPF_LS_ROUTER = 1,       /**< OSPF Router LSA */
1024        TRACE_OSPF_LS_NETWORK = 2,      /**< OSPF Network LSA */
1025        TRACE_OSPF_LS_SUMMARY = 3,      /**< OSPF Summary LSA */
1026        TRACE_OSPF_LS_ASBR_SUMMARY = 4, /**< OSPF Summary LSA (ASBR) */
1027        TRACE_OSPF_LS_EXTERNAL = 5      /**< OSPF AS External LSA */
1028} libtrace_ospf_ls_types_t;
1029
1030/** A local definition of an SLL header */
1031typedef struct libtrace_sll_header_t {
1032        uint16_t pkttype;               /**< Packet type */
1033        uint16_t hatype;                /**< Link-layer address type */
1034        uint16_t halen;                 /**< Link-layer address length */
1035        unsigned char addr[8];          /**< Link-layer address */
1036        uint16_t protocol;              /**< Protocol */
1037} libtrace_sll_header_t;
1038
1039
1040/* SLL packet types */
1041
1042/** Packet was addressed for the local host */
1043#define TRACE_SLL_HOST          0
1044/** Packet was addressed for a broadcast address */
1045#define TRACE_SLL_BROADCAST     1
1046/** Packet was addressed for a multicast address */
1047#define TRACE_SLL_MULTICAST     2
1048/** Packet was addressed for another host but was captured by a promiscuous
1049 * device */
1050#define TRACE_SLL_OTHERHOST     3
1051/** Packet originated from the local host */
1052#define TRACE_SLL_OUTGOING      4
1053
1054
1055#ifdef WIN32
1056#pragma pack(pop)
1057#endif
1058
1059
1060/*@}*/
1061
1062/** Prints help information for libtrace
1063 *
1064 * Function prints out some basic help information regarding libtrace,
1065 * and then prints out the help() function registered with each input module
1066 */
1067DLLEXPORT void trace_help(void);
1068
1069/** Causes a libtrace reader to stop blocking whilst waiting on new packets
1070 * and immediately return EOF.
1071 *
1072 * This function is useful if you are handling signals within your libtrace
1073 * program. If a live source is not receiving any packets (or they are being
1074 * filtered), a call to trace_read_packet will result in an infinite loop as
1075 * it will block until a packet is received. Normally, a SIGINT would cause the
1076 * program to end and thus break the loop, but if you are handling the signal
1077 * yourself then that signal will never reach libtrace.
1078 *
1079 * Instead this function sets a global variable within libtrace that will
1080 * cause a blocking live capture to break on the next internal timeout,
1081 * allowing control to be returned to the user and their own signal handling
1082 * to kick in.
1083 */
1084DLLEXPORT void trace_interrupt(void);
1085
1086/** @name Trace management
1087 * These members deal with creating, configuring, starting, pausing and
1088 * cleaning up a trace object
1089 *@{
1090 */
1091
1092/** Takes a uri and splits it into a format and uridata component.
1093 * @param uri           The uri to be parsed
1094 * @param [out] format  A pointer that will be updated to point to an allocated
1095 *                      string holding the format component of the URI
1096 * @return NULL if an error occured, otherwise return a pointer to the uridata
1097 * component
1098 *
1099 * @note The format component is strdup'd by this function, so be sure to free
1100 * it when you are done with the split URI. Similarly, do not pass a pointer
1101 * to an allocated string into this function as the 'format' parameter, as
1102 * that memory will be leaked and replaced with the strdup'd format.
1103 */
1104DLLEXPORT const char *trace_parse_uri(const char *uri, char **format);
1105
1106/** Create an input trace from a URI
1107 *
1108 * @param uri A valid libtrace URI to be opened
1109 * @return An opaque pointer to a libtrace_t
1110 *
1111 * Some valid URI's are:
1112 *  - erf:/path/to/erf/file
1113 *  - erf:-  (stdin)
1114 *  - dag:/dev/dagcard                 
1115 *  - pcapint:pcapinterface                (eg: pcap:eth0)
1116 *  - pcap:/path/to/pcap/file
1117 *  - pcap:-
1118 *  - rt:hostname
1119 *  - rt:hostname:port
1120 *
1121 *  If an error occured when attempting to open the trace file, a
1122 *  trace is still returned so trace_is_err() should be called to find out
1123 *  if an error occured. The trace is created in the configuration state, you
1124 *  must call trace_start before attempting to read packets from the trace.
1125 */
1126DLLEXPORT libtrace_t *trace_create(const char *uri);
1127
1128/** Creates a "dummy" trace file that has only the format type set.
1129 *
1130 * @param uri A valid (but fake) URI indicating the format of the dummy trace that is to be created.
1131 * @return An opaque pointer to a (sparsely initialised) libtrace_t
1132 *
1133 * Only the format portion of the uri parameter matters - the 'file' being
1134 * opened does not have to exist.
1135 *
1136 * @note IMPORTANT: Do not attempt to call trace_read_packet or other such
1137 * functions with the dummy trace. Its intended purpose is to provide access
1138 * to the format functions where the original trace may no longer exist or is
1139 * not the correct format, e.g. reading ERF packets from an RT input.
1140 */
1141DLLEXPORT libtrace_t *trace_create_dead(const char *uri);
1142
1143/** Creates a trace output file from a URI.
1144 *
1145 * @param uri The uri string describing the output format and destination
1146 * @return An opaque pointer to a libtrace_output_t
1147 *
1148 * Valid URIs include:
1149 *  - erf:/path/to/erf/file
1150 *  - pcap:/path/to/pcap/file
1151 *
1152 *  If an error occured when attempting to open the output trace, a trace is
1153 *  still returned but trace_errno will be set. Use trace_is_err_out() and
1154 *  trace_perror_output() to get more information.
1155 */
1156DLLEXPORT libtrace_out_t *trace_create_output(const char *uri);
1157
1158/** Start an input trace
1159 * @param libtrace      The trace to start
1160 * @return 0 on success, -1 on failure
1161 *
1162 * This does the actual work of starting the input trace and applying
1163 * all the config options.  This may fail, returning -1. The libtrace error
1164 * handling functions can be used to get more information about what
1165 * specifically went wrong.
1166 */
1167DLLEXPORT int trace_start(libtrace_t *libtrace);
1168
1169/** Pauses an input trace
1170 * @param libtrace      The trace to pause
1171 * @return 0 on success, -1 on failure
1172 *
1173 * This stops an input trace that is in progress and returns you to the
1174 * configuration state.  Any packets that arrive on a live capture after
1175 * trace_pause() has been called will be discarded.  To resume the trace, call
1176 * trace_start().
1177 */
1178DLLEXPORT int trace_pause(libtrace_t *libtrace);
1179
1180/** Start an output trace
1181 * @param libtrace      The trace to start
1182 * @return 0 on success, -1 on failure
1183 *
1184 * This does the actual work with starting a trace capable of writing packets. 
1185 * This generally creates the output file.
1186 */
1187DLLEXPORT int trace_start_output(libtrace_out_t *libtrace);
1188
1189/** Valid configuration options for input traces */
1190typedef enum {
1191        /** Maximum number of bytes to be captured for any given packet */
1192        TRACE_OPTION_SNAPLEN,   
1193
1194        /** If enabled, places a live capture interface into promiscuous mode */
1195        TRACE_OPTION_PROMISC,   
1196
1197        /** Apply this filter to all packets read from this trace */
1198        TRACE_OPTION_FILTER,   
1199
1200        /** Defines the frequency of meta-data reporting, e.g. DUCK packets */
1201        TRACE_OPTION_META_FREQ,
1202
1203        /** If enabled, the libtrace event API will ignore time gaps between
1204         * packets when reading from a trace file */
1205        TRACE_OPTION_EVENT_REALTIME
1206} trace_option_t;
1207
1208/** Sets an input config option
1209 * @param libtrace      The trace object to apply the option to
1210 * @param option        The option to set
1211 * @param value         The value to set the option to
1212 * @return -1 if option configuration failed, 0 otherwise
1213 * This should be called after trace_create, and before trace_start
1214 */
1215DLLEXPORT int trace_config(libtrace_t *libtrace,
1216                trace_option_t option,
1217                void *value);
1218
1219/** Valid compression types
1220 * Note, this must be kept in sync with WANDIO_COMPRESS_* numbers in wandio.h
1221 */
1222typedef enum {
1223        TRACE_OPTION_COMPRESSTYPE_NONE = 0, /**< No compression */
1224        TRACE_OPTION_COMPRESSTYPE_ZLIB = 1, /**< GZip Compression */
1225        TRACE_OPTION_COMPRESSTYPE_BZ2  = 2, /**< BZip2 Compression */
1226        TRACE_OPTION_COMPRESSTYPE_LZO  = 3,  /**< LZO Compression */
1227        TRACE_OPTION_COMPRESSTYPE_LAST
1228} trace_option_compresstype_t;
1229
1230/** Valid configuration options for output traces */
1231typedef enum {
1232        /** File flags to use when opening an output file, e.g. O_APPEND */
1233        TRACE_OPTION_OUTPUT_FILEFLAGS,
1234        /** Compression level: 0 = no compression, 1 = faster compression,
1235         * 9 = better compression */
1236        TRACE_OPTION_OUTPUT_COMPRESS,
1237        /** Compression type, see trace_option_compresstype_t */
1238        TRACE_OPTION_OUTPUT_COMPRESSTYPE
1239} trace_option_output_t;
1240
1241/** Sets an output config option
1242 *
1243 * @param libtrace      The output trace object to apply the option to
1244 * @param option        The option to set
1245 * @param value         The value to set the option to
1246 * @return -1 if option configuration failed, 0 otherwise
1247 * This should be called after trace_create_output, and before
1248 * trace_start_output
1249 */
1250DLLEXPORT int trace_config_output(libtrace_out_t *libtrace,
1251                trace_option_output_t option,
1252                void *value
1253                );
1254
1255/** Close an input trace, freeing up any resources it may have been using
1256 *
1257 * @param trace         The input trace to be destroyed
1258 *
1259 */
1260DLLEXPORT void trace_destroy(libtrace_t *trace);
1261
1262/** Close a dummy trace file, freeing up any resources it may have been using
1263 * @param trace         The dummy trace to be destroyed
1264 */
1265DLLEXPORT void trace_destroy_dead(libtrace_t *trace);
1266
1267/** Close an output trace, freeing up any resources it may have been using
1268 * @param trace         The output trace to be destroyed
1269 */
1270DLLEXPORT void trace_destroy_output(libtrace_out_t *trace);
1271
1272/** Check (and clear) the current error state of an input trace
1273 * @param trace         The input trace to check the error state on
1274 * @return The current error status and message
1275 *
1276 * This reads and returns the current error state and sets the current error
1277 * to "no error".
1278 */
1279DLLEXPORT libtrace_err_t trace_get_err(libtrace_t *trace);
1280
1281/** Indicate if there has been an error on an input trace
1282 * @param trace         The input trace to check the error state on
1283 * @return true if an error has occurred, false otherwise
1284 *
1285 * @note This does not clear the error status, and only returns true or false.
1286 */
1287DLLEXPORT bool trace_is_err(libtrace_t *trace);
1288
1289/** Outputs the error message for an input trace to stderr and clear the error
1290 * status.
1291 * @param trace         The input trace with the error to output
1292 * @param msg           The message to prepend to the error
1293 *
1294 * This function does clear the error status.
1295 */
1296DLLEXPORT void trace_perror(libtrace_t *trace, const char *msg,...) PRINTF(2,3);
1297
1298/** Checks (and clears) the current error state for an output trace
1299 * @param trace         The output trace to check the error state on
1300 * @return The current error status and message
1301 *
1302 * This reads and returns the current error state and sets the current error
1303 * to "no error".
1304 */
1305DLLEXPORT libtrace_err_t trace_get_err_output(libtrace_out_t *trace);
1306
1307/** Indicates if there is an error on an output trace
1308 * @param trace         The output trace to check the error state on
1309 * @return true if an error has occurred, false otherwise.
1310 *
1311 * This does not clear the error status, and only returns true or false.
1312 */
1313DLLEXPORT bool trace_is_err_output(libtrace_out_t *trace);
1314
1315/** Outputs the error message for an output trace to stderr and clear the error
1316 * status.
1317 * @param trace         The output trace with the error to output
1318 * @param msg           The message to prepend to the error
1319 * This function does clear the error status.
1320 */
1321DLLEXPORT void trace_perror_output(libtrace_out_t *trace, const char *msg,...)
1322        PRINTF(2,3);
1323
1324/** Returns the number of packets observed on an input trace.
1325 * Includes the number of packets counted as early as possible, before
1326 * filtering, and includes dropped packets.
1327 *
1328 * @param trace         The input trace to examine
1329 * @returns The number of packets seen at the capture point before filtering.
1330 *
1331 * If the number is not known, this function will return UINT64_MAX
1332 */
1333DLLEXPORT
1334uint64_t trace_get_received_packets(libtrace_t *trace);
1335
1336/** Returns the number of packets that were captured, but discarded for not
1337 * matching a provided filter.
1338 *
1339 * @param trace         The input trace to examine
1340 * @returns The number of packets that were successfully captured, but filtered
1341 *
1342 * If the number is not known, this function will return UINT64_MAX
1343 */
1344DLLEXPORT
1345uint64_t trace_get_filtered_packets(libtrace_t *trace);
1346
1347/** Returns the number of packets that have been dropped on an input trace due
1348 * to lack of buffer space on the capturing device.
1349 *
1350 * @param trace         The input trace to examine
1351 * @returns The number of packets captured, but dropped due to buffer overruns
1352 *
1353 * If the number is not known, this function will return UINT64_MAX
1354 */
1355DLLEXPORT
1356uint64_t trace_get_dropped_packets(libtrace_t *trace);
1357
1358/** Returns the number of packets that have been read from the input trace using
1359 * trace_read_packet().
1360 *
1361 * @param trace         The input trace to examine
1362 * @returns The number of packets that have been read by the libtrace user.
1363 *
1364 * If the number is not known, this function will return UINT64_MAX
1365 */
1366DLLEXPORT
1367uint64_t trace_get_accepted_packets(libtrace_t *trace);
1368
1369
1370/*@}*/
1371
1372/** @name Reading / Writing packets
1373 * These members deal with creating, reading and writing packets
1374 *
1375 * @{
1376 */
1377
1378/** Create a new packet object
1379 *
1380 * @return A pointer to an initialised libtrace_packet_t object
1381 */
1382DLLEXPORT libtrace_packet_t *trace_create_packet(void);
1383
1384/** Copy a packet object
1385 * @param packet        The source packet to copy
1386 * @return A new packet which has the same content as the source packet
1387 *
1388 * @note This always involves a copy, which can be slow.  Use of this
1389 * function should be avoided where possible.
1390 *
1391 * @par The reason you would want to use this function is that a zerocopied
1392 * packet from a device will be stored using memory owned by the device which
1393 * may be a limited resource. Copying the packet will ensure that the packet
1394 * is now stored in memory owned and managed by libtrace.
1395 */
1396DLLEXPORT libtrace_packet_t *trace_copy_packet(const libtrace_packet_t *packet);
1397
1398/** Destroy a packet object
1399 * @param packet        The packet to be destroyed
1400 *
1401 */
1402DLLEXPORT void trace_destroy_packet(libtrace_packet_t *packet);
1403
1404
1405/** Read the next packet from an input trace
1406 *
1407 * @param trace         The libtrace opaque pointer for the input trace
1408 * @param packet        The packet opaque pointer
1409 * @return 0 on EOF, negative value on error, number of bytes read when successful.
1410 *
1411 * @note The number of bytes read is usually (but not always) the same as
1412 * trace_get_framing_length()+trace_get_capture_length() depending on the
1413 * trace format.
1414 *
1415 * @note The trace must have been started with trace_start before calling
1416 * this function
1417 *
1418 * @note When reading from a live capture, this function will block until a
1419 * packet is observed on the capture interface. The libtrace event API
1420 * (e.g. trace_event()) should be used if non-blocking operation is required.
1421 */
1422DLLEXPORT int trace_read_packet(libtrace_t *trace, libtrace_packet_t *packet);
1423
1424/** Event types
1425 * see \ref libtrace_eventobj_t and \ref trace_event
1426 */
1427typedef enum {
1428        TRACE_EVENT_IOWAIT,     /**< Wait on the given file descriptor */
1429        TRACE_EVENT_SLEEP,      /**< Sleep for the given amount of time */
1430        TRACE_EVENT_PACKET,     /**< Packet has been read from input trace */
1431        TRACE_EVENT_TERMINATE   /**< End of input trace */
1432} libtrace_event_t;
1433
1434/** Structure returned by libtrace_event explaining what the current event is */
1435typedef struct libtrace_eventobj_t {
1436        libtrace_event_t type; /**< Event type (iowait,sleep,packet) */
1437       
1438        /** If the event is IOWAIT, the file descriptor to wait on */
1439        int fd;               
1440        /** If the event is SLEEP, the amount of time to sleep for in seconds */
1441        double seconds;       
1442        /** If the event is PACKET, the value returned by trace_read_packet() */
1443        int size;
1444} libtrace_eventobj_t;
1445
1446/** Processes the next libtrace event from an input trace.
1447 * @param trace The libtrace opaque pointer for the input trace
1448 * @param packet The libtrace_packet opaque pointer to use for reading packets
1449 * @return A libtrace_event struct containing the event type and details of the event.
1450 *
1451 * Type can be:
1452 *  TRACE_EVENT_IOWAIT  Waiting on I/O on a file descriptor
1453 *  TRACE_EVENT_SLEEP   Wait a specified amount of time for the next event
1454 *  TRACE_EVENT_PACKET  Packet was read from the trace
1455 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
1456 */
1457DLLEXPORT libtrace_eventobj_t trace_event(libtrace_t *trace,
1458                libtrace_packet_t *packet);
1459
1460
1461/** Write one packet out to the output trace
1462 *
1463 * @param trace         The libtrace_out opaque pointer for the output trace
1464 * @param packet        The packet opaque pointer of the packet to be written
1465 * @return The number of bytes written out, if zero or negative then an error has occured.
1466 */
1467DLLEXPORT int trace_write_packet(libtrace_out_t *trace, libtrace_packet_t *packet);
1468
1469/** Gets the capture format for a given packet.
1470 * @param packet        The packet to get the capture format for.
1471 * @return The capture format of the packet
1472 *
1473 * @note Due to ability to convert packets between formats relatively easily
1474 * in Libtrace, the format of the packet right now may not be the format that
1475 * the packet was originally captured with.
1476 */
1477DLLEXPORT
1478enum base_format_t trace_get_format(struct libtrace_packet_t *packet);
1479
1480/** Construct a libtrace packet from a buffer containing the packet payload.
1481 * @param[in,out] packet        Libtrace Packet object to update with the new
1482 *                              data.
1483 * @param linktype              The linktype of the packet data.
1484 * @param[in] data              The packet data (including linklayer).
1485 * @param len                   Length of packet data provided in the buffer.
1486 *
1487 * @note The constructed packet will be in the PCAP format.
1488 *
1489 * @note To be useful, the provided buffer must start with the layer 2 header
1490 * (or a metadata header, if desired).
1491 */
1492DLLEXPORT
1493void trace_construct_packet(libtrace_packet_t *packet,
1494                libtrace_linktype_t linktype, const void *data, uint16_t len);
1495
1496/*@}*/
1497
1498/** @name Protocol decodes
1499 * These functions locate and return a pointer to various headers inside a
1500 * packet
1501 *
1502 * A packet is divided up into several "layers.":
1503 *
1504 * @li Framing header -- This is the header provided by the capture format
1505 * itself rather than anything that was sent over the network. This provides
1506 * basic details about the packet record including capture lengths, wire
1507 * lengths, timestamps, direction information and any other metadata that is
1508 * part of the capture format. 
1509 *
1510 * @li Metadata header (optional) -- A header containing metadata about a
1511 * packet that was captured, but the metadata was not transmitted over the
1512 * wire.  Some examples include RadioTap and Linux_sll headers.  This can be
1513 * retrieved by trace_get_packet_meta(), or skipped using
1514 * trace_get_payload_from_meta(). There may be multiple "metadata" headers on
1515 * a packet.
1516 *
1517 * @li Layer 2/Link layer/Datalink header -- This can be retrieved by
1518 * trace_get_layer2(), or skipped using trace_get_payload_from_layer2().
1519 *
1520 * @li Layer 3/IP/IPv6 -- This can be retrieved by trace_get_layer3().  As a
1521 * convenience trace_get_ip()/trace_get_ip6() can be used to find an IPv4/IPv6
1522 * header.
1523 *
1524 * @li Layer 5/transport -- These are protocols carried in IPv4/IPv6 frames.
1525 * These can be retrieved using trace_get_transport().
1526 *
1527 * @{
1528 */
1529
1530
1531/** Gets a pointer to the first byte of the packet as it was captured and
1532 * returns its corresponding linktype and capture length.
1533 *
1534 * Use this function instead of the deprecated trace_get_link().
1535 *
1536 * @param packet The packet to get the buffer from
1537 * @param[out] linktype The linktype of the returned pointer
1538 * @param[out] remaining The capture length (the number of captured bytes from
1539 * the returned pointer)
1540 * @return A pointer to the first byte of the packet
1541 */
1542DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet,
1543                libtrace_linktype_t *linktype, uint32_t *remaining);
1544
1545/** Get a pointer to the link layer for a given packet
1546 * @param packet        The packet to get the link layer for
1547 *
1548 * @return A pointer to the link layer, or NULL if there is no link layer
1549 *
1550 * @deprecated This function is deprecated: Use trace_get_packet_buffer() or
1551 * one of the trace_get_layer*() functions instead.
1552 * @note You should call trace_get_link_type to find out what type of link
1553 * layer has been returned to you.
1554 */
1555DLLEXPORT SIMPLE_FUNCTION DEPRECATED
1556void *trace_get_link(const libtrace_packet_t *packet);
1557
1558/** Get a pointer to the IPv4 header (if any) for a given packet
1559 * @param packet        The packet to get the IPv4 header for
1560 *
1561 * @return A pointer to the IPv4 header, or NULL if there is no IPv4 header
1562 *
1563 * If a partial IP header is present, i.e. the packet has been truncated before
1564 * the end of the IP header, this function will return NULL.
1565 *
1566 * You should consider using \ref trace_get_layer3 instead of this function.
1567 */
1568DLLEXPORT SIMPLE_FUNCTION
1569libtrace_ip_t *trace_get_ip(libtrace_packet_t *packet);
1570
1571/** get a pointer to the IPv6 header (if any)
1572 * @param packet        The packet to get the IPv6 header for
1573 *
1574 * @return A pointer to the IPv6 header, or NULL if there is no IPv6 header
1575 *
1576 * If a partial IPv6 header is present, i.e. the packet has been truncated
1577 * before the end of the IP header, this function will return NULL.
1578 *
1579 * You should consider using \ref trace_get_layer3 instead of this function.
1580 */
1581DLLEXPORT SIMPLE_FUNCTION
1582libtrace_ip6_t *trace_get_ip6(libtrace_packet_t *packet);
1583
1584/** Return a pointer to the first metadata header in a packet, if present.
1585 *
1586 * This function takes a pointer to a libtrace packet and if any metadata
1587 * headers exist, returns a pointer to the first one, along with its
1588 * corresponding linktype.
1589 *
1590 * If no metadata headers exist in the packet, NULL is returned.
1591 *
1592 * A metadata header is a header that was prepended by the capturing device,
1593 * such as a Linux SLL header, or a Radiotap wireless monitoring header.
1594 * Subsequent metadata headers may be accessed with the
1595 * trace_get_payload_from_meta(...) function.
1596 *
1597 * @param packet The libtrace packet
1598 * @param[out] linktype The linktype of the returned metadata header
1599 * @param[out] remaining The number of bytes captured after the returned
1600 * pointer.
1601 * @return A pointer to the first metadata header, or NULL if there are no
1602 * metadata headers present.
1603 *
1604 * remaining may be NULL, however linktype must be provided.
1605 */
1606DLLEXPORT void *trace_get_packet_meta(const libtrace_packet_t *packet,
1607                libtrace_linktype_t *linktype,
1608                uint32_t *remaining);
1609
1610/** Returns the payload of a metadata header.
1611 *
1612 * This function takes a pointer to the start of a metadata header (either
1613 * obtained via trace_get_packet_meta(...) or by a previous call to
1614 * trace_get_payload_from_meta(...)) along with its corresponding linktype and
1615 * returns the payload, i.e. the next header. It will also update the linktype
1616 * parameter to indicate the type of payload.
1617 * 
1618 * If the linktype indicates that the header passed in is not a metadata
1619 * header, the function returns NULL to indicate this. The linktype remains
1620 * unchanged in this case.
1621 *
1622 * This function allows the user to iterate through metadata headers which are
1623 * sometimes present before the actual packet as it was received on the wire.
1624 * Examples of metadata headers include the Linux SLL header and the Radiotap
1625 * wireless monitoring header.
1626 *
1627 * If the metadata header passed into this function is truncated, this
1628 * function will return NULL, and remaining will be set to 0.
1629 *
1630 * If there are 0 bytes of payload following the provided metadata header, the
1631 * function will return a pointer to where the header would otherwise be and
1632 * remaining will be 0.
1633 *
1634 * Therefore, be sure to check the value of remaining after calling this
1635 * function!
1636 *
1637 * @param[in] meta A pointer to a metadata header
1638 * @param[in,out] linktype The linktype of meta (updated to indicate the
1639 * linktype of the returned header if applicable).
1640 * @param[in,out] remaining The number of bytes after the meta pointer.
1641 * @return A pointer to the payload of the metadata header. If meta is not a
1642 * pointer to a metadata header, NULL is returned and linktype remains
1643 * unchanged.
1644 *
1645 * All parameters are mandatory.
1646 */
1647DLLEXPORT void *trace_get_payload_from_meta(const void *meta,
1648                libtrace_linktype_t *linktype,
1649                uint32_t *remaining);
1650
1651
1652/** Get a pointer to the layer 2 header. Generally this is the first byte of the
1653 * packet as it was seen on the wire.
1654 *
1655 * This function takes a libtrace packet and skips over any metadata headers if
1656 * present (such as Linux SLL or Radiotap) and returns a pointer to the first
1657 * byte of the packet that was actually received by the network interface.
1658 *
1659 * @param packet The libtrace packet to find the layer 2 header for
1660 * @param[out] linktype The linktype of the returned layer 2 header
1661 * @param[out] remaining The number of bytes left in the packet after the
1662 * returned pointer.
1663 * @return A pointer to the first byte of the packet as it was seen on the
1664 * wire. If no layer 2 header is present, this function will return NULL.
1665 *
1666 * remaining may be NULL, otherwise it will be filled in by the function.
1667 */
1668DLLEXPORT void *trace_get_layer2(const libtrace_packet_t *packet,
1669                libtrace_linktype_t *linktype,
1670                uint32_t *remaining);
1671
1672/** Gets a pointer to the next header following a layer 2 header
1673 *
1674 * @param l2                    The pointer to the current layer 2 header
1675 * @param linktype              The type of the layer 2 header
1676 * @param[out] ethertype        An optional output variable of the ethernet type of the new header
1677 * @param[in,out] remaining     Updated with the number of captured bytes
1678                                remaining
1679 *
1680 * @return A pointer to the header following the provided layer 2 header, or
1681 * NULL if no subsequent header is present.
1682 *
1683 * Remaining must point to the number of bytes captured from the layer 2 header
1684 * and beyond.  It will be decremented by the number of bytes skipped to find
1685 * the payload.
1686 *
1687 * If the layer 2 header is complete but there are zero bytes of payload after
1688 * the end of the header, a pointer to where the payload would be is returned
1689 * and remaining will be set to 0.  If the layer 2 header is incomplete
1690 * (truncated), then NULL is returned and remaining will be set to 0.
1691 * Therefore, it is very important to check the value of remaining after
1692 * calling this function.
1693 *
1694 */
1695DLLEXPORT void *trace_get_payload_from_layer2(void *l2,
1696                libtrace_linktype_t linktype,
1697                uint16_t *ethertype,
1698                uint32_t *remaining);
1699
1700
1701/** Get a pointer to the layer 3 (e.g. IP) header.
1702 * @param packet  The libtrace packet to find the layer 3 header for
1703 * @param[out] ethertype The ethertype of the layer 3 header
1704 * @param[out] remaining The amount of captured data remaining in the packet starting from the returned pointer, i.e. including the layer 3 header.
1705 *
1706 * @return A pointer to the layer 3 header. If no layer 3 header is present in
1707 * the packet, NULL is returned. If the layer 3 header is truncated, a valid
1708 * pointer will still be returned so be sure to check the value of remaining
1709 * before attempting to process the returned header.
1710 *
1711 * remaining may be NULL, otherwise it will be set to the number of captured
1712 * bytes after the pointer returned.
1713 */
1714DLLEXPORT
1715void *trace_get_layer3(const libtrace_packet_t *packet,
1716                uint16_t *ethertype, uint32_t *remaining);
1717
1718/** Calculates the expected IP checksum for a packet.
1719 * @param packet        The libtrace packet to calculate the checksum for
1720 * @param[out] csum     The checksum that is calculated by this function. This
1721 *                      may not be NULL.
1722 *
1723 * @return A pointer to the original checksum field within the IP
1724 * header. If the checksum field is not present in the packet, NULL is returned.
1725 *
1726 * @note The return value points to the checksum that exists within the current
1727 * packet. The value in csum is the value that the checksum should be, given
1728 * the current packet contents. 
1729 *
1730 * @note This function involves the use of a memcpy, so be careful about
1731 * calling it excessively if performance is a concern for you.
1732 *
1733 * New in libtrace 3.0.17
1734 */
1735DLLEXPORT uint16_t *trace_checksum_layer3(libtrace_packet_t *packet,
1736                uint16_t *csum);
1737
1738/** Calculates the expected checksum for the transport header in a packet.
1739 * @param packet        The libtrace packet to calculate the checksum for
1740 * @param[out] csum     The checksum that is calculated by this function. This
1741 *                      may not be NULL.
1742 *
1743 * @return A pointer to the original checksum field within the transport
1744 * header. If the checksum field is not present in the packet, NULL is returned.
1745 *
1746 * @note The return value points to the checksum that exists within the current
1747 * packet. The value in csum is the value that the checksum should be, given
1748 * the current packet contents. 
1749 *
1750 * @note This function involves the use of a memcpy, so be careful about
1751 * calling it excessively if performance is a concern for you.
1752 *
1753 * @note Because transport checksums are calculated across the entire payload,
1754 * truncated packets will result in NULL being returned.
1755 *
1756 * This function will determine the appropriate checksum for whatever transport
1757 * layer header is present in the provided packet. At this stage, this only
1758 * currently works for TCP, UDP and ICMP packets.
1759 *
1760 * Be wary of TCP checksum offloading if you are examining the checksum of
1761 * packets captured on the same host that generated them!
1762 *
1763 * New in libtrace 3.0.17
1764 */
1765DLLEXPORT uint16_t *trace_checksum_transport(libtrace_packet_t *packet,
1766                uint16_t *csum);
1767
1768/** Gets a pointer to the transport layer header (if any)
1769 * @param packet   The libtrace packet to find the transport header for
1770 * @param[out] proto    The protocol present at the transport layer.
1771 * @param[out] remaining The amount of captured data remaining in the packet
1772 * starting from the returned pointer, i.e. including the transport header.
1773 *
1774 * @return A pointer to the transport layer header. If no transport header is
1775 * present in the packet, NULL is returned. If the transport header is
1776 * truncated, a valid pointer will still be returned so be sure to check the
1777 * value of remaining before attempting to process the returned header.
1778 *
1779 * remaining may be NULL, otherwise it will be set to the number of captured
1780 * bytes after the returned pointer.
1781 *
1782 * @note proto may be NULL if proto is unneeded.
1783 */
1784DLLEXPORT void *trace_get_transport(const libtrace_packet_t *packet,
1785                uint8_t *proto, uint32_t *remaining);
1786
1787/** Gets a pointer to the payload following an IPv4 header
1788 * @param ip            The IPv4 Header
1789 * @param[out] proto    The protocol of the header following the IPv4 header
1790 * @param[in,out] remaining Updated with the number of captured bytes remaining
1791 *
1792 * @return A pointer to the transport layer header, or NULL if no subsequent
1793 * header is present.
1794 *
1795 * When calling this function, remaining must contain the number of captured
1796 * bytes remaining in the packet starting from the IPv4 header (including the
1797 * IPv4 header itself).
1798 *
1799 * remaining will be decremented by the size of the IPv4 header (including any
1800 * options). If the IPv4 header is complete but there are zero bytes of payload
1801 * after the IPv4 header, a pointer to where the payload would be is returned
1802 * and remaining will be set to 0.  If the IPv4 header is incomplete, NULL will
1803 * be returned and remaining will be set to 0. Therefore, it is very important
1804 * to check the value of remaining after calling this function.
1805 *
1806 * proto may be NULL, in which case it won't be updated.
1807 *
1808 * @note This is similar to trace_get_transport_from_ip in libtrace2
1809 */
1810DLLEXPORT void *trace_get_payload_from_ip(libtrace_ip_t *ip, uint8_t *proto,
1811                uint32_t *remaining);
1812
1813/** Gets a pointer to the payload following an IPv6 header
1814 * @param ipptr         The IPv6 Header
1815 * @param[out] proto    The protocol of the header following the IPv6 header
1816 * @param[in,out] remaining Updated with the number of captured bytes remaining
1817 *
1818 * @return A pointer to the transport layer header, or NULL if no subsequent
1819 * header is present.
1820 *
1821 * When calling this function, remaining must contain the number of captured
1822 * bytes remaining in the packet starting from the IPv6 header (including the
1823 * IPv6 header itself).
1824 *
1825 * remaining will be decremented by the size of the IPv6 header (including any
1826 * options). If the IPv6 header is complete but there are zero bytes of payload
1827 * after the IPv6 header, a pointer to where the payload would be is returned
1828 * and remaining will be set to 0.  If the IPv6 header is incomplete, NULL will
1829 * be returned and remaining will be set to 0. Therefore, it is very important
1830 * to check the value of remaining after calling this function.
1831 *
1832 * proto may be NULL, in which case it won't be updated.
1833 *
1834 */
1835DLLEXPORT void *trace_get_payload_from_ip6(libtrace_ip6_t *ipptr,
1836                uint8_t *proto, uint32_t *remaining);
1837
1838/** Gets a pointer to the payload following a link header
1839 * @param linkptr       A pointer to the link layer header
1840 * @param linktype      The linktype of the link header being examined
1841 * @param[out] type     An output variable for the ethernet type
1842 * @param[in,out] remaining Updated with the number of captured bytes remaining
1843 *
1844 * @return A pointer to the header following the link header, or NULL if no
1845 * subsequent header is present.
1846 *
1847 * When calling this function, remaining must contain the number of captured
1848 * bytes remaining in the packet starting from the link header (including the
1849 * link header itself). remaining will be updated to contain the number of
1850 * bytes remaining after the link header has been skipped.
1851 *
1852 * @deprecated This function is deprecated: you should be using
1853 * trace_get_payload_from_layer2() or trace_get_payload_from_meta() instead.
1854 *
1855 */
1856DLLEXPORT void *trace_get_payload_from_link(void *linkptr,
1857                libtrace_linktype_t linktype,
1858                uint16_t *type, uint32_t *remaining);
1859
1860/** Gets a pointer to the payload following an 802.1q (VLAN) header.
1861 * @param vlan      A pointer to the VLAN header
1862 * @param[out] type  The ethernet type, replaced with the VLAN ether type
1863 * @param[in,out] remaining Updated with the number of captured bytes remaining
1864 *
1865 * @return A pointer to the header beyond the VLAN header, if one is present.
1866 * Otherwise, returns NULL. 
1867 *
1868 * When calling this function, remaining must contain the number of captured
1869 * bytes remaining in the packet starting from the VLAN header (including the
1870 * VLAN header itself). remaining will be updated to contain the number of
1871 * bytes remaining after the VLAN header has been skipped.
1872 *
1873 * If the VLAN header is complete but there are zero bytes of payload after
1874 * the VLAN header, a pointer to where the payload would be is returned and
1875 * remaining will be set to 0.  If the VLAN header is incomplete, NULL will be
1876 * returned and remaining will be set to 0. Therefore, it is important to check
1877 * the value of remaining after calling this function.
1878 *
1879 * type will be set to the ethertype of the VLAN payload. This parameter is not
1880 * mandatory, but is highly recommended.
1881 *
1882 */
1883DLLEXPORT void *trace_get_payload_from_vlan(
1884                void *vlan, uint16_t *type, uint32_t *remaining);
1885
1886/** Gets a pointer to the payload following an MPLS header.
1887 * @param mpls      A pointer to the MPLS header
1888 * @param[out] type  The ethernet type, replaced by the ether type of the
1889 * returned header - 0x0000 if an Ethernet header is returned
1890 * @param[in,out] remaining Updated with the number of captured bytes remaining
1891 *
1892 * @return A pointer to the header beyond the MPLS label, if one is present.
1893 * Will return NULL if there is not enough bytes remaining to skip past the
1894 * MPLS label.
1895 *
1896 * When calling this function, remaining must contain the number of captured
1897 * bytes remaining in the packet starting from the MPLS header (including the
1898 * MPLS header itself). remaining will be updated to contain the number of
1899 * bytes remaining after the MPLS header has been skipped.
1900 *
1901 * If the MPLS header is complete but there are zero bytes of payload after
1902 * the MPLS header, a pointer to where the payload would be is returned and
1903 * remaining will be set to 0.  If the MPLS header is incomplete, NULL will be
1904 * returned and remaining will be set to 0. Therefore, it is important to check
1905 * the value of remaining after calling this function.
1906 *
1907 * type will be set to the ethertype of the MPLS payload. This parameter is
1908 * mandatory - it may not be NULL.
1909 *
1910 * @note This function will only remove one MPLS label at a time - the type
1911 * will be set to 0x8847 if there is another MPLS label following the one
1912 * skipped by this function.
1913 *
1914 */
1915DLLEXPORT void *trace_get_payload_from_mpls(
1916                void *mpls, uint16_t *type, uint32_t *remaining);
1917
1918/** Gets a pointer to the payload following a PPPoE header
1919 * @param pppoe      A pointer to the PPPoE header
1920 * @param[out] type  The ethernet type, replaced by the ether type of the
1921 * returned header - 0x0000 if an Ethernet header is returned
1922 * @param[in,out] remaining  Updated with the number of captured bytes remaining
1923 *
1924 * @return A pointer to the header beyond the PPPoE header. NOTE that this
1925 * function will also skip over the PPP header that will immediately follow
1926 * the PPPoE header. This function will return NULL if there are not enough
1927 * bytes remaining to skip past both the PPPoE and PPP headers.
1928 *
1929 * When calling this function, remaining must contain the number of captured
1930 * bytes remaining in the packet starting from the PPPoE header (including the
1931 * PPPoE header itself). remaining will be updated to contain the number of
1932 * bytes remaining after the PPPoE and PPP headers have been removed.
1933 *
1934 * If the PPPoE and PPP headers are complete but there are zero bytes of
1935 * payload after the PPP header, a pointer to where the payload would be is
1936 * returned and remaining will be set to 0.  If the PPPoE or PPP header is
1937 * incomplete, NULL will be returned and remaining will be set to 0. Therefore,
1938 * it is important to check the value of remaining after calling this function.
1939 *
1940 * type will be set to the ether type of the PPP payload. This parameter is
1941 * mandatory - it may not be NULL.
1942 *
1943 */
1944DLLEXPORT void *trace_get_payload_from_pppoe(
1945                void *pppoe, uint16_t *type, uint32_t *remaining);
1946
1947/** Gets a pointer to the payload following a TCP header
1948 * @param tcp           A pointer to the TCP header
1949 * @param[in,out] remaining Updated with the number of captured bytes remaining
1950 *
1951 * @return A pointer to the TCP payload, or NULL if the TCP header is truncated.
1952 *
1953 * When calling this function, remaining must contain the number of captured
1954 * bytes remaining in the packet starting from the TCP header (including the
1955 * TCP header itself). remaining will be updated to contain the number of
1956 * bytes remaining after the TCP header has been skipped.
1957 *
1958 * If the TCP header is complete but there are zero bytes of payload after
1959 * the TCP header, a pointer to where the payload would be is returned and
1960 * remaining will be set to 0.  If the TCP header is incomplete, NULL will be
1961 * returned and remaining will be set to 0. Therefore, it is important to check
1962 * the value of remaining after calling this function.
1963 *
1964 */
1965DLLEXPORT void *trace_get_payload_from_tcp(libtrace_tcp_t *tcp,
1966                uint32_t *remaining);
1967
1968/** Gets a pointer to the payload following a UDP header
1969 * @param udp           A pointer to the UDP header
1970 * @param[in,out] remaining Updated with the number of captured bytes remaining
1971 *
1972 * @return A pointer to the UDP payload, or NULL if the UDP header is truncated.
1973 *
1974 * When calling this function, remaining must contain the number of captured
1975 * bytes remaining in the packet starting from the UDP header (including the
1976 * UDP header itself). remaining will be updated to contain the number of
1977 * bytes remaining after the UDP header has been skipped.
1978 *
1979 * If the UDP header is complete but there are zero bytes of payload after
1980 * the UDP header, a pointer to where the payload would be is returned and
1981 * remaining will be set to 0.  If the UDP header is incomplete, NULL will be
1982 * returned and remaining will be set to 0. Therefore, it is important to check
1983 * the value of remaining after calling this function.
1984 *
1985 */
1986DLLEXPORT void *trace_get_payload_from_udp(libtrace_udp_t *udp, uint32_t *remaining);
1987
1988/** Gets a pointer to the payload following a ICMP header
1989 * @param icmp           A pointer to the ICMP header
1990 * @param[in,out] remaining Updated with the number of captured bytes remaining
1991 *
1992 * @return A pointer to the ICMP payload, or NULL if the ICMP header is
1993 * truncated.
1994 *
1995 * When calling this function, remaining must contain the number of captured
1996 * bytes remaining in the packet starting from the ICMP header (including the
1997 * ICMP header itself). remaining will be updated to contain the number of
1998 * bytes remaining after the ICMP header has been skipped.
1999 *
2000 * If the ICMP header is complete but there are zero bytes of payload after
2001 * the ICMP header, a pointer to where the payload would be is returned and
2002 * remaining will be set to 0.  If the ICMP header is incomplete, NULL will be
2003 * returned and remaining will be set to 0. Therefore, it is important to check
2004 * the value of remaining after calling this function.
2005 *
2006 * @note In the case of some ICMP messages, the payload may be the IP header
2007 * from the packet that triggered the ICMP message.
2008 *
2009 */
2010DLLEXPORT void *trace_get_payload_from_icmp(libtrace_icmp_t *icmp,
2011                uint32_t *remaining);
2012
2013/** Gets a pointer to the payload following a ICMPv6 header
2014 * @param icmp           A pointer to the ICMPv6 header
2015 * @param[in,out] remaining Updated with the number of captured bytes remaining
2016 *
2017 * @return A pointer to the ICMPv6 payload, or NULL if the ICMPv6 header is
2018 * truncated.
2019 *
2020 * When calling this function, remaining must contain the number of captured
2021 * bytes remaining in the packet starting from the ICMPv6 header (including the
2022 * ICMP header itself). remaining will be updated to contain the number of
2023 * bytes remaining after the ICMPv6 header has been skipped.
2024 *
2025 * If the ICMPv6 header is complete but there are zero bytes of payload after
2026 * the header, a pointer to where the payload would be is returned and
2027 * remaining will be set to 0.  If the ICMPv6 header is incomplete, NULL will be
2028 * returned and remaining will be set to 0. Therefore, it is important to check
2029 * the value of remaining after calling this function.
2030 *
2031 * @note In the case of some ICMPv6 messages, the payload may be the IP header
2032 * from the packet that triggered the ICMP message.
2033 *
2034 */
2035DLLEXPORT void *trace_get_payload_from_icmp6(libtrace_icmp6_t *icmp,
2036                uint32_t *remaining);
2037
2038/** Get a pointer to the TCP header (if present)
2039 * @param packet        The packet to get the TCP header from
2040 *
2041 * @return A pointer to the TCP header, or NULL if there is not a complete TCP
2042 * header present in the packet.
2043 *
2044 * This is a short-cut function enabling quick and easy access to the TCP
2045 * header if that is all you care about. However, we recommend the use of the
2046 * more generic trace_get_transport() function instead.
2047 *
2048 * @note Unlike trace_get_transport(), this function will return NULL if the
2049 * TCP header is incomplete or truncated.
2050 */
2051DLLEXPORT SIMPLE_FUNCTION
2052libtrace_tcp_t *trace_get_tcp(libtrace_packet_t *packet);
2053
2054/** Get a pointer to the TCP header following an IPv4 header (if present)
2055 * @param ip            The IP header to find the subsequent TCP header for
2056 * @param[in,out] remaining Updated with the number of captured bytes remaining
2057 *
2058 * @return A pointer to the TCP header, or NULL if no TCP header is present in
2059 * the packet.
2060 *
2061 * When calling this function, remaining must contain the number of captured
2062 * bytes remaining in the packet starting from the IP header (including the
2063 * IP header itself). remaining will be updated to contain the number of
2064 * bytes remaining after the IP header has been skipped.
2065 *
2066 * If the IP header is complete but there are zero bytes of payload after
2067 * the IP header, a pointer to where the payload would be is returned and
2068 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
2069 * returned and remaining will be set to 0. Therefore, it is important to check
2070 * the value of remaining after calling this function.
2071 *
2072 * @note This function is rather redundant now that the layer 3 header is
2073 * cached. There should be no performance advantage for the user to call this
2074 * function over just calling trace_get_transport().
2075 *
2076 * @note The last parameter has changed from libtrace2
2077 */
2078DLLEXPORT SIMPLE_FUNCTION
2079libtrace_tcp_t *trace_get_tcp_from_ip(libtrace_ip_t *ip, uint32_t *remaining);
2080
2081/** Get a pointer to the UDP header (if present)
2082 * @param packet        The packet to get the UDP header from
2083 *
2084 * @return A pointer to the UDP header, or NULL if there is not a complete UDP
2085 * header present in the packet.
2086 *
2087 * This is a short-cut function enabling quick and easy access to the UDP
2088 * header if that is all you care about. However, we recommend the use of the
2089 * more generic trace_get_transport() function instead.
2090 *
2091 * @note Unlike trace_get_transport(), this function will return NULL if the
2092 * UDP header is incomplete or truncated.
2093 */
2094DLLEXPORT SIMPLE_FUNCTION
2095libtrace_udp_t *trace_get_udp(libtrace_packet_t *packet);
2096
2097/** Get a pointer to the UDP header following an IPv4 header (if present)
2098 * @param ip            The IP header to find the subsequent UDP header for
2099 * @param[in,out] remaining Updated with the number of captured bytes remaining
2100 *
2101 * @return A pointer to the UDP header, or NULL if no UDP header is present in
2102 * the packet.
2103 *
2104 * When calling this function, remaining must contain the number of captured
2105 * bytes remaining in the packet starting from the IP header (including the
2106 * IP header itself). remaining will be updated to contain the number of
2107 * bytes remaining after the IP header has been skipped.
2108 *
2109 * If the IP header is complete but there are zero bytes of payload after
2110 * the IP header, a pointer to where the payload would be is returned and
2111 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
2112 * returned and remaining will be set to 0. Therefore, it is important to check
2113 * the value of remaining after calling this function.
2114 *
2115 * @note This function is rather redundant now that the layer 3 header is
2116 * cached. There should be no performance advantage for the user to call this
2117 * function over just calling trace_get_transport().
2118 *
2119 * @note The last parameter has changed from libtrace2
2120 */
2121DLLEXPORT SIMPLE_FUNCTION
2122libtrace_udp_t *trace_get_udp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
2123
2124/** Get a pointer to the ICMP header (if present)
2125 * @param packet        The packet to get the ICMP header from
2126 *
2127 * @return A pointer to the ICMP header, or NULL if there is not a complete
2128 * ICMP header present in the packet.
2129 *
2130 * This is a short-cut function enabling quick and easy access to the ICMP
2131 * header if that is all you care about. However, we recommend the use of the
2132 * more generic trace_get_transport() function instead.
2133 *
2134 * @note Unlike trace_get_transport(), this function will return NULL if the
2135 * ICMP header is incomplete or truncated.
2136 */
2137DLLEXPORT SIMPLE_FUNCTION
2138libtrace_icmp_t *trace_get_icmp(libtrace_packet_t *packet);
2139
2140/** Get a pointer to the ICMPv6 header (if present)
2141 * @param packet        The packet to get the ICMPv6 header from
2142 *
2143 * @return A pointer to the ICMPv6 header, or NULL if there is not a complete
2144 * ICMP header present in the packet.
2145 *
2146 * This is a short-cut function enabling quick and easy access to the ICMPv6
2147 * header if that is all you care about. However, we recommend the use of the
2148 * more generic trace_get_transport() function instead.
2149 *
2150 * @note Unlike trace_get_transport(), this function will return NULL if the
2151 * ICMPv6 header is incomplete or truncated.
2152 */
2153DLLEXPORT SIMPLE_FUNCTION
2154libtrace_icmp6_t *trace_get_icmp6(libtrace_packet_t *packet);
2155
2156/** Get a pointer to the ICMP header following an IPv4 header (if present)
2157 * @param ip            The IP header to find the subsequent ICMP header for
2158 * @param[in,out] remaining Updated with the number of captured bytes remaining
2159 *
2160 * @return A pointer to the ICMP header, or NULL if no UDP header is present in
2161 * the packet.
2162 *
2163 * When calling this function, remaining must contain the number of captured
2164 * bytes remaining in the packet starting from the IP header (including the
2165 * IP header itself). remaining will be updated to contain the number of
2166 * bytes remaining after the IP header has been skipped.
2167 *
2168 * If the IP header is complete but there are zero bytes of payload after
2169 * the IP header, a pointer to where the payload would be is returned and
2170 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
2171 * returned and remaining will be set to 0. Therefore, it is important to check
2172 * the value of remaining after calling this function.
2173 *
2174 * @note This function is rather redundant now that the layer 3 header is
2175 * cached. There should be no performance advantage for the user to call this
2176 * function over just calling trace_get_transport().
2177 *
2178 * @note The last parameter has changed from libtrace2
2179 */
2180DLLEXPORT SIMPLE_FUNCTION
2181libtrace_icmp_t *trace_get_icmp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
2182
2183/** Get a pointer to the OSPF header (if present)
2184 * @param packet        The packet to get the OSPF header from
2185 * @param[out] version  The OSPF version number
2186 * @param[out] remaining        Updated with the number of captured bytes remaining
2187 * @return A pointer to the start of the OSPF header or NULL if there is no
2188 * complete OSPF header present in the packet
2189 *
2190 * This is a short-cut function enabling quick and easy access to the OSPF
2191 * header. If you only care about the OSPF header, this function may be useful
2192 * but we otherwise recommend the use of the more generic trace_get_transport()
2193 * function instead.
2194 *
2195 * Upon return, 'version' is updated to contain the OSPF version number for the
2196 * packet so that the returned pointer may be cast to the correct type.
2197 * The version parameter MUST contain a valid pointer; it MUST NOT be NULL.
2198 *
2199 * 'remaining' is also set to contain the number of captured bytes remaining
2200 * starting from the pointer returned by this function.
2201 *
2202 * @note Unlike trace_get_transport(), this function will return NULL if the
2203 * OSPF header is incomplete or truncated.
2204 */
2205DLLEXPORT SIMPLE_FUNCTION
2206void *trace_get_ospf_header(libtrace_packet_t *packet, uint8_t *version,
2207                uint32_t *remaining);
2208
2209/** Get a pointer to the contents of the OSPF packet *after* the OSPF header
2210 * @param header        The OSPF header to get the OSPF contents from
2211 * @param[out] ospf_type        The OSPF packet type
2212 * @param[in, out] remaining    Updated with the number of captured bytes remaining
2213 * @return A pointer to the first byte after the OSPF header.
2214 *
2215 * This function returns a void pointer that can be cast appropriately
2216 * based on the ospf_type. For example, if the ospf_type is TRACE_OSPF_HELLO
2217 * then the return pointer should be cast as a libtrace_ospf_hello_v2_t
2218 * structure.
2219 *
2220 * If the OSPF header is truncated, then NULL will be returned. If the OSPF
2221 * contents are missing or truncated, the pointer to the start of the content
2222 * will still be returned so be careful to check the value of remaining.
2223 *
2224 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2225 * packet starting from the beginning of the OSPF header. It will be updated
2226 * to contain the number of bytes remaining from the start of the OSPF contents.
2227 *
2228 * @note This function only works for OSPF version 2 packets.
2229 * @note Use trace_get_first_ospf_lsa_v2_from_X() and trace_get_next_ospf_lsa_v2() to read the LSAs from Link State Update packets.
2230 * @note Use trace_get_first_ospf_lsa_v2_from_X() and trace_get_next_ospf_lsa_header_v2() to read the LSA headers from Link State Ack packets.
2231 *
2232 */
2233DLLEXPORT SIMPLE_FUNCTION
2234void *trace_get_ospf_contents_v2(libtrace_ospf_v2_t *header,
2235                uint8_t *ospf_type, uint32_t *remaining);
2236
2237/** Get a pointer to the start of the first LSA contained within an LS Update packet
2238 * @param ls_update     Pointer to the LS Update header
2239 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2240 * @return A pointer to the first LSA in the packet.
2241 *
2242 * This function simply skips past the LS Update header to provide a suitable
2243 * pointer to pass into trace_get_next_ospf_lsa_v2.
2244 *
2245 * If the OSPF packet is truncated, then NULL will be returned.
2246 *
2247 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2248 * packet starting from the beginning of the LS Update header. It will be
2249 * updated to contain the number of bytes remaining from the start of the
2250 * first LSA.
2251 *
2252 * @note This function only works for OSPF version 2 packets.
2253 * @note trace_get_next_ospf_lsa_v2() should be subequently used to process the LSAs
2254 */
2255DLLEXPORT SIMPLE_FUNCTION
2256unsigned char *trace_get_first_ospf_lsa_from_update_v2(
2257                libtrace_ospf_ls_update_t *ls_update,
2258                uint32_t *remaining);
2259
2260/** Get a pointer to the start of the first LSA contained within an Database Description packet
2261 * @param db_desc       Pointer to the Database Description header
2262 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2263 * @return A pointer to the first LSA in the packet.
2264 *
2265 * This function simply skips past the Database Description header to provide a
2266 * suitable pointer to pass into trace_get_next_ospf_lsa_header_v2.
2267 *
2268 * If the OSPF packet is truncated, then NULL will be returned.
2269 *
2270 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2271 * packet starting from the beginning of the Database Description header. It
2272 * will be updated to contain the number of bytes remaining from the start of
2273 * the first LSA.
2274 *
2275 * @note This function only works for OSPF version 2 packets.
2276 * @note trace_get_next_ospf_lsa_header_v2() should be subequently used to process the LSA headers
2277 */
2278DLLEXPORT SIMPLE_FUNCTION
2279unsigned char *trace_get_first_ospf_lsa_from_db_desc_v2(
2280                libtrace_ospf_db_desc_v2_t *db_desc,
2281                uint32_t *remaining);
2282
2283/** Get a pointer to the start of the first link contained within a Router LSA
2284 * @param lsa   Pointer to the Router LSA
2285 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2286 * @return A pointer to the first link in the packet.
2287 *
2288 * This function simply skips past the Router LSA header to provide a
2289 * suitable pointer to pass into trace_get_next_ospf_link_v2.
2290 *
2291 * If the OSPF packet is truncated, then NULL will be returned.
2292 *
2293 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2294 * packet starting from the beginning of the Router LSA (not including the LSA
2295 * header) header. It will be updated to contain the number of bytes remaining
2296 * from the start of the first Link.
2297 *
2298 * @note This function only works for OSPF version 2 packets.
2299 * @note trace_get_next_ospf_link_v2() should be subequently used to process
2300 * the links
2301 */
2302DLLEXPORT SIMPLE_FUNCTION
2303unsigned char *trace_get_first_ospf_link_from_router_lsa_v2(
2304                libtrace_ospf_router_lsa_v2_t *lsa,
2305                uint32_t *remaining);
2306
2307/** Parses an OSPF Router LSA Link and finds the next Link (if there is one)
2308 * @param[in,out] current       Pointer to the next Link (updated by this function)
2309 * @param[out] link             Set to point to the Link located at the original value of current
2310 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2311 * @param[out] link_len         Set to the size of the Link pointed to by 'link'
2312 * @return 0 if there are no more links after the current one, 1 otherwise.
2313 *
2314 * When called, 'current' MUST point to an OSPF Router LSA link. Ideally, this
2315 * would come from either a call to
2316 * trace_get_first_ospf_link_from_router_lsa_v2() or a previous call of this
2317 * function.
2318 *
2319 * 'link' will be set to the value of 'current', so that the caller may then
2320 * do any processing they wish on that particular link. 'current' is advanced
2321 * to point to the next link and 'link_len' is updated to report the size of
2322 * the original link.
2323 *
2324 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2325 * packet starting from the beginning of the Link pointed to by 'current'.
2326 * It will be updated to contain the number of bytes remaining from the start
2327 * of the next link.
2328 *
2329 * If this function returns 0 but 'link' is NOT NULL, that link is still valid
2330 * but there are no more links after this one.
2331 * If this function returns 0 AND link is NULL, the link is obviously not
2332 * suitable for processing.
2333 *
2334 * @note This function only works for OSPF version 2 packets.
2335 */
2336DLLEXPORT SIMPLE_FUNCTION
2337int trace_get_next_ospf_link_v2(unsigned char **current,
2338                libtrace_ospf_link_v2_t **link,
2339                uint32_t *remaining,
2340                uint32_t *link_len);
2341
2342/** Parses an OSPF LSA and finds the next LSA (if there is one)
2343 * @param[in,out] current       Pointer to the next LSA (updated by this function)
2344 * @param[out] lsa_hdr          Set to point to the header of the LSA located at the original value of current
2345 * @param[out] lsa_body         Set to point to the body of the LSA located at the original value of current
2346 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2347 * @param[out] lsa_type         Set to the type of the LSA located at the original value of current
2348 * @param[out] lsa_length       Set to the size of the LSA located at the original value of current
2349 * @return 1 if there are more LSAs after the current one, 0 if there are no more LSAs to come, and -1 if the current LSA is incomplete, truncated or invalid.
2350 *
2351 * When called, 'current' MUST point to an OSPF LSA. Ideally, this would come
2352 * from either a call to trace_get_first_ospf_lsa_from_update_v2() or a
2353 * previous call of this function.
2354 *
2355 * This function should only be used to access COMPLETE LSAs, i.e. LSAs that
2356 * have both a header and a body. In OSPFv2, only the LSAs contained within
2357 * LSA Update packets meet this requirement. trace_get_next_ospf_lsa_header_v2
2358 * should be used to read header-only LSAs, e.g. those present in LS Acks.
2359 *
2360 * 'lsa_hdr' will be set to the value of 'current', so that the caller may then
2361 * do any processing they wish on that particular LSA. 'lsa_body' will be set
2362 * to point to the first byte after the LSA header. 'current' is advanced
2363 * to point to the next LSA. 'lsa_length' is updated to contain the size of
2364 * the parsed LSA, while 'lsa_type' is set to indicate the LSA type.
2365 *
2366 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2367 * packet starting from the beginning of the LSA pointed to by 'current'.
2368 * It will be updated to contain the number of bytes remaining from the start
2369 * of the next LSA.
2370 *
2371 * If this function returns 0 but 'lsa_hdr' is NOT NULL, that LSA is still
2372 * valid but there are no more LSAs after this one.
2373 * If this function returns 0 AND 'lsa_hdr' is NULL, the LSA is obviously not
2374 * suitable for processing.
2375 *
2376 * It is also recommended to check the value of 'lsa_body' before
2377 * de-referencing it. 'lsa_body' will be set to NULL if there is only an LSA
2378 * header present.
2379 *
2380 * @note This function only works for OSPF version 2 packets.
2381 *
2382 */
2383DLLEXPORT SIMPLE_FUNCTION
2384int trace_get_next_ospf_lsa_v2(unsigned char **current,
2385                libtrace_ospf_lsa_v2_t **lsa_hdr,
2386                unsigned char **lsa_body,
2387                uint32_t *remaining,
2388                uint8_t *lsa_type,
2389                uint16_t *lsa_length);
2390
2391/** Parses an OSPF LSA header and finds the next LSA (if there is one)
2392 * @param[in,out] current       Pointer to the next LSA (updated by this function)
2393 * @param[out] lsa_hdr          Set to point to the header of the LSA located at the original value of current
2394 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2395 * @param[out] lsa_length       Set to the size of the LSA located at the original value of current
2396 * @return 1 if there are more LSAs after the current one, 0 if there are no more LSAs to come, and -1 if the current LSA is incomplete, truncated or invalid.
2397 *
2398 * When called, 'current' MUST point to an OSPF LSA. Ideally, this would come
2399 * from either a call to trace_get_first_ospf_lsa_from_db_desc_v2() or a
2400 * previous call of this function.
2401 *
2402 * This function should only be used to access LSA headers, i.e. LSAs that
2403 * have a header only. In OSPFv2, the LSAs contained within LSA Ack and
2404 * Database Description packets meet this requirement.
2405 * trace_get_next_ospf_lsa_v2 should be used to read full LSAs, e.g. those
2406 * present in LS Updates.
2407 *
2408 * 'lsa_hdr' will be set to the value of 'current', so that the caller may then
2409 * do any processing they wish on that particular LSA header. 'current' is
2410 * advanced to point to the next LSA header. 'lsa_length' is updated to contain
2411 * the size of the parsed LSA header.
2412 *
2413 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2414 * packet starting from the beginning of the LSA pointed to by 'current'.
2415 * It will be updated to contain the number of bytes remaining from the start
2416 * of the next LSA.
2417 *
2418 * If this function returns 0 but 'lsa_hdr' is NOT NULL, that LSA is still
2419 * valid but there are no more LSAs after this one.
2420 * If this function returns 0 AND 'lsa_hdr' is NULL, the LSA is obviously not
2421 * suitable for processing.
2422 *
2423 * @note This function only works for OSPF version 2 packets.
2424 *
2425 */
2426DLLEXPORT SIMPLE_FUNCTION
2427int trace_get_next_ospf_lsa_header_v2(unsigned char **current,
2428                libtrace_ospf_lsa_v2_t **lsa_hdr,
2429                uint32_t *remaining,
2430                uint8_t *lsa_type,
2431                uint16_t *lsa_length);
2432
2433/** Extracts the metric field from an AS External LSA packet
2434 *
2435 * @param as_lsa        The AS External LSA
2436 * @returns The value of the metric field
2437 *
2438 * The metric field in the AS External LSA packet is a 24-bit value, which
2439 * is difficult to extract correctly. To avoid byte-ordering issues, use this
2440 * function which will extract the correct value for you.
2441 */
2442DLLEXPORT SIMPLE_FUNCTION
2443uint32_t trace_get_ospf_metric_from_as_external_lsa_v2(
2444                libtrace_ospf_as_external_lsa_v2_t *as_lsa);
2445
2446/** Extracts the metric field from a Summary LSA packet
2447 *
2448 * @param sum_lsa       The Summary LSA
2449 * @returns The value of the metric field
2450 *
2451 * The metric field in the Summary LSA packet is a 24-bit value, which
2452 * is difficult to extract correctly. To avoid byte-ordering issues, use this
2453 * function which will extract the correct value for you.
2454 */
2455DLLEXPORT SIMPLE_FUNCTION
2456uint32_t trace_get_ospf_metric_from_summary_lsa_v2(
2457                libtrace_ospf_summary_lsa_v2_t *sum_lsa);
2458
2459
2460/** Gets the destination MAC address for a given packet
2461 * @param packet        The packet to extract the destination MAC address from
2462 *
2463 * @return A pointer to the destination MAC address field in the layer 2
2464 * header, (or NULL if there is no destination MAC address or layer 2 header
2465 * available)
2466 *
2467 * @note This is a zero-copy function, so the memory that the returned pointer
2468 * points to is part of the packet itself.
2469 */
2470DLLEXPORT SIMPLE_FUNCTION
2471uint8_t *trace_get_destination_mac(libtrace_packet_t *packet);
2472
2473/** Gets the source MAC address for a given packet
2474 * @param packet        The packet to extract the source MAC address from
2475 *
2476 * @return A pointer to the source MAC address field in the layer 2
2477 * header, (or NULL if there is no source MAC address or layer 2 header
2478 * available)
2479 *
2480 * @note This is a zero-copy function, so the memory that the returned pointer
2481 * points to is part of the packet itself.
2482 */
2483DLLEXPORT SIMPLE_FUNCTION
2484uint8_t *trace_get_source_mac(libtrace_packet_t *packet);
2485
2486/** Get the source IP address for a given packet
2487 * @param packet        The packet to extract the source IP address from
2488 * @param addr          A pointer to a sockaddr structure to store the address
2489 *                      in. If NULL, static storage is used instead.
2490 * @return A pointer to a sockaddr holding a v4 or v6 IP address or on some
2491 * platforms a sockaddr holding a MAC address. Returns NULL if no source IP
2492 * address was available.
2493 *
2494 * @note The best way to use this function is to pass in a pointer to the
2495 * struct sockaddr_storage for the addr parameter. This will avoid problems
2496 * with trying to shoe-horn an IPv6 address into a sockaddr that only supports
2497 * IPv4.
2498 */
2499DLLEXPORT SIMPLE_FUNCTION
2500struct sockaddr *trace_get_source_address(const libtrace_packet_t *packet,
2501                struct sockaddr *addr);
2502
2503/** Get the source IP address for a packet and convert it into a string
2504 * @param packet        The packet to extract the source IP address from
2505 * @param space         A pointer to a character buffer to store the address
2506 *                      in. If NULL, static storage is used instead.
2507 * @param spacelen      The size of the buffer passed in via 'space'. Set this
2508 *                      to zero if you are going to pass in a NULL buffer.
2509 * @return A pointer to a character buffer containing the string representation
2510 * of the source IP address. For packets where there is no suitable IP address,
2511 * the source MAC will be returned instead. Returns NULL if no valid address
2512 * is available.
2513 *
2514 * @note Be wary of the possibility of the address being an IPv6 address - make
2515 * sure your buffer is large enough!
2516 *
2517 * New in libtrace 3.0.17.
2518 */
2519DLLEXPORT SIMPLE_FUNCTION
2520char *trace_get_source_address_string(const libtrace_packet_t *packet,
2521                char *space, int spacelen);
2522
2523/** Get the destination IP address for a given packet
2524 * @param packet        The packet to extract the destination IP address from
2525 * @param addr          A pointer to a sockaddr structure to store the address
2526 *                      in. If NULL, static storage is used instead.
2527 * @return A pointer to a sockaddr holding a v4 or v6 IP address or on some
2528 * platforms a sockaddr holding a MAC address. Returns NULL if no destination
2529 * IP address was available.
2530 *
2531 * @note The best way to use this function is to pass in a pointer to the
2532 * struct sockaddr_storage for the addr parameter. This will avoid problems
2533 * with trying to shoe-horn an IPv6 address into a sockaddr that only supports
2534 * IPv4.
2535 */
2536DLLEXPORT SIMPLE_FUNCTION
2537struct sockaddr *trace_get_destination_address(const libtrace_packet_t *packet,
2538                struct sockaddr *addr);
2539
2540/** Get the destination IP address for a packet and convert it into a string
2541 * @param packet        The packet to extract the destination IP address from
2542 * @param space         A pointer to a character buffer to store the address
2543 *                      in. If NULL, static storage is used instead.
2544 * @param spacelen      The size of the buffer passed in via 'space'. Set this
2545 *                      to zero if you are going to pass in a NULL buffer.
2546 * @return A pointer to a character buffer containing the string representation
2547 * of the destination IP address. For packets where there is no suitable IP
2548 * address, the destination MAC will be returned instead. Returns NULL if no
2549 * valid address is available.
2550 *
2551 * @note Be wary of the possibility of the address being an IPv6 address - make
2552 * sure your buffer is large enough!
2553 *
2554 * New in libtrace 3.0.17.
2555 */
2556DLLEXPORT SIMPLE_FUNCTION
2557char *trace_get_destination_address_string(const libtrace_packet_t *packet,
2558                char *space, int spacelen);
2559
2560/** Parses an IP or TCP option
2561 * @param[in,out] ptr   The pointer to the current option
2562 * @param[in,out] len   The total length of all the remaining options
2563 * @param[out] type     The type of the option
2564 * @param[out] optlen   The length of the option
2565 * @param[out] data     The data of the option
2566 *
2567 * @return bool true if there is another option (and the fields are filled in)
2568 *               or false if this was the last option.
2569 *
2570 * This updates ptr to point to the next option after this one, and updates
2571 * len to be the number of bytes remaining in the options area.  Type is updated
2572 * to be the code of this option, and data points to the data of this option,
2573 * with optlen saying how many bytes there are.
2574 *
2575 * @note Beware of fragmented packets.
2576 */
2577DLLEXPORT int trace_get_next_option(unsigned char **ptr,int *len,
2578                        unsigned char *type,
2579                        unsigned char *optlen,
2580                        unsigned char **data);
2581
2582/*@}*/
2583
2584/** @name Time
2585 * These functions deal with the timestamp describing when a packet was
2586 * captured and can convert it into various formats
2587 * @{
2588 */
2589
2590/** Get the packet timestamp in the DAG time format
2591 * @param packet        The packet to extract the timestamp from
2592 *
2593 * @return a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
2594 * past 1970-01-01, the lower 32bits are partial seconds)
2595 */
2596DLLEXPORT SIMPLE_FUNCTION
2597uint64_t trace_get_erf_timestamp(const libtrace_packet_t *packet);
2598
2599/** Get the packet timestamp as a struct timeval
2600 * @param packet        The packet to extract the timestamp from
2601 *
2602 * @return The time that this packet was captured in a struct timeval
2603 */
2604DLLEXPORT SIMPLE_FUNCTION
2605struct timeval trace_get_timeval(const libtrace_packet_t *packet);
2606
2607/** Get the packet timestamp as a struct timespec
2608 * @param packet        The packet to extract the timestamp from
2609 *
2610 * @return The time that this packet was captured in a struct timespec
2611 */
2612DLLEXPORT SIMPLE_FUNCTION
2613struct timespec trace_get_timespec(const libtrace_packet_t *packet);
2614
2615/** Get the packet timestamp in floating point seconds
2616 * @param packet        The packet to extract the timestamp from
2617 *
2618 * @return time that this packet was seen in 64-bit floating point seconds from
2619 * the UNIX epoch (1970-01-01 00:00:00 UTC).
2620 */
2621DLLEXPORT SIMPLE_FUNCTION
2622double trace_get_seconds(const libtrace_packet_t *packet);
2623
2624/** Seek within an input trace to a time specified in floating point seconds
2625 * @param trace         The input trace to seek within
2626 * @param seconds       The time to seek to, in floating point seconds
2627 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
2628 * the error that occurred.
2629 *
2630 * This will make the next packet read to be the first packet to occur at or
2631 * after the specified time.  This must be called in the configuration state
2632 * (i.e. before trace_start() or after trace_pause()).
2633 *
2634 * The time format accepted by this function is 64-bit floating point seconds
2635 * since the UNIX epoch (1970-01-01 00:00:00 UTC), i.e. the same format as
2636 * trace_get_seconds().
2637 *
2638 * @note This function may be extremely slow.
2639 */
2640DLLEXPORT int trace_seek_seconds(libtrace_t *trace, double seconds);
2641
2642/** Seek within an input trace to a time specified as a timeval
2643 * @param trace         The input trace to seek within
2644 * @param tv            The time to seek to, as a timeval
2645 *
2646 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
2647 * the error that occurred.
2648 *
2649 * This will make the next packet read to be the first packet to occur at or
2650 * after the specified time.  This must be called in the configuration state
2651 * (i.e. before trace_start() or after trace_pause()).
2652 *
2653 * @note This function may be extremely slow.
2654 */
2655DLLEXPORT int trace_seek_timeval(libtrace_t *trace, struct timeval tv);
2656
2657/** Seek within an input trace to a time specified as an ERF timestamp
2658 * @param trace         The input trace to seek within
2659 * @param ts            The time to seek to, as an ERF timestamp
2660 *
2661 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
2662 * the error that occurred.
2663 *
2664 * This will make the next packet read to be the first packet to occur at or
2665 * after the specified time.  This must be called in the configuration state
2666 * (i.e. before trace_start() or after trace_pause()).
2667 *
2668 * The time format accepted by this function is the ERF timestamp, which is a
2669 * 64-bit value where the upper 32 bits are seconds since the UNIX epoch and
2670 * the lower 32 bits are partial seconds.
2671 *
2672 * @note This function may be extremely slow.
2673 */
2674DLLEXPORT int trace_seek_erf_timestamp(libtrace_t *trace, uint64_t ts);
2675
2676/*@}*/
2677
2678/** @name Sizes
2679 * This section deals with finding or setting the various different lengths
2680 * that a packet can have, e.g. capture lengths, wire lengths, etc.
2681 * @{
2682 */
2683/** Get the current size of the packet (in bytes), taking into account any
2684 * truncation or snapping that may have previously been performed.
2685 *
2686 * @param packet        The packet to determine the capture length for
2687 * @return The size of the packet read from the input trace, i.e. what is
2688 * actually available to libtrace at the moment.
2689 *
2690 * @note Most traces are header captures, so this value may not be the same
2691 * as the size of the packet when it was captured. Use trace_get_wire_length()
2692 * to get the original size of the packet.
2693 
2694 * @note This can (and often is) different for different packets in a trace!
2695 
2696 * @note This is sometimes called the "snaplen".
2697 *
2698 * @note The return size refers to the network-level payload of the packet and
2699 * does not include any capture framing headers. For example, an Ethernet
2700 * packet with an empty TCP packet will return sizeof(ethernet_header) +
2701 * sizeof(ip_header) + sizeof(tcp_header), but not the capture format
2702 * (pcap/erf/etc) header.
2703 */
2704DLLEXPORT SIMPLE_FUNCTION
2705size_t trace_get_capture_length(const libtrace_packet_t *packet);
2706
2707/** Get the size of the packet as it was originally seen on the wire (in bytes).
2708 * @param packet        The packet to determine the wire length for
2709 * @return The size of the packet as it was on the wire.
2710 *
2711 * @note This value may not be the same as the capture length, due to
2712 * truncation.
2713 *
2714 * @note trace_get_wire_length \em includes  the Frame Check Sequence. This is
2715 * different behaviour compared to most PCAP-based tools.
2716 *
2717 * @note The return size refers to the network-level payload of the packet and
2718 * does not include any capture framing headers. For example, an Ethernet
2719 * packet with an empty TCP packet will return sizeof(ethernet_header) +
2720 * sizeof(ip_header) + sizeof(tcp_header), but not the capture format
2721 * (pcap/erf/etc) header.
2722 */
2723DLLEXPORT SIMPLE_FUNCTION
2724size_t trace_get_wire_length(const libtrace_packet_t *packet);
2725
2726/** Get the length of the capture framing headers (in bytes).
2727 * @param packet        The packet to determine the framing length for
2728 * @return The size of the capture format header encapsulating the packet.
2729 *
2730 * @note This length corresponds to the difference between the amount of
2731 * memory required to store a captured packet and the capture length reported
2732 * by trace_capture_length()
2733 */
2734DLLEXPORT SIMPLE_FUNCTION
2735size_t trace_get_framing_length(const libtrace_packet_t *packet);
2736
2737/** Get the length of the original payload content of the packet (in bytes).
2738 * @param packet        The packet to determine the payload length for
2739 * @return The size of the packet payload (without headers). Returns 0 if
2740 * unable to calculate payload length correctly.
2741 *
2742 * This function reports the amount of data that followed the transport header
2743 * when the packet was originally captured, i.e. prior to any snapping. Best
2744 * described as the wire length minus the packet headers.
2745 *
2746 * Currently only supports some protocols and will return 0 if an unsupported
2747 * protocol header is encountered, or if one of the headers is truncated.
2748 *
2749 * @note Supports IPv4, IPv6, TCP, UDP and ICMP.
2750 */
2751DLLEXPORT SIMPLE_FUNCTION
2752size_t trace_get_payload_length(const libtrace_packet_t *packet);
2753
2754/** Truncate ("snap") the packet to the suggested length
2755 * @param packet        The packet to truncate
2756 * @param size          The new length of the packet (in bytes)
2757 *
2758 * @return The new capture length of the packet or the original capture
2759 * length of the packet if unchanged.
2760 *
2761 * This function will modify the capture length of the given packet. The wire
2762 * length will not be changed, so you can always determine what the original
2763 * packet size was, prior to the truncation.
2764 *
2765 * @note You can only use this function to decrease the capture length. Any
2766 * attempt to increase capture length will have no effect.
2767 */
2768DLLEXPORT size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
2769
2770/*@}*/
2771
2772
2773/** Gets the link layer type for a packet
2774 * @param packet        The packet to extract the link layer type for
2775 * @return A libtrace_linktype_t describing the link layer protocol being used
2776 * by this packet.
2777 */
2778DLLEXPORT SIMPLE_FUNCTION
2779libtrace_linktype_t trace_get_link_type(const libtrace_packet_t *packet);
2780
2781/** Set the direction flag for a packet, if the capture format supports
2782 * direction tagging.
2783 *
2784 * @param packet        The packet to set the direction for
2785 * @param direction     The new direction
2786 * @returns -1 on error, or the direction that was set.
2787 *
2788 * @note Few capture formats actually support direction tagging. Most notably,
2789 * we cannot set the direction on PCAP packets.
2790 */
2791DLLEXPORT libtrace_direction_t trace_set_direction(libtrace_packet_t *packet, libtrace_direction_t direction);
2792
2793/** Get the direction flag for a packet, if it has one.
2794 * @param packet  The packet to get the direction for
2795 *
2796 * @return A value representing the direction flag, or -1 if this is not
2797 * supported by the capture format.
2798 *
2799 * The direction is defined as 0 for packets originating locally (ie, outbound)
2800 * and 1 for packets originating remotely (ie, inbound). Other values are
2801 * possible, which might be overloaded to mean special things for certain
2802 * traces, e.g. in the Waikato traces, 2 is used to represent an "Unknown"
2803 * direction.
2804 *
2805 * For DAG/ERF traces, the direction is extracted from the "Interface" bits in
2806 * the ERF header, which can range from 0 - 3.
2807 */
2808DLLEXPORT SIMPLE_FUNCTION
2809libtrace_direction_t trace_get_direction(const libtrace_packet_t *packet);
2810
2811/** @name BPF
2812 * This section deals with using Berkley Packet Filters to filter input traces
2813 * @{
2814 */
2815/** Creates a BPF filter
2816 * @param filterstring The filter string describing the BPF filter to create
2817 * @return An opaque pointer to a libtrace_filter_t object
2818 *
2819 * @note The filter is not actually compiled at this point, so no correctness
2820 * tests are performed here. trace_create_filter() will always return ok, but
2821 * if the filter is poorly constructed an error will be generated when the
2822 * filter is actually used.
2823 */
2824DLLEXPORT SIMPLE_FUNCTION
2825libtrace_filter_t *trace_create_filter(const char *filterstring);
2826
2827/** Create a BPF filter based on pre-compiled byte-code.
2828 * @param bf_insns      A pointer to the start of the byte-code
2829 * @param bf_len        The number of BPF instructions 
2830 * @return              An opaque pointer to a libtrace_filter_t object
2831 * @note                The supplied byte-code is not checked for correctness.
2832 *                      Instead, incorrect byte-code will generate an error
2833 *                      once the filter is actually used.
2834 * @author              Scott Raynel
2835 */
2836DLLEXPORT libtrace_filter_t *
2837trace_create_filter_from_bytecode(void *bf_insns, unsigned int bf_len);
2838
2839/** Apply a BPF filter to a packet
2840 * @param filter        The filter to be applied       
2841 * @param packet        The packet to be matched against the filter
2842 * @return >0 if the filter matches, 0 if it doesn't, -1 on error.
2843 *
2844 * @note Due to the way BPF filters are built, the filter is not actually
2845 * compiled until the first time trace_create_filter is called. If your filter
2846 * is incorrect, it will generate an error message and assert, exiting the
2847 * program. This behaviour may change to a more graceful handling of this error
2848 * in the future.
2849 */
2850DLLEXPORT int trace_apply_filter(libtrace_filter_t *filter,
2851                const libtrace_packet_t *packet);
2852
2853/** Destroy a BPF filter
2854 * @param filter        The filter to be destroyed
2855 *
2856 * Deallocates all the resources associated with a BPF filter.
2857 */
2858DLLEXPORT void trace_destroy_filter(libtrace_filter_t *filter);
2859/*@}*/
2860
2861/** @name Portability
2862 * This section contains functions that deal with portability issues, e.g. byte
2863 * ordering.
2864 * @{
2865 */
2866
2867/** Converts an ethernet address to a printable string
2868 * @param addr  Ethernet address in network byte order
2869 * @param buf   Buffer to store the ascii representation, or NULL to indicate
2870 * that static storage should be used.
2871 * @return buf, or if buf is NULL then a statically allocated buffer.
2872 *
2873 * This function is similar to the GNU ether_ntoa_r function, with a few
2874 * minor differences.  If NULL is passed as buf, then the function will
2875 * use an internal static buffer. If NULL isn't passed then the function
2876 * will use that buffer instead.
2877 *
2878 * The address pointers returned by trace_get_source_mac() and
2879 * trace_get_destination_mac() can be passed directly into this function.
2880 *
2881 * @note The type of addr isn't struct ether_addr as it is with ether_ntoa_r,
2882 * however it is bit compatible so that a cast will work.
2883 */
2884DLLEXPORT char *trace_ether_ntoa(const uint8_t *addr, char *buf);
2885
2886/** Convert a string to an ethernet address
2887 * @param buf   A string containing an Ethernet address in hex format
2888 * delimited with :'s.
2889 * @param addr  Buffer to store the binary representation, or NULL to indicate
2890 * that static storage should be used.
2891 * @return addr, or if addr is NULL then a statically allocated buffer.
2892 *
2893 * This function is similar to the GNU ether_aton_r function, with a few
2894 * minor differences.  If NULL is passed as addr, then the function will
2895 * use an internal static buffer. If NULL isn't passed then the function will
2896 * use that buffer instead.
2897 *
2898 * The address returned by this function will be in network byte order.
2899 *
2900 * @note the type of addr isn't struct ether_addr as it is with ether_aton_r,
2901 * however it is bit compatible so that a cast will work.
2902 */
2903DLLEXPORT uint8_t *trace_ether_aton(const char *buf, uint8_t *addr);
2904
2905/*@}*/
2906
2907/** @name Ports
2908 * This section contains functions for dealing with port numbers at the
2909 * transport layer.
2910 *
2911 * @{
2912 */
2913
2914/** An indication of which port is the "server" port for a given port pair */
2915typedef enum {
2916        USE_DEST,       /**< Destination port is the server port */
2917        USE_SOURCE      /**< Source port is the server port */
2918} serverport_t;
2919
2920/** Gets the source port for a given packet
2921 * @param packet        The packet to get the source port from
2922 * @return The source port in HOST byte order or 0 if no suitable port number
2923 * can be extracted from the packet.
2924 *
2925 * This function will return 0 if the transport protocol is known not to
2926 * use port numbers, e.g. ICMP. 0 is also returned if no transport header is
2927 * present in the packet or the transport header has been truncated such that
2928 * the port fields are not readable.
2929 *
2930 * @note If the transport protocol is not known by libtrace, the first two
2931 * bytes of the transport header will be treated as the source port field.
2932 */
2933DLLEXPORT SIMPLE_FUNCTION
2934uint16_t trace_get_source_port(const libtrace_packet_t *packet);
2935
2936/** Gets the destination port for a given packet
2937 * @param packet        The packet to get the destination port from
2938 * @return The destination port in HOST byte order or 0 if no suitable port
2939 * number can be extracted from the packet.
2940 *
2941 * This function will return 0 if the transport protocol is known not to
2942 * use port numbers, e.g. ICMP. 0 is also returned if no transport header is
2943 * present in the packet or the transport header has been truncated such that
2944 * the port fields are not readable.
2945 *
2946 * @note If the transport protocol is not known by libtrace, the third and
2947 * fourth bytes of the transport header will be treated as the destination
2948 * port field.
2949 *
2950 */
2951DLLEXPORT SIMPLE_FUNCTION
2952uint16_t trace_get_destination_port(const libtrace_packet_t *packet);
2953
2954/** Hint at which of the two provided ports is the server port.
2955 *
2956 * @param protocol      The IP layer protocol, eg 6 (tcp), 17 (udp)
2957 * @param source        The source port from the packet
2958 * @param dest          The destination port from the packet
2959 *
2960 * @return one of USE_SOURCE or USE_DEST describing on which of the two ports
2961 * is most likely to be the server port.
2962 *
2963 * @note Ports must be provided in HOST byte order!
2964 *
2965 * This function is based almost entirely on heuristics and should not be
2966 * treated as a definitive means of identifying the server port. However, it
2967 * is deterministic, so it is very handy for identifying both halves of the
2968 * same flow.
2969 */
2970DLLEXPORT SIMPLE_FUNCTION
2971int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
2972
2973/*@}*/
2974
2975/** @name Wireless trace support
2976 * Functions to access wireless information from packets that have wireless
2977 * monitoring headers such as Radiotap or Prism.
2978 *
2979 * The trace_get_wireless_* functions provide an abstract interface for
2980 * retrieving information from wireless traces. They take a pointer to the
2981 * wireless monitoring header (usually found with trace_get_packet_meta()) and
2982 * the linktype of the header passed in.
2983 *
2984 * All of the trace_get_wireless_* functions return false if the requested
2985 * information was unavailable, or true if it was. The actual data is stored
2986 * in an output variable supplied by the caller. Values returned into the
2987 * output variable will always be returned in host byte order.
2988 * @{
2989 */
2990
2991
2992#ifndef ARPHRD_80211_RADIOTAP
2993/** libc doesn't define this yet, so we have to do so ourselves */
2994#define ARPHRD_80211_RADIOTAP 803
2995#endif
2996
2997/** Get the wireless Timer Synchronisation Function
2998 *
2999 * Gets the value of the timer synchronisation function for this frame, which
3000 * is a value in microseconds indicating the time that the first bit of the
3001 * MPDU was received by the MAC.
3002 *
3003 * @param linkptr The wireless meta header
3004 * @param linktype The linktype of the wireless meta header passed in
3005 * @param[out] tsft The value of the timer synchronisation function.
3006 * @return true if the field was available, false if not.
3007 */
3008DLLEXPORT bool trace_get_wireless_tsft(void *linkptr,
3009        libtrace_linktype_t linktype, uint64_t *tsft);
3010
3011/** Get the wireless data rate
3012 *
3013 * @param linkptr The wireless meta header
3014 * @param linktype The linktype of the wireless meta header passed in
3015 * @param[out] rate The data-rate of the frame in units of 500kbps
3016 * @return true if the field was available, false if not.
3017 */
3018DLLEXPORT bool trace_get_wireless_rate(void *linkptr,
3019        libtrace_linktype_t linktype, uint8_t *rate);
3020
3021/** Get the wireless channel frequency
3022 * @param linkptr The wireless meta header
3023 * @param linktype The linktype of the wireless meta header passed in
3024 * @param[out] freq The frequency in MHz of the channel the frame was
3025 * transmitted or received on.
3026 * @return true if the field was available, false if not.
3027 */
3028DLLEXPORT bool trace_get_wireless_freq(void *linkptr,
3029        libtrace_linktype_t linktype, uint16_t *freq);
3030
3031/** Get the wireless signal strength in dBm
3032 * @param linkptr The wireless meta header
3033 * @param linktype The linktype of the wireless meta header passed in
3034 * @param[out] strength The RF signal power at the antenna, in dB difference
3035 * from 1mW.
3036 * @return true if the field was available, false if not.
3037 */
3038DLLEXPORT bool trace_get_wireless_signal_strength_dbm(void *linkptr,
3039        libtrace_linktype_t linktype, int8_t *strength);
3040
3041/** Get the wireless noise strength in dBm
3042 * @param linkptr The wireless meta header
3043 * @param linktype The linktype of the wireless meta header passed in
3044 * @param[out] strength The RF noise power at the antenna, in dB difference
3045 * from 1mW.
3046 * @return true if the field was available, false if not.
3047 */
3048DLLEXPORT bool trace_get_wireless_noise_strength_dbm(void *linkptr,
3049        libtrace_linktype_t linktype, int8_t *strength);
3050
3051/** Get the wireless signal strength in dB
3052 * @param linkptr The wireless meta header
3053 * @param linktype The linktype of the wireless meta header passed in
3054 * @param[out] strength The RF signal power at the antenna, in dB difference
3055 * from a fixed reference.
3056 * @return true if the field was available, false if not.
3057 */
3058DLLEXPORT bool trace_get_wireless_signal_strength_db(void *linkptr,
3059        libtrace_linktype_t linktype, uint8_t *strength);
3060
3061/** Get the wireless noise strength in dB
3062 * @param linkptr The wireless meta header
3063 * @param linktype The linktype of the wireless meta header passed in
3064 * @param[out] strength The RF noise power at the antenna, in dB difference
3065 * from a fixed reference.
3066 * @return true if the field was available, false if not.
3067 */
3068DLLEXPORT bool trace_get_wireless_noise_strength_db(void *linkptr,
3069        libtrace_linktype_t linktype, uint8_t *strength);
3070
3071/** Get the wireless transmit attenuation
3072 * @param linkptr The wireless meta header
3073 * @param linktype The linktype of the wireless meta header passed in
3074 * @param[out] attenuation The transmit power as a unitless distance from
3075 * maximum power set at factory calibration. 0 indicates maximum transmission
3076 * power.
3077 * @return true if the field was available, false if not.
3078 */
3079DLLEXPORT bool trace_get_wireless_tx_attenuation(void *linkptr,
3080        libtrace_linktype_t linktype, uint16_t *attenuation);
3081
3082/** Get the wireless transmit attenuation in dB
3083 * @param linkptr The wireless meta header
3084 * @param linktype The linktype of the wireless meta header passed in
3085 * @param[out] attenuation The transmit power as dB difference from maximum
3086 * power set at factory calibration. 0 indicates maximum power.
3087 * @return true if the field was available, false if not.
3088 */
3089DLLEXPORT bool trace_get_wireless_tx_attenuation_db(void *linkptr,
3090        libtrace_linktype_t linktype, uint16_t *attenuation);
3091
3092/** Get the wireless transmit power in dBm
3093 * @param linkptr The wireless meta header
3094 * @param linktype The linktype of the wireless meta header passed in
3095 * @param[out] txpower The transmit power as dB from a 1mW reference. This is
3096 * the absolute power level measured at the antenna port. 
3097 * @return true if the field was available, false if not.
3098 */
3099DLLEXPORT bool trace_get_wireless_tx_power_dbm(void *linkptr,
3100                libtrace_linktype_t linktype, int8_t *txpower);
3101
3102/** Get the wireless antenna
3103 * @param linkptr The wireless meta header
3104 * @param linktype The linktype of the wireless meta header passed in
3105 * @param[out] antenna The antenna that was used to transmit or receive the
3106 * frame.
3107 * @return true if the field was available, false if not.
3108 */
3109DLLEXPORT bool trace_get_wireless_antenna(void *linkptr,
3110        libtrace_linktype_t linktype, uint8_t *antenna);
3111
3112/*@}*/
3113
3114typedef void* (*fn_per_pkt)(libtrace_t* trace, libtrace_packet_t *p, libtrace_message_t *m, libtrace_thread_t *thread);
3115typedef void* (*fn_reducer)(libtrace_t* trace, void* global_blob);
3116typedef uint64_t (*fn_hasher)(const libtrace_packet_t* packet, void *data);
3117
3118DLLEXPORT int trace_pstart(libtrace_t *libtrace, void* global_blob, fn_per_pkt per_pkt, fn_reducer reducer);
3119DLLEXPORT int trace_pread_packet(libtrace_t *libtrace, libtrace_packet_t **packet);
3120DLLEXPORT int trace_ppause(libtrace_t *libtrace);
3121DLLEXPORT int trace_pstop(libtrace_t *libtrace);
3122DLLEXPORT void trace_join(libtrace_t * trace);
3123DLLEXPORT void print_contention_stats (libtrace_t *libtrace);
3124
3125DLLEXPORT void libtrace_result_set_key(libtrace_result_t * result, uint64_t key);
3126DLLEXPORT uint64_t libtrace_result_get_key(libtrace_result_t * result);
3127DLLEXPORT void libtrace_result_set_value(libtrace_result_t * result, void * value);
3128DLLEXPORT void* libtrace_result_get_value(libtrace_result_t * result);
3129DLLEXPORT void libtrace_result_set_key_value(libtrace_result_t * result, uint64_t key, void * value);
3130DLLEXPORT void trace_destroy_result(libtrace_result_t ** result);
3131
3132// Ways to access Global and TLS storage that we provide the user
3133DLLEXPORT void * trace_get_global(libtrace_t *trace);
3134DLLEXPORT void * trace_set_global(libtrace_t *trace, void * data);
3135DLLEXPORT void * trace_set_tls(libtrace_thread_t *t, void * data);
3136DLLEXPORT void * trace_get_tls(libtrace_thread_t *t);
3137
3138
3139DLLEXPORT void trace_publish_result(libtrace_t *libtrace, uint64_t key, void * value);
3140DLLEXPORT void trace_publish_packet(libtrace_t *libtrace, libtrace_packet_t *packet);
3141typedef struct libtrace_vector libtrace_vector_t;
3142DLLEXPORT int trace_get_results(libtrace_t *libtrace, libtrace_vector_t * results);
3143
3144DLLEXPORT int trace_post_reduce(libtrace_t *libtrace);
3145DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace);
3146DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace, libtrace_message_t * message);
3147DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace, libtrace_message_t * message);
3148DLLEXPORT int trace_send_message_to_reducer(libtrace_t * libtrace, libtrace_message_t * message);
3149DLLEXPORT int trace_send_message_to_perpkts(libtrace_t * libtrace, libtrace_message_t * message);
3150DLLEXPORT int trace_send_message_to_thread(libtrace_t * libtrace, libtrace_thread_t *t, libtrace_message_t * message);
3151DLLEXPORT int trace_finished(libtrace_t * libtrace);
3152DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
3153DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
3154DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
3155DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
3156DLLEXPORT inline uint64_t tv_to_usec(struct timeval *tv);
3157
3158DLLEXPORT int retrive_first_packet(libtrace_t *libtrace, libtrace_packet_t **packet, struct timeval **tv);
3159
3160union libtrace_64byte_things {
3161        void *ptr;
3162        int64_t sint64;
3163        uint64_t uint64;
3164        uint32_t uint32s[2];
3165        int32_t sint32s[2];
3166        uint32_t uint32;
3167        int32_t sint32;
3168        int sint;
3169        unsigned int uint;
3170        char schars[8];
3171        char uchars[8];
3172};
3173
3174typedef struct libtrace_message_t {
3175        int code;
3176        union libtrace_64byte_things additional;
3177        libtrace_thread_t *sender;
3178} libtrace_message_t;
3179
3180typedef enum {
3181        /**
3182         * Sets the hasher function, if NULL(default) no hashing is used a
3183         * cores will get packets on a first in first served basis
3184         */
3185        TRACE_OPTION_SET_HASHER,
3186       
3187        /**
3188         * See diagrams, this sets the maximum size of freelist used to
3189         * maintain packets and there memory buffers.
3190         * NOTE setting this to less than recommend could cause deadlock a
3191         * trace that manages its own packets.
3192         * A unblockable error message will be printed.
3193         */
3194        TRACE_OPTION_SET_PACKET_FREELIST_SIZE,
3195       
3196        /**
3197         * See diagrams, this sets the maximum size of buffers used between
3198         * the single hasher thread and the buffer.
3199         * NOTE setting this to less than recommend could cause deadlock a
3200         * trace that manages its own packets.
3201         * A unblockable warning message will be printed to stderr in this case.
3202         */
3203        TRACE_OPTION_SET_PERPKT_BUFFER_SIZE,
3204       
3205        /**
3206         * Libtrace set perpkt thread count
3207         */
3208        TRACE_OPTION_SET_PERPKT_THREAD_COUNT,
3209       
3210        /**
3211         * Libtrace should expect sequential keys from the output to count
3212         * up starting numbered from 1, 2, 3 ...
3213         * such as is the case with numbered packets.
3214         *
3215         * ALSO consider - TRACE_OPTIONS_ORDERED_RESULTS suitable for live formats
3216         */
3217         TRACE_OPTION_SEQUENTIAL,
3218         
3219         /**
3220          * Libtrace ordered results, results in each queue are ordered by key
3221          * however my not be sequential, a typically case is packet timestamps
3222          * the reducer will receive packets in order - note threasholds
3223          * will be used such that a empty queue wont break things
3224          */
3225         TRACE_OPTION_ORDERED,
3226         
3227         
3228         /**
3229          * When accepting ordered results if a threashold is meet before an
3230          * older result is available from another queue drop that packet
3231          */
3232          TRACE_DROP_OUT_OF_ORDER,
3233         
3234          /**
3235           * If set to true (i.e. 1) the trace starts a dedicated hasher thread
3236           */
3237          TRACE_OPTION_USE_DEDICATED_HASHER,
3238          TRACE_OPTION_USE_SLIDING_WINDOW_BUFFER,
3239          TRACE_OPTION_TRACETIME
3240} trace_parallel_option_t;
3241
3242enum libtrace_messages {
3243        MESSAGE_STARTED,
3244        MESSAGE_DO_PAUSE,
3245        MESSAGE_PAUSING,
3246        MESSAGE_PAUSED,
3247        MESSAGE_DO_STOP,
3248        MESSAGE_STOPPED,
3249        MESSAGE_FIRST_PACKET,
3250        MESSAGE_PERPKT_ENDED,
3251        MESSAGE_PERPKT_RESUMED,
3252        MESSAGE_PERPKT_PAUSED,
3253        MESSAGE_PERPKT_EOF,
3254        MESSAGE_POST_REDUCE,
3255        MESSAGE_POST_RANGE,
3256        MESSAGE_TICK,
3257        MESSAGE_USER
3258};
3259
3260enum hasher_types {
3261        HASHER_BALANCE, /** Balance load across CPUs best as possible this is basically to say don't care about hash, but this might still might be implemented using a hash or round robin etc.. */
3262        HASHER_BIDIRECTIONAL, /** Use a hash which is uni-directional for TCP flows (IP src dest,TCP port src dest), non TCP
3263                                                        Will be sent to the same place, with the exception of UDP which may or may not be sent to separate cores */
3264        HASHER_UNIDIRECTIONAL, /** Use a hash which is uni-directional across TCP flow */
3265        HASHER_CUSTOM, /** Always use the user supplied hasher */
3266        HASHER_HARDWARE, /** Set by the format if the hashing is going to be done in hardware */
3267};
3268
3269DLLEXPORT int trace_parallel_config(libtrace_t *libtrace, trace_parallel_option_t option, void *value);
3270DLLEXPORT libtrace_packet_t* trace_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
3271DLLEXPORT void trace_free_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
3272enum hasher_types;
3273DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type, fn_hasher hasher, void *data);
3274
3275#ifdef __cplusplus
3276} /* extern "C" */
3277#endif /* #ifdef __cplusplus */
3278#endif /* LIBTRACE_H_ */
Note: See TracBrowser for help on using the repository browser.