source: lib/libtrace.h.in @ 5b4d121

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

Adds a configuration parser to make it easy to change the parallel configuration.
Adds more configuration options (Tidies some verbose debugging output).
Implements tick packets for the hasher thread case.
Some other minor bug fixes

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