src/include/gnunet_mst_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2013, 2016 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Library for tokenizing a message stream
  26
  27  * @defgroup server  Server library
  28  * Library for tokenizing a message stream
  29  *
  30  * @see [Documentation](https://gnunet.org/mst)
  31  *
  32  * @{
  33  */
  34
  35 #ifndef GNUNET_MST_LIB_H
  36 #define GNUNET_MST_LIB_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 #include "gnunet_common.h"
  47
  48
  49 /**
  50  * Handle to a message stream tokenizer.
  51  */
  52 struct GNUNET_MessageStreamTokenizer;
  53
  54
  55 /**
  56  * Functions with this signature are called whenever a
  57  * complete message is received by the tokenizer.
  58  *
  59  * Do not call #GNUNET_mst_destroy from within
  60  * the scope of this callback.
  61  *
  62  * @param cls closure
  63  * @param message the actual message
  64  * @return #GNUNET_OK on success, #GNUNET_SYSERR to stop further processing
  65  */
  66 typedef int
  67 (*GNUNET_MessageTokenizerCallback) (void *cls,
  68                                     const struct GNUNET_MessageHeader *message);
  69
  70
  71 /**
  72  * Create a message stream tokenizer.
  73  *
  74  * @param cb function to call on completed messages
  75  * @param cb_cls closure for @a cb
  76  * @return handle to tokenizer
  77  */
  78 struct GNUNET_MessageStreamTokenizer *
  79 GNUNET_MST_create (GNUNET_MessageTokenizerCallback cb,
  80                    void *cb_cls);
  81
  82
  83 /**
  84  * Add incoming data to the receive buffer and call the
  85  * callback for all complete messages.
  86  *
  87  * @param mst tokenizer to use
  88  * @param buf input data to add
  89  * @param size number of bytes in @a buf
  90  * @param purge should any excess bytes in the buffer be discarded
  91  *       (i.e. for packet-based services like UDP)
  92  * @param one_shot only call callback once, keep rest of message in buffer
  93  * @return #GNUNET_OK if we are done processing (need more data)
  94  *         #GNUNET_NO if one_shot was set and we have another message ready
  95  *         #GNUNET_SYSERR if the data stream is corrupt
  96  */
  97 int
  98 GNUNET_MST_from_buffer (struct GNUNET_MessageStreamTokenizer *mst,
  99                         const char *buf,
 100                         size_t size,
 101                         int purge,
 102                         int one_shot);
 103
 104
 105 /**
 106  * Add incoming data to the receive buffer and call the
 107  * callback for all complete messages.
 108  *
 109  * @param mst tokenizer to use
 110  * @param buf input data to add
 111  * @param size number of bytes in @a buf
 112  * @param purge should any excess bytes in the buffer be discarded
 113  *       (i.e. for packet-based services like UDP)
 114  * @param one_shot only call callback once, keep rest of message in buffer
 115  * @return #GNUNET_OK if we are done processing (need more data)
 116  *         #GNUNET_NO if one_shot was set and we have another message ready
 117  *         #GNUNET_SYSERR if the data stream is corrupt
 118  */
 119 int
 120 GNUNET_MST_read (struct GNUNET_MessageStreamTokenizer *mst,
 121                  struct GNUNET_NETWORK_Handle *sock,
 122                  int purge,
 123                  int one_shot);
 124
 125
 126 /**
 127  * Obtain the next message from the @a mst, assuming that
 128  * there are more unprocessed messages in the internal buffer
 129  * of the @a mst.
 130  *
 131  * @param mst tokenizer to use
 132  * @param one_shot only call callback once, keep rest of message in buffer
 133  * @return #GNUNET_OK if we are done processing (need more data)
 134  *         #GNUNET_NO if one_shot was set and we have another message ready
 135  *         #GNUNET_SYSERR if the data stream is corrupt
 136  */
 137 int
 138 GNUNET_MST_next (struct GNUNET_MessageStreamTokenizer *mst,
 139                  int one_shot);
 140
 141
 142 /**
 143  * Destroys a tokenizer.
 144  *
 145  * @param mst tokenizer to destroy
 146  */
 147 void
 148 GNUNET_MST_destroy (struct GNUNET_MessageStreamTokenizer *mst);
 149
 150
 151 #if 0                           /* keep Emacsens' auto-indent happy */
 152 {
 153 #endif
 154 #ifdef __cplusplus
 155 }
 156 #endif
 157
 158 #endif
 159
 160 /** @} */  /* end of group server */
 161
 162 /* end of gnunet_mst_lib.h */