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