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