From 50eaf8d7de763d25b7dae7ffdee8d7c6b5fe71ea Mon Sep 17 00:00:00 2001 From: Gabor X Toth <*@tg-x.net> Date: Tue, 12 Jan 2016 23:26:47 +0000 Subject: psycutil reorg: message, env, slicer --- src/include/gnunet_psyc_slicer.h | 319 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 src/include/gnunet_psyc_slicer.h (limited to 'src/include/gnunet_psyc_slicer.h') diff --git a/src/include/gnunet_psyc_slicer.h b/src/include/gnunet_psyc_slicer.h new file mode 100644 index 000000000..1851a6002 --- /dev/null +++ b/src/include/gnunet_psyc_slicer.h @@ -0,0 +1,319 @@ +/* + This file is part of GNUnet. + Copyright (C) 2013 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, 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 + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +/** + * @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_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 nym + * The sender of the message. + * Can be NULL if the message is not connected to a pseudonym. + * @param flags + * OR'ed GNUNET_PSYC_MessageFlags + * @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_MessageMethod *msg, + uint64_t message_id, + uint32_t flags, + const struct GNUNET_CRYPTO_EcdsaPublicKey *nym_pub_key, + 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 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_MessageHeader *msg, + 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 message_id + * Message ID this data fragment belongs to. + * @param msg + * Message part, as it arrived from the network. + * @param data_offset + * Byte offset of @a data in the overall data of the method. + * @param data_size + * Number of bytes in @a data. + * @param data + * Data stream given to the method. + * @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_MessageHeader *msg, + uint64_t message_id, + uint64_t data_offset, + 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 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_MessageHeader *msg, + uint64_t message_id, + uint8_t 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_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 + * Method handler. + * @param modifier_cb + * Modifier handler. + * @param data_cb + * Data handler. + * @param eom_cb + * End of message handler. + * + * @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_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 part and call matching handlers. + * + * @param cls + * Closure. + * @param message_id + * ID of the message. + * @param flags + * Flags for the message. + * @see enum GNUNET_PSYC_MessageFlags + * @param msg + * The message part. as it arrived from the network. + */ +void +GNUNET_PSYC_slicer_message (void *cls, + const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_pub_key, + uint64_t message_id, + uint32_t flags, + uint64_t fragment_offset, + const struct GNUNET_MessageHeader *msg); + + +/** + * 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 */ -- cgit v1.2.3