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 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
  16 /**
  17  * @author Christian Grothoff
  18  *
  19  * @file
  20  * Library for tokenizing a message stream
  21
  22  * @defgroup server  Server library
  23  * Library for tokenizing a message stream
  24  *
  25  * @see [Documentation](https://gnunet.org/mst)
  26  *
  27  * @{
  28  */
  29
  30 #ifndef GNUNET_MST_LIB_H
  31 #define GNUNET_MST_LIB_H
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41 #include "gnunet_common.h"
  42
  43
  44 /**
  45  * Handle to a message stream tokenizer.
  46  */
  47 struct GNUNET_MessageStreamTokenizer;
  48
  49
  50 /**
  51  * Functions with this signature are called whenever a
  52  * complete message is received by the tokenizer.
  53  *
  54  * Do not call #GNUNET_mst_destroy from within
  55  * the scope of this callback.
  56  *
  57  * @param cls closure
  58  * @param message the actual message
  59  * @return #GNUNET_OK on success,
  60  *     #GNUNET_NO to stop further processing due to disconnect (no error)
  61  *     #GNUNET_SYSERR to stop further processing due to error
  62  */
  63 typedef int
  64 (*GNUNET_MessageTokenizerCallback) (void *cls,
  65                                     const struct GNUNET_MessageHeader *message);
  66
  67
  68 /**
  69  * Create a message stream tokenizer.
  70  *
  71  * @param cb function to call on completed messages
  72  * @param cb_cls closure for @a cb
  73  * @return handle to tokenizer
  74  */
  75 struct GNUNET_MessageStreamTokenizer *
  76 GNUNET_MST_create (GNUNET_MessageTokenizerCallback cb,
  77                    void *cb_cls);
  78
  79
  80 /**
  81  * Add incoming data to the receive buffer and call the
  82  * callback for all complete messages.
  83  *
  84  * @param mst tokenizer to use
  85  * @param buf input data to add
  86  * @param size number of bytes in @a buf
  87  * @param purge should any excess bytes in the buffer be discarded
  88  *       (i.e. for packet-based services like UDP)
  89  * @param one_shot only call callback once, keep rest of message in buffer
  90  * @return #GNUNET_OK if we are done processing (need more data)
  91  *         #GNUNET_NO if one_shot was set and we have another message ready
  92  *         #GNUNET_SYSERR if the data stream is corrupt
  93  */
  94 int
  95 GNUNET_MST_from_buffer (struct GNUNET_MessageStreamTokenizer *mst,
  96                         const char *buf,
  97                         size_t size,
  98                         int purge,
  99                         int one_shot);
 100
 101
 102 /**
 103  * Add incoming data to the receive buffer and call the
 104  * callback for all complete messages.
 105  *
 106  * @param mst tokenizer to use
 107  * @param buf input data to add
 108  * @param size number of bytes in @a buf
 109  * @param purge should any excess bytes in the buffer be discarded
 110  *       (i.e. for packet-based services like UDP)
 111  * @param one_shot only call callback once, keep rest of message in buffer
 112  * @return #GNUNET_OK if we are done processing (need more data)
 113  *         #GNUNET_NO if one_shot was set and we have another message ready
 114  *         #GNUNET_SYSERR if the data stream is corrupt
 115  */
 116 int
 117 GNUNET_MST_read (struct GNUNET_MessageStreamTokenizer *mst,
 118                  struct GNUNET_NETWORK_Handle *sock,
 119                  int purge,
 120                  int one_shot);
 121
 122
 123 /**
 124  * Obtain the next message from the @a mst, assuming that
 125  * there are more unprocessed messages in the internal buffer
 126  * of the @a mst.
 127  *
 128  * @param mst tokenizer to use
 129  * @param one_shot only call callback once, keep rest of message in buffer
 130  * @return #GNUNET_OK if we are done processing (need more data)
 131  *         #GNUNET_NO if one_shot was set and we have another message ready
 132  *         #GNUNET_SYSERR if the data stream is corrupt
 133  */
 134 int
 135 GNUNET_MST_next (struct GNUNET_MessageStreamTokenizer *mst,
 136                  int one_shot);
 137
 138
 139 /**
 140  * Destroys a tokenizer.
 141  *
 142  * @param mst tokenizer to destroy
 143  */
 144 void
 145 GNUNET_MST_destroy (struct GNUNET_MessageStreamTokenizer *mst);
 146
 147
 148 #if 0                           /* keep Emacsens' auto-indent happy */
 149 {
 150 #endif
 151 #ifdef __cplusplus
 152 }
 153 #endif
 154
 155 #endif
 156
 157 /** @} */  /* end of group server */
 158
 159 /* end of gnunet_mst_lib.h */