src/fs/gnunet-service-fs_pr.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2010 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  * Generate the message corresponding to the given pending request for
 124  * transmission to other peers (or at least determine its size).
 125  *
 126  * @param pr request to generate the message for
 127  * @param buf_size number of bytes available in buf
 128  * @param buf where to copy the message (can be NULL)
 129  * @return number of bytes needed (if > buf_size) or used
 130  */
 131 size_t
 132 GSF_pending_request_get_message_ (struct GSF_PendingRequest *pr,
 133                                   size_t buf_size,
 134                                   void *buf);
 135
 136
 137 /**
 138  * Explicitly cancel a pending request.
 139  *
 140  * @param pr request to cancel
 141  */
 142 void
 143 GSF_pending_request_cancel_ (struct GSF_PendingRequest *pr);
 144
 145
 146 /**
 147  * Signature of function called on each request.
 148  *
 149  * @param cls closure
 150  * @param key query for the request
 151  * @param pr handle to the pending request
 152  */
 153 typedef int (*GSF_PendingRequestIterator)(void *cls,
 154                                           const GNUNET_HashCode *key,
 155                                           struct GSF_PendingRequest *pr);
 156
 157
 158 /**
 159  * Iterate over all pending requests.
 160  *
 161  * @param it function to call for each request
 162  * @param cls closure for it
 163  */
 164 void
 165 GSF_iterate_pending_requests_ (GSF_PendingRequestIterator it,
 166                                void *cls);
 167
 168
 169
 170 /**
 171  * Register callback to invoke on request destruction.
 172  *
 173  * @param pr request to monitor
 174  * @param it function to call on destruction
 175  * @param it_cls closure for it
 176  */
 177 void
 178 GSF_pending_request_register_destroy_callback_ (struct GSF_PendingRequest *pr,
 179                                        GSF_PendingRequestIterator it,
 180                                        void *it_cls);
 181
 182
 183 /**
 184  * Unregister callback to invoke on request destruction.
 185  *
 186  * @param pr request to stop monitoring
 187  * @param it function to no longer call on destruction
 188  * @param it_cls closure for it
 189  */
 190 void
 191 GSF_pending_request_unregister_destroy_callback_ (struct GSF_PendingRequest *pr,
 192                                                   GSF_PendingRequestIterator it,
 193                                                   void *it_cls);
 194
 195
 196 #endif
 197 /* end of gnunet-service-fs_pr.h */