2 This file is part of GNUnet.
3 Copyright (C) 2009-2013, 2016 GNUnet e.V.
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.
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.
17 * @author Christian Grothoff
20 * Library for tokenizing a message stream
22 * @defgroup server Server library
23 * Library for tokenizing a message stream
25 * @see [Documentation](https://gnunet.org/mst)
30 #ifndef GNUNET_MST_LIB_H
31 #define GNUNET_MST_LIB_H
36 #if 0 /* keep Emacsens' auto-indent happy */
41 #include "gnunet_common.h"
45 * Handle to a message stream tokenizer.
47 struct GNUNET_MessageStreamTokenizer;
51 * Functions with this signature are called whenever a
52 * complete message is received by the tokenizer.
54 * Do not call #GNUNET_mst_destroy from within
55 * the scope of this callback.
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
64 (*GNUNET_MessageTokenizerCallback) (void *cls,
65 const struct GNUNET_MessageHeader *message);
69 * Create a message stream tokenizer.
71 * @param cb function to call on completed messages
72 * @param cb_cls closure for @a cb
73 * @return handle to tokenizer
75 struct GNUNET_MessageStreamTokenizer *
76 GNUNET_MST_create (GNUNET_MessageTokenizerCallback cb,
81 * Add incoming data to the receive buffer and call the
82 * callback for all complete messages.
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
95 GNUNET_MST_from_buffer (struct GNUNET_MessageStreamTokenizer *mst,
103 * Add incoming data to the receive buffer and call the
104 * callback for all complete messages.
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
117 GNUNET_MST_read (struct GNUNET_MessageStreamTokenizer *mst,
118 struct GNUNET_NETWORK_Handle *sock,
124 * Obtain the next message from the @a mst, assuming that
125 * there are more unprocessed messages in the internal buffer
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
135 GNUNET_MST_next (struct GNUNET_MessageStreamTokenizer *mst,
140 * Destroys a tokenizer.
142 * @param mst tokenizer to destroy
145 GNUNET_MST_destroy (struct GNUNET_MessageStreamTokenizer *mst);
148 #if 0 /* keep Emacsens' auto-indent happy */
157 /** @} */ /* end of group server */
159 /* end of gnunet_mst_lib.h */