src/fs/gnunet-service-fs_pr.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009, 2010, 2011 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @file fs/gnunet-service-fs_pr.h
  21  * @brief API to handle pending requests
  22  * @author Christian Grothoff
  23  */
  24 #ifndef GNUNET_SERVICE_FS_PR_H
  25 #define GNUNET_SERVICE_FS_PR_H
  26
  27 #include "gnunet-service-fs.h"
  28
  29
  30 /**
  31  * Options for pending requests (bits to be ORed).
  32  */
  33 enum GSF_PendingRequestOptions
  34 {
  35
  36   /**
  37    * No special options (P2P-default).
  38    */
  39   GSF_PRO_DEFAULTS = 0,
  40
  41   /**
  42    * Request must only be processed locally.
  43    */
  44   GSF_PRO_LOCAL_ONLY = 1,
  45
  46   /**
  47    * Request must only be forwarded (no routing)
  48    */
  49   GSF_PRO_FORWARD_ONLY = 2,
  50
  51   /**
  52    * Request persists indefinitely (no expiration).
  53    */
  54   GSF_PRO_REQUEST_NEVER_EXPIRES = 4,
  55
  56   /**
  57    * Request is allowed to refresh bloomfilter and change mingle value.
  58    */
  59   GSF_PRO_BLOOMFILTER_FULL_REFRESH = 8,
  60
  61   /**
  62    * Request priority is allowed to be exceeded.
  63    */
  64   GSF_PRO_PRIORITY_UNLIMITED = 16,
  65
  66   /**
  67    * Option mask for typical local requests.
  68    */
  69   GSF_PRO_LOCAL_REQUEST =
  70       (GSF_PRO_BLOOMFILTER_FULL_REFRESH | GSF_PRO_PRIORITY_UNLIMITED | GSF_PRO_REQUEST_NEVER_EXPIRES)
  71 };
  72
  73
  74 /**
  75  * Public data (in the sense of not encapsulated within
  76  * 'gnunet-service-fs_pr', not in the sense of network-wide
  77  * known) associated with each pending request.
  78  */
  79 struct GSF_PendingRequestData
  80 {
  81
  82   /**
  83    * Primary query hash for this request.
  84    */
  85   struct GNUNET_HashCode query;
  86
  87   /**
  88    * Identity of a peer hosting the content, otherwise NULl.
  89    * Allocated after struct only if needed. Do not free!
  90    */
  91   const struct GNUNET_PeerIdentity *target;
  92
  93   /**
  94    * Fields for the plan module to track a DLL with the request.
  95    */
  96   struct GSF_PendingRequestPlanBijection *pr_head;
  97
  98   /**
  99    * Fields for the plan module to track a DLL with the request.
 100    */
 101   struct GSF_PendingRequestPlanBijection *pr_tail;
 102
 103   /**
 104    * Current TTL for the request.
 105    */
 106   struct GNUNET_TIME_Absolute ttl;
 107
 108   /**
 109    * When did we start with the request.
 110    */
 111   struct GNUNET_TIME_Absolute start_time;
 112
 113   /**
 114    * Desired anonymity level.
 115    */
 116   uint32_t anonymity_level;
 117
 118   /**
 119    * Priority that this request (still) has for us.
 120    */
 121   uint32_t priority;
 122
 123   /**
 124    * Priority that this request (originally) had for us.
 125    */
 126   uint32_t original_priority;
 127
 128   /**
 129    * Counter for how often this request has been transmitted (estimate,
 130    * because we might have the same request pending for multiple clients,
 131    * and of course because a transmission may have failed at a lower
 132    * layer).
 133    */
 134   uint32_t num_transmissions;
 135
 136   /**
 137    * How much respect did we (in total) offer for this request so far (estimate,
 138    * because we might have the same request pending for multiple clients,
 139    * and of course because a transmission may have failed at a lower
 140    * layer).
 141    */
 142   uint32_t respect_offered;
 143
 144   /**
 145    * Options for the request.
 146    */
 147   enum GSF_PendingRequestOptions options;
 148
 149   /**
 150    * Type of the requested block.
 151    */
 152   enum GNUNET_BLOCK_Type type;
 153
 154   /**
 155    * Number of results we have found for this request so far.
 156    */
 157   unsigned int results_found;
 158
 159   /**
 160    * Has this request been started yet (local/p2p operations)?  Or are
 161    * we still constructing it?
 162    */
 163   int has_started;
 164
 165 };
 166
 167
 168 /**
 169  * Handle a reply to a pending request.  Also called if a request
 170  * expires (then with data == NULL).  The handler may be called
 171  * many times (depending on the request type), but will not be
 172  * called during or after a call to GSF_pending_request_cancel
 173  * and will also not be called anymore after a call signalling
 174  * expiration.
 175  *
 176  * @param cls user-specified closure
 177  * @param eval evaluation of the result
 178  * @param pr handle to the original pending request
 179  * @param reply_anonymity_level anonymity level for the reply, UINT32_MAX for "unknown"
 180  * @param expiration when does @a data expire?
 181  * @param last_transmission the last time we've tried to get this block (FOREVER if unknown)
 182  * @param type type of the block
 183  * @param data response data, NULL on request expiration
 184  * @param data_len number of bytes in @a data
 185  */
 186 typedef void
 187 (*GSF_PendingRequestReplyHandler) (void *cls,
 188                                    enum GNUNET_BLOCK_EvaluationResult eval,
 189                                    struct GSF_PendingRequest *pr,
 190                                    uint32_t reply_anonymity_level,
 191                                    struct GNUNET_TIME_Absolute expiration,
 192                                    struct GNUNET_TIME_Absolute last_transmission,
 193                                    enum GNUNET_BLOCK_Type type,
 194                                    const void *data,
 195                                    size_t data_len);
 196
 197
 198 /**
 199  * Create a new pending request.
 200  *
 201  * @param options request options
 202  * @param type type of the block that is being requested
 203  * @param query key for the lookup
 204  * @param target preferred target for the request, NULL for none
 205  * @param bf_data raw data for bloom filter for known replies, can be NULL
 206  * @param bf_size number of bytes in bf_data
 207  * @param mingle mingle value for bf
 208  * @param anonymity_level desired anonymity level
 209  * @param priority maximum outgoing cummulative request priority to use
 210  * @param ttl current time-to-live for the request
 211  * @param sender_pid peer ID to use for the sender when forwarding, 0 for none;
 212  *                   reference counter is taken over by this function
 213  * @param origin_pid peer ID of origin of query (do not loop back)
 214  * @param replies_seen hash codes of known local replies
 215  * @param replies_seen_count size of the 'replies_seen' array
 216  * @param rh handle to call when we get a reply
 217  * @param rh_cls closure for rh
 218  * @return handle for the new pending request
 219  */
 220 struct GSF_PendingRequest *
 221 GSF_pending_request_create_ (enum GSF_PendingRequestOptions options,
 222                              enum GNUNET_BLOCK_Type type,
 223                              const struct GNUNET_HashCode *query,
 224                              const struct GNUNET_PeerIdentity *target,
 225                              const char *bf_data,
 226                              size_t bf_size,
 227                              uint32_t mingle,
 228                              uint32_t anonymity_level,
 229                              uint32_t priority,
 230                              int32_t ttl,
 231                              GNUNET_PEER_Id sender_pid,
 232                              GNUNET_PEER_Id origin_pid,
 233                              const struct GNUNET_HashCode *replies_seen,
 234                              unsigned int replies_seen_count,
 235                              GSF_PendingRequestReplyHandler rh,
 236                              void *rh_cls);
 237
 238
 239 /**
 240  * Update a given pending request with additional replies
 241  * that have been seen.
 242  *
 243  * @param pr request to update
 244  * @param replies_seen hash codes of replies that we've seen
 245  * @param replies_seen_count size of the @a replies_seen array
 246  */
 247 void
 248 GSF_pending_request_update_ (struct GSF_PendingRequest *pr,
 249                              const struct GNUNET_HashCode *replies_seen,
 250                              unsigned int replies_seen_count);
 251
 252
 253 /**
 254  * Obtain the public data associated with a pending request
 255  *
 256  * @param pr pending request
 257  * @return associated public data
 258  */
 259 struct GSF_PendingRequestData *
 260 GSF_pending_request_get_data_ (struct GSF_PendingRequest *pr);
 261
 262
 263 /**
 264  * Check if the given request is still active.
 265  *
 266  * @param pr pending request
 267  * @return #GNUNET_YES if the request is still active
 268  */
 269 int
 270 GSF_pending_request_test_active_ (struct GSF_PendingRequest *pr);
 271
 272
 273 /**
 274  * Test if two pending requests are compatible (would generate
 275  * the same query modulo filters and should thus be processed
 276  * jointly).
 277  *
 278  * @param pra a pending request
 279  * @param prb another pending request
 280  * @return #GNUNET_OK if the requests are compatible
 281  */
 282 int
 283 GSF_pending_request_is_compatible_ (struct GSF_PendingRequest *pra,
 284                                     struct GSF_PendingRequest *prb);
 285
 286
 287 /**
 288  * Generate the message corresponding to the given pending request for
 289  * transmission to other peers.
 290  *
 291  * @param pr request to generate the message for
 292  * @return envelope with the request message
 293  */
 294 struct GNUNET_MQ_Envelope *
 295 GSF_pending_request_get_message_ (struct GSF_PendingRequest *pr);
 296
 297
 298 /**
 299  * Explicitly cancel a pending request.
 300  *
 301  * @param pr request to cancel
 302  * @param full_cleanup fully purge the request
 303  */
 304 void
 305 GSF_pending_request_cancel_ (struct GSF_PendingRequest *pr,
 306                              int full_cleanup);
 307
 308
 309 /**
 310  * Signature of function called on each request.
 311  * (Note: 'subtype' of GNUNET_CONTAINER_HashMapIterator).
 312  *
 313  * @param cls closure
 314  * @param key query for the request
 315  * @param pr handle to the pending request
 316  * @return #GNUNET_YES to continue to iterate
 317  */
 318 typedef int
 319 (*GSF_PendingRequestIterator) (void *cls,
 320                                const struct GNUNET_HashCode *key,
 321                                struct GSF_PendingRequest *pr);
 322
 323
 324 /**
 325  * Iterate over all pending requests.
 326  *
 327  * @param it function to call for each request
 328  * @param cls closure for it
 329  */
 330 void
 331 GSF_iterate_pending_requests_ (GSF_PendingRequestIterator it,
 332                                void *cls);
 333
 334
 335 /**
 336  * Handle P2P "CONTENT" message.  Checks that the message is
 337  * well-formed and then checks if there are any pending requests for
 338  * this content and possibly passes it on (to local clients or other
 339  * peers).  Does NOT perform migration (content caching at this peer).
 340  *
 341  * @param cls the other peer involved (sender)
 342  * @param put the actual message
 343  */
 344 void
 345 handle_p2p_put (void *cls,
 346                 const struct PutMessage *put);
 347
 348
 349 /**
 350  * Consider looking up the data in the DHT (anonymity-level permitting).
 351  *
 352  * @param pr the pending request to process
 353  */
 354 void
 355 GSF_dht_lookup_ (struct GSF_PendingRequest *pr);
 356
 357
 358 /**
 359  * Consider downloading via cadet (if possible)
 360  *
 361  * @param pr the pending request to process
 362  */
 363 void
 364 GSF_cadet_lookup_ (struct GSF_PendingRequest *pr);
 365
 366
 367 /**
 368  * Function to be called after we're done processing
 369  * replies from the local lookup.
 370  *
 371  * @param cls closure
 372  * @param pr the pending request we were processing
 373  * @param result final datastore lookup result
 374  */
 375 typedef void
 376 (*GSF_LocalLookupContinuation) (void *cls,
 377                                 struct GSF_PendingRequest *pr,
 378                                 enum GNUNET_BLOCK_EvaluationResult result);
 379
 380
 381 /**
 382  * Look up the request in the local datastore.
 383  *
 384  * @param pr the pending request to process
 385  * @param cont function to call at the end
 386  * @param cont_cls closure for @a cont
 387  */
 388 void
 389 GSF_local_lookup_ (struct GSF_PendingRequest *pr,
 390                    GSF_LocalLookupContinuation cont,
 391                    void *cont_cls);
 392
 393
 394 /**
 395  * Is the given target a legitimate peer for forwarding the given request?
 396  *
 397  * @param pr request
 398  * @param target
 399  * @return #GNUNET_YES if this request could be forwarded to the given peer
 400  */
 401 int
 402 GSF_pending_request_test_target_ (struct GSF_PendingRequest *pr,
 403                                   const struct GNUNET_PeerIdentity *target);
 404
 405
 406
 407 /**
 408  * Setup the subsystem.
 409  */
 410 void
 411 GSF_pending_request_init_ (void);
 412
 413
 414 /**
 415  * Shutdown the subsystem.
 416  */
 417 void
 418 GSF_pending_request_done_ (void);
 419
 420
 421 #endif
 422 /* end of gnunet-service-fs_pr.h */