source: lib/libtrace.h.in @ cc6fcee

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