2 This file is part of GNUnet
3 (C) 2013 Christian Grothoff (and other contributing authors)
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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file set/gnunet-service-set.h
23 * @brief common components for the implementation the different set operations
24 * @author Florian Dold
27 #ifndef GNUNET_SERVICE_SET_H_PRIVATE
28 #define GNUNET_SERVICE_SET_H_PRIVATE
31 #include "gnunet_util_lib.h"
32 #include "gnunet_protocols.h"
33 #include "gnunet_applications.h"
34 #include "gnunet_core_service.h"
35 #include "gnunet_cadet_service.h"
36 #include "gnunet_set_service.h"
41 * Implementation-specific set state.
42 * Used as opaque pointer, and specified further
43 * in the respective implementation.
49 * Implementation-specific set operation.
50 * Used as opaque pointer, and specified further
51 * in the respective implementation.
53 struct OperationState;
56 /* forward declarations */
63 * Detail information about an operation.
65 struct OperationSpecification
68 * The type of the operation.
70 enum GNUNET_SET_OperationType operation;
73 * The remove peer we evaluate the operation with
75 struct GNUNET_PeerIdentity peer;
78 * Application ID for the operation, used to distinguish
79 * multiple operations of the same type with the same peer.
81 struct GNUNET_HashCode app_id;
84 * Context message, may be NULL.
86 struct GNUNET_MessageHeader *context_msg;
89 * Salt to use for the operation.
94 * Remote peers element count
96 uint32_t remote_element_count;
99 * ID used to identify an operation between service and client
101 uint32_t client_request_id;
104 * Set associated with the operation, NULL until the spec has been associated
110 * When are elements sent to the client, and which elements are sent?
112 enum GNUNET_SET_ResultMode result_mode;
119 * Signature of functions that create the implementation-specific
120 * state for a set supporting a specific operation.
122 * @return a set state specific to the supported operation
124 typedef struct SetState *(*CreateImpl) (void);
128 * Signature of functions that implement the add/remove functionality
129 * for a set supporting a specific operation.
131 * @param set implementation-specific set state
132 * @param msg element message from the client
134 typedef void (*AddRemoveImpl) (struct SetState *state, struct ElementEntry *ee);
138 * Signature of functions that handle disconnection
139 * of the remote peer.
141 * @param op the set operation, contains implementation-specific data
143 typedef void (*PeerDisconnectImpl) (struct Operation *op);
147 * Signature of functions that implement the destruction of the
148 * implementation-specific set state.
150 * @param state the set state, contains implementation-specific data
152 typedef void (*DestroySetImpl) (struct SetState *state);
156 * Signature of functions that implement the creation of set operations
157 * (currently evaluate and accept).
159 * @param op operation that is created, should be initialized by the implementation
161 typedef void (*OpCreateImpl) (struct Operation *op);
165 * Signature of functions that implement the message handling for
166 * the different set operations.
168 * @param op operation state
169 * @param msg received message
170 * @return GNUNET_OK on success, GNUNET_SYSERR to
171 * destroy the operation and the tunnel
173 typedef int (*MsgHandlerImpl) (struct Operation *op,
174 const struct GNUNET_MessageHeader *msg);
177 * Signature of functions that implement operation cancellation
179 * @param op operation state
181 typedef void (*CancelImpl) (struct Operation *op);
185 * Dispatch table for a specific set operation.
186 * Every set operation has to implement the callback
192 * Callback for the set creation.
197 * Callback for element insertion
202 * Callback for element removal.
204 AddRemoveImpl remove;
207 * Callback for accepting a set operation request
212 * Callback for starting evaluation with a remote peer.
214 OpCreateImpl evaluate;
217 * Callback for destruction of the set state.
219 DestroySetImpl destroy_set;
222 * Callback for handling operation-specific messages.
224 MsgHandlerImpl msg_handler;
227 * Callback for handling the remote peer's
230 PeerDisconnectImpl peer_disconnect;
233 * Callback for canceling an operation by
241 * Information about an element element in the set.
242 * All elements are stored in a hash-table
243 * from their hash-code to their 'struct Element',
244 * so that the remove and add operations are reasonably
250 * The actual element. The data for the element
251 * should be allocated at the end of this struct.
253 struct GNUNET_SET_Element element;
256 * Hash of the element.
258 * Will be used to derive the different IBF keys
259 * for different salts.
261 struct GNUNET_HashCode element_hash;
264 * Generation the element was added by the client.
265 * Operations of earlier generations will not consider the element.
267 unsigned int generation_added;
270 * GNUNET_YES if the element has been removed in some generation.
275 * Generation the element was removed by the client.
276 * Operations of later generations will not consider the element.
277 * Only valid if is_removed is GNUNET_YES.
279 unsigned int generation_removed;
282 * GNUNET_YES if the element is a remote element, and does not belong
283 * to the operation's set.
285 * //TODO: Move to Union, unless additional set-operations are implemented ever
294 * V-Table for the operation belonging
295 * to the tunnel contest.
297 * Used for all operation specific operations after receiving the ops request
299 const struct SetVT *vt;
302 * Tunnel to the peer.
304 struct GNUNET_CADET_Channel *channel;
307 * Message queue for the tunnel.
309 struct GNUNET_MQ_Handle *mq;
312 * GNUNET_YES if this is not a "real" set operation yet, and we still
313 * need to wait for the other peer to give us more details.
318 * Generation in which the operation handle
321 unsigned int generation_created;
324 * Detail information about the set operation,
325 * including the set to use.
326 * When 'spec' is NULL, the operation is not yet entirely
329 struct OperationSpecification *spec;
332 * Operation-specific operation state.
334 struct OperationState *state;
337 * Evaluate operations are held in
340 struct Operation *next;
343 * Evaluate operations are held in
346 struct Operation *prev;
349 * Set to GNUNET_YES if the set service should not free
350 * the operation, as it is still needed (e.g. in some scheduled task).
357 * A set that supports a specific operation
363 * Client that owns the set.
364 * Only one client may own a set.
366 struct GNUNET_SERVER_Client *client;
369 * Message queue for the client
371 struct GNUNET_MQ_Handle *client_mq;
374 * Type of operation supported for this set
376 enum GNUNET_SET_OperationType operation;
379 * Virtual table for this set.
380 * Determined by the operation type of this set.
382 * Used only for Add/remove of elements and when receiving an incoming
383 * operation from a remote peer.
385 const struct SetVT *vt;
388 * Sets are held in a doubly linked list.
393 * Sets are held in a doubly linked list.
398 * Implementation-specific state.
400 struct SetState *state;
403 * Current state of iterating elements for the client.
404 * NULL if we are not currently iterating.
406 struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
409 * Maps 'struct GNUNET_HashCode' to 'struct ElementEntry'.
411 struct GNUNET_CONTAINER_MultiHashMap *elements;
414 * Current generation, that is, number of
415 * previously executed operations on this set
417 unsigned int current_generation;
420 * Evaluate operations are held in
423 struct Operation *ops_head;
426 * Evaluate operations are held in
429 struct Operation *ops_tail;
434 * Destroy the given operation. Call the implementation-specific cancel function
435 * of the operation. Disconnects from the remote peer.
436 * Does not disconnect the client, as there may be multiple operations per set.
438 * @param op operation to destroy
441 _GSS_operation_destroy (struct Operation *op);
445 * Get the table with implementing functions for
448 * @return the operation specific VTable
451 _GSS_union_vt (void);
455 * Get the table with implementing functions for
458 * @return the operation specific VTable
461 _GSS_intersection_vt (void);