source: lib/libtrace.h.in @ f0fb38f

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since f0fb38f was f0fb38f, checked in by Shane Alcock <salcock@…>, 13 years ago
  • Added prepare_packet functions to all formats, primarily to support translating RT packets into the appropriate format. These functions are all used internally as well, as most formats still need to "prepare" packets that have been read by setting pointers, updating loss counters etc.
  • Also added a trace_prepare_packet function, but this is not made available externally at this stage
  • Added init_format_data functions to some formats to initialise format data structures in cases where the init_trace function does more than just that
  • Refactored rt packet reading code to use the new trace_prepare_packet functionality - also did a lot of tidying of the code
  • Added missing RT type for BPF format
  • Property mode set to 100644
File size: 66.8 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008 The University of Waikato, Hamilton, New Zealand.
5 * Authors: Daniel Lawson
6 *          Perry Lorier
7 *         
8 * All rights reserved.
9 *
10 * This code has been developed by the University of Waikato WAND
11 * research group. For further information please see http://www.wand.net.nz/
12 *
13 * libtrace is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * libtrace is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with libtrace; if not, write to the Free Software
25 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 *
27 * $Id: libtrace.h 773 2006-05-01 12:58:09Z perry $
28 *
29 */
30
31#ifndef LIBTRACE_H
32#define LIBTRACE_H
33
34/** @file
35 *
36 * @brief Trace file processing library header
37 *
38 * @author Daniel Lawson
39 * @author Perry Lorier
40 *
41 * @version $Id: libtrace.h 773 2006-05-01 12:58:09Z perry $
42 *
43 * This library provides a per packet interface into a trace file, or a live
44 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
45 * pcap etc.
46 *
47 * @par Usage
48 * See the example/ directory in the source distribution for some simple examples
49 * @par Linking
50 * To use this library you need to link against libtrace by passing -ltrace
51 * to your linker. You may also need to link against a version of libpcap
52 * and of zlib which are compiled for largefile support (if you wish to access
53 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
54 * Woody, at least, does not support large file offsets.
55 *
56 */
57
58#include <sys/types.h>
59#ifndef WIN32
60#include <sys/time.h>
61#endif
62
63#ifdef _MSC_VER
64    /* define the following from MSVC's internal types */
65    typedef             __int8  int8_t;
66    typedef             __int16 int16_t;
67    typedef             __int32 int32_t;
68    typedef             __int64 int64_t;
69    typedef unsigned    __int8  uint8_t;
70    typedef unsigned    __int16 uint16_t;
71    typedef unsigned    __int32 uint32_t;
72    typedef unsigned    __int64 uint64_t;
73    #ifdef BUILDING_DLL
74        #define DLLEXPORT __declspec(dllexport)
75    #else
76        #define DLLEXPORT __declspec(dllimport)
77    #endif
78    #define DLLLOCAL
79    /* Windows pads bitfields out to to the size of their parent type
80     * however gcc warns that this doesn't meet with the iso C specification
81     * so produces warnings for this behaviour.  sigh.
82     */
83    #define LT_BITFIELD8        uint8_t
84    #define LT_BITFIELD16       uint16_t
85    #define LT_BITFIELD32       uint32_t
86    #define LT_BITFIELD64       uint64_t
87#else
88#   include <stdint.h>
89    #ifdef HAVE_GCCVISIBILITYPATCH
90        #define DLLEXPORT __attribute__ (visibility("default"))
91        #define DLLLOCAL __attribute__ (visibility("hidden"))
92    #else
93        #define DLLEXPORT
94        #define DLLLOCAL
95    #endif
96    /* GCC warns if the bitfield type is not "unsigned int", however windows
97     * generates incorrect code for this (see above), so we define these
98     * macros.  How Hidious.  So much for C's portability.
99     */
100    #define LT_BITFIELD8        unsigned int
101    #define LT_BITFIELD16       unsigned int
102    #define LT_BITFIELD32       unsigned int
103    #define LT_BITFIELD64       unsigned int
104#endif
105
106#ifdef WIN32
107#   include <winsock2.h>
108#   include <ws2tcpip.h>
109    typedef short sa_family_t;
110    /* Make up for a lack of stdbool.h */
111#    define bool signed char
112#    define false 0
113#    define true 1
114#    if !defined(ssize_t)
115     /* XXX: Not 64-bit safe! */
116#    define ssize_t int
117#    endif   
118#else
119#    include <netinet/in.h>
120
121#ifndef __cplusplus
122#    include <stdbool.h>
123#endif
124
125#    include <sys/types.h>
126#    include <sys/socket.h>
127#endif
128
129/** API version as 2 byte hex digits, eg 0xXXYYZZ */
130#define LIBTRACE_API_VERSION \
131            ((@LIBTRACE_MAJOR@<<16)|(@LIBTRACE_MID@<<8)|(@LIBTRACE_MINOR@))
132
133#define LIBTRACE_SVN_REVISION 0
134#define DAG_DRIVER_V "@DAG_VERSION_NUM@"
135   
136#ifdef __cplusplus
137extern "C" {
138#endif
139
140/* Function does not depend on anything but its
141 * parameters, used to hint gcc's optimisations
142 */
143#if __GNUC__ >= 3
144#  define DEPRECATED __attribute__((deprecated))
145#  define SIMPLE_FUNCTION __attribute__((pure))
146#  define UNUSED __attribute__((unused))
147#  define PACKED __attribute__((packed))
148#  define PRINTF(formatpos,argpos) __attribute__((format(printf,formatpos,argpos)))
149#else
150#  define DEPRECATED
151#  define SIMPLE_FUNCTION
152#  define UNUSED
153#  define PACKED
154#  define PRINTF(formatpos,argpos)
155#endif
156       
157/** Opaque structure holding information about an output trace */
158typedef struct libtrace_out_t libtrace_out_t;
159       
160/** Opaque structure holding information about a trace */
161typedef struct libtrace_t libtrace_t;
162       
163/** Opaque structure holding information about a bpf filter */
164typedef struct libtrace_filter_t libtrace_filter_t;
165
166/** If a packet has memory allocated
167 * If the packet has allocated it's own memory it's buffer_control should
168 * be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be
169 * free()'d.  If it's doing zerocopy out of memory owned by something else
170 * it should be TRACE_CTRL_EXTERNAL.
171 * @note the letters p and e are magic numbers used to detect if the packet
172 * wasn't created properly
173 */
174typedef enum {
175        TRACE_CTRL_PACKET='p',
176        TRACE_CTRL_EXTERNAL='e'
177} buf_control_t;
178/** The size of a packet's buffer when managed by libtrace */
179#define LIBTRACE_PACKET_BUFSIZE 65536
180
181/** libtrace error information */
182typedef struct trace_err_t{
183        int err_num;            /**< error code */
184        char problem[255];      /**< the format, uri etc that caused the error for reporting purposes */
185} libtrace_err_t;
186
187/** Enumeration of error codes */
188enum {
189        /** No Error has occured.... yet. */
190        TRACE_ERR_NOERROR       = 0,
191        /** The URI passed to trace_create() is unsupported, or badly formed */
192        TRACE_ERR_BAD_FORMAT    = -1,
193        /** The trace failed to initialise */
194        TRACE_ERR_INIT_FAILED   = -2,
195        /** Unknown config option */
196        TRACE_ERR_UNKNOWN_OPTION= -3,
197        /** This output uri cannot write packets of this type */
198        TRACE_ERR_NO_CONVERSION = -4,
199        /** This packet is corrupt, or unusable for the action required */
200        TRACE_ERR_BAD_PACKET    = -5,
201        /** Option known, but unsupported by this format */
202        TRACE_ERR_OPTION_UNAVAIL= -6,
203        /** This feature is unsupported */
204        TRACE_ERR_UNSUPPORTED   = -7,
205        /** Illegal use of the API */
206        TRACE_ERR_BAD_STATE     = -8
207};
208
209/** Enumeration of DLT supported by libtrace
210 */
211typedef enum {
212        TRACE_DLT_NULL = 0,
213        TRACE_DLT_EN10MB = 1,
214        TRACE_DLT_PPP = 9,
215        TRACE_DLT_ATM_RFC1483 = 11,
216        /* Sigh. This is handled in files with LINKTYPE's */
217#ifdef __OpenBSD__
218        TRACE_DLT_RAW = 14,     
219#else
220        TRACE_DLT_RAW = 12,
221#endif
222        TRACE_DLT_LINKTYPE_RAW = 101,
223        TRACE_DLT_C_HDLC = 104,
224        TRACE_DLT_IEEE802_11 = 105,
225        TRACE_DLT_LINUX_SLL = 113,
226        TRACE_DLT_PFLOG = 117,
227        TRACE_DLT_IEEE802_11_RADIO = 127 /**< Radiotap */
228} libtrace_dlt_t ;
229
230/** Enumeration of link layer types supported by libtrace */
231typedef enum {
232    /* TRACE_TYPE_LEGACY = 0            Obsolete */
233       TRACE_TYPE_HDLC_POS = 1,
234       TRACE_TYPE_ETH = 2,              /**< 802.3 style Ethernet */
235       TRACE_TYPE_ATM = 3,              /**< ATM frame */
236       TRACE_TYPE_80211 = 4,            /**< 802.11 frames */
237       TRACE_TYPE_NONE = 5,             /**< Raw IP frames */
238       TRACE_TYPE_LINUX_SLL = 6,        /**< Linux "null" framing */
239       TRACE_TYPE_PFLOG = 7,            /**< FreeBSD's PFlug */
240    /* TRACE_TYPE_LEGACY_DEFAULT        Obsolete */
241       TRACE_TYPE_POS = 9,
242    /* TRACE_TYPE_LEGACY_ATM            Obsolete */
243    /* TRACE_TYPE_LEGACY_ETH            Obsolete */
244       TRACE_TYPE_80211_PRISM = 12,
245       TRACE_TYPE_AAL5 = 13,
246       TRACE_TYPE_DUCK = 14,         /**< Pseudo link layer for DUCK packets */
247       TRACE_TYPE_80211_RADIO = 15,  /**< Radiotap + 802.11 */
248       TRACE_TYPE_LLCSNAP = 16,      /**< Raw LLC/SNAP */
249       TRACE_TYPE_PPP = 17,          /**< PPP frames */
250       TRACE_TYPE_METADATA = 18         /**< WDCAP-style meta-data */
251       
252} libtrace_linktype_t;
253
254/** RT protocol base format identifiers
255 * This is used to say what kind of packet is being sent over the rt protocol
256 */
257enum base_format_t {
258        TRACE_FORMAT_ERF          =1,
259        TRACE_FORMAT_PCAP         =2,
260        TRACE_FORMAT_PCAPFILE     =3,
261        TRACE_FORMAT_WAG          =4,
262        TRACE_FORMAT_RT           =5,
263        TRACE_FORMAT_LEGACY_ATM   =6,
264        TRACE_FORMAT_LEGACY_POS   =7,
265        TRACE_FORMAT_LEGACY_ETH   =8,
266        TRACE_FORMAT_LINUX_NATIVE =9,
267        TRACE_FORMAT_DUCK         =10,
268        TRACE_FORMAT_BPF          =11,
269        TRACE_FORMAT_TSH          =12,
270        TRACE_FORMAT_ATMHDR       =13,
271        TRACE_FORMAT_LEGACY_NZIX  =14
272};
273
274/* RT protocol packet types */
275typedef enum {
276        TRACE_RT_HELLO          =1, /**< Connection accepted */
277        TRACE_RT_START          =2, /**< Request for data transmission to begin
278                                    */
279        TRACE_RT_ACK            =3, /**< Data acknowledgement */
280        TRACE_RT_STATUS         =4, /**< Fifo status packet */
281        TRACE_RT_DUCK           =5, /**< Dag duck info packet */
282        TRACE_RT_END_DATA       =6, /**< Server is exiting message */
283        TRACE_RT_CLOSE          =7, /**< Client is exiting message */
284        TRACE_RT_DENY_CONN      =8, /**< Connection has been denied */
285        TRACE_RT_PAUSE          =9, /**< Request server to suspend sending data
286                                     */
287        TRACE_RT_PAUSE_ACK      =10,/**< Server is paused message */
288        TRACE_RT_OPTION         =11,/**< Option request */
289        TRACE_RT_KEYCHANGE      =12,/**< Anonymisation key has changed */
290        TRACE_RT_DUCK_2_4       =13,/**< Dag 2.4 Duck */
291        TRACE_RT_DUCK_2_5       =14,/**< Dag 2.5 Duck */
292        TRACE_RT_LOSTCONN       =15,/**< Lost connection to server */
293        TRACE_RT_SERVERSTART    =16,/**< Reliable server has been restarted */
294        TRACE_RT_CLIENTDROP     =17,/**< Reliable client was lost */
295        TRACE_RT_METADATA       =18,/**< Packet contains server meta-data */
296
297        TRACE_RT_DATA_SIMPLE    = 1000, /**< Trace types that know their link
298                                          * type
299                                          */
300        TRACE_RT_DATA_ERF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_ERF,
301        TRACE_RT_DATA_WAG       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_WAG,
302        TRACE_RT_DATA_LEGACY_ATM=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ATM,
303        TRACE_RT_DATA_LEGACY_POS=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_POS,
304        TRACE_RT_DATA_LEGACY_ETH=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ETH,
305        TRACE_RT_DATA_LINUX_NATIVE=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_NATIVE,
306        TRACE_RT_DATA_BPF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_BPF,
307        TRACE_RT_DATA_TSH       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_TSH,
308
309        TRACE_RT_DATA_ATMHDR = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_ATMHDR,
310        TRACE_RT_DATA_LEGACY_NZIX=TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_LEGACY_NZIX,
311        TRACE_RT_DATA_DLT               = 2000, /**< Pcap doesn't store the
312                                                  * linktype per packet, and
313                                                  * thus we have to store it
314                                                  * in here.  sigh.
315                                                  */
316        TRACE_RT_DLT_NULL               =TRACE_RT_DATA_DLT+TRACE_DLT_NULL,
317        TRACE_RT_DLT_EN10MB             =TRACE_RT_DATA_DLT+TRACE_DLT_EN10MB,
318        TRACE_RT_DLT_IEEE802_11         =TRACE_RT_DATA_DLT+TRACE_DLT_IEEE802_11,
319        TRACE_RT_DLT_LINUX_SLL          =TRACE_RT_DATA_DLT+TRACE_DLT_LINUX_SLL,
320        TRACE_RT_DLT_PFLOG              =TRACE_RT_DATA_DLT+TRACE_DLT_PFLOG,
321        TRACE_RT_DLT_ATM_RFC1483        =TRACE_RT_DATA_DLT+TRACE_DLT_ATM_RFC1483,
322        TRACE_RT_DATA_DLT_END           = 2999,
323        TRACE_RT_LAST                   = (2<<31)
324} libtrace_rt_types_t;
325
326/** The libtrace packet structure, applications shouldn't be
327 * meddling around in here
328 */
329typedef struct libtrace_packet_t {
330        struct libtrace_t *trace;       /**< pointer to the trace */
331        void *header;                   /**< pointer to the framing header */
332        void *payload;                  /**< pointer to the link layer */
333        void *buffer;                   /**< allocated buffer */
334        libtrace_rt_types_t  type;      /**< rt protocol type for the packet */
335        buf_control_t buf_control;      /**< who owns the memory */
336        int capture_length;             /**< Cached capture length */
337        void *l3_header;                /**< Cached l3 header */
338        uint16_t l3_ethertype;          /**< Cached l3 ethertype */
339} libtrace_packet_t;
340
341
342/** Trace directions
343 * Note that these are the directions used by convention, more directions
344 * are possible, not just these 3, and that they may not conform to this
345 * convention.
346 */
347typedef enum {
348        TRACE_DIR_OUTGOING = 0,         /**< Packets originating "inside" */
349        TRACE_DIR_INCOMING = 1,         /**< Packets originating "outside" */
350        TRACE_DIR_OTHER    = 2          /**< Packets with an unknown direction, or one that's unknown */
351} libtrace_direction_t;
352
353/** Enumeration of Radiotap fields */
354typedef enum {
355    TRACE_RADIOTAP_TSFT = 0, /**< Timer synchronisation function, in microseconds (uint64) */
356    TRACE_RADIOTAP_FLAGS = 1, /**< Wireless flags (uint8) */
357    TRACE_RADIOTAP_RATE = 2, /**< Bitrate in units of 500kbps (uint8) */
358    TRACE_RADIOTAP_CHANNEL = 3, /**< Frequency in MHz (uint16) and channel flags (uint16) */
359    TRACE_RADIOTAP_FHSS = 4, /**< FHSS hop set (uint8) and hopping pattern (uint8) */
360    TRACE_RADIOTAP_DBM_ANTSIGNAL = 5, /**< Signal power in dBm (int8) */
361    TRACE_RADIOTAP_DBM_ANTNOISE = 6, /**< Noise power in dBm (int8) */
362    TRACE_RADIOTAP_LOCK_QUALITY = 7, /**< Barker Code lock quality (uint16) */
363    TRACE_RADIOTAP_TX_ATTENUATION = 8, /**< TX attenuation as unitless distance from max power (uint16) */
364    TRACE_RADIOTAP_DB_TX_ATTENUATION = 9, /**< TX attenutation as dB from max power (uint16) */
365    TRACE_RADIOTAP_DBM_TX_POWER = 10, /**< TX Power in dBm (int8) */
366    TRACE_RADIOTAP_ANTENNA = 11, /**< Antenna frame was rx'd or tx'd on (uint8) */
367    TRACE_RADIOTAP_DB_ANTSIGNAL = 12, /**< Signal power in dB from a fixed reference (uint8) */
368    TRACE_RADIOTAP_DB_ANTNOISE = 13, /**< Noise power in dB from a fixed reference (uint8) */
369    TRACE_RADIOTAP_RX_FLAGS = 14, /** Properties of received frame (uint16) */
370    TRACE_RADIOTAP_TX_FLAGS = 15, /** Properties of transmitted frame (uint16) */
371    TRACE_RADIOTAP_RTS_RETRIES = 16, /** Number of rts retries frame used (uint8) */
372    TRACE_RADIOTAP_DATA_RETRIES = 17, /** Number of unicast retries a transmitted frame used (uint8) */
373    TRACE_RADIOTAP_EXT = 31
374} libtrace_radiotap_field_t;
375
376
377/** @name Protocol structures
378 * These convenience structures are here as they are portable ways of dealing
379 * with various protocols.
380 * @{
381 */
382
383#ifdef WIN32
384#pragma pack(push)
385#pragma pack(1)
386#endif
387
388/** Generic IP header structure */
389typedef struct libtrace_ip
390{
391#if BYTE_ORDER == LITTLE_ENDIAN
392    LT_BITFIELD8 ip_hl:4;               /**< Header Length */
393    LT_BITFIELD8 ip_v:4;                /**< Version */
394#elif BYTE_ORDER == BIG_ENDIAN
395    LT_BITFIELD8 ip_v:4;                /**< Version */
396    LT_BITFIELD8 ip_hl:4;               /**< Header Length */
397#else
398#   error "Adjust your <bits/endian.h> defines"
399#endif
400    uint8_t  ip_tos;                    /**< Type of Service */
401    uint16_t ip_len;                    /**< Total Length */
402    int16_t  ip_id;                     /**< Identification */
403    uint16_t ip_off;                    /**< IP Fragment offset (and flags) */
404    uint8_t  ip_ttl;                    /**< Time to Live */
405    uint8_t  ip_p;                      /**< Protocol */
406    uint16_t ip_sum;                    /**< Checksum */
407    struct in_addr ip_src;              /**< Source Address */
408    struct in_addr ip_dst;              /**< Destination Address */
409} PACKED libtrace_ip_t;
410
411/** IPv6 header extension structure */
412typedef struct libtrace_ip6_ext
413{
414        uint8_t nxt;
415        uint8_t len;
416} PACKED libtrace_ip6_ext_t;
417
418/** Generic IPv6 header structure */
419typedef struct libtrace_ip6
420{
421    uint32_t flow;
422    uint16_t plen;                      /**< Payload length */
423    uint8_t nxt;                        /**< Next header */
424    uint8_t hlim;                       /**< Hop limit */
425    struct in6_addr ip_src;             /**< source address */
426    struct in6_addr ip_dst;             /**< dest address */
427} PACKED libtrace_ip6_t;
428
429/** Generic TCP header structure */
430typedef struct libtrace_tcp
431  {
432    uint16_t source;            /**< Source Port */
433    uint16_t dest;              /**< Destination port */
434    uint32_t seq;               /**< Sequence number */
435    uint32_t ack_seq;           /**< Acknowledgement Number */
436#  if BYTE_ORDER == LITTLE_ENDIAN
437    LT_BITFIELD8 res1:4;        /**< Reserved bits */
438    LT_BITFIELD8 doff:4;        /**< Data Offset */     
439    LT_BITFIELD8 fin:1;         /**< FIN */
440    LT_BITFIELD8 syn:1;         /**< SYN flag */
441    LT_BITFIELD8 rst:1;         /**< RST flag */
442    LT_BITFIELD8 psh:1;         /**< PuSH flag */
443    LT_BITFIELD8 ack:1;         /**< ACK flag */
444    LT_BITFIELD8 urg:1;         /**< URG flag */
445    LT_BITFIELD8 res2:2;        /**< Reserved */
446#  elif BYTE_ORDER == BIG_ENDIAN
447    LT_BITFIELD8 doff:4;        /**< Data offset */
448    LT_BITFIELD8 res1:4;        /**< Reserved bits */
449    LT_BITFIELD8 res2:2;        /**< Reserved */
450    LT_BITFIELD8 urg:1;         /**< URG flag */
451    LT_BITFIELD8 ack:1;         /**< ACK flag */
452    LT_BITFIELD8 psh:1;         /**< PuSH flag */
453    LT_BITFIELD8 rst:1;         /**< RST flag */
454    LT_BITFIELD8 syn:1;         /**< SYN flag */
455    LT_BITFIELD8 fin:1;         /**< FIN flag */
456#  else
457#   error "Adjust your <bits/endian.h> defines"
458#  endif
459    uint16_t window;            /**< Window Size */
460    uint16_t check;             /**< Checksum */
461    uint16_t urg_ptr;           /**< Urgent Pointer */
462} PACKED libtrace_tcp_t;
463
464/** Generic UDP header structure */
465typedef struct libtrace_udp {
466  uint16_t      source;         /**< Source port */
467  uint16_t      dest;           /**< Destination port */
468  uint16_t      len;            /**< Length */
469  uint16_t      check;          /**< Checksum */
470} PACKED libtrace_udp_t;
471
472/** Generic ICMP header structure */
473typedef struct libtrace_icmp
474{
475  uint8_t type;         /**< Message Type */
476  uint8_t code;         /**< Type Sub-code */
477  uint16_t checksum;            /**< Checksum */
478  union
479  {
480    struct
481    {
482      uint16_t  id;
483      uint16_t  sequence;
484    } echo;                     /**< Echo Datagram */
485    uint32_t    gateway;        /**< Gateway Address */
486    struct
487    {
488      uint16_t  unused;
489      uint16_t  mtu;
490    } frag;                     /**< Path MTU Discovery */
491  } un;                         /**< Union for Payloads of Various ICMP Codes */
492} PACKED libtrace_icmp_t;
493
494/** Generic LLC/SNAP header structure */
495typedef struct libtrace_llcsnap
496{
497/* LLC */
498  uint8_t dsap;                 /**< Destination Service Access Point */
499  uint8_t ssap;                 /**< Source Service Access Point */
500  uint8_t control;
501/* SNAP */
502  LT_BITFIELD32 oui:24;         /**< Organisationally Unique Identifier (scope)*/
503  uint16_t type;                /**< Protocol within OUI */
504} PACKED libtrace_llcsnap_t;
505
506/** 802.3 frame */
507typedef struct libtrace_ether
508{
509  uint8_t ether_dhost[6];       /**< Destination Ether Addr */
510  uint8_t ether_shost[6];       /**< Source Ether Addr */
511  uint16_t ether_type;          /**< Packet Type ID Field (next-header) */
512} PACKED libtrace_ether_t;
513
514/** 802.1Q frame */
515typedef struct libtrace_8021q
516{
517  LT_BITFIELD16 vlan_pri:3;      /**< VLAN User Priority */
518  LT_BITFIELD16 vlan_cfi:1;      /**< VLAN Format Indicator,
519                                   * 0 for ethernet, 1 for token ring */
520  LT_BITFIELD16 vlan_id:12;      /**< VLAN Id */
521  uint16_t vlan_ether_type;      /**< VLAN Sub-packet Type ID Field
522                                   * (next-header)*/
523} PACKED libtrace_8021q_t;
524
525/** ATM User Network Interface (UNI) Cell. */
526typedef struct libtrace_atm_cell
527{
528  LT_BITFIELD32 gfc:4;          /**< Generic Flow Control */
529  LT_BITFIELD32 vpi:8;          /**< Virtual Path Identifier */
530  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
531  LT_BITFIELD32 pt:3;           /**< Payload Type */
532  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
533  LT_BITFIELD32 hec:8;          /**< Header Error Control */
534} PACKED libtrace_atm_cell_t;
535
536/** ATM Network Node/Network Interface (NNI) Cell. */
537typedef struct libtrace_atm_nni_cell
538{
539  LT_BITFIELD32 vpi:12;         /**< Virtual Path Identifier */
540  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
541  LT_BITFIELD32 pt:3;           /**< Payload Type */
542  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
543  LT_BITFIELD32 hec:8;          /**< Header Error Control */
544} PACKED libtrace_atm_nni_cell_t;
545
546/** Captured UNI cell.
547 *
548 * Endance don't capture the HEC, presumably to keep alignment.  This
549 * version of the \ref libtrace_atm_cell  is used when dealing with dag
550 * captures of uni cells.
551 *
552 */
553typedef struct libtrace_atm_capture_cell
554{
555  LT_BITFIELD32 gfc:4;          /**< Generic Flow Control */
556  LT_BITFIELD32 vpi:8;          /**< Virtual Path Identifier */
557  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
558  LT_BITFIELD32 pt:3;           /**< Payload Type */
559  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
560} PACKED libtrace_atm_capture_cell_t;
561
562/** Captured NNI cell.
563 *
564 * Endance don't capture the HEC, presumably to keep alignment.  This
565 * version of the \ref libtrace_atm_nni_cell  is used when dealing with dag
566 * captures of nni cells.
567 *
568 */
569typedef struct libtrace_atm_nni_capture_cell
570{
571  LT_BITFIELD32 vpi:12;         /**< Virtual Path Identifier */
572  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
573  LT_BITFIELD32 pt:3;           /**< Payload Type */
574  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
575  LT_BITFIELD32 hec:8;          /**< Header Error Control */
576} PACKED libtrace_atm_nni_capture_cell_t;
577
578/** PPP header */
579typedef struct libtrace_pps
580{
581 uint8_t addres;                /**< PPP Address (0xFF - All stations) */
582 uint8_t header;                /**< PPP Control (0x03 - Unnumbered info) */
583 uint16_t protocol;             /**< PPP Protocol (htons(0x0021) - IPv4 */
584} PACKED libtrace_ppp_t;
585
586/** 802.11 header */
587typedef struct libtrace_80211_t {
588#if BYTE_ORDER == LITTLE_ENDIAN
589        LT_BITFIELD32      protocol:2;
590        LT_BITFIELD32      type:2;
591        LT_BITFIELD32      subtype:4;
592#else
593        LT_BITFIELD32      subtype:4;
594        LT_BITFIELD32      type:2;
595        LT_BITFIELD32      protocol:2;
596#endif
597
598#if BYTE_ORDER == LITTLE_ENDIAN
599        LT_BITFIELD32      to_ds:1;     /**< Packet to Distribution Service */
600        LT_BITFIELD32      from_ds:1;   /**< Packet from Distribution Service */
601        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
602        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
603        LT_BITFIELD32      power:1;
604        LT_BITFIELD32      more_data:1;
605        LT_BITFIELD32      wep:1;
606        LT_BITFIELD32      order:1;
607#else
608        LT_BITFIELD32      order:1;
609        LT_BITFIELD32      wep:1;
610        LT_BITFIELD32      more_data:1;
611        LT_BITFIELD32      power:1;
612        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
613        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
614        LT_BITFIELD32      from_ds:1;   /**< Packet from Distribution Service */
615        LT_BITFIELD32      to_ds:1;     /**< Packet to Distribution Service */
616#endif
617        uint16_t     duration;
618        uint8_t      mac1[6];
619        uint8_t      mac2[6];
620        uint8_t      mac3[6];
621        uint16_t     SeqCtl;
622        uint8_t      mac4[6];
623} PACKED libtrace_80211_t;
624
625/** The Radiotap header pre-amble
626 *
627 * All Radiotap headers start with this pre-amble, followed by the fields
628 * specified in the it_present bitmask. If bit 31 of it_present is set, then
629 * another bitmask follows.
630 * @note All of the radiotap data fields are in little-endian byte-order.
631 */
632typedef struct libtrace_radiotap_t {
633    uint8_t     it_version; /**< Radiotap version */
634    uint8_t     it_pad; /**< Padding for natural alignment */
635    uint16_t    it_len; /**< Length in bytes of the entire Radiotap header */
636    uint32_t    it_present; /**< Which Radiotap fields are present */
637} PACKED libtrace_radiotap_t;
638
639
640#ifdef WIN32
641#pragma pack(pop)
642#endif
643
644
645/*@}*/
646
647/** Prints help information for libtrace
648 *
649 * Function prints out some basic help information regarding libtrace,
650 * and then prints out the help() function registered with each input module
651 */
652DLLEXPORT void trace_help(void);
653
654/** @name Trace management
655 * These members deal with creating, configuring, starting, pausing and
656 * cleaning up a trace object
657 *@{
658 */
659
660/** Create a trace file from a URI
661 *
662 * @param uri containing a valid libtrace URI
663 * @return an opaque pointer to a libtrace_t
664 *
665 * Valid URI's are:
666 *  - erf:/path/to/erf/file
667 *  - erf:-  (stdin)
668 *  - dag:/dev/dagcard                 
669 *  - pcapint:pcapinterface                (eg: pcap:eth0)
670 *  - pcap:/path/to/pcap/file
671 *  - pcap:-
672 *  - rt:hostname
673 *  - rt:hostname:port
674 *  - rtclient:hostname (deprecated)
675 *  - rtclient:hostname:port (deprecated)
676 *
677 *  If an error occured when attempting to open the trace file, an error
678 *  trace is returned and trace_get_error should be called to find out
679 *  if an error occured, and what that error was.  The trace is created in the
680 *  configuration state, you must call trace_start to start the capture.
681 */
682DLLEXPORT libtrace_t *trace_create(const char *uri);
683
684/** Creates a "dummy" trace file that has only the format type set.
685 *
686 * @return an opaque pointer to a (sparsely initialised) libtrace_t
687 *
688 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions
689 * with the dummy trace. Its intended purpose is to act as a packet->trace for
690 * libtrace_packet_t's that are not associated with a libtrace_t structure.
691 */
692DLLEXPORT libtrace_t *trace_create_dead(const char *uri);
693
694/** Creates a trace output file from a URI.
695 *
696 * @param uri   the uri string describing the output format and destination
697 * @return an opaque pointer to a libtrace_output_t
698 *
699 * Valid URI's are:
700 *  - erf:/path/to/erf/file
701 *  - pcap:/path/to/pcap/file
702 *  - wtf:/path/to/wtf/file
703 *
704 *  If an error occured when attempting to open the output trace, NULL is returned
705 *  and trace_errno is set. Use trace_perror_output() to get more information
706 */
707DLLEXPORT libtrace_out_t *trace_create_output(const char *uri);
708
709/** Start the capture
710 * @param libtrace      The trace to start
711 * @return 0 on success, -1 on failure
712 *
713 * This does the actual work with starting the trace capture, and applying
714 * all the config options.  This may fail.
715 */
716DLLEXPORT int trace_start(libtrace_t *libtrace);
717
718/** Pause the capture
719 * @param libtrace      The trace to pause
720 * @return 0 on success, -1 on failure
721 *
722 * This stops a capture in progress and returns you to the configuration
723 * state.  Any packets that arrive after trace_pause() has been called
724 * will be discarded.  To resume capture, call trace_start().
725 */
726DLLEXPORT int trace_pause(libtrace_t *libtrace);
727
728/** Start an output trace
729 * @param libtrace      The trace to start
730 * @return 0 on success, -1 on failure
731 *
732 * This does the actual work with starting a trace for write.  This generally
733 * creates the file.
734 */
735DLLEXPORT int trace_start_output(libtrace_out_t *libtrace);
736
737/** Valid trace capture options */
738typedef enum {
739        TRACE_OPTION_SNAPLEN,   /**< Number of bytes captured */
740        TRACE_OPTION_PROMISC,   /**< Capture packets to other hosts */
741        TRACE_OPTION_FILTER,    /**< Apply this filter to all packets */
742        TRACE_OPTION_META_FREQ, /**< Frequency of meta-data information, e.g. DUCK packets */
743        /** trace_event ignores gaps between packets when reading traces off disk */
744        TRACE_OPTION_EVENT_REALTIME
745} trace_option_t;
746
747/** Sets an input config option
748 * @param libtrace      the trace object to apply the option to
749 * @param option        the option to set
750 * @param value         the value to set the option to
751 * @return -1 if option configuration failed, 0 otherwise
752 * This should be called after trace_create, and before trace_start
753 */
754DLLEXPORT int trace_config(libtrace_t *libtrace,
755                trace_option_t option,
756                void *value);
757
758typedef enum {
759        TRACE_OPTION_OUTPUT_FILEFLAGS, /**< File flags to open the trace file
760                                        * with.  eg O_APPEND
761                                        */
762        TRACE_OPTION_OUTPUT_COMPRESS   /**< Compression level, eg 6. */
763} trace_option_output_t;
764
765/** Sets an output config option
766 *
767 * @param libtrace      the output trace object to apply the option to
768 * @param option        the option to set
769 * @param value         the value to set the option to
770 * @return -1 if option configuration failed, 0 otherwise
771 * This should be called after trace_create_output, and before
772 * trace_start_output
773 */
774DLLEXPORT int trace_config_output(libtrace_out_t *libtrace,
775                trace_option_output_t option,
776                void *value
777                );
778
779/** Close a trace file, freeing up any resources it may have been using
780 *
781 */
782DLLEXPORT void trace_destroy(libtrace_t *trace);
783
784/** Close a trace file, freeing up any resources it may have been using
785 * @param trace         trace file to be destroyed
786 */
787DLLEXPORT void trace_destroy_dead(libtrace_t *trace);
788
789/** Close a trace output file, freeing up any resources it may have been using
790 * @param trace         the output trace file to be destroyed
791 */
792DLLEXPORT void trace_destroy_output(libtrace_out_t *trace);
793
794/** Check (and clear) the current error state of an input trace
795 * @param trace         the trace file to check the error state on
796 * @return Error report
797 * This reads and returns the current error state and sets the current error
798 * to "no error".
799 */
800DLLEXPORT libtrace_err_t trace_get_err(libtrace_t *trace);
801
802/** Return if there is an error
803 * @param trace         the trace file to check the error state on
804 * This does not clear the error status, and only returns true or false.
805 */
806DLLEXPORT bool trace_is_err(libtrace_t *trace);
807
808/** Output an error message to stderr and clear the error status.
809 * @param trace         the trace with the error to output
810 * @param msg           the message to prefix to the error
811 * This function does clear the error status.
812 */
813DLLEXPORT void trace_perror(libtrace_t *trace, const char *msg,...) PRINTF(2,3);
814
815/** Check (and clear) the current error state of an output trace
816 * @param trace         the output trace file to check the error state on
817 * @return Error report
818 * This reads and returns the current error state and sets the current error
819 * to "no error".
820 */
821DLLEXPORT libtrace_err_t trace_get_err_output(libtrace_out_t *trace);
822
823/** Return if there is an error
824 * @param trace         the trace file to check the error state on
825 * This does not clear the error status, and only returns true or false.
826 */
827DLLEXPORT bool trace_is_err_output(libtrace_out_t *trace);
828
829/** Output an error message to stderr and clear the error status.
830 * @param trace         the trace with the error to output
831 * @param msg           the message to prefix to the error
832 * This function does clear the error status.
833 */
834DLLEXPORT void trace_perror_output(libtrace_out_t *trace, const char *msg,...)
835        PRINTF(2,3);
836
837/** Return the number of captured packets
838 * Includes the number of packets counted as early as possible, before
839 * filtering, and includes dropped packets.
840 *
841 * @param trace         Trace to examine
842 * @returns number of packets seen at the capture point before filtering.
843 *
844 * If this is not known, this will return UINT64_MAX
845 */
846uint64_t trace_get_received_packets(libtrace_t *trace);
847
848/** Return the number of filtered packets
849 * Returns the number of packets that were captured, but discarded for not
850 * matching a trace filter.  This includes packets
851 *
852 * @param trace         Trace file to examine
853 * @returns the number of packets that were successfully captured, but filtered
854 *
855 * If this is not known, this will return UINT64_MAX
856 */
857uint64_t trace_get_filtered_packets(libtrace_t *trace);
858
859/** Return the number of packets that have been dropped for lack of packets
860 * @param trace         Trace file to examine
861 * @returns The number of packets captured, but dropped due to buffer overruns
862 */
863uint64_t trace_get_dropped_packets(libtrace_t *trace);
864
865/** Return the number of packets that have been returned to library user
866 * @param trace         Trace file to examine
867 * @returns The number of packets returned to the user of the library.
868 */
869uint64_t trace_get_accepted_packets(libtrace_t *trace);
870
871
872/*@}*/
873
874/** @name Reading/Writing packets
875 * These members deal with creating, reading and writing packets
876 *
877 * @{
878 */
879
880/** Create a new packet object
881 *
882 * @return a pointer to an initialised libtrace_packet_t object
883 */
884DLLEXPORT libtrace_packet_t *trace_create_packet(void);
885
886/** Copy a packet
887 * @param packet        the source packet to copy
888 * @return a new packet which has the same content as the source packet
889 * @note This always involves a copy, which can be slow.  Use of this
890 * function should be avoided where possible.
891 * @par The reason you would want to use this function is that a zerocopied
892 * packet from a device is using the devices memory which may be a limited
893 * resource.  Copying the packet will cause it to be copied into the systems
894 * memory.
895 */
896DLLEXPORT libtrace_packet_t *trace_copy_packet(const libtrace_packet_t *packet);
897
898/** Destroy a packet object
899 *
900 * sideeffect: sets packet to NULL
901 */
902DLLEXPORT void trace_destroy_packet(libtrace_packet_t *packet);
903
904
905/** Read one packet from the trace
906 *
907 * @param trace         the libtrace opaque pointer
908 * @param packet        the packet opaque pointer
909 * @return 0 on EOF, negative value on error, number of bytes read when
910 * successful.
911 *
912 * @note the number of bytes read is usually (but not always) the same as
913 * trace_get_framing_length()+trace_get_capture_length() depending on the
914 * trace format.
915 * @note the trace must have been started with trace_start before calling
916 * this function
917 */
918DLLEXPORT int trace_read_packet(libtrace_t *trace, libtrace_packet_t *packet);
919
920/** Event types
921 * see \ref libtrace_eventobj_t and \ref trace_event
922 */
923typedef enum {
924        TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
925        TRACE_EVENT_SLEEP,      /**< Sleep for some time */
926        TRACE_EVENT_PACKET,     /**< packet has arrived */
927        TRACE_EVENT_TERMINATE   /**< End of trace */
928} libtrace_event_t;
929
930/** Structure returned by libtrace_event explaining what the current event is */
931typedef struct libtrace_eventobj_t {
932        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
933        int fd;                /**< if IOWAIT, the fd to sleep on */
934        double seconds;        /**< if SLEEP, the amount of time to sleep for
935                                */
936        int size;              /**< if PACKET, the value returned from
937                                *  trace_read_packet
938                                */
939} libtrace_eventobj_t;
940
941/** Processes the next libtrace event
942 * @param trace the libtrace opaque pointer
943 * @param packet the libtrace_packet opaque pointer
944 * @return libtrace_event struct containing the type, and potential
945 *      fd or seconds to sleep on
946 *
947 * Type can be:
948 *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
949 *  TRACE_EVENT_SLEEP   Next event in seconds
950 *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
951 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
952 */
953DLLEXPORT libtrace_eventobj_t trace_event(libtrace_t *trace,
954                libtrace_packet_t *packet);
955
956
957/** Write one packet out to the output trace
958 *
959 * @param trace         the libtrace_out opaque pointer
960 * @param packet        the packet opaque pointer
961 * @return the number of bytes written out, if zero or negative then an error has occured.
962 */
963DLLEXPORT int trace_write_packet(libtrace_out_t *trace, libtrace_packet_t *packet);
964/*@}*/
965
966/** @name Protocol decodes
967 * These functions locate and return a pointer to various headers inside a
968 * packet
969 * @{
970 */
971
972
973/** Gets a pointer to the first byte of the packet as it was captured and
974 * returns its corresponding linktype and capture length.
975 *
976 * Use this function instead of the deprecated trace_get_link().
977 *
978 * @param packet the packet pointer
979 * @param[out] linktype the linktype of the returned pointer
980 * @param[out] remaining the capture length (the number of captured bytes from
981 * the returned pointer)
982 * @return a pointer to the first byte of the packet
983 */
984DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet,
985                libtrace_linktype_t *linktype, uint32_t *remaining);
986
987/** get a pointer to the link layer
988 * @param packet        the packet opaque pointer
989 *
990 * @return a pointer to the link layer, or NULL if there is no link layer
991 *
992 * @deprecated This function is deprecated: Use trace_get_packet_buffer() or
993 * one of the trace_get_layer*() functions instead.
994 * @note you should call trace_get_link_type to find out what type of link
995 * layer this is
996 */
997DLLEXPORT SIMPLE_FUNCTION DEPRECATED
998void *trace_get_link(const libtrace_packet_t *packet);
999
1000/** get a pointer to the IPv4 header (if any)
1001 * @param packet        the packet opaque pointer
1002 *
1003 * @return a pointer to the IPv4 header, or NULL if there is no IPv4 header
1004 *
1005 * You should consider using \ref trace_get_layer3 instead of this function.
1006 */
1007DLLEXPORT SIMPLE_FUNCTION
1008libtrace_ip_t *trace_get_ip(libtrace_packet_t *packet);
1009
1010/** get a pointer to the IPv6 header (if any)
1011 * @param packet        the packet opaque pointer
1012 *
1013 * @return a pointer to the IPv6 header, or NULL if there is no IPv6 header
1014 *
1015 * You should consider using \ref trace_get_layer3 instead of this function.
1016 */
1017DLLEXPORT SIMPLE_FUNCTION
1018libtrace_ip6_t *trace_get_ip6(libtrace_packet_t *packet);
1019
1020/** Return a pointer to the first metadata header in a packet, if present.
1021 *
1022 * This function takes a pointer to a libtrace packet and if any metadata
1023 * headers exist, returns a pointer to the first one, along with its
1024 * corresponding linktype.
1025 *
1026 * If no metadata headers exist in the packet, NULL is returned.
1027 *
1028 * A metadata header is a header that was prepended by the capturing device,
1029 * such as a Linux SLL header, or a Radiotap wireless monitoring header.
1030 * Subsequent metadata headers may be accessed with the
1031 * trace_get_payload_from_meta(...) function.
1032 *
1033 * @param packet the libtrace packet
1034 * @param[out] linktype the linktype of the returned metadata header
1035 * @param[out] remaining the number of bytes captured after the returned
1036 * pointer.
1037 * @return a pointer to the first metadata header, or NULL if there are no
1038 * metadata headers present.
1039 *
1040 * remaining may be NULL, however linktype must be provided.
1041 */
1042DLLEXPORT void *trace_get_packet_meta(const libtrace_packet_t *packet,
1043                libtrace_linktype_t *linktype,
1044                uint32_t *remaining);
1045
1046/** Returns the payload of a metadata header.
1047 *
1048 * This function takes a pointer to the start of a metadata header (either
1049 * obtained via trace_get_packet_meta(...) or by a previous call to
1050 * trace_get_payload_from_meta(...)) along with its corresponding linktype and
1051 * returns the payload, i.e. the next header. It will also update the linktype
1052 * parameter to indicate the type of payload.
1053 * 
1054 * If the linktype indicates that the header passed in is not a metadata
1055 * header, the function returns NULL to indicate this. The linktype remains
1056 * unchanged in this case.
1057 *
1058 * This function allows the user to iterate through metadata headers which are
1059 * sometimes present before the actual packet as it was received on the wire.
1060 * Examples of metadata headers include the Linux SLL header and the Radiotap
1061 * wireless monitoring header.
1062 *
1063 * @param[in] meta a pointer to a header
1064 * @param[in,out] linktype the linktype of meta (updated to indicate the
1065 * linktype of the returned header if applicable).
1066 * @param[in,out] remaining the number of bytes after the meta pointer.
1067 * @return a pointer to the payload of the metadata header. If meta is not a
1068 * pointer to a metadata header, NULL is returned and linktype remains
1069 * unchanged.
1070 *
1071 * All parameters are mandatory. NULL will be returned if any are NULL.
1072 */
1073DLLEXPORT void *trace_get_payload_from_meta(const void *meta,
1074                libtrace_linktype_t *linktype,
1075                uint32_t *remaining);
1076
1077
1078/** Get a pointer to the layer 2 header. Generally this is the first byte of the
1079 * packet as it was seen on the wire.
1080 *
1081 * This function takes a libtrace packet and skips over any metadata headers if
1082 * present (such as Linux SLL or Radiotap) and returns a pointer to the first
1083 * byte of the packet that was actually received by the network interface.
1084 *
1085 * @param packet the libtrace packet
1086 * @param[out] linktype the linktype of the returned layer 2 header
1087 * @param[out] remaining the number of bytes left in the packet after the
1088 * returned pointer.
1089 * @return a pointer to the first byte of the packet as it was seen on the
1090 * wire.
1091 *
1092 * remaining may be NULL, otherwise it will be filled in by the function.
1093 */
1094DLLEXPORT void *trace_get_layer2(const libtrace_packet_t *packet,
1095                libtrace_linktype_t *linktype,
1096                uint32_t *remaining);
1097
1098/** Gets a pointer to the next header given a pointer to a layer2 header
1099 *
1100 * @param l2                    The pointer to the current layer2 header
1101 * @param linktype              The type of the layer2 header
1102 * @param[out] ethertype        An optional output variable of the ethernet type
1103 * @param[in,out] remaining     Optionally updated with the length remaining
1104 *
1105 * @return a pointer to the transport layer header, or NULL if header isn't
1106 * present.
1107 *
1108 * type may be NULL if not needed.
1109 *
1110 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1111 * of bytes captured of the layer2 header and beyond.  It will be decremented
1112 * by the number of bytes skipped to find the payload.
1113 *
1114 */
1115DLLEXPORT void *trace_get_payload_from_layer2(void *l2,
1116                libtrace_linktype_t linktype,
1117                uint16_t *ethertype,
1118                uint32_t *remaining);
1119
1120
1121/** Get a pointer to the layer 3 header.
1122 * @param packet                The packet opaque pointer
1123 * @param[out] ethertype        The ethertype of the layer 3 header
1124 * @param[out] remaining        The amount of space available after this header
1125 *                              has been removed.
1126 *
1127 * @return a pointer to the layer 3 header.
1128 * remaining may be NULL, otherwise it will be set to the number of captured
1129 * bytes after the pointer returned.
1130 */
1131DLLEXPORT
1132void *trace_get_layer3(const libtrace_packet_t *packet,
1133                uint16_t *ethertype, uint32_t *remaining);
1134
1135/** Gets a pointer to the transport layer header (if any)
1136 * @param packet        a pointer to a libtrace_packet structure
1137 * @param[out] proto    transport layer protocol
1138 *
1139 * @return a pointer to the transport layer header, or NULL if there is no
1140 * header
1141 *
1142 * @note proto may be NULL if proto is unneeded.
1143 */
1144DLLEXPORT void *trace_get_transport(const libtrace_packet_t *packet,
1145                uint8_t *proto, uint32_t *remaining);
1146
1147/** Gets a pointer to the payload given a pointer to the IP header
1148 * @param ip            The IP Header
1149 * @param[out] proto    An output variable of the IP protocol
1150 * @param[in,out] remaining Updated with the number of bytes remaining
1151 *
1152 * @return a pointer to the transport layer header, or NULL if header isn't
1153 * present.
1154 *
1155 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1156 * of bytes captured of the IP header and beyond.  It will be decremented by
1157 * the length of the IPv4 header (including any options).
1158 *
1159 * proto may be NULL if not needed.
1160 *
1161 * @note This is similar to trace_get_transport_from_ip in libtrace2
1162 */
1163DLLEXPORT void *trace_get_payload_from_ip(libtrace_ip_t *ip, uint8_t *proto,
1164                uint32_t *remaining);
1165
1166/** Gets a pointer to the payload given a pointer to the IPv6 header
1167 * @param ipptr         The IPv6 Header
1168 * @param[out] proto    An output variable of the protocol of the next header
1169 * @param[in,out] remaining Updated with the number of bytes remaining
1170 *
1171 * @return a pointer to the transport layer header, or NULL if the IPv6 header
1172 * isn't complete.
1173 *
1174 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1175 * of bytes captured of the IP header and beyond.  It will be decremented by
1176 * this function by the length of the IPV6 header.
1177 *
1178 * proto may be NULL if not needed.
1179 *
1180 */
1181DLLEXPORT void *trace_get_payload_from_ip6(libtrace_ip6_t *ipptr,
1182                uint8_t *prot, uint32_t *remaining);
1183
1184/** Gets a pointer to the payload given a pointer to the link header
1185 * @param ip            The link pointer
1186 * @param[out] type     An output variable of the ethernet type
1187 * @param[in,out] remaining Updated with the number of bytes remaining
1188 *
1189 * @return a pointer to the transport layer header, or NULL if header isn't
1190 * present.
1191 *
1192 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1193 * of bytes captured of the linklayer and beyond.  It will be updated after
1194 * this function to the number of bytes remaining after the IP header (and any
1195 * IP options) have been removed.
1196 *
1197 * type may be NULL if not needed.
1198 *
1199 */
1200DLLEXPORT void *trace_get_payload_from_link(void *linkptr,
1201                libtrace_linktype_t linktype,
1202                uint16_t *type, uint32_t *remaining);
1203
1204/** Skips over any 802.1q headers, if present.
1205 * @param ethernet      A pointer to the payload following an ethernet header
1206 * -usually the result of calling trace_get_payload_from_link
1207 * @param[in,out] type  The ethernet type, replaced with the vlan ether type
1208 * @param[in,out] remaining Updated with the number of bytes remaining
1209 *
1210 * @return a pointer to the header beyond the vlan header, if present.
1211 * Otherwise, returns the ethernet payload that was passed in
1212 *
1213 * Remaining may be NULL. If Remaining is not NULL it must point to the number
1214 * of bytes captured past (but not including) the link layer. This function
1215 * will decrement it by the length of the 802.1q headers if present.
1216 *
1217 * Type must point to the value of the ethernet type. Libtrace will assert
1218 * fail if type is NULL.
1219 *
1220 */
1221DLLEXPORT void *trace_get_vlan_payload_from_ethernet_payload(
1222                void *ethernet_payload, uint16_t *type, uint32_t *remaining);
1223
1224/** Gets a pointer to the payload given a pointer to a tcp header
1225 * @param tcp           The tcp Header
1226 * @param[in,out] remaining Updated with the number of bytes remaining
1227 *
1228 * @return a pointer to the tcp payload, or NULL if the payload isn't present.
1229 *
1230 * Remaining may be NULL.  If remaining is not NULL it must point to the number
1231 * of bytes captured of the TCP header and beyond.  It will be decremented by
1232 * this function by the length of the TCP header (including any options).
1233 *
1234 */
1235DLLEXPORT void *trace_get_payload_from_tcp(libtrace_tcp_t *tcp,
1236                uint32_t *remaining);
1237
1238/** Gets a pointer to the payload given a pointer to a udp header
1239 * @param udp           The udp Header
1240 * @param[in,out] remaining Updated with the number of bytes remaining
1241 *
1242 * @return a pointer to the udp payload, or NULL if the payload isn't present.
1243 *
1244 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1245 * of bytes captured of the UDP header and beyond.  It will be decremented by
1246 * this function to the number of bytes remaining after the UDP header.
1247 *
1248 */
1249DLLEXPORT void *trace_get_payload_from_udp(libtrace_udp_t *udp, uint32_t *remaining);
1250
1251/** Gets a pointer to the payload given a pointer to a icmp header
1252 * @param icmp          The icmp Header
1253 * @param[in,out] remaining Updated with the number of bytes remaining
1254 *
1255 * @return a pointer to the icmp payload, or NULL if the payload isn't present.
1256 *
1257 * Remaining may be NULL.  If remaining is not NULL it must point to the number
1258 * of bytes captured of the ICMP header and beyond.  It will be decremented
1259 * by the number of bytes in the ICMP header.
1260 *
1261 */
1262DLLEXPORT void *trace_get_payload_from_icmp(libtrace_icmp_t *icmp,
1263                uint32_t *remaining);
1264
1265/** get a pointer to the TCP header (if any)
1266 * @param packet        the packet opaque pointer
1267 *
1268 * @return a pointer to the TCP header, or NULL if there is not a TCP packet
1269 *
1270 * @note you should probably use trace_get_transport()
1271 */
1272DLLEXPORT SIMPLE_FUNCTION
1273libtrace_tcp_t *trace_get_tcp(libtrace_packet_t *packet);
1274
1275/** get a pointer to the TCP header (if any) given a pointer to the IP header
1276 * @param ip            The IP header
1277 * @param[in,out] remaining Updated with the number of bytes remaining
1278 *
1279 * @return a pointer to the TCP header, or NULL if this is not a TCP packet
1280 *
1281 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1282 * of bytes captured of the TCP header and beyond.  It will be decremented by
1283 * the number of bytes in the TCP header (including any TCP options).
1284 *
1285 * @note The last parameter has changed from libtrace2
1286 */
1287DLLEXPORT SIMPLE_FUNCTION
1288libtrace_tcp_t *trace_get_tcp_from_ip(libtrace_ip_t *ip, uint32_t *remaining);
1289
1290/** get a pointer to the UDP header (if any)
1291 * @param packet        the packet opaque pointer
1292 *
1293 * @return a pointer to the UDP header, or NULL if this is not a UDP packet
1294 */
1295DLLEXPORT SIMPLE_FUNCTION
1296libtrace_udp_t *trace_get_udp(libtrace_packet_t *packet);
1297
1298/** get a pointer to the UDP header (if any) given a pointer to the IP header
1299 * @param       ip      The IP header
1300 * @param[in,out] remaining Updated with the number of bytes remaining
1301 *
1302 * @return a pointer to the UDP header, or NULL if this is not an UDP packet
1303 *
1304 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1305 * of bytes captured of the UDP header and beyond.  This function will
1306 * decremented it by the length of the UDP header.
1307 *
1308 * @note Beware the change from libtrace2 from skipped to remaining
1309 */
1310DLLEXPORT SIMPLE_FUNCTION
1311libtrace_udp_t *trace_get_udp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
1312
1313/** get a pointer to the ICMP header (if any)
1314 * @param packet        the packet opaque pointer
1315 *
1316 * @return a pointer to the ICMP header, or NULL if this is not a ICMP packet
1317 */
1318DLLEXPORT SIMPLE_FUNCTION
1319libtrace_icmp_t *trace_get_icmp(libtrace_packet_t *packet);
1320
1321/** get a pointer to the ICMP header (if any) given a pointer to the IP header
1322 * @param ip            The IP header
1323 * @param[in,out] remaining Updated with the number of bytes remaining
1324 *
1325 * @return a pointer to the ICMP header, or NULL if this is not an ICMP packet
1326 *
1327 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
1328 * of bytes captured of the ICMP header and beyond.  It will be decremented by
1329 * the length of the ICMP head in bytes.
1330 *
1331 * @note Beware the change from libtrace2 from skipped to remaining
1332 */
1333DLLEXPORT SIMPLE_FUNCTION
1334libtrace_icmp_t *trace_get_icmp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
1335
1336/** Get the destination MAC address
1337 * @param packet        the packet opaque pointer
1338 * @return a pointer to the destination mac, (or NULL if there is no
1339 * destination MAC)
1340 */
1341DLLEXPORT SIMPLE_FUNCTION
1342uint8_t *trace_get_destination_mac(libtrace_packet_t *packet);
1343
1344/** Get the source MAC address
1345 * @param packet        the packet opaque pointer
1346 * @return a pointer to the source mac, (or NULL if there is no source MAC)
1347 */
1348DLLEXPORT SIMPLE_FUNCTION
1349uint8_t *trace_get_source_mac(libtrace_packet_t *packet);
1350
1351/** Get the source IP address
1352 * @param packet        the packet opaque pointer
1353 * @param addr          a pointer to a sockaddr to store the address in, or NULL to use
1354 *                      static storage.
1355 * @return NULL if there is no source address, or a sockaddr holding a v4 or v6
1356 * address
1357 */
1358DLLEXPORT SIMPLE_FUNCTION
1359struct sockaddr *trace_get_source_address(const libtrace_packet_t *packet,
1360                struct sockaddr *addr);
1361
1362/** Get the destination IP address
1363 * @param packet        the packet opaque pointer
1364 * @param addr          a pointer to a sockaddr to store the address in, or NULL to use
1365 *                      static storage.
1366 * @return NULL if there is no destination address, or a sockaddr holding a v4
1367 * or v6 address
1368 */
1369DLLEXPORT SIMPLE_FUNCTION
1370struct sockaddr *trace_get_destination_address(const libtrace_packet_t *packet,
1371                struct sockaddr *addr);
1372
1373/*@}*/
1374
1375/** parse an ip or tcp option
1376 * @param[in,out] ptr   the pointer to the current option
1377 * @param[in,out] len   the length of the remaining buffer
1378 * @param[out] type     the type of the option
1379 * @param[out] optlen   the length of the option
1380 * @param[out] data     the data of the option
1381 *
1382 * @return bool true if there is another option (and the fields are filled in)
1383 *               or false if this was the last option.
1384 *
1385 * This updates ptr to point to the next option after this one, and updates
1386 * len to be the number of bytes remaining in the options area.  Type is updated
1387 * to be the code of this option, and data points to the data of this option,
1388 * with optlen saying how many bytes there are.
1389 *
1390 * @note Beware of fragmented packets.
1391 */
1392DLLEXPORT int trace_get_next_option(unsigned char **ptr,int *len,
1393                        unsigned char *type,
1394                        unsigned char *optlen,
1395                        unsigned char **data);
1396
1397
1398/** @name Time
1399 * These functions deal with time that a packet arrived and return it
1400 * in various formats
1401 * @{
1402 */
1403/** Get the current time in DAG time format
1404 * @param packet        the packet opaque pointer
1405 *
1406 * @return a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
1407 * past 1970-01-01, the lower 32bits are partial seconds)
1408 */
1409DLLEXPORT SIMPLE_FUNCTION
1410uint64_t trace_get_erf_timestamp(const libtrace_packet_t *packet);
1411
1412/** Get the current time in struct timeval
1413 * @param packet        the packet opaque pointer
1414 *
1415 * @return time that this packet was seen in a struct timeval
1416 */
1417DLLEXPORT SIMPLE_FUNCTION
1418struct timeval trace_get_timeval(const libtrace_packet_t *packet);
1419
1420/** Get the current time in floating point seconds
1421 * @param packet        the packet opaque pointer
1422 *
1423 * @return time that this packet was seen in 64bit floating point seconds from
1424 * the unix epoch (1970-01-01 00:00:00 UTC).
1425 */
1426DLLEXPORT SIMPLE_FUNCTION
1427double trace_get_seconds(const libtrace_packet_t *packet);
1428
1429/** Seek within a trace
1430 * @param trace         trace to seek
1431 * @param seconds       time to seek to
1432 * @return 0 on success.
1433 * Make the next packet read to be the first packet to occur at or after the
1434 * time searched for.  This must be called in the configuration state (ie,
1435 * before trace_start() or after trace_pause().
1436 * @note This function may be extremely slow.
1437 */
1438DLLEXPORT int trace_seek_seconds(libtrace_t *trace, double seconds);
1439
1440/** Seek within a trace
1441 * @param trace         trace to seek
1442 * @param tv            time to seek to
1443 * @return 0 on success.
1444 * Make the next packet read to be the first packet to occur at or after the
1445 * time searched for.  This must be called in the configuration state (ie,
1446 * before trace_start() or after trace_pause().
1447 * @note This function may be extremely slow.
1448 */
1449DLLEXPORT int trace_seek_timeval(libtrace_t *trace, struct timeval tv);
1450
1451/** Seek within a trace
1452 * @param trace         trace to seek
1453 * @param ts            erf timestamp
1454 * @return 0 on success.
1455 * Make the next packet read to be the first packet to occur at or after the
1456 * time searched for.  This must be called in the configuration state (ie,
1457 * before trace_start() or after trace_pause().
1458 * @note This function may be extremely slow.
1459 */
1460DLLEXPORT int trace_seek_erf_timestamp(libtrace_t *trace, uint64_t ts);
1461
1462/*@}*/
1463
1464/** @name Sizes
1465 * This section deals with finding or setting the various different lengths
1466 * a packet can have
1467 * @{
1468 */
1469/** Get the size of the packet in the trace (in bytes)
1470 * @param packet        the packet opaque pointer
1471 * @return the size of the packet in the trace
1472 * @note Due to this being a header capture, or anonymisation, this may not
1473 * be the same size as the original packet.  See get_wire_length() for the
1474 * original size of the packet.
1475 * @note This can (and often is) different for different packets in a trace!
1476 * @note This is sometimes called the "snaplen".
1477 * @note The return size refers to the network-level payload of the packet and
1478 * does not include any capture framing headers. For example, an Ethernet
1479 * packet with an empty TCP packet will return sizeof(ethernet_header) +
1480 * sizeof(ip_header) + sizeof(tcp_header), but not the capture file
1481 * (pcap/erf/etc) header.
1482 */
1483DLLEXPORT SIMPLE_FUNCTION
1484size_t trace_get_capture_length(const libtrace_packet_t *packet);
1485
1486/** Get the size of the packet as it was seen on the wire (in bytes).
1487 * @param packet        the packet opaque pointer
1488 * @return the size of the packet as it was on the wire.
1489 * @note Due to the trace being a header capture, or anonymisation this may
1490 * not be the same as the Capture Len.
1491 * @note trace_getwire_length \em{includes} FCS.
1492 * @note The return size refers to the network-level payload of the packet and
1493 * does not include any capture framing headers. For example, an Ethernet
1494 * packet with an empty TCP packet will return sizeof(ethernet_header) +
1495 * sizeof(ip_header) + sizeof(tcp_header), but not the capture file
1496 * (pcap/erf/etc) header.
1497 */
1498DLLEXPORT SIMPLE_FUNCTION
1499size_t trace_get_wire_length(const libtrace_packet_t *packet);
1500
1501/** Get the length of the capture framing headers (in bytes).
1502 * @param packet        the packet opaque pointer
1503 * @return the size of the packet as it was on the wire.
1504 * @note this length corresponds to the difference between the size of a
1505 * captured packet in memory, and the captured length of the packet
1506 */
1507DLLEXPORT SIMPLE_FUNCTION
1508size_t trace_get_framing_length(const libtrace_packet_t *packet);
1509
1510/** Truncate ("snap") the packet at the suggested length
1511 * @param packet        the packet opaque pointer
1512 * @param size          the new length of the packet (in bytes)
1513 * @return the new capture length of the packet, or the original capture
1514 * length of the packet if unchanged
1515 */
1516DLLEXPORT size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
1517
1518/*@}*/
1519
1520
1521/** Get the type of the link layer
1522 * @param packet        the packet opaque pointer
1523 * @return libtrace_linktype_t
1524 */
1525DLLEXPORT SIMPLE_FUNCTION
1526libtrace_linktype_t trace_get_link_type(const libtrace_packet_t *packet);
1527
1528/** Set the direction flag, if it has one
1529 * @param packet        the packet opaque pointer
1530 * @param direction     the new direction
1531 * @returns -1 on error, or the direction that was set.
1532 */
1533DLLEXPORT libtrace_direction_t trace_set_direction(libtrace_packet_t *packet, libtrace_direction_t direction);
1534
1535/** Get the direction flag, if it has one
1536 * @param packet        the packet opaque pointer
1537 * @return a value containing the direction flag, or -1 if this is not supported
1538 * The direction is defined as 0 for packets originating locally (ie, outbound)
1539 * and 1 for packets originating remotely (ie, inbound).
1540 * Other values are possible, which might be overloaded to mean special things
1541 * for a special trace.
1542 */
1543DLLEXPORT SIMPLE_FUNCTION
1544libtrace_direction_t trace_get_direction(const libtrace_packet_t *packet);
1545
1546/** @name BPF
1547 * This section deals with using Berkley Packet Filters
1548 * @{
1549 */
1550/** setup a BPF filter
1551 * @param filterstring a char * containing the bpf filter string
1552 * @return opaque pointer pointer to a libtrace_filter_t object
1553 * @note The filter is not actually compiled at this point, so no correctness
1554 * tests are performed here. trace_create_filter will always return ok, but
1555 * if the filter is poorly constructed an error will be generated when the
1556 * filter is actually used
1557 */
1558DLLEXPORT SIMPLE_FUNCTION
1559libtrace_filter_t *trace_create_filter(const char *filterstring);
1560
1561/** Setup a BPF filter based on pre-compiled byte-code.
1562 * @param bf_insns      A pointer to the start of the byte-code
1563 * @param bf_len        The number of BPF instructions 
1564 * @returns             an opaque pointer to a libtrace_filter_t object
1565 * @note                The supplied byte-code is not checked for correctness.
1566 * @author              Scott Raynel
1567 */
1568DLLEXPORT libtrace_filter_t *
1569trace_create_filter_from_bytecode(void *bf_insns, unsigned int bf_len);
1570
1571/** Apply a BPF filter to a packet
1572 * @param filter        the filter opaque pointer
1573 * @param packet        the packet opaque pointer
1574 * @return >0 if the filter matches, 0 if it doesn't, -1 on error.
1575 * @note Due to the way BPF filters are built, the filter is not actually
1576 * compiled until the first time trace_create_filter is called. If your filter
1577 * is incorrect, it will generate an error message and assert, exiting the
1578 * program. This behaviour may change to more graceful handling of this error
1579 * in the future.
1580 */
1581DLLEXPORT int trace_apply_filter(libtrace_filter_t *filter,
1582                const libtrace_packet_t *packet);
1583
1584/** Destroy a BPF filter
1585 * @param filter        the filter opaque pointer
1586 * Deallocate all the resources associated with a BPF filter
1587 */
1588DLLEXPORT void trace_destroy_filter(libtrace_filter_t *filter);
1589/*@}*/
1590
1591/** @name Portability
1592 * This section has functions that causes annoyances to portability for one
1593 * reason or another.
1594 * @{
1595 */
1596
1597/** Convert an ethernet address to a string
1598 * @param addr  Ethernet address in network byte order
1599 * @param buf   Buffer to store the ascii representation, or NULL
1600 * @return buf, or if buf is NULL then a statically allocated buffer.
1601 *
1602 * This function is similar to the GNU ether_ntoa_r function, with a few
1603 * minor differences.  if NULL is passed as buf, then the function will
1604 * use an internal static buffer, if NULL isn't passed then the function
1605 * will use that buffer instead.
1606 *
1607 * @note the type of addr isn't struct ether_addr as it is with ether_ntoa_r,
1608 * however it is bit compatible so that a cast will work.
1609 */
1610DLLEXPORT char *trace_ether_ntoa(const uint8_t *addr, char *buf);
1611
1612/** Convert a string to an ethernet address
1613 * @param buf   Ethernet address in hex format delimited with :'s.
1614 * @param addr  buffer to store the binary representation, or NULL
1615 * @return addr, or if addr is NULL, then a statically allocated buffer.
1616 *
1617 * This function is similar to the GNU ether_aton_r function, with a few
1618 * minor differences.  if NULL is passed as addr, then the function will
1619 * use an internal static buffer, if NULL isn't passed then the function will
1620 * use that buffer instead.
1621 *
1622 * @note the type of addr isn't struct ether_addr as it is with ether_aton_r,
1623 * however it is bit compatible so that a cast will work.
1624 */
1625DLLEXPORT uint8_t *trace_ether_aton(const char *buf, uint8_t *addr);
1626
1627/*@}*/
1628
1629
1630/** Which port is the server port */
1631typedef enum {
1632        USE_DEST,       /**< Destination port is the server port */
1633        USE_SOURCE      /**< Source port is the server port */
1634} serverport_t;
1635
1636/** Get the source port
1637 * @param packet        the packet to read from
1638 * @return a port in \em HOST byte order, or equivalent to ports for this
1639 * protocol, or 0 if this protocol has no ports.
1640 */
1641DLLEXPORT SIMPLE_FUNCTION
1642uint16_t trace_get_source_port(const libtrace_packet_t *packet);
1643
1644/** Get the destination port
1645 * @param packet        the packet to read from
1646 * @return a port in \em HOST byte order, or equivilent to ports for this
1647 * protocol, or 0 if this protocol has no ports.
1648 */
1649DLLEXPORT SIMPLE_FUNCTION
1650uint16_t trace_get_destination_port(const libtrace_packet_t *packet);
1651
1652/** hint at the server port in specified protocol
1653 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
1654 * @param source        the source port from the packet
1655 * @param dest          the destination port from the packet
1656 * @return one of USE_SOURCE or USE_DEST depending on which one you should use
1657 * @note ports must be in \em HOST byte order!
1658 */
1659DLLEXPORT SIMPLE_FUNCTION
1660int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
1661
1662/** Takes a uri and splits it into a format and uridata component.
1663 * @param uri           the uri to be parsed
1664 * @param format        destination location for the format component of the uri
1665 * @return 0 if an error occured, otherwise return the uridata component
1666 */
1667DLLEXPORT const char *trace_parse_uri(const char *uri, char **format);
1668
1669/** Gets the format type for a given packet.
1670 * @param packet        the packet opaque pointer
1671 * @return the format of the packet
1672 */
1673DLLEXPORT
1674enum base_format_t trace_get_format(struct libtrace_packet_t *packet);
1675
1676/** Construct a packet from a buffer.
1677 * @param packet[in,out]        Libtrace Packet object to update with the new
1678 *                              data.
1679 * @param linktype              The linktype of the packet.
1680 * @param[in] data              The packet data (including linklayer)
1681 * @param len                   Length of packet data
1682 */
1683DLLEXPORT
1684void trace_construct_packet(libtrace_packet_t *packet,
1685                libtrace_linktype_t linktype, const void *data, uint16_t len);
1686
1687/*@}*/
1688
1689/** @name Wireless trace support
1690 * Functions to access wireless information from packets that have wireless
1691 * monitoring headers such as Radiotap or Prism.
1692 *
1693 * The trace_get_wireless_* functions provide an abstract interface for
1694 * retrieving information from wireless traces. They take a pointer to the
1695 * wireless monitoring header (usually found with trace_get_link(packet)) and
1696 * the linktype of the header passed in.
1697 *
1698 * All of the trace_get_wireless_* functions return false if the requested
1699 * information was unavailable, or true if it was. The actual data is stored
1700 * in an output variable supplied by the caller. Values returned into the
1701 * output variable will always be returned in host byte order.
1702 * @{
1703 */
1704
1705
1706#ifndef ARPHRD_80211_RADIOTAP
1707/* libc doesn't define this yet, but it seems to be what everyone is using
1708 */
1709#define ARPHRD_80211_RADIOTAP 803
1710#endif
1711
1712/** Get the wireless Timer Syncronisation Function
1713 *
1714 * Gets the value of the timer syncronisation function for this frame, which
1715 * is a value in microseconds indicating the time that the first bit of the
1716 * MPDU was received by the MAC.
1717 *
1718 * @param link the wireless header
1719 * @param linktype the linktype of the wireless header passed in
1720 * @param[out] tsft the value of the timer syncronisation function.
1721 * @return true if the field was available, false if not.
1722 */
1723DLLEXPORT bool trace_get_wireless_tsft(void *linkptr,
1724        libtrace_linktype_t linktype, uint64_t *tsft);
1725
1726/** Get the wireless rate
1727 * @param link the wireless header
1728 * @param linktype the linktype of the wireless header passed in
1729 * @param[out] rate the data-rate of the frame in units of 500kbps
1730 * @return true if the field was available, false if not.
1731 */
1732DLLEXPORT bool trace_get_wireless_rate(void *linkptr,
1733        libtrace_linktype_t linktype, uint8_t *rate);
1734
1735/** Get the wireless channel frequency
1736 * @param link the wireless header
1737 * @param linktype the linktype of the wireless header passed in
1738 * @param[out] freq the frequency in MHz of the channel the frame was transmitted
1739 * or received on.
1740 * @return true if the field was available, false if not.
1741 */
1742DLLEXPORT bool trace_get_wireless_freq(void *linkptr,
1743        libtrace_linktype_t linktype, uint16_t *freq);
1744
1745/** Get the wireless signal strength in dBm
1746 * @param link the wireless header
1747 * @param linktype the linktype of the wireless header passed in
1748 * @param[out] strength the RF signal power at the antenna, in dB difference
1749 * from 1mW.
1750 * @return true if the field was available, false if not.
1751 */
1752DLLEXPORT bool trace_get_wireless_signal_strength_dbm(void *linkptr,
1753        libtrace_linktype_t linktype, int8_t *strength);
1754
1755/** Get the wireless noise strength in dBm
1756 * @param link the wireless header
1757 * @param linktype the linktype of the wireless header passed in
1758 * @param[out] strength the RF noise power at the antenna, in dB difference
1759 * from 1mW.
1760 * @return true if the field was available, false if not.
1761 */
1762DLLEXPORT bool trace_get_wireless_noise_strength_dbm(void *linkptr,
1763        libtrace_linktype_t linktype, int8_t *strength);
1764
1765/** Get the wireless signal strength in dB
1766 * @param link the wireless header
1767 * @param linktype the linktype of the wireless header passed in
1768 * @param[out] strength the RF signal power at the antenna,in dB difference
1769 * from a fixed reference.
1770 * @return true if the field was available, false if not.
1771 */
1772DLLEXPORT bool trace_get_wireless_signal_strength_db(void *linkptr,
1773        libtrace_linktype_t linktype, uint8_t *strength);
1774
1775/** Get the wireless noise strength in dB
1776 * @param link the wireless header
1777 * @param linktype the linktype of the wireless header passed in
1778 * @param[out] strength the RF noise power at the antenna, in dB difference
1779 * from a fixed reference.
1780 * @return true if the field was available, false if not.
1781 */
1782DLLEXPORT bool trace_get_wireless_noise_strength_db(void *linkptr,
1783        libtrace_linktype_t linktype, uint8_t *strength);
1784
1785/** Get the wireless transmit attenuation
1786 * @param link the wireless header
1787 * @param linktype the linktype of the wireless header passed in
1788 * @param[out] attenuation the transmit power as a unitless distance from maximum
1789 * power set at factory calibration. 0 indicates maximum transmission power.
1790 * @return true if the field was available, false if not.
1791 */
1792DLLEXPORT bool trace_get_wireless_tx_attenuation(void *linkptr,
1793        libtrace_linktype_t linktype, uint16_t *attenuation);
1794
1795/** Get the wireless transmit attenuation in dB
1796 * @param link the wireless header
1797 * @param linktype the linktype of the wireless header passed in
1798 * @param[out] attenuation the transmit power as dB difference from maximum power
1799 * set at factory calibration. 0 indicates maximum power.
1800 * @return true if the field was available, false if not.
1801 */
1802DLLEXPORT bool trace_get_wireless_tx_attenuation_db(void *linkptr,
1803        libtrace_linktype_t linktype, uint16_t *attenuation);
1804
1805/** Get the wireless transmit power in dBm @param link the wireless header
1806 * @param linktype the linktype of the wireless header passed in
1807 * @param[out] txpower the transmit power as dB from a 1mW reference. This is the absolute power level measured at the antenna port. 
1808 * @return true if the field was available, false if not.
1809 */
1810DLLEXPORT bool trace_get_wireless_tx_power_dbm(void *linkptr, libtrace_linktype_t
1811                linktype, int8_t *txpower);
1812
1813/** Get the wireless antenna
1814 * @param link the wireless header
1815 * @param linktype the linktype of the wireless header passed in
1816 * @param[out] antenna which antenna was used to transmit or receive the frame.
1817 * @return true if the field was available, false if not.
1818 */
1819DLLEXPORT bool trace_get_wireless_antenna(void *linkptr,
1820        libtrace_linktype_t linktype, uint8_t *antenna);
1821
1822/*@}*/
1823
1824#ifdef __cplusplus
1825} /* extern "C" */
1826#endif /* #ifdef __cplusplus */
1827#endif /* LIBTRACE_H_ */
Note: See TracBrowser for help on using the repository browser.