|
- /*
- This file is part of GNUnet.
- Copyright (C) 2013 GNUnet e.V.
-
- GNUnet is free software: you can redistribute it and/or modify it
- under the terms of the GNU Affero General Public License as published
- by the Free Software Foundation, either version 3 of the License,
- or (at your option) any later version.
-
- GNUnet is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Affero General Public License for more details.
-
- You should have received a copy of the GNU Affero General Public License
- along with this program. If not, see <http://www.gnu.org/licenses/>.
-
- SPDX-License-Identifier: AGPL3.0-or-later
- */
-
- /**
- * @author Gabor X Toth
- * @author Christian Grothoff
- *
- * @file
- * PSYC Slicer library
- *
- * @defgroup psyc-util-slicer PSYC Utilities library: Slicer
- * Try-and-slice processing of PSYC method names and environment.
- * @{
- */
-
- #ifndef GNUNET_PSYC_SLICER_H
- #define GNUNET_PSYC_SLICER_H
-
-
- #ifdef __cplusplus
- extern "C"
- {
- #if 0 /* keep Emacsens' auto-indent happy */
- }
- #endif
- #endif
-
- #include <gnunet/gnunet_util_lib.h>
-
-
- /**
- * Handle to an implementation of try-and-slice.
- */
- struct GNUNET_PSYC_Slicer;
-
-
- /**
- * Function called upon receiving a message indicating a call to a @e method.
- *
- * This function is called one or more times for each message until all data
- * fragments arrive from the network.
- *
- * @param cls
- * Closure.
- * @param msg
- * Message part, as it arrived from the network.
- * @param message_id
- * Message counter, monotonically increasing from 1.
- * @param flags
- * OR'ed GNUNET_PSYC_MessageFlags
- * @param fragment_offset
- * Multicast message fragment offset.
- * @param tmit_flags
- * OR'ed GNUNET_PSYC_MasterTransmitFlags
- * @param nym
- * The sender of the message.
- * Can be NULL if the message is not connected to a pseudonym.
- * @param method_name
- * Original method name from PSYC.
- * May be more specific than the registered method name due to
- * try-and-slice matching.
- */
- typedef void
- (*GNUNET_PSYC_MethodCallback) (void *cls,
- const struct GNUNET_PSYC_MessageHeader *msg,
- const struct GNUNET_PSYC_MessageMethod *meth,
- uint64_t message_id,
- const char *method_name);
-
-
- /**
- * Function called upon receiving a modifier of a message.
- *
- * @param cls
- * Closure.
- * @param message_id
- * Message ID this data fragment belongs to.
- * @param flags
- * OR'ed GNUNET_PSYC_MessageFlags
- * @param fragment_offset
- * Multicast message fragment offset.
- * @param msg
- * Message part, as it arrived from the network.
- * @param oper
- * Operation to perform.
- * 0 in case of a modifier continuation.
- * @param name
- * Name of the modifier.
- * NULL in case of a modifier continuation.
- * @param value
- * Value of the modifier.
- * @param value_size
- * Size of @value.
- */
- typedef void
- (*GNUNET_PSYC_ModifierCallback) (void *cls,
- const struct GNUNET_PSYC_MessageHeader *msg,
- const struct GNUNET_MessageHeader *pmsg,
- uint64_t message_id,
- enum GNUNET_PSYC_Operator oper,
- const char *name,
- const void *value,
- uint16_t value_size,
- uint16_t full_value_size);
-
-
- /**
- * Function called upon receiving a data fragment of a message.
- *
- * @param cls
- * Closure.
- * @param msg
- * Message part, as it arrived from the network.
- * @param message_id
- * Message ID this data fragment belongs to.
- * @param flags
- * OR'ed GNUNET_PSYC_MessageFlags
- * @param fragment_offset
- * Multicast message fragment offset.
- * @param data
- * Data stream given to the method.
- * @param data_size
- * Number of bytes in @a data.
- * @param end
- * End of message?
- * #GNUNET_NO if there are further fragments,
- * #GNUNET_YES if this is the last fragment,
- * #GNUNET_SYSERR indicates the message was cancelled by the sender.
- */
- typedef void
- (*GNUNET_PSYC_DataCallback) (void *cls,
- const struct GNUNET_PSYC_MessageHeader *msg,
- const struct GNUNET_MessageHeader *pmsg,
- uint64_t message_id,
- const void *data,
- uint16_t data_size);
-
-
- /**
- * End of message.
- *
- * @param cls
- * Closure.
- * @param msg
- * Message part, as it arrived from the network.
- * @param message_id
- * Message ID this data fragment belongs to.
- * @param flags
- * OR'ed GNUNET_PSYC_MessageFlags
- * @param fragment_offset
- * Multicast message fragment offset.
- * @param cancelled
- * #GNUNET_YES if the message was cancelled,
- * #GNUNET_NO if the message is complete.
- */
- typedef void
- (*GNUNET_PSYC_EndOfMessageCallback) (void *cls,
- const struct GNUNET_PSYC_MessageHeader *msg,
- const struct GNUNET_MessageHeader *pmsg,
- uint64_t message_id,
- uint8_t is_cancelled);
-
-
- /**
- * Create a try-and-slice instance.
- *
- * A slicer processes incoming messages and notifies callbacks about matching
- * methods or modifiers encountered.
- *
- * @return A new try-and-slice construct.
- */
- struct GNUNET_PSYC_Slicer *
- GNUNET_PSYC_slicer_create (void);
-
-
- /**
- * Add a method to the try-and-slice instance.
- *
- * The callbacks are called for messages with a matching @a method_name prefix.
- *
- * @param slicer
- * The try-and-slice instance to extend.
- * @param method_name
- * Name of the given method, use empty string to match all.
- * @param method_cb
- * Method handler invoked upon a matching message.
- * @param modifier_cb
- * Modifier handler, invoked after @a method_cb
- * for each modifier in the message.
- * @param data_cb
- * Data handler, invoked after @a modifier_cb for each data fragment.
- * @param eom_cb
- * Invoked upon reaching the end of a matching message.
- * @param cls
- * Closure for the callbacks.
- */
- void
- GNUNET_PSYC_slicer_method_add (struct GNUNET_PSYC_Slicer *slicer,
- const char *method_name,
- GNUNET_PSYC_MessageCallback msg_cb,
- GNUNET_PSYC_MethodCallback method_cb,
- GNUNET_PSYC_ModifierCallback modifier_cb,
- GNUNET_PSYC_DataCallback data_cb,
- GNUNET_PSYC_EndOfMessageCallback eom_cb,
- void *cls);
-
- /**
- * Remove a registered method from the try-and-slice instance.
- *
- * Removes one matching handler registered with the given
- * @a method_name and callbacks.
- *
- * @param slicer
- * The try-and-slice instance.
- * @param method_name
- * Name of the method to remove.
- * @param method_cb
- * Only remove matching method handler, or NULL.
- * @param modifier_cb
- * Only remove matching modifier handler, or NULL.
- * @param data_cb
- * Only remove matching data handler, or NULL.
- * @param eom_cb
- * Only remove matching End of Message handler, or NULL.
- *
- * @return #GNUNET_OK if a method handler was removed,
- * #GNUNET_NO if no handler matched the given method name and callbacks.
- */
- int
- GNUNET_PSYC_slicer_method_remove (struct GNUNET_PSYC_Slicer *slicer,
- const char *method_name,
- GNUNET_PSYC_MessageCallback msg_cb,
- GNUNET_PSYC_MethodCallback method_cb,
- GNUNET_PSYC_ModifierCallback modifier_cb,
- GNUNET_PSYC_DataCallback data_cb,
- GNUNET_PSYC_EndOfMessageCallback eom_cb);
-
-
- /**
- * Watch a place for changed objects.
- *
- * @param slicer
- * The try-and-slice instance.
- * @param object_filter
- * Object prefix to match.
- * @param modifier_cb
- * Function to call when encountering a state modifier.
- * @param cls
- * Closure for callback.
- */
- void
- GNUNET_PSYC_slicer_modifier_add (struct GNUNET_PSYC_Slicer *slicer,
- const char *object_filter,
- GNUNET_PSYC_ModifierCallback modifier_cb,
- void *cls);
-
-
- /**
- * Remove a registered modifier from the try-and-slice instance.
- *
- * Removes one matching handler registered with the given
- * @a object_filter and callback.
- *
- * @param slicer
- * The try-and-slice instance.
- * @param object_filter
- * Object prefix to match.
- * @param modifier_cb
- * Function to call when encountering a state modifier changes.
- */
- int
- GNUNET_PSYC_slicer_modifier_remove (struct GNUNET_PSYC_Slicer *slicer,
- const char *object_filter,
- GNUNET_PSYC_ModifierCallback modifier_cb);
-
-
- /**
- * Process an incoming message and call matching handlers.
- *
- * @param slicer
- * The slicer to use.
- * @param msg
- * The message as it arrived from the network.
- */
- void
- GNUNET_PSYC_slicer_message (struct GNUNET_PSYC_Slicer *slicer,
- const struct GNUNET_PSYC_MessageHeader *msg);
-
-
- /**
- * Process an incoming message part and call matching handlers.
- *
- * @param slicer
- * The slicer to use.
- * @param message_id
- * ID of the message.
- * @param flags
- * Flags for the message.
- * @see enum GNUNET_PSYC_MessageFlags
- * @param fragment offset
- * Fragment offset of the message.
- * @param msg
- * The message part as it arrived from the network.
- */
- void
- GNUNET_PSYC_slicer_message_part (struct GNUNET_PSYC_Slicer *slicer,
- const struct GNUNET_PSYC_MessageHeader *msg,
- const struct GNUNET_MessageHeader *pmsg);
-
-
- /**
- * Remove all registered method handlers.
- *
- * @param slicer
- * Slicer to clear.
- */
- void
- GNUNET_PSYC_slicer_method_clear (struct GNUNET_PSYC_Slicer *slicer);
-
-
- /**
- * Remove all registered modifier handlers.
- *
- * @param slicer
- * Slicer to clear.
- */
- void
- GNUNET_PSYC_slicer_modifier_clear (struct GNUNET_PSYC_Slicer *slicer);
-
-
- /**
- * Remove all registered method & modifier handlers.
- *
- * @param slicer
- * Slicer to clear.
- */
- void
- GNUNET_PSYC_slicer_clear (struct GNUNET_PSYC_Slicer *slicer);
-
-
- /**
- * Destroy a given try-and-slice instance.
- *
- * @param slicer
- * Slicer to destroy
- */
- void
- GNUNET_PSYC_slicer_destroy (struct GNUNET_PSYC_Slicer *slicer);
-
-
- #if 0 /* keep Emacsens' auto-indent happy */
- {
- #endif
- #ifdef __cplusplus
- }
- #endif
-
- /* ifndef GNUNET_PSYC_SLICER_H */
- #endif
-
- /** @} */ /* end of group */
|