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.
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/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @author Christian Grothoff
25 * Library for tokenizing a message stream
27 * @defgroup server Server library
28 * Library for tokenizing a message stream
30 * @see [Documentation](https://gnunet.org/mst)
35 #ifndef GNUNET_MST_LIB_H
36 #define GNUNET_MST_LIB_H
41 #if 0 /* keep Emacsens' auto-indent happy */
46 #include "gnunet_common.h"
50 * Handle to a message stream tokenizer.
52 struct GNUNET_MessageStreamTokenizer;
56 * Functions with this signature are called whenever a
57 * complete message is received by the tokenizer.
59 * Do not call #GNUNET_mst_destroy from within
60 * the scope of this callback.
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
69 (*GNUNET_MessageTokenizerCallback) (void *cls,
70 const struct GNUNET_MessageHeader *message);
74 * Create a message stream tokenizer.
76 * @param cb function to call on completed messages
77 * @param cb_cls closure for @a cb
78 * @return handle to tokenizer
80 struct GNUNET_MessageStreamTokenizer *
81 GNUNET_MST_create (GNUNET_MessageTokenizerCallback cb,
86 * Add incoming data to the receive buffer and call the
87 * callback for all complete messages.
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
100 GNUNET_MST_from_buffer (struct GNUNET_MessageStreamTokenizer *mst,
108 * Add incoming data to the receive buffer and call the
109 * callback for all complete messages.
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
122 GNUNET_MST_read (struct GNUNET_MessageStreamTokenizer *mst,
123 struct GNUNET_NETWORK_Handle *sock,
129 * Obtain the next message from the @a mst, assuming that
130 * there are more unprocessed messages in the internal buffer
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
140 GNUNET_MST_next (struct GNUNET_MessageStreamTokenizer *mst,
145 * Destroys a tokenizer.
147 * @param mst tokenizer to destroy
150 GNUNET_MST_destroy (struct GNUNET_MessageStreamTokenizer *mst);
153 #if 0 /* keep Emacsens' auto-indent happy */
162 /** @} */ /* end of group server */
164 /* end of gnunet_mst_lib.h */