src/fs/gnunet-service-fs_pr.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2010, 2011 Christian Grothoff (and other contributing authors)
   4
   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.
   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      General Public License for more details.
  14
  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.
  19 */
  20
  21 /**
  22  * @file fs/gnunet-service-fs_pr.h
  23  * @brief API to handle pending requests
  24  * @author Christian Grothoff
  25  */
  26 #ifndef GNUNET_SERVICE_FS_PR_H
  27 #define GNUNET_SERVICE_FS_PR_H
  28
  29 #include "gnunet-service-fs.h"
  30
  31
  32 /**
  33  * Options for pending requests (bits to be ORed).
  34  */
  35 enum GSF_PendingRequestOptions
  36   {
  37     /**
  38      * Request must only be processed locally.
  39      */
  40     GSF_PRO_LOCAL_ONLY = 1,
  41
  42     /**
  43      * Request must only be forwarded (no routing)
  44      */
  45     GSF_PRO_FORWARD_ONLY = 2,
  46
  47     /**
  48      * Request persists indefinitely (no expiration).
  49      */
  50     GSF_PRO_REQUEST_EXPIRES = 4,
  51
  52     /**
  53      * Request is allowed to refresh bloomfilter and change mingle value.
  54      */
  55     GSF_PRO_BLOOMFILTER_FULL_REFRESH = 8,
  56
  57     /**
  58      * Request priority is allowed to be exceeded.
  59      */
  60     GSF_PRO_PRIORITY_UNLIMITED = 16,
  61
  62     /**
  63      * Option mask for typical local requests.
  64      */
  65     GSF_PRO_LOCAL_REQUEST = (GSF_PRO_BLOOMFILTER_FULL_REFRESH | GSF_PRO_PRIORITY_UNLIMITED)
  66   };
  67
  68
  69 /**
  70  * Handle a reply to a pending request.  Also called if a request
  71  * expires (then with data == NULL).  The handler may be called
  72  * many times (depending on the request type), but will not be
  73  * called during or after a call to GSF_pending_request_cancel
  74  * and will also not be called anymore after a call signalling
  75  * expiration.
  76  *
  77  * @param cls user-specified closure
  78  * @param pr handle to the original pending request
  79  * @param data response data, NULL on request expiration
  80  * @param data_len number of bytes in data
  81  */
  82 typedef void (*GSF_PendingRequestReplyHandler)(void *cls,
  83                                                struct GSF_PendingRequest *pr,
  84                                                const void *data,
  85                                                size_t data_len);
  86
  87
  88 /**
  89  * Create a new pending request.
  90  *
  91  * @param options request options
  92  * @param type type of the block that is being requested
  93  * @param query key for the lookup
  94  * @param namespace namespace to lookup, NULL for no namespace
  95  * @param target preferred target for the request, NULL for none
  96  * @param bf bloom filter for known replies, can be NULL
  97  * @param mingle mingle value for bf
  98  * @param anonymity_level desired anonymity level
  99  * @param priority maximum outgoing cummulative request priority to use
 100  * @param replies_seen hash codes of known local replies
 101  * @param replies_seen_count size of the 'replies_seen' array
 102  * @param rh handle to call when we get a reply
 103  * @param rh_cls closure for rh
 104  * @return handle for the new pending request
 105  */
 106 struct GSF_PendingRequest *
 107 GSF_pending_request_create_ (enum GSF_PendingRequestOptions options,
 108                              enum GNUNET_BLOCK_Type type,
 109                              const GNUNET_HashCode *query,
 110                              const GNUNET_HashCode *namespace,
 111                              const struct GNUNET_PeerIdentity *target,
 112                              struct GNUNET_CONTAINER_BloomFilter *bf,
 113                              int32_t mingle,
 114                              uint32_t anonymity_level,
 115                              uint32_t priority,
 116                              const GNUNET_HashCode *replies_seen,
 117                              unsigned int replies_seen_count,
 118                              GSF_PendingRequestReplyHandler rh,
 119                              void *rh_cls);
 120
 121
 122 /**
 123  * Update a given pending request with additional replies
 124  * that have been seen.
 125  *
 126  * @param pr request to update
 127  * @param replies_seen hash codes of replies that we've seen
 128  * @param replies_seen_count size of the replies_seen array
 129  */
 130 void
 131 GSF_pending_request_update_ (struct GSF_PendingRequest *pr,
 132                              const GNUNET_HashCode *replies_seen,
 133                              unsigned int replies_seen_count);
 134
 135
 136 /**
 137  * Get the query for a given pending request.
 138  *
 139  * @param pr the request
 140  * @return pointer to the query (only valid as long as pr is valid)
 141  */
 142 const GNUNET_HashCode *
 143 GSF_pending_request_get_query_ (const struct GSF_PendingRequest *pr);
 144
 145
 146 /**
 147  * Get the type of a given pending request.
 148  *
 149  * @param pr the request
 150  * @return query type
 151  */
 152 enum GNUNET_BLOCK_Type
 153 GSF_pending_request_get_type_ (const struct GSF_PendingRequest *pr);
 154
 155
 156 /**
 157  * Generate the message corresponding to the given pending request for
 158  * transmission to other peers (or at least determine its size).
 159  *
 160  * @param pr request to generate the message for
 161  * @param buf_size number of bytes available in buf
 162  * @param buf where to copy the message (can be NULL)
 163  * @return number of bytes needed (if > buf_size) or used
 164  */
 165 size_t
 166 GSF_pending_request_get_message_ (struct GSF_PendingRequest *pr,
 167                                   size_t buf_size,
 168                                   void *buf);
 169
 170
 171 /**
 172  * Explicitly cancel a pending request.
 173  *
 174  * @param pr request to cancel
 175  */
 176 void
 177 GSF_pending_request_cancel_ (struct GSF_PendingRequest *pr);
 178
 179
 180 /**
 181  * Signature of function called on each request.
 182  *
 183  * @param cls closure
 184  * @param key query for the request
 185  * @param pr handle to the pending request
 186  */
 187 typedef int (*GSF_PendingRequestIterator)(void *cls,
 188                                           const GNUNET_HashCode *key,
 189                                           struct GSF_PendingRequest *pr);
 190
 191
 192 /**
 193  * Iterate over all pending requests.
 194  *
 195  * @param it function to call for each request
 196  * @param cls closure for it
 197  */
 198 void
 199 GSF_iterate_pending_requests_ (GSF_PendingRequestIterator it,
 200                                void *cls);
 201
 202
 203
 204 #endif
 205 /* end of gnunet-service-fs_pr.h */