Block plugin API

To be implemented by applications storing data in the DHT. More...

Collaboration diagram for Block plugin API:

Data Structures
struct	GNUNET_BLOCK_Group
	Block group data. More...
struct	GNUNET_BLOCK_PluginFunctions
	Each plugin is required to return a pointer to a struct of this type as the return value from its entry point. More...

Typedefs
typedef void(*	GNUNET_BLOCK_GroupMarkSeenFunction) (struct GNUNET_BLOCK_Group *bg, const struct GNUNET_HashCode *seen_results, unsigned int seen_results_count)
	Mark elements as "seen" using a hash of the element.
typedef enum GNUNET_GenericReturnValue(*	GNUNET_BLOCK_GroupMergeFunction) (struct GNUNET_BLOCK_Group *bg1, const struct GNUNET_BLOCK_Group *bg2)
	Merge two groups, if possible.
typedef enum GNUNET_GenericReturnValue(*	GNUNET_BLOCK_GroupSerializeFunction) (struct GNUNET_BLOCK_Group *bg, void **raw_data, size_t *raw_data_size)
	Serialize state of a block group.
typedef void(*	GNUNET_BLOCK_GroupDestroyFunction) (struct GNUNET_BLOCK_Group *bg)
	Destroy resources used by a block group.
typedef struct GNUNET_BLOCK_Group *(*	GNUNET_BLOCK_GroupCreateFunction) (void *cls, enum GNUNET_BLOCK_Type type, const void *raw_data, size_t raw_data_size, va_list va)
	Create a new block group.
typedef enum GNUNET_GenericReturnValue(*	GNUNET_BLOCK_QueryEvaluationFunction) (void *cls, enum GNUNET_BLOCK_Type type, const struct GNUNET_HashCode *query, const void *xquery, size_t xquery_size)
	Function called to validate a query.
typedef enum GNUNET_GenericReturnValue(*	GNUNET_BLOCK_BlockEvaluationFunction) (void *cls, enum GNUNET_BLOCK_Type type, const void *block, size_t block_size)
	Function called to validate a block for storage.
typedef enum GNUNET_BLOCK_ReplyEvaluationResult(*	GNUNET_BLOCK_ReplyEvaluationFunction) (void *cls, enum GNUNET_BLOCK_Type type, struct GNUNET_BLOCK_Group *group, const struct GNUNET_HashCode *query, const void *xquery, size_t xquery_size, const void *reply_block, size_t reply_block_size)
	Function called to validate a reply to a request.
typedef enum GNUNET_GenericReturnValue(*	GNUNET_BLOCK_GetKeyFunction) (void *cls, enum GNUNET_BLOCK_Type type, const void *block, size_t block_size, struct GNUNET_HashCode *key)
	Function called to obtain the key for a block.

Detailed Description

To be implemented by applications storing data in the DHT.

Each block plugin must conform to the API specified by this header.

Typedef Documentation

GNUNET_BLOCK_GroupMarkSeenFunction

typedef void(* GNUNET_BLOCK_GroupMarkSeenFunction) (struct GNUNET_BLOCK_Group *bg, const struct GNUNET_HashCode *seen_results, unsigned int seen_results_count)

Mark elements as "seen" using a hash of the element.

Not supported by all block plugins.

Parameters

bg	group to update
seen_results	results already seen
seen_results_count	number of entries in seen_results

Definition at line 54 of file gnunet_block_plugin.h.

GNUNET_BLOCK_GroupMergeFunction

typedef enum GNUNET_GenericReturnValue(* GNUNET_BLOCK_GroupMergeFunction) (struct GNUNET_BLOCK_Group *bg1, const struct GNUNET_BLOCK_Group *bg2)

Merge two groups, if possible.

Not supported by all block plugins, can also fail if the nonces were different.

Parameters

bg1	group to update
bg2	group to merge into bg1

Returns

GNUNET_OK on success, GNUNET_NO if the nonces were different and thus we failed.

Definition at line 54 of file gnunet_block_plugin.h.

GNUNET_BLOCK_GroupSerializeFunction

typedef enum GNUNET_GenericReturnValue(* GNUNET_BLOCK_GroupSerializeFunction) (struct GNUNET_BLOCK_Group *bg, void **raw_data, size_t *raw_data_size)

Serialize state of a block group.

