source: lib/libtrace.h.in @ 2498008

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

Refactor the combining step to allow user defined functions here.

Remove the old trace_get_results, now instead simply provide a reporter function which gets called as soon as results are ready.
The combiner function used determines the order of these results and when they are released etc.
The combiner function can be selected from those built-in or a custom version can be defined results are provided when ready.
Quickly hacked the parallel tests to work with this update, these are still a bit messy.

Also some fixes some compile warnings.

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