2 This file is part of GNUnet.
3 Copyright (C) 2013 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/>.
20 * @author Gabor X Toth
21 * @author Christian Grothoff
26 * @defgroup psyc-util-slicer PSYC Utilities library: Slicer
27 * Try-and-slice processing of PSYC method names and environment.
31 #ifndef GNUNET_PSYC_SLICER_H
32 #define GNUNET_PSYC_SLICER_H
38 #if 0 /* keep Emacsens' auto-indent happy */
43 #include "gnunet_util_lib.h"
47 * Handle to an implementation of try-and-slice.
49 struct GNUNET_PSYC_Slicer;
53 * Function called upon receiving a message indicating a call to a @e method.
55 * This function is called one or more times for each message until all data
56 * fragments arrive from the network.
61 * Message part, as it arrived from the network.
63 * Message counter, monotonically increasing from 1.
65 * OR'ed GNUNET_PSYC_MessageFlags
66 * @param fragment_offset
67 * Multicast message fragment offset.
69 * OR'ed GNUNET_PSYC_MasterTransmitFlags
71 * The sender of the message.
72 * Can be NULL if the message is not connected to a pseudonym.
74 * Original method name from PSYC.
75 * May be more specific than the registered method name due to
76 * try-and-slice matching.
79 (*GNUNET_PSYC_MethodCallback) (void *cls,
80 const struct GNUNET_PSYC_MessageHeader *msg,
81 const struct GNUNET_PSYC_MessageMethod *meth,
83 const char *method_name);
87 * Function called upon receiving a modifier of a message.
92 * Message ID this data fragment belongs to.
94 * OR'ed GNUNET_PSYC_MessageFlags
95 * @param fragment_offset
96 * Multicast message fragment offset.
98 * Message part, as it arrived from the network.
100 * Operation to perform.
101 * 0 in case of a modifier continuation.
103 * Name of the modifier.
104 * NULL in case of a modifier continuation.
106 * Value of the modifier.
111 (*GNUNET_PSYC_ModifierCallback) (void *cls,
112 const struct GNUNET_PSYC_MessageHeader *msg,
113 const struct GNUNET_MessageHeader *pmsg,
115 enum GNUNET_PSYC_Operator oper,
119 uint16_t full_value_size);
123 * Function called upon receiving a data fragment of a message.
128 * Message part, as it arrived from the network.
130 * Message ID this data fragment belongs to.
132 * OR'ed GNUNET_PSYC_MessageFlags
133 * @param fragment_offset
134 * Multicast message fragment offset.
136 * Data stream given to the method.
138 * Number of bytes in @a data.
141 * #GNUNET_NO if there are further fragments,
142 * #GNUNET_YES if this is the last fragment,
143 * #GNUNET_SYSERR indicates the message was cancelled by the sender.
146 (*GNUNET_PSYC_DataCallback) (void *cls,
147 const struct GNUNET_PSYC_MessageHeader *msg,
148 const struct GNUNET_MessageHeader *pmsg,
160 * Message part, as it arrived from the network.
162 * Message ID this data fragment belongs to.
164 * OR'ed GNUNET_PSYC_MessageFlags
165 * @param fragment_offset
166 * Multicast message fragment offset.
168 * #GNUNET_YES if the message was cancelled,
169 * #GNUNET_NO if the message is complete.
172 (*GNUNET_PSYC_EndOfMessageCallback) (void *cls,
173 const struct GNUNET_PSYC_MessageHeader *msg,
174 const struct GNUNET_MessageHeader *pmsg,
176 uint8_t is_cancelled);
180 * Create a try-and-slice instance.
182 * A slicer processes incoming messages and notifies callbacks about matching
183 * methods or modifiers encountered.
185 * @return A new try-and-slice construct.
187 struct GNUNET_PSYC_Slicer *
188 GNUNET_PSYC_slicer_create (void);
192 * Add a method to the try-and-slice instance.
194 * The callbacks are called for messages with a matching @a method_name prefix.
197 * The try-and-slice instance to extend.
199 * Name of the given method, use empty string to match all.
201 * Method handler invoked upon a matching message.
203 * Modifier handler, invoked after @a method_cb
204 * for each modifier in the message.
206 * Data handler, invoked after @a modifier_cb for each data fragment.
208 * Invoked upon reaching the end of a matching message.
210 * Closure for the callbacks.
213 GNUNET_PSYC_slicer_method_add (struct GNUNET_PSYC_Slicer *slicer,
214 const char *method_name,
215 GNUNET_PSYC_MessageCallback msg_cb,
216 GNUNET_PSYC_MethodCallback method_cb,
217 GNUNET_PSYC_ModifierCallback modifier_cb,
218 GNUNET_PSYC_DataCallback data_cb,
219 GNUNET_PSYC_EndOfMessageCallback eom_cb,
223 * Remove a registered method from the try-and-slice instance.
225 * Removes one matching handler registered with the given
226 * @a method_name and callbacks.
229 * The try-and-slice instance.
231 * Name of the method to remove.
233 * Only remove matching method handler, or NULL.
235 * Only remove matching modifier handler, or NULL.
237 * Only remove matching data handler, or NULL.
239 * Only remove matching End of Message handler, or NULL.
241 * @return #GNUNET_OK if a method handler was removed,
242 * #GNUNET_NO if no handler matched the given method name and callbacks.
245 GNUNET_PSYC_slicer_method_remove (struct GNUNET_PSYC_Slicer *slicer,
246 const char *method_name,
247 GNUNET_PSYC_MessageCallback msg_cb,
248 GNUNET_PSYC_MethodCallback method_cb,
249 GNUNET_PSYC_ModifierCallback modifier_cb,
250 GNUNET_PSYC_DataCallback data_cb,
251 GNUNET_PSYC_EndOfMessageCallback eom_cb);
255 * Watch a place for changed objects.
258 * The try-and-slice instance.
259 * @param object_filter
260 * Object prefix to match.
262 * Function to call when encountering a state modifier.
264 * Closure for callback.
267 GNUNET_PSYC_slicer_modifier_add (struct GNUNET_PSYC_Slicer *slicer,
268 const char *object_filter,
269 GNUNET_PSYC_ModifierCallback modifier_cb,
274 * Remove a registered modifier from the try-and-slice instance.
276 * Removes one matching handler registered with the given
277 * @a object_filter and callback.
280 * The try-and-slice instance.
281 * @param object_filter
282 * Object prefix to match.
284 * Function to call when encountering a state modifier changes.
287 GNUNET_PSYC_slicer_modifier_remove (struct GNUNET_PSYC_Slicer *slicer,
288 const char *object_filter,
289 GNUNET_PSYC_ModifierCallback modifier_cb);
293 * Process an incoming message and call matching handlers.
298 * The message as it arrived from the network.
301 GNUNET_PSYC_slicer_message (struct GNUNET_PSYC_Slicer *slicer,
302 const struct GNUNET_PSYC_MessageHeader *msg);
306 * Process an incoming message part and call matching handlers.
313 * Flags for the message.
314 * @see enum GNUNET_PSYC_MessageFlags
315 * @param fragment offset
316 * Fragment offset of the message.
318 * The message part as it arrived from the network.
321 GNUNET_PSYC_slicer_message_part (struct GNUNET_PSYC_Slicer *slicer,
322 const struct GNUNET_PSYC_MessageHeader *msg,
323 const struct GNUNET_MessageHeader *pmsg);
327 * Remove all registered method handlers.
333 GNUNET_PSYC_slicer_method_clear (struct GNUNET_PSYC_Slicer *slicer);
337 * Remove all registered modifier handlers.
343 GNUNET_PSYC_slicer_modifier_clear (struct GNUNET_PSYC_Slicer *slicer);
347 * Remove all registered method & modifier handlers.
353 GNUNET_PSYC_slicer_clear (struct GNUNET_PSYC_Slicer *slicer);
357 * Destroy a given try-and-slice instance.
363 GNUNET_PSYC_slicer_destroy (struct GNUNET_PSYC_Slicer *slicer);
366 #if 0 /* keep Emacsens' auto-indent happy */
373 /* ifndef GNUNET_PSYC_SLICER_H */
376 /** @} */ /* end of group */