source: lib/libtrace.h.in @ 17a3dff

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

Rename from google map/reduce framework names to something more meaningful.
Rename mapper to perpkt since this is what it actually is in libtrace.

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