source: lib/libtrace.h.in @ 73dd29f

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 73dd29f was 73dd29f, checked in by Perry Lorier <perry@…>, 14 years ago

Sooo, pcap has two types of DLT's "pure" DLT's that are platform dependant,
and "linktype" DLT's that are portable and are what are written to pcap files.

Instead of fudging the two concepts together so much, attempt to disintangle
this mess without exposing too much of the god awful mess to the end user.

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