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 it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @author Christian Grothoff
  21  *
  22  * @file
  23  * Library for tokenizing a message stream
  24
  25  * @defgroup server  Server library
  26  * Library for tokenizing a message stream
  27  *
  28  * @see [Documentation](https://gnunet.org/mst)
  29  *
  30  * @{
  31  */
  32
  33 #ifndef GNUNET_MST_LIB_H
  34 #define GNUNET_MST_LIB_H
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #if 0                           /* keep Emacsens' auto-indent happy */
  40 }
  41 #endif
  42 #endif
  43
  44 #include "gnunet_common.h"
  45
  46
  47 /**
  48  * Handle to a message stream tokenizer.
  49  */
  50 struct GNUNET_MessageStreamTokenizer;
  51
  52
  53 /**
  54  * Functions with this signature are called whenever a
  55  * complete message is received by the tokenizer.
  56  *
  57  * Do not call #GNUNET_mst_destroy from within
  58  * the scope of this callback.
  59  *
  60  * @param cls closure
  61  * @param message the actual message
  62  * @return #GNUNET_OK on success,
  63  *     #GNUNET_NO to stop further processing due to disconnect (no error)
  64  *     #GNUNET_SYSERR to stop further processing due to error
  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 */