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      SPDX-License-Identifier: AGPL3.0-or-later
  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,
  65  *     #GNUNET_NO to stop further processing due to disconnect (no error)
  66  *     #GNUNET_SYSERR to stop further processing due to error
  67  */
  68 typedef int
  69 (*GNUNET_MessageTokenizerCallback) (void *cls,
  70                                     const struct GNUNET_MessageHeader *message);
  71
  72
  73 /**
  74  * Create a message stream tokenizer.
  75  *
  76  * @param cb function to call on completed messages
  77  * @param cb_cls closure for @a cb
  78  * @return handle to tokenizer
  79  */
  80 struct GNUNET_MessageStreamTokenizer *
  81 GNUNET_MST_create (GNUNET_MessageTokenizerCallback cb,
  82                    void *cb_cls);
  83
  84
  85 /**
  86  * Add incoming data to the receive buffer and call the
  87  * callback for all complete messages.
  88  *
  89  * @param mst tokenizer to use
  90  * @param buf input data to add
  91  * @param size number of bytes in @a buf
  92  * @param purge should any excess bytes in the buffer be discarded
  93  *       (i.e. for packet-based services like UDP)
  94  * @param one_shot only call callback once, keep rest of message in buffer
  95  * @return #GNUNET_OK if we are done processing (need more data)
  96  *         #GNUNET_NO if one_shot was set and we have another message ready
  97  *         #GNUNET_SYSERR if the data stream is corrupt
  98  */
  99 int
 100 GNUNET_MST_from_buffer (struct GNUNET_MessageStreamTokenizer *mst,
 101                         const char *buf,
 102                         size_t size,
 103                         int purge,
 104                         int one_shot);
 105
 106
 107 /**
 108  * Add incoming data to the receive buffer and call the
 109  * callback for all complete messages.
 110  *
 111  * @param mst tokenizer to use
 112  * @param buf input data to add
 113  * @param size number of bytes in @a buf
 114  * @param purge should any excess bytes in the buffer be discarded
 115  *       (i.e. for packet-based services like UDP)
 116  * @param one_shot only call callback once, keep rest of message in buffer
 117  * @return #GNUNET_OK if we are done processing (need more data)
 118  *         #GNUNET_NO if one_shot was set and we have another message ready
 119  *         #GNUNET_SYSERR if the data stream is corrupt
 120  */
 121 int
 122 GNUNET_MST_read (struct GNUNET_MessageStreamTokenizer *mst,
 123                  struct GNUNET_NETWORK_Handle *sock,
 124                  int purge,
 125                  int one_shot);
 126
 127
 128 /**
 129  * Obtain the next message from the @a mst, assuming that
 130  * there are more unprocessed messages in the internal buffer
 131  * of the @a mst.
 132  *
 133  * @param mst tokenizer to use
 134  * @param one_shot only call callback once, keep rest of message in buffer
 135  * @return #GNUNET_OK if we are done processing (need more data)
 136  *         #GNUNET_NO if one_shot was set and we have another message ready
 137  *         #GNUNET_SYSERR if the data stream is corrupt
 138  */
 139 int
 140 GNUNET_MST_next (struct GNUNET_MessageStreamTokenizer *mst,
 141                  int one_shot);
 142
 143
 144 /**
 145  * Destroys a tokenizer.
 146  *
 147  * @param mst tokenizer to destroy
 148  */
 149 void
 150 GNUNET_MST_destroy (struct GNUNET_MessageStreamTokenizer *mst);
 151
 152
 153 #if 0                           /* keep Emacsens' auto-indent happy */
 154 {
 155 #endif
 156 #ifdef __cplusplus
 157 }
 158 #endif
 159
 160 #endif
 161
 162 /** @} */  /* end of group server */
 163
 164 /* end of gnunet_mst_lib.h */