epan/stream.h

   1 /* stream.h
   2  *
   3  * Definititions for handling circuit-switched protocols
   4  * which are handled as streams, and don't have lengths
   5  * and IDs such as are required for reassemble.h
   6  *
   7  * $Id$
   8  *
   9  * Wireshark - Network traffic analyzer
  10  * By Gerald Combs <gerald@wireshark.org>
  11  * Copyright 1998 Gerald Combs
  12  *
  13  * This program is free software; you can redistribute it and/or
  14  * modify it under the terms of the GNU General Public License
  15  * as published by the Free Software Foundation; either version 2
  16  * of the License, or (at your option) any later version.
  17  *
  18  * This program 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 this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  26  */
  27
  28 #ifndef STREAM_H
  29 #define STREAM_H
  30
  31 #include <epan/tvbuff.h>
  32 #include <epan/reassemble.h>
  33 #include "ws_symbol_export.h"
  34
  35 struct _fragment_items;
  36
  37 /* A stream represents the concept of an arbitrary stream of data,
  38    divided up into frames for transmission, where the frames have
  39    little or no correspondence to the PDUs of the protocol being
  40    streamed, and those PDUs are just delineated by a magic number.
  41
  42    For example, we stream H.223 over IAX2. IAX2 has no concept of
  43    H.223 PDUs and just divides the H.223 stream into 160-byte
  44    frames. H.223 PDUs are delineated by two-byte magic numbers (which
  45    may, of course, straddle an IAX2 frame boundary).
  46
  47    Essentially we act as a wrapper to reassemble.h, by making up
  48    PDU ids and keeping some additional data on fragments to allow the
  49    PDUs to be defragmented again.
  50 */
  51
  52
  53 /* A stream_t represents a stream. There might be one or two streams
  54    in a circuit, depending on whether that circuit is mono- or bi-directional.
  55 */
  56 typedef struct stream stream_t;
  57
  58 /* Fragments in a PDU are represented using a stream_pdu_fragment_t,
  59    and placed in a linked-list with other fragments in the PDU.
  60
  61    (They're also placed in a hash so we can find them again later)
  62 */
  63 typedef struct stream_pdu_fragment stream_pdu_fragment_t;
  64
  65
  66
  67 struct circuit;
  68 struct conversation;
  69
  70 /* initialise a new stream. Call this when you first identify a distinct
  71  * stream. The circit pointer is just used as a key to look up the stream. */
  72 WS_DLL_PUBLIC stream_t *stream_new_circ ( const struct circuit *circuit, int p2p_dir );
  73 extern stream_t *stream_new_conv ( const struct conversation *conv, int p2p_dir );
  74
  75 /* retrieve a previously-created stream.
  76  *
  77  * Returns null if no matching stream was found.
  78  */
  79 WS_DLL_PUBLIC stream_t *find_stream_circ ( const struct circuit *circuit, int p2p_dir );
  80 extern stream_t *find_stream_conv ( const struct conversation *conv, int p2p_dir );
  81
  82
  83
  84 /* see if we've seen this fragment before.
  85
  86    The framenum and offset are just hash keys, so can be any values unique
  87    to this frame, but the idea is that you use the number of the frame being
  88    disassembled, and the byte-offset within that frame.
  89 */
  90 WS_DLL_PUBLIC stream_pdu_fragment_t *stream_find_frag( stream_t *stream, guint32 framenum, guint32 offset );
  91
  92 /* add a new fragment to the fragment tables for the stream. The framenum and
  93  * offset are keys allowing future access with stream_find_frag(), tvb is the
  94  * fragment to be added, and pinfo is the information for the frame containing
  95  * this fragment. more_frags should be set if this is the final fragment in the
  96  * PDU.
  97  *
  98  * * the fragment must be later in the stream than any previous fragment
  99  *   (ie, framenum.offset must be greater than those passed on the previous
 100  *   call)
 101  *
 102  * This essentially means that you can only add fragments on the first pass
 103  * through the stream.
 104  */
 105 WS_DLL_PUBLIC stream_pdu_fragment_t *stream_add_frag( stream_t *stream, guint32 framenum, guint32 offset,
 106                                         tvbuff_t *tvb, packet_info *pinfo, gboolean more_frags );
 107
 108 /* Get the length of a fragment previously found by stream_find_frag().
 109  */
 110 extern guint32 stream_get_frag_length( const stream_pdu_fragment_t *frag);
 111
 112 /* Get a handle on the top of the chain of fragment_datas underlying this PDU
 113  * frag can be any fragment within a PDU, and it will always return the head of
 114  * the chain
 115  *
 116  * Returns NULL until the last fragment is added.
 117  */
 118 extern fragment_head *stream_get_frag_data( const stream_pdu_fragment_t *frag);
 119
 120 /*
 121  * Process reassembled data; if this is the last fragment, put the fragment
 122  * information into the protocol tree, and construct a tvbuff with the
 123  * reassembled data, otherwise just put a "reassembled in" item into the
 124  * protocol tree.
 125  */
 126 WS_DLL_PUBLIC tvbuff_t *stream_process_reassembled(
 127     tvbuff_t *tvb, int offset, packet_info *pinfo,
 128     const char *name, const stream_pdu_fragment_t *frag,
 129     const struct _fragment_items *fit,
 130     gboolean *update_col_infop, proto_tree *tree);
 131
 132 /* Get the PDU number. PDUs are numbered from zero within a stream.
 133  * frag can be any fragment within a PDU.
 134  */
 135 extern guint32 stream_get_pdu_no( const stream_pdu_fragment_t *frag);
 136
 137 /* initialise the stream routines */
 138 void stream_init( void );
 139 void stream_cleanup( void );
 140
 141 #endif /* STREAM_H */