Changeset 81c0b9e


Ignore:
Timestamp:
02/08/10 13:20:06 (11 years ago)
Author:
Shane Alcock <salcock@…>
Branches:
4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, getfragoff, help, libtrace4, master, ndag_format, pfring, rc-4.0.1, rc-4.0.2, rc-4.0.3, rc-4.0.4, ringdecrementfix, ringperformance, ringtimestampfixes
Children:
5511c14
Parents:
8106a45
Message:
  • Documented and licensed the last two header files in lib/
Location:
lib
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • lib/rt_protocol.h

    rb778083 r81c0b9e  
     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
    134#ifndef _RT_PROTOCOL_H
    235#define _RT_PROTOCOL_H
     
    538#include <time.h>
    639
    7 #define CAPTURE_PORT 3434
     40/** @file
     41 *
     42 * @brief Header file containing definitions specific to the RT protocol that
     43 * can be used to transport captured packets over a network connection.
     44 *
     45 */
     46
     47/** Default port for RT clients */
    848#define COLLECTOR_PORT 3435
    949
     50/** Maximum size for the RT header */
    1051#define RT_MAX_HDR_SIZE 256
     52/** Maximum sequence number for the RT protocol */
    1153#define MAX_SEQUENCE 2147483647
    1254
     
    3577 */
    3678
     79/** Fifo statistics reported by the RT_STATUS message */
    3780typedef struct fifo_info {
    38         uint64_t in;
    39         uint64_t out;
    40         uint64_t ack;
    41         uint64_t length;
    42         uint64_t used;
     81        uint64_t in;            /**< The offset for the fifo write pointer */
     82        uint64_t out;           /**< The offset for the fifo read pointer */
     83        uint64_t ack;           /**< The offset for the fifo ACK pointer */
     84        uint64_t length;        /**< The total length of the fifo */
     85        uint64_t used;          /**< The amount of fifo space in use */
    4386} fifo_info_t;
    4487
    4588/** RT packet header */
    4689typedef struct rt_header {
    47         libtrace_rt_types_t type;
    48         uint16_t length;
     90        /** The type of RT packet */
     91        libtrace_rt_types_t type;       
     92        /** The length of the packet (not including the RT header */
     93        uint16_t length;               
     94        /** The sequence number of the packet */
    4995        uint32_t sequence;
    5096} rt_header_t;
    5197
    5298/* TODO: Reorganise this struct once more hello info is added */
     99
    53100/** RT Hello packet sub-header */
    54101typedef struct rt_hello {
    55         uint8_t reliable;
     102        /** Indicates whether the sender is acting in a reliable fashion,
     103         *  i.e. expecting acknowledgements */
     104        uint8_t reliable;       
    56105} rt_hello_t;
    57106
     
    64113/** RT Ack sub-header */
    65114typedef struct rt_ack {
     115        /** The sequence number of the last received RT packet */
    66116        uint32_t sequence;
    67117} rt_ack_t;
     
    69119/** RT Status sub-header */
    70120typedef struct rt_status {
     121        /** Statistics describing the current status of the sender fifo */
    71122        fifo_info_t fifo_status;
    72123} rt_status_t;
     
    90141#endif
    91142
    92 /** Connection denied reasons */
     143/** Reasons that an RT connection may be denied */
    93144enum rt_conn_denied_t {
    94  RT_DENY_WRAPPER        =1,
    95  RT_DENY_FULL           =2,
    96  RT_DENY_AUTH           =3
     145        /** The client failed a TCP wrapper check */
     146        RT_DENY_WRAPPER         =1,
     147        /** The server has reached the maximum number of client connections */
     148        RT_DENY_FULL            =2,
     149        /** Client failed to correctly authenticate */
     150        RT_DENY_AUTH            =3
    97151};
    98152
    99153/** RT Denied Connection sub-header */
    100154typedef struct rt_deny_conn {
     155        /** The reason that the connection was denied */
    101156        enum rt_conn_denied_t reason;
    102157} rt_deny_conn_t;
     
    126181#endif
    127182
     183/** RT meta-data sub-header */
    128184typedef struct rt_metadata {
     185        /** Length of the label string that follows the header */
    129186        uint32_t label_len;
     187        /** Length of the value string that follows the header */
    130188        uint32_t value_len;
    131189} rt_metadata_t ;
    132190
    133191/** Specifications of duck structures - duck2_4 and duck2_5 match Endace's
    134  * duck_inf and duckinf_t respectively */
     192 * duck_inf and duckinf_t respectively. Unfortunately, Endace don't exactly
     193 * make it clear what each value within the duck structure actually means.
     194 * Some are self-explanatory but I have no idea about the others so our own
     195 * documentation is a bit weak as a result */
    135196
    136197/** DAG 2.4 DUCK */
  • lib/wandio.h

    r15e9390 r81c0b9e  
     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
    134#ifndef IO_H
    235#define IO_H 1
     
    437#include <stdio.h>
    538
     39/** @file
     40 *
     41 * @brief Header file dealing with the Libtrace IO sub-system
     42 *
     43 * @author Perry Lorier
     44 * @author Shane Alcock
     45 *
     46 * @version $Id$
     47 */
     48
    649typedef struct io_t io_t;
    750typedef struct iow_t iow_t;
    851
     52/** Structure defining a supported compression method */
    953struct compression_type {
     54        /** Name of the compression method */
    1055        const char *name;
     56        /** Extension to add to the filename of files written using this
     57         *  method */
    1158        const char *ext;
     59        /** Internal type identifying the compression method */
    1260        int compress_flag;
    1361};
     62
     63/** The list of supported compression methods */
    1464extern struct compression_type compression_type[];
    1565
     66/** Structure defining a libtrace IO reader module */
    1667typedef struct {
     68        /** Module name */
    1769        const char *name;
     70
     71        /** Reads from the IO source into the provided buffer.
     72         *
     73         * @param io            The IO reader
     74         * @param buffer        The buffer to read into
     75         * @param len           The amount of space available in the buffer
     76         * @return The amount of bytes read, 0 if end of file is reached, -1
     77         * if an error occurs
     78         */
    1879        off_t (*read)(io_t *io, void *buffer, off_t len);
     80
     81        /** Reads from the IO source into the provided buffer but does not
     82         *  advance the read pointer.
     83         *
     84         * @param io            The IO reader
     85         * @param buffer        The buffer to read into
     86         * @param len           The amount of space available in the buffer
     87         * @return The amount of bytes read, 0 if end of file is reached, -1
     88         * if an error occurs
     89         */
    1990        off_t (*peek)(io_t *io, void *buffer, off_t len);
     91
     92        /** Returns the current offset of the read pointer for an IO source.
     93         *
     94         * @param io            The IO reader to get the read offset for
     95         * @return The offset of the read pointer, or -1 if an error occurs
     96         */
    2097        off_t (*tell)(io_t *io);
     98       
     99        /** Moves the read pointer for an IO source.
     100         *
     101         * @param io            The IO reader to move the read pointer for
     102         * @param offset        The new read pointer offset
     103         * @param whence        Where to start counting the new offset from.
     104         *                      whence can be one of three values: SEEK_SET,
     105         *                      SEEK_CUR and SEEK_END. See the lseek(2) manpage
     106         *                      for more details as to what these mean.
     107         * @return The value of the new read pointer, or -1 if an error occurs
     108         */
    21109        off_t (*seek)(io_t *io, off_t offset, int whence);
     110       
     111        /** Closes an IO reader. This function should free the IO reader.
     112         *
     113         * @param io            The IO reader to close
     114         */
    22115        void (*close)(io_t *io);
    23116} io_source_t;
    24117
     118/** Structure defining a libtrace IO writer module */
    25119typedef struct {
     120        /** The name of the module */
    26121        const char *name;
     122       
     123        /** Writes the contents of a buffer using an IO writer.
     124         *
     125         * @param iow           The IO writer to write the data with
     126         * @param buffer        The buffer to be written
     127         * @param len           The amount of writable data in the buffer
     128         * @return The amount of data written, or -1 if an error occurs
     129         */
    27130        off_t (*write)(iow_t *iow, const char *buffer, off_t len);
     131
     132        /** Closes an IO writer. This function should free the IO writer.
     133         *
     134         * @param iow           The IO writer to close
     135         */
    28136        void (*close)(iow_t *iow);
    29137} iow_source_t;
    30138
     139/** A libtrace IO reader */
    31140struct io_t {
     141        /** The IO module that is used by the reader */
    32142        io_source_t *source;
     143        /** Generic pointer to data required by the IO module */
    33144        void *data;
    34145};
    35146
     147/** A libtrace IO writer */
    36148struct iow_t {
     149        /** The IO module that is used by the writer */
    37150        iow_source_t *source;
     151        /** Generic pointer to data required by the IO module */
    38152        void *data;
    39153};
    40154
     155/** Enumeration of all supported compression methods */
    41156enum {
     157        /** No compression */
    42158        WANDIO_COMPRESS_NONE    = 0,
     159        /** Zlib compression */
    43160        WANDIO_COMPRESS_ZLIB    = 1,
     161        /** Bzip compression */
    44162        WANDIO_COMPRESS_BZ2     = 2,
     163        /** All supported methods - used as a bitmask */
    45164        WANDIO_COMPRESS_MASK    = 3
    46165};
    47166
     167/** @name IO open functions
     168 *
     169 * These functions deal with creating and initialising a new IO reader or
     170 * writer.
     171 *
     172 * @{
     173 */
    48174
    49175io_t *bz_open(io_t *parent);
     
    58184iow_t *stdio_wopen(const char *filename);
    59185
     186/* @} */
     187
     188/**
     189 * @name Libtrace IO API functions
     190 *
     191 * These are the functions that should be called by the format modules to open
     192 * and use files with the libtrace IO sub-system.
     193 *
     194 * @{ */
     195
     196/** Creates a new libtrace IO reader and opens the provided file for reading.
     197 *
     198 * @param filename      The name of the file to open
     199 * @return A pointer to a new libtrace IO reader, or NULL if an error occurs
     200 *
     201 * This function will attempt to detect the compression format used for the
     202 * given file (if any), provided that libtrace was built with the appropriate
     203 * libraries.
     204 */
    60205io_t *wandio_create(const char *filename);
     206
     207/** Returns the current offset of the read pointer for a libtrace IO reader.
     208 *
     209 * @param io            The IO reader to get the read offset for
     210 * @return The offset of the read pointer, or -1 if an error occurs
     211 */
    61212off_t wandio_tell(io_t *io);
     213
     214/** Changes the read pointer offset to the specified value for a libtrace IO
     215 * reader.
     216 *
     217 * @param io            The IO reader to adjust the read pointer for
     218 * @param offset        The new offset for the read pointer
     219 * @param whence        Indicates where to set the read pointer from. Can be
     220 *                      one of SEEK_SET, SEEK_CUR or SEEK_END.
     221 * @return The new value for the read pointer, or -1 if an error occurs
     222 *
     223 * The arguments for this function are the same as those for lseek(2). See the
     224 * lseek(2) manpage for more details.
     225 */
    62226off_t wandio_seek(io_t *io, off_t offset, int whence);
     227
     228/** Reads from a libtrace IO reader into the provided buffer.
     229 *
     230 * @param io            The IO reader to read from
     231 * @param buffer        The buffer to read into
     232 * @param len           The size of the buffer
     233 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
     234 */
    63235off_t wandio_read(io_t *io, void *buffer, off_t len);
     236
     237/** Reads from a libtrace IO reader into the provided buffer, but does not
     238 * update the read pointer.
     239 *
     240 * @param io            The IO reader to read from
     241 * @param buffer        The buffer to read into
     242 * @param len           The size of the buffer
     243 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
     244 */
    64245off_t wandio_peek(io_t *io, void *buffer, off_t len);
     246
     247/** Destroys a libtrace IO reader, closing the file and freeing the reader
     248 * structure.
     249 *
     250 * @param io            The IO reader to destroy
     251 */
    65252void wandio_destroy(io_t *io);
    66253
     254/** Creates a new libtrace IO writer and opens the provided file for writing.
     255 *
     256 * @param filename              The name of the file to open
     257 * @param compression_level     The compression level to use when writing
     258 * @param flags                 Flags to apply when opening the file, e.g.
     259 *                              O_CREATE
     260 * @return A pointer to the new libtrace IO writer, or NULL if an error occurs
     261 */
    67262iow_t *wandio_wcreate(const char *filename, int compression_level, int flags);
     263
     264/** Writes the contents of a buffer using a libtrace IO writer.
     265 *
     266 * @param iow           The IO writer to write the data with
     267 * @param buffer        The buffer to write out
     268 * @param len           The amount of writable data in the buffer
     269 * @return The amount of data written, or -1 if an error occurs
     270 */
    68271off_t wandio_wwrite(iow_t *iow, const void *buffer, off_t len);
     272
     273/** Destroys a libtrace IO writer, closing the file and freeing the writer
     274 * structure.
     275 *
     276 * @param iow           The IO writer to destroy
     277 */
    69278void wandio_wdestroy(iow_t *iow);
    70279
     280/** @} */
    71281#endif
Note: See TracChangeset for help on using the changeset viewer.