379 linhas
11 KiB
C
379 linhas
11 KiB
C
/*
|
|
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_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 */
|