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
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Gabor X Toth
23 * @author Christian Grothoff
28 * @defgroup psyc-util-slicer PSYC Utilities library: Slicer
29 * Try-and-slice processing of PSYC method names and environment.
33 #ifndef GNUNET_PSYC_SLICER_H
34 #define GNUNET_PSYC_SLICER_H
40 #if 0 /* keep Emacsens' auto-indent happy */
45 #include "gnunet_util_lib.h"
49 * Handle to an implementation of try-and-slice.
51 struct GNUNET_PSYC_Slicer;
55 * Function called upon receiving a message indicating a call to a @e method.
57 * This function is called one or more times for each message until all data
58 * fragments arrive from the network.
63 * Message part, as it arrived from the network.
65 * Message counter, monotonically increasing from 1.
67 * OR'ed GNUNET_PSYC_MessageFlags
68 * @param fragment_offset
69 * Multicast message fragment offset.
71 * OR'ed GNUNET_PSYC_MasterTransmitFlags
73 * The sender of the message.
74 * Can be NULL if the message is not connected to a pseudonym.
76 * Original method name from PSYC.
77 * May be more specific than the registered method name due to
78 * try-and-slice matching.
81 (*GNUNET_PSYC_MethodCallback) (void *cls,
82 const struct GNUNET_PSYC_MessageHeader *msg,
83 const struct GNUNET_PSYC_MessageMethod *meth,
85 const char *method_name);
89 * Function called upon receiving a modifier of a message.
94 * Message ID this data fragment belongs to.
96 * OR'ed GNUNET_PSYC_MessageFlags
97 * @param fragment_offset
98 * Multicast message fragment offset.
100 * Message part, as it arrived from the network.
102 * Operation to perform.
103 * 0 in case of a modifier continuation.
105 * Name of the modifier.
106 * NULL in case of a modifier continuation.
108 * Value of the modifier.
113 (*GNUNET_PSYC_ModifierCallback) (void *cls,
114 const struct GNUNET_PSYC_MessageHeader *msg,
115 const struct GNUNET_MessageHeader *pmsg,
117 enum GNUNET_PSYC_Operator oper,
121 uint16_t full_value_size);
125 * Function called upon receiving a data fragment of a message.
130 * Message part, as it arrived from the network.
132 * Message ID this data fragment belongs to.
134 * OR'ed GNUNET_PSYC_MessageFlags
135 * @param fragment_offset
136 * Multicast message fragment offset.
138 * Data stream given to the method.
140 * Number of bytes in @a data.
143 * #GNUNET_NO if there are further fragments,
144 * #GNUNET_YES if this is the last fragment,
145 * #GNUNET_SYSERR indicates the message was cancelled by the sender.
148 (*GNUNET_PSYC_DataCallback) (void *cls,
149 const struct GNUNET_PSYC_MessageHeader *msg,
150 const struct GNUNET_MessageHeader *pmsg,
162 * Message part, as it arrived from the network.
164 * Message ID this data fragment belongs to.
166 * OR'ed GNUNET_PSYC_MessageFlags
167 * @param fragment_offset
168 * Multicast message fragment offset.
170 * #GNUNET_YES if the message was cancelled,
171 * #GNUNET_NO if the message is complete.
174 (*GNUNET_PSYC_EndOfMessageCallback) (void *cls,
175 const struct GNUNET_PSYC_MessageHeader *msg,
176 const struct GNUNET_MessageHeader *pmsg,
178 uint8_t is_cancelled);
182 * Create a try-and-slice instance.
184 * A slicer processes incoming messages and notifies callbacks about matching
185 * methods or modifiers encountered.
187 * @return A new try-and-slice construct.
189 struct GNUNET_PSYC_Slicer *
190 GNUNET_PSYC_slicer_create (void);
194 * Add a method to the try-and-slice instance.
196 * The callbacks are called for messages with a matching @a method_name prefix.
199 * The try-and-slice instance to extend.
201 * Name of the given method, use empty string to match all.
203 * Method handler invoked upon a matching message.
205 * Modifier handler, invoked after @a method_cb
206 * for each modifier in the message.
208 * Data handler, invoked after @a modifier_cb for each data fragment.
210 * Invoked upon reaching the end of a matching message.
212 * Closure for the callbacks.
215 GNUNET_PSYC_slicer_method_add (struct GNUNET_PSYC_Slicer *slicer,
216 const char *method_name,
217 GNUNET_PSYC_MessageCallback msg_cb,
218 GNUNET_PSYC_MethodCallback method_cb,
219 GNUNET_PSYC_ModifierCallback modifier_cb,
220 GNUNET_PSYC_DataCallback data_cb,
221 GNUNET_PSYC_EndOfMessageCallback eom_cb,
225 * Remove a registered method from the try-and-slice instance.
227 * Removes one matching handler registered with the given
228 * @a method_name and callbacks.
231 * The try-and-slice instance.
233 * Name of the method to remove.
235 * Only remove matching method handler, or NULL.
237 * Only remove matching modifier handler, or NULL.
239 * Only remove matching data handler, or NULL.
241 * Only remove matching End of Message handler, or NULL.
243 * @return #GNUNET_OK if a method handler was removed,
244 * #GNUNET_NO if no handler matched the given method name and callbacks.
247 GNUNET_PSYC_slicer_method_remove (struct GNUNET_PSYC_Slicer *slicer,
248 const char *method_name,
249 GNUNET_PSYC_MessageCallback msg_cb,
250 GNUNET_PSYC_MethodCallback method_cb,
251 GNUNET_PSYC_ModifierCallback modifier_cb,
252 GNUNET_PSYC_DataCallback data_cb,
253 GNUNET_PSYC_EndOfMessageCallback eom_cb);
257 * Watch a place for changed objects.
260 * The try-and-slice instance.
261 * @param object_filter
262 * Object prefix to match.
264 * Function to call when encountering a state modifier.
266 * Closure for callback.
269 GNUNET_PSYC_slicer_modifier_add (struct GNUNET_PSYC_Slicer *slicer,
270 const char *object_filter,
271 GNUNET_PSYC_ModifierCallback modifier_cb,
276 * Remove a registered modifier from the try-and-slice instance.
278 * Removes one matching handler registered with the given
279 * @a object_filter and callback.
282 * The try-and-slice instance.
283 * @param object_filter
284 * Object prefix to match.
286 * Function to call when encountering a state modifier changes.
289 GNUNET_PSYC_slicer_modifier_remove (struct GNUNET_PSYC_Slicer *slicer,
290 const char *object_filter,
291 GNUNET_PSYC_ModifierCallback modifier_cb);
295 * Process an incoming message and call matching handlers.
300 * The message as it arrived from the network.
303 GNUNET_PSYC_slicer_message (struct GNUNET_PSYC_Slicer *slicer,
304 const struct GNUNET_PSYC_MessageHeader *msg);
308 * Process an incoming message part and call matching handlers.
315 * Flags for the message.
316 * @see enum GNUNET_PSYC_MessageFlags
317 * @param fragment offset
318 * Fragment offset of the message.
320 * The message part as it arrived from the network.
323 GNUNET_PSYC_slicer_message_part (struct GNUNET_PSYC_Slicer *slicer,
324 const struct GNUNET_PSYC_MessageHeader *msg,
325 const struct GNUNET_MessageHeader *pmsg);
329 * Remove all registered method handlers.
335 GNUNET_PSYC_slicer_method_clear (struct GNUNET_PSYC_Slicer *slicer);
339 * Remove all registered modifier handlers.
345 GNUNET_PSYC_slicer_modifier_clear (struct GNUNET_PSYC_Slicer *slicer);
349 * Remove all registered method & modifier handlers.
355 GNUNET_PSYC_slicer_clear (struct GNUNET_PSYC_Slicer *slicer);
359 * Destroy a given try-and-slice instance.
365 GNUNET_PSYC_slicer_destroy (struct GNUNET_PSYC_Slicer *slicer);
368 #if 0 /* keep Emacsens' auto-indent happy */
375 /* ifndef GNUNET_PSYC_SLICER_H */
378 /** @} */ /* end of group */