source: lib/libtrace.h.in @ 7428ab2

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 7428ab2 was 7428ab2, checked in by Shane Alcock <salcock@…>, 5 years ago

Add trace_strip_packet to libtrace API

This function will allow callers to strip MPLS and VLAN headers from
libtrace packets. Some analysis tools (especially those written with
libpcap in the days before these technologies were popular) don't
work so well when these headers are present.

Stripping VLAN headers also makes BPF filtering easier.

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