source: lib/libtrace_int.h @ 81c2da8

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 81c2da8 was 8488c15, checked in by Shane Alcock <salcock@…>, 12 years ago
  • Updated the documentation for the internal header file
  • Also removed the reference to trace_get_payload_from_pos() which doesn't exist and the define for RP_BUFSIZE which is never used
  • Property mode set to 100644
File size: 35.2 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
7 * Authors: Daniel Lawson
8 *          Perry Lorier
9 *          Shane Alcock
10 *         
11 * All rights reserved.
12 *
13 * This code has been developed by the University of Waikato WAND
14 * research group. For further information please see http://www.wand.net.nz/
15 *
16 * libtrace is free software; you can redistribute it and/or modify
17 * it under the terms of the GNU General Public License as published by
18 * the Free Software Foundation; either version 2 of the License, or
19 * (at your option) any later version.
20 *
21 * libtrace is distributed in the hope that it will be useful,
22 * but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24 * GNU General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with libtrace; if not, write to the Free Software
28 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29 *
30 * $Id$
31 *
32 */
33
34/** @file
35 *
36 * @brief Header file containing definitions for structures and functions that
37 * are internal
38 *
39 * @author Daniel Lawson
40 * @author Perry Lorier
41 * @author Shane Alcock
42 *
43 * @version $Id$
44 *
45 * All of the structures and functions defined in this header file are intended
46 * for internal use within Libtrace only. They should not be exported as part
47 * of the library API as we don't want users accessing things like the
48 * contents of the libtrace packet structure directly!
49 */
50#ifndef LIBTRACE_INT_H
51#define LIBTRACE_INT_H
52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57#include "common.h"
58#include "config.h"
59#include "libtrace.h"
60#include "wandio.h"
61
62#ifdef _MSC_VER
63// warning: deprecated function
64#pragma warning(disable:4996)
65// warning: benign redefinitions of types
66#pragma warning(disable:4142)
67#endif
68
69#ifdef HAVE_INTTYPES_H
70# include <inttypes.h>
71#else
72# include "lt_inttypes.h"
73#endif
74
75#ifdef HAVE_STDDEF_H
76# include <stddef.h>
77#else
78#ifndef WIN32
79# error "Can't find stddev.h -- do you define ptrdiff_t elsewhere?"
80#endif
81#endif
82
83
84#include "rt_protocol.h"
85       
86/* Prefer net/bpf.h over pcap-bpf.h for format_bpf.c on MacOS */
87#ifdef HAVE_NET_BPF_H
88#    include <net/bpf.h>
89#    define HAVE_BPF 1
90#else
91#ifdef HAVE_PCAP_BPF_H
92#  include <pcap-bpf.h>
93#  define HAVE_BPF 1
94#endif
95#endif
96
97#ifdef HAVE_PCAP_H
98#  include <pcap.h>
99#  ifdef HAVE_PCAP_INT_H
100#    include <pcap-int.h>
101#  endif
102#endif
103
104#ifdef HAVE_ZLIB_H
105#  include <zlib.h>
106#endif
107
108#ifndef HAVE_STRNCASECMP
109# ifndef HAVE__STRNICMP
110/** A local implementation of strncasecmp (as some systems do not have it) */
111int strncasecmp(const char *str1, const char *str2, size_t n);
112# else
113# define strncasecmp _strnicmp
114# endif
115#endif
116
117#ifndef HAVE_SNPRINTF
118# ifndef HAVE_SPRINTF_S
119/** A local implementation of snprintf (as some systems do not have it) */
120int snprintf(char *str, size_t size, const char *format, ...);
121# else
122# define snprintf sprintf_s
123# endif
124#endif
125
126#include "daglegacy.h"
127       
128#ifdef HAVE_DAG_API
129#  include "dagnew.h"
130#  include "dagapi.h"
131#       if DAG_VERSION == 25
132#               include <daginf.h>
133#       else
134#               include <erftypes.h>
135#       endif
136#else
137#  include "dagformat.h"
138#endif
139
140//#define RP_BUFSIZE 65536U
141
142/** Data about the most recent event from a trace file */
143struct libtrace_event_status_t {
144        /** A libtrace packet to store the packet when a PACKET event occurs */
145        libtrace_packet_t *packet;
146        /** Time between the timestamp for the current packet and the current
147         * walltime */
148        double tdelta;
149        /** The timestamp of the previous PACKET event */
150        double trace_last_ts;
151        /** The size of the current PACKET event */
152        int psize;
153};
154
155/** A libtrace input trace
156 * @internal
157 */
158struct libtrace_t {
159        /** The capture format for the input trace */
160        struct libtrace_format_t *format; 
161        /** Details of the most recent PACKET event reported by the trace */
162        struct libtrace_event_status_t event;
163        /** Pointer to the "global" data for the capture format module */       
164        void *format_data;             
165        /** A BPF filter to be applied to all packets read by the trace -
166         * used only if the capture format does not support filters natively */
167        struct libtrace_filter_t *filter; 
168        /** The snap length to be applied to all packets read by the trace -
169         * used only if the capture format does not support snapping natively */
170        size_t snaplen;                 
171        /** Count of the number of packets returned to the libtrace user */
172        uint64_t accepted_packets;     
173        /** Count of the number of packets filtered by libtrace */
174        uint64_t filtered_packets;     
175        /** The filename from the uri for the trace */
176        char *uridata;                 
177        /** The libtrace IO reader for this trace (if applicable) */
178        io_t *io;                       
179        /** Error information for the trace */
180        libtrace_err_t err;             
181        /** Boolean flag indicating whether the trace has been started */
182        bool started;                   
183};
184
185/** A libtrace output trace
186 * @internal
187 */
188struct libtrace_out_t {
189        /** The capture format for the output trace */
190        struct libtrace_format_t *format;
191        /** Pointer to the "global" data for the capture format module */
192        void *format_data;             
193        /** The filename for the uri for the output trace */
194        char *uridata;                 
195        /** Error information for the output trace */
196        libtrace_err_t err;
197        /** Boolean flag indicating whether the trace has been started */
198        bool started;                   
199};
200
201/** Sets the error status on an input trace
202 *
203 * @param trace         The input trace to set the error status for
204 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
205 * @param msg           A message to print when reporting the error
206 */
207void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...) 
208
209                                                                PRINTF(3,4);
210/** Sets the error status on an output trace
211 *
212 * @param trace         The output trace to set the error status for
213 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
214 * @param msg           A message to print when reporting the error
215 */
216void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...)
217                                                                PRINTF(3,4);
218
219
220/** Converts the data provided in buffer into a valid libtrace packet
221 *
222 * @param trace         An input trace of the same format as the "packet"
223 *                      contained in the buffer
224 * @param packet        The libtrace packet to prepare
225 * @param buffer        A buffer containing the packet data, including the
226 *                      capture format header
227 * @param rt_type       The RT type for the packet that is being prepared
228 * @param flags         Used to specify options for the preparation function,
229 *                      e.g. who owns the packet buffer
230 *
231 * @return -1 if an error occurs, 0 otherwise
232 *
233 * Packet preparation is a tricky concept - the idea is to take the data
234 * pointed to by 'buffer' and treat it as a packet record of the same capture
235 * format as that used by the input trace. The provided libtrace packet then
236 * has its internal pointers and values set to describe the packet record in
237 * the buffer.
238 *
239 * The primary use of this function is to allow the RT packet reader to
240 * easily and safely convert packets from the RT format back into the format
241 * that they were originally captured with., essentially removing the RT
242 * encapsulation.
243 *
244 * We've decided not to make this function available via the exported API
245 * because there are several issues that can arise if it is not used very
246 * carefully and it is not very useful outside of internal contexts anyway.
247 */
248int trace_prepare_packet(libtrace_t *trace, libtrace_packet_t *packet,
249                void *buffer, libtrace_rt_types_t rt_type, uint32_t flags);
250
251/** Flags for prepare_packet functions */
252enum {
253        /** The buffer memory has been allocated by libtrace and should be
254         * freed when the packet is destroyed. */
255        TRACE_PREP_OWN_BUFFER           =1,
256       
257        /** The buffer memory is externally-owned and must not be freed by
258         * libtrace when the packet is destroyed. */
259        TRACE_PREP_DO_NOT_OWN_BUFFER    =0
260};
261
262/** A local definition of an SLL header */
263typedef struct libtrace_sll_header_t {
264        uint16_t pkttype;               /**< Packet type */
265        uint16_t hatype;                /**< Link-layer address type */
266        uint16_t halen;                 /**< Link-layer address length */
267        unsigned char addr[8];          /**< Link-layer address */
268        uint16_t protocol;              /**< Protocol */
269} libtrace_sll_header_t;
270
271
272/* SLL packet types */
273
274/** Packet was addressed for the local host */
275#define TRACE_SLL_HOST          0
276/** Packet was addressed for a broadcast address */
277#define TRACE_SLL_BROADCAST     1
278/** Packet was addressed for a multicast address */
279#define TRACE_SLL_MULTICAST     2
280/** Packet was addressed for another host but was captured by a promiscuous
281 * device */
282#define TRACE_SLL_OTHERHOST     3
283/** Packet originated from the local host */
284#define TRACE_SLL_OUTGOING      4
285
286#ifndef PF_RULESET_NAME_SIZE
287#define PF_RULESET_NAME_SIZE 16
288#endif
289
290#ifndef IFNAMSIZ
291#define IFNAMSIZ 16
292#endif
293
294
295/** A local definition of a PFLOG header */
296typedef struct libtrace_pflog_header_t {
297        uint8_t    length;     
298        sa_family_t   af;
299        uint8_t    action;
300        uint8_t    reason;
301        char       ifname[IFNAMSIZ];
302        char       ruleset[PF_RULESET_NAME_SIZE];
303        uint32_t   rulenr;
304        uint32_t   subrulenr;
305        uint8_t    dir;
306        uint8_t    pad[3];
307} PACKED libtrace_pflog_header_t;
308
309
310
311/** A libtrace capture format module */
312/* All functions should return -1, or NULL on failure */
313struct libtrace_format_t {
314        /** The name of this module, used in the libtrace URI to identify the
315         * capture format */
316        const char *name;
317        /** The version of this module */
318        const char *version;
319        /** The RT protocol type of this module */
320        enum base_format_t type;
321
322
323        /** Given a filename, return if this is the most likely capture format
324         * (used for devices). Used to "guess" the capture format when the
325         * URI is not fully specified.
326         *
327         * @param fname         The name of the device or file to examine
328         * @return 1 if the name matches the capture format, 0 otherwise
329         */
330        int (*probe_filename)(const char *fname);
331       
332        /** Given a file, looks at the start of the file to determine if this
333         * is the capture format. Used to "guess" the capture format when the
334         * URI is not fully specified.
335         *
336         * @param io            An open libtrace IO reader for the file to check
337         * @return 1 if the file matches the capture format, 0 otherwise
338         */
339        int (*probe_magic)(io_t *io);
340
341        /** Initialises an input trace using the capture format.
342         *
343         * @param libtrace      The input trace to be initialised
344         * @return 0 if successful, -1 in the event of error
345         */
346        int (*init_input)(libtrace_t *libtrace);
347       
348        /** Applies a configuration option to an input trace.
349         *
350         * @param libtrace      The input trace to apply the option to
351         * @param option        The option that is being configured
352         * @param value         A pointer to the value that the option is to be
353         *                      set to
354         * @return 0 if successful, -1 if the option is unsupported or an error
355         * occurs
356         */
357        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
358        /** Starts or unpauses an input trace - note that this function is
359         * often the one that opens the file or device for reading.
360         *
361         * @param libtrace      The input trace to be started or unpaused
362         * @return 0 if successful, -1 in the event of error */
363        int (*start_input)(libtrace_t *libtrace);
364
365        /** Pauses an input trace - this function should close or detach the
366         * file or device that is being read from.
367         *
368         * @param libtrace      The input trace to be paused
369         * @return 0 if successful, -1 in the event of error
370         */
371        int (*pause_input)(libtrace_t *libtrace);
372
373        /** Initialises an output trace using the capture format.
374         *
375         * @param libtrace      The output trace to be initialised
376         * @return 0 if successful, -1 in the event of error
377         */
378        int (*init_output)(libtrace_out_t *libtrace);
379       
380        /** Applies a configuration option to an output trace.
381         *
382         * @param libtrace      The output trace to apply the option to
383         * @param option        The option that is being configured
384         * @param value         A pointer to the value that the option is to be
385         *                      set to
386         * @return 0 if successful, -1 if the option is unsupported or an error
387         * occurs
388         * */
389        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value);
390
391        /** Starts an output trace - note that this function is often the one
392         * that opens the file or device for writing.
393         *
394         * @param libtrace      The output trace to be started
395         * @return 0 if successful, -1 if an error occurs
396         *
397         * There is no pause for output traces, as writing is not performed
398         * asynchronously.
399         */
400        int (*start_output)(libtrace_out_t *libtrace);
401
402        /** Concludes an input trace and cleans up the capture format data.
403         *
404         * @param libtrace      The input trace to be concluded
405         * @return 0 if successful, -1 if an error occurs
406         *
407         * Libtrace will call the pause_input function if the input trace is
408         * currently active prior to calling this function.
409         */
410        int (*fin_input)(libtrace_t *libtrace);
411
412        /** Concludes an output trace and cleans up the capture format data.
413         *
414         * @param libtrace      The output trace to be concluded
415         * @return 0 if successful, -1 if an error occurs
416         */
417        int (*fin_output)(libtrace_out_t *libtrace);
418
419        /** Reads the next packet from an input trace into the provided packet
420         * structure.
421         *
422         * @param libtrace      The input trace to read from
423         * @param packet        The libtrace packet to read into
424         * @return The size of the packet read (in bytes) including the capture
425         * framing header, or -1 if an error occurs. 0 is returned in the
426         * event of an EOF.
427         *
428         * If no packets are available for reading, this function should block
429         * until one appears or return 0 if the end of a trace file has been
430         * reached.
431         */
432        int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet);
433       
434        /** Converts a buffer containing a packet record into a libtrace packet
435         *
436         * @param libtrace      An input trace in the capture format for the
437         *                      packet
438         * @param packet        A libtrace packet to put the prepared packet
439         *                      into
440         * @param buffer        The buffer containing the packet record
441         *                      (including the capture format header)
442         * @param rt_type       The RT type for the packet
443         * @param flags         Flags describing properties that should be
444         *                      applied to the new packet
445         * @return 0 if successful, -1 if an error occurs.
446         *
447         * Updates internal trace and packet details, such as payload pointers,
448         * loss counters and packet types to match the packet record provided
449         * in the buffer. This is a zero-copy function.
450         *
451         * Intended (at this stage) only for internal use, particularly by
452         * RT which needs to decapsulate RT packets */
453        int (*prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet,
454                        void *buffer, libtrace_rt_types_t rt_type, 
455                        uint32_t flags);
456       
457        /** Frees any resources allocated by the capture format module for a
458         * libtrace packet.
459         *
460         * @param The packet to be finalised
461         *       */
462        void (*fin_packet)(libtrace_packet_t *packet);
463
464        /** Write a libtrace packet to an output trace.
465         *
466         * @param libtrace      The output trace to write the packet to
467         * @param packet        The packet to be written out
468         * @return The number of bytes written, or -1 if an error occurs
469         */
470        int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet);
471        /** Returns the libtrace link type for a packet.
472         *
473         * @param packet        The packet to get the link type for
474         * @return The libtrace link type, or -1 if this link type is unknown
475         */ 
476        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
477
478        /** Returns the direction of a packet.
479         *
480         * @param packet        The packet to get the direction for
481         * @return The direction of the packet, or -1 if no direction tag is
482         * present or an error occurs
483         */ 
484        libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet);
485       
486        /** Sets the direction of a packet.
487         *
488         * @param packet        The packet to set the direction for
489         * @param direction     The direction to assign to the packet
490         * @return The updated direction for the packet, or -1 if an error
491         * occurs
492         *
493         * @note Some capture formats do not feature direction tagging, so it
494         * will not make sense to implement a set_direction function for them.
495         */ 
496        libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction);
497       
498        /** Returns the timestamp for a packet in the ERF timestamp format.
499         *
500         * @param packet        The packet to get the timestamp from
501         * @return The 64-bit ERF timestamp
502         *
503         * @note Each format must implement at least one of the four "get
504         * timestamp" functions.
505         *
506         * If not implemented, libtrace will convert the result of one of the
507         * other timestamp functions into the appropriate format instead.
508         * This means each capture format only needs to implement the most
509         * sensible of the four and let libtrace handle any conversions.
510         *
511         */
512        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
513
514        /** Returns the timestamp for a packet in the timeval format
515         *
516         * @param packet        The packet to get the timestamp from
517         * @return The timestamp from the packet as a timeval
518         *
519         * @note Each format must implement at least one of the four "get
520         * timestamp" functions.
521         *
522         * If not implemented, libtrace will convert the result of one of the
523         * other timestamp functions into the appropriate format instead.
524         * This means each capture format only needs to implement the most
525         * sensible of the four and let libtrace handle any conversions.
526         */
527        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
528       
529        /** Returns the timestamp for a packet in the timespec format.
530         *
531         * @param packet        The packet to get the timestamp from
532         * @return The timestamp from the packet as a timespec
533         *
534         * @note Each format must implement at least one of the four "get
535         * timestamp" functions.
536         *
537         * If not implemented, libtrace will convert the result of one of the
538         * other timestamp functions into the appropriate format instead.
539         * This means each capture format only needs to implement the most
540         * sensible of the four and let libtrace handle any conversions.
541         */
542        struct timespec (*get_timespec)(const libtrace_packet_t *packet);
543       
544        /** Returns the timestamp for a packet in floating point seconds.
545         *
546         * @param packet        The packet to get the timestamp from
547         * @return The timestamp from the packet as a floating point number of
548         * seconds since 1970-01-01 00:00:00 UTC
549         *
550         * @note Each format must implement at least one of the four "get
551         * timestamp" functions.
552         *
553         * If not implemented, libtrace will convert the result of one of the
554         * other timestamp functions into the appropriate format instead.
555         * This means each capture format only needs to implement the most
556         * sensible of the four and let libtrace handle any conversions.
557         */
558        double (*get_seconds)(const libtrace_packet_t *packet);
559       
560        /** Moves the read pointer to a certain ERF timestamp within an input
561         * trace file.
562         *
563         * @param trace         The input trace to seek within
564         * @param timestamp     The timestamp to seek to, as an ERF timestamp
565         *
566         * @return 0 on success, -1 on failure.
567         *
568         * The next packet read from this trace will now be the first packet
569         * to have a timestamp equal to or greater than the provided timestamp.
570         *
571         * @note Each format that supports seeking must implement at least one
572         * of the seek functions.
573         *
574         * If not implemented, libtrace will convert the timestamp into the
575         * appropriate format to use a seek function that has been implemented.
576         * This means each capture format only needs to implement the seek
577         * function that matches the native timestamp format for that capture.
578         *
579         */
580        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
581        /** Moves the read pointer to a certain timestamp represented using a
582         * timeval within an input trace file.
583         *
584         * @param trace         The input trace to seek within
585         * @param timestamp     The timestamp to seek to, as a timeval
586         *
587         * @return 0 on success, -1 on failure.
588         *
589         * The next packet read from this trace will now be the first packet
590         * to have a timestamp equal to or greater than the provided timestamp.
591         *
592         * @note Each format that supports seeking must implement at least one
593         * of the seek functions.
594         *
595         * If not implemented, libtrace will convert the timestamp into the
596         * appropriate format to use a seek function that has been implemented.
597         * This means each capture format only needs to implement the seek
598         * function that matches the native timestamp format for that capture.
599         *
600         */
601        int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
602       
603        /** Moves the read pointer to a certain timestamp represented using
604         * floating point seconds within an input trace file.
605         *
606         * @param trace         The input trace to seek within
607         * @param timestamp     The timestamp to seek to, as floating point
608         *                      seconds since 1970-01-01 00:00:00 UTC
609         *
610         * @return 0 on success, -1 on failure.
611         *
612         * The next packet read from this trace will now be the first packet
613         * to have a timestamp equal to or greater than the provided timestamp.
614         *
615         * @note Each format that supports seeking must implement at least one
616         * of the seek functions.
617         *
618         * If not implemented, libtrace will convert the timestamp into the
619         * appropriate format to use a seek function that has been implemented.
620         * This means each capture format only needs to implement the seek
621         * function that matches the native timestamp format for that capture.
622         *
623         */
624        int (*seek_seconds)(libtrace_t *trace, double seconds);
625       
626        /** Returns the payload length of the captured packet record.
627         *
628         * @param packet        The packet to get the capture length from
629         * @return The capture length for the packet, or -1 if an error occurs
630         *
631         * Capture length is the current size of the packet record itself,
632         * following any truncation that may have occurred during the capture
633         * process. This length does not include the capture format framing
634         * header.
635         */
636        int (*get_capture_length)(const libtrace_packet_t *packet);
637
638        /** Returns the original length of the packet as it was on the wire.
639         *
640         * @param packet        The packet to get the wire length from
641         * @return The length of the packet on the wire at the time of capture,
642         * or -1 if an error occurs
643         *
644         * Wire length is the original size of the packet prior to any
645         * truncation that may have occurred as part of the capture process.
646         * This length does not include the capture format framing header.
647         */
648        int (*get_wire_length)(const libtrace_packet_t *packet);
649       
650        /** Returns the length of the capture format framing header
651         *
652         * @param packet        The packet to get the framing length from
653         * @return The length of the framing header, or -1 if an error occurs
654         *
655         * The framing header is the extra metadata that the capture process
656         * records about a packet.  The framing length does not include any
657         * of the packet payload itself. The total size of the packet record
658         * can be calculated be adding this value with the capture length.
659         */
660        int (*get_framing_length)(const libtrace_packet_t *packet);
661
662        /** Sets the capture length for a packet.
663         *
664         * @param packet        The packet to adjust the capture length for.
665         * @param size          The new capture length
666         * @return The new capture length of the packet, or -1 if an error
667         * occurs
668         *
669         * @note This function should only reduce the capture length. If the
670         * provided length is larger than the current capture length, -1 should
671         * be returned.
672         */
673        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
674        /** Returns the number of packets observed by an input trace.
675         *
676         * @param trace         The input trace to get the packet count for
677         * @return The number of packets observed by an input trace, or
678         * UINT64_MAX if the number is unknown
679         *
680         * This count includes packets that have been filtered and dropped.
681         */
682        uint64_t (*get_received_packets)(libtrace_t *trace);
683
684        /** Returns the number of packets filtered by an input trace.
685         *
686         * @param trace         The input trace to get the filtered count for
687         * @return The number of packets filtered by the input trace, or
688         * UINT64_MAX if the number is unknown
689         *
690         */
691        uint64_t (*get_filtered_packets)(libtrace_t *trace);
692       
693        /** Returns the number of packets dropped by an input trace.
694         *
695         * @param trace         The input trace to get the dropped count for
696         * @return The number of packets dropped by the input trace, or
697         * UINT64_MAX if the number is unknown
698         *
699         */
700        uint64_t (*get_dropped_packets)(libtrace_t *trace);
701       
702        /** Returns the number of packets captured and returned by an input
703         * trace.
704         *
705         * @param trace         The input trace to get the capture count for
706         * @return The number of packets returned to the libtrace user, or
707         * UINT64_MAX if the number is unknown
708         *
709         * This is the number of packets that have been successfully returned
710         * to the libtrace user via the read_packet() function.
711         *
712         */
713        uint64_t (*get_captured_packets)(libtrace_t *trace);
714       
715        /** Returns the file descriptor used by the input trace.
716         *
717         * @param trace         The input trace to get the file descriptor for
718         * @return The file descriptor used by the input trace to read packets
719         *
720         */
721        int (*get_fd)(const libtrace_t *trace);
722       
723        /** Returns the next libtrace event for the input trace.
724         *
725         * @param trace         The input trace to get the next event from
726         * @param packet        A libtrace packet to read a packet into
727         * @return A libtrace event describing the event that occured
728         *
729         * The event API allows for non-blocking reading of packets from an
730         * input trace. If a packet is available and ready to be read, a packet
731         * event should be returned. Otherwise a sleep or fd event should be
732         * returned to indicate that the caller needs to wait. If the input
733         * trace has an error or reaches EOF, a terminate event should be
734         * returned.
735         */
736        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
737
738        /** Prints some useful help information to standard output. */
739        void (*help)(void);
740
741        /** Next pointer, should always be NULL - used by the format module
742         * manager. */
743        struct libtrace_format_t *next;
744};
745
746/** The list of registered capture formats */
747extern struct libtrace_format_t *form;
748
749/** Registers a new capture format module.
750 *
751 * @param format        The format module to be registered
752 */
753void register_format(struct libtrace_format_t *format);
754
755/** Converts a PCAP DLT into a libtrace link type.
756 *
757 * @param linktype      The PCAP DLT to be converted
758 * @return The libtrace link type that is equivalent to the provided DLT, or
759 * -1 if the DLT is unknown
760 */
761libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype);
762
763/** Converts a PCAP DLT into an RT protocol type.
764 *
765 * @param linktype      The PCAP DLT to be converted
766 * @return The RT type that is equivalent to the provided DLT
767 */
768libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype);
769
770/** Converts a libtrace link type into a PCAP linktype.
771 *
772 * @param type          The libtrace link type to be converted
773 * @return The PCAP linktype that is equivalent to the provided libtrace link
774 * type, or -1 if the link type is unknown
775 */
776libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type);
777
778/** Converts a libtrace link type into a PCAP DLT.
779 *
780 * @param type          The libtrace link type to be converted
781 * @return The PCAP DLT that is equivalent to the provided libtrace link
782 * type, or -1 if the link type is unknown
783 */
784libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type);
785
786/** Converts an RT protocol type into a PCAP DLT.
787 *
788 * @param rt_type       The RT type to be converted
789 * @return The PCAP DLT that is equivalent to the provided RT protocol
790 */
791libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type);
792
793/** Converts an ERF type into a libtrace link type.
794 *
795 * @param erf           The ERF type to be converted
796 * @return The libtrace link type that is equivalent to the provided ERF type,
797 * or -1 if the ERF type is unknown
798 */
799libtrace_linktype_t erf_type_to_libtrace(uint8_t erf);
800
801/** Converts a libtrace link type into an ERF type.
802 *
803 * @param linktype      The libtrace link type to be converted
804 * @return The ERF type that is equivalent to the provided libtrace link type,
805 * or -1 if the link type cannot be matched to an ERF type.
806 */
807uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype);
808
809/** Converts an ARPHRD type into a libtrace link type.
810 *
811 * @param arphrd        The ARPHRD type to be converted
812 * @return The libtrace link type that is equivalent to the provided ARPHRD
813 * type, or -1 if the ARPHRD type is unknown
814 */
815libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd);
816
817/** Converts a libtrace link type into an ARPHRD type.
818 *
819 * @param type          The libtrace link type to be converted
820 * @return The ARPHRD type that is equivalent to the provided libtrace link
821 * type, or -1 if the link type cannot be matched to an ARPHRD type
822 */
823unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type);
824
825/** Converts a libtrace packet to the Linux SLL type.
826 *
827 * @param packet        The packet to be promoted
828 *
829 * @note This will involve memcpy() so use sparingly.
830 *
831 * This function prepends a Linux SLL header to a packet so that we can store
832 * direction tagging information.
833 */
834void promote_packet(libtrace_packet_t *packet);
835
836/** Attempts to demote a packet by removing the first header.
837 *
838 * @param packet        The packet to be demoted
839 * @return True if the packet was demoted, false otherwise.
840 *
841 * Essentially the opposite of promote_packet, except that it will also remove
842 * an ATM header as well as Linux SLL.
843 *
844 */
845bool demote_packet(libtrace_packet_t *packet);
846
847/** Returns a pointer to the header following a Linux SLL header.
848 *
849 * @param link          A pointer to the Linux SLL header to be skipped
850 * @param[out] type     The ethertype of the next header
851 * @param[in,out] remaining     Updated with the number of captured bytes
852 *                              remaining
853 * @return A pointer to the header following the Linux SLL header, or NULL if
854 * no subsequent header is present.
855 *
856 * Remaining must point to the number of bytes captured from the Linux SLL
857 * header and beyond.  It will be decremented by the number of bytes skipped
858 * to find the payload.
859 *
860 * If the Linux SLL header is complete but there are zero bytes of payload
861 * after the end of the header, a pointer to where the payload would be is
862 * returned and remaining will be set to zero. If the Linux SLL header is
863 * incomplete (truncated), then NULL is returned and remaining will be set to
864 * 0. Therefore, it is very important to check the value of remaining after
865 * calling this function.
866 */     
867void *trace_get_payload_from_linux_sll(const void *link, uint16_t *type, 
868                uint32_t *remaining);
869
870/** Returns a pointer to the header following an ATM header.
871 *
872 * @param link          A pointer to the ATM header to be skipped
873 * @param[out] type     The ethertype of the next header
874 * @param[in,out] remaining     Updated with the number of captured bytes
875 *                              remaining
876 * @return A pointer to the header following the ATM header, or NULL if
877 * no subsequent header is present.
878 *
879 * Remaining must point to the number of bytes captured from the ATM header
880 * and beyond.  It will be decremented by the number of bytes skipped to find
881 * the payload.
882 *
883 * If the ATM header is complete but there are zero bytes of payload
884 * after the end of the header, a pointer to where the payload would be is
885 * returned and remaining will be set to zero. If the ATM header is
886 * incomplete (truncated), then NULL is returned and remaining will be set to
887 * 0. Therefore, it is very important to check the value of remaining after
888 * calling this function.
889 */     
890DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type, 
891                uint32_t *remaining);
892
893/** Byteswaps a 64-bit value.
894 *
895 * @param num           The value to be byteswapped.
896 * @return The byteswapped 64-bit number
897 *
898 */
899uint64_t byteswap64(uint64_t num);
900
901/** Byteswaps a 32-bit value.
902 *
903 * @param num           The value to be byteswapped.
904 * @return The byteswapped 32-bit number
905 *
906 */
907uint32_t byteswap32(uint32_t num);
908
909/** Byteswaps a 16-bit value.
910 *
911 * @param num           The value to be byteswapped.
912 * @return The byteswapped 16-bit number
913 *
914 */
915uint16_t byteswap16(uint16_t num);
916
917/** @name Byte ordering
918 * Macros that define how to convert a value into a particular byte-order
919 *
920 * @{
921 */
922#if BYTE_ORDER == BIG_ENDIAN
923#define bswap_host_to_be64(num) ((uint64_t)(num))
924#define bswap_host_to_le64(num) byteswap64(num)
925#define bswap_host_to_be32(num) ((uint32_t)(num))
926#define bswap_host_to_le32(num) byteswap32(num)
927#define bswap_host_to_be16(num) ((uint16_t)(num))
928#define bswap_host_to_le16(num) byteswap16(num)
929
930#define bswap_be_to_host64(num) ((uint64_t)(num))
931#define bswap_le_to_host64(num) byteswap64(num)
932#define bswap_be_to_host32(num) ((uint32_t)(num))
933#define bswap_le_to_host32(num) byteswap32(num)
934#define bswap_be_to_host16(num) ((uint16_t)(num))
935#define bswap_le_to_host16(num) byteswap16(num)
936
937/* We use ntoh*() here, because the compiler may
938 * attempt to optimise it
939 */
940#elif BYTE_ORDER == LITTLE_ENDIAN
941#define bswap_host_to_be64(num) (byteswap64(num))
942#define bswap_host_to_le64(num) ((uint64_t)(num))
943#define bswap_host_to_be32(num) (htonl(num))
944#define bswap_host_to_le32(num) ((uint32_t)(num))
945#define bswap_host_to_be16(num) (htons(num))
946#define bswap_host_to_le16(num) ((uint16_t)(num))
947
948#define bswap_be_to_host64(num) (byteswap64(num))
949#define bswap_le_to_host64(num) ((uint64_t)(num))
950#define bswap_be_to_host32(num) (ntohl(num))
951#define bswap_le_to_host32(num) ((uint32_t)(num))
952#define bswap_be_to_host16(num) (ntohs(num))
953#define bswap_le_to_host16(num) ((uint16_t)(num))
954
955#else
956#error "Unknown byte order"
957#endif
958/** @} */
959
960#ifdef HAVE_BPF
961/* A type encapsulating a bpf filter
962 * This type covers the compiled bpf filter, as well as the original filter
963 * string
964 *
965 */
966
967/** Internal representation of a BPF filter */
968struct libtrace_filter_t {
969        struct bpf_program filter;      /**< The BPF program itself */
970        char * filterstring;            /**< The filter string */
971        int flag;                       /**< Indicates if the filter is valid */
972};
973#else
974/** BPF not supported by this system, but we still need to define a structure
975 * for the filter */
976struct libtrace_filter_t {};
977#endif
978
979/** Local definition of a PCAP header */
980typedef struct libtrace_pcapfile_pkt_hdr_t {
981        uint32_t ts_sec;        /* Seconds portion of the timestamp */
982        uint32_t ts_usec;       /* Microseconds portion of the timestamp */
983        uint32_t caplen;        /* Capture length of the packet */
984        uint32_t wirelen;       /* The wire length of the packet */
985} libtrace_pcapfile_pkt_hdr_t;
986
987#ifdef HAVE_DAG
988/** Constructor for the DAG format module */
989void dag_constructor(void);
990#endif
991/** Constructor for the ERF format module */
992void erf_constructor(void);
993/** Constructor for the TSH format module */
994void tsh_constructor(void);
995/** Constructor for the Legacy DAG format module */
996void legacy_constructor(void);
997/** Constructor for the Linux Native format module */
998void linuxnative_constructor(void);
999/** Constructor for the PCAP format module */
1000void pcap_constructor(void);
1001/** Constructor for the PCAP File format module */
1002void pcapfile_constructor(void);
1003/** Constructor for the RT format module */
1004void rt_constructor(void);
1005/** Constructor for the DUCK format module */
1006void duck_constructor(void);
1007/** Constructor for the ATM Header format module */
1008void atmhdr_constructor(void);
1009#ifdef HAVE_BPF
1010/** Constructor for the BPF format module */
1011void bpf_constructor(void);
1012#endif
1013
1014/** Extracts the RadioTap flags from a wireless link header
1015 *
1016 * @param link          A pointer to the wireless link header
1017 * @param linktype      The link type of the wireless header
1018 * @param[out] flags    Space to store the extracted flags
1019 * @return True if libtrace was able to extract flags from the link header,
1020 * false otherwise.
1021 *
1022 * This function has been left internal because it is not portable across
1023 * drivers.
1024 */
1025bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags);
1026#define TRACE_RADIOTAP_F_FCS 0x10
1027       
1028#ifdef __cplusplus
1029}
1030#endif
1031
1032#endif /* LIBTRACE_INT_H */
Note: See TracBrowser for help on using the repository browser.