Parameters

	bg	group to serialize
[out]	raw_data	set to the serialized state
[out]	raw_data_size	set to the number of bytes in raw_data

Returns

GNUNET_OK on success, GNUNET_NO if serialization is not supported, GNUNET_SYSERR on error

Definition at line 54 of file gnunet_block_plugin.h.

GNUNET_BLOCK_GroupDestroyFunction

typedef void(* GNUNET_BLOCK_GroupDestroyFunction) (struct GNUNET_BLOCK_Group *bg)

Destroy resources used by a block group.

Parameters

bg	group to destroy, NULL is allowed

Definition at line 95 of file gnunet_block_plugin.h.

GNUNET_BLOCK_GroupCreateFunction

typedef struct GNUNET_BLOCK_Group *(* GNUNET_BLOCK_GroupCreateFunction) (void *cls, enum GNUNET_BLOCK_Type type, const void *raw_data, size_t raw_data_size, va_list va)

Create a new block group.

Parameters

ctx	block context in which the block group is created
type	type of the block for which we are creating the group
nonce	random value used to seed the group creation
raw_data	optional serialized prior state of the group, NULL if unavailable/fresh
raw_data_size	number of bytes in raw_data, 0 if unavailable/fresh
va	variable arguments specific to type

Returns

block group handle, NULL if block groups are not supported by this type of block (this is not an error)

Definition at line 95 of file gnunet_block_plugin.h.

GNUNET_BLOCK_QueryEvaluationFunction

typedef enum GNUNET_GenericReturnValue(* GNUNET_BLOCK_QueryEvaluationFunction) (void *cls, enum GNUNET_BLOCK_Type type, const struct GNUNET_HashCode *query, const void *xquery, size_t xquery_size)

Function called to validate a query.

Parameters

cls	closure
type	block type
query	original query (hash)
xquery	extrended query data (can be NULL, depending on type)
xquery_size	number of bytes in xquery

Returns

GNUNET_OK if the query is fine, GNUNET_NO if not

Definition at line 95 of file gnunet_block_plugin.h.

GNUNET_BLOCK_BlockEvaluationFunction

typedef enum GNUNET_GenericReturnValue(* GNUNET_BLOCK_BlockEvaluationFunction) (void *cls, enum GNUNET_BLOCK_Type type, const void *block, size_t block_size)

Function called to validate a block for storage.

Parameters

cls	closure
type	block type
block	block data to validate
block_size	number of bytes in block

Returns

GNUNET_OK if the block is fine, GNUNET_NO if not, GNUNET_SYSERR if the type is not supported

Definition at line 95 of file gnunet_block_plugin.h.

GNUNET_BLOCK_ReplyEvaluationFunction

typedef enum GNUNET_BLOCK_ReplyEvaluationResult(* GNUNET_BLOCK_ReplyEvaluationFunction) (void *cls, enum GNUNET_BLOCK_Type type, struct GNUNET_BLOCK_Group *group, const struct GNUNET_HashCode *query, const void *xquery, size_t xquery_size, const void *reply_block, size_t reply_block_size)

Function called to validate a reply to a request.

Note that it is assumed that the reply has already been matched to the key (and signatures checked) as it would be done with the GetKeyFunction and the BlockEvaluationFunction.

Parameters

cls	closure
type	block type
group	which block group to use for evaluation
query	original query (hash)
xquery	extrended query data (can be NULL, depending on type)
xquery_size	number of bytes in xquery
reply_block	response to validate
reply_block_size	number of bytes in reply_block

Returns

characterization of result

Definition at line 95 of file gnunet_block_plugin.h.

GNUNET_BLOCK_GetKeyFunction

typedef enum GNUNET_GenericReturnValue(* GNUNET_BLOCK_GetKeyFunction) (void *cls, enum GNUNET_BLOCK_Type type, const void *block, size_t block_size, struct GNUNET_HashCode *key)

Function called to obtain the key for a block.

If the block is malformed, the function should zero-out key and return GNUNET_OK.

Parameters

	cls	closure
	type	block type
	block	block to get the key for
	block_size	number of bytes in block
[out]	key	set to the key (query) for the given block

Returns

GNUNET_YES on success, GNUNET_NO if extracting a key for this type does not work GNUNET_SYSERR if type not supported

Definition at line 95 of file gnunet_block_plugin.h.