summaryrefslogtreecommitdiff
path: root/src/transport/gnunet-service-transport_validation.h
blob: 0d6e0ef5aeed2fb02e40ebad18e99a924eacfd35 (plain)
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
/*
     This file is part of GNUnet.
     (C) 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 transport/gnunet-service-transport_validation.h
 * @brief address validation API
 * @author Christian Grothoff
 */
#ifndef GNUNET_SERVICE_TRANSPORT_VALIDATION_H
#define GNUNET_SERVICE_TRANSPORT_VALIDATION_H

#include "gnunet_statistics_service.h"
#include "gnunet_util_lib.h"


/**
 * Start the validation subsystem.
 */
void 
GST_validation_start (void);


/**
 * Stop the validation subsystem.
 */
void
GST_validation_stop (void);


/**
 * We've received a PING.  If appropriate, generate a PONG.
 *
 * @param sender peer sending the PING
 * @param hdr the PING
 * @param plugin_name name of plugin that received the PING
 * @param sender_address address of the sender as known to the plugin, NULL
 *                       if we did not initiate the connection
 * @param sender_address_len number of bytes in sender_address
 */
void
GST_validation_handle_ping (const struct GNUNET_PeerIdentity *sender,
			    const struct GNUNET_MessageHeader *hdr,
			    const char *plugin_name,
			    const void *sender_address,
			    size_t sender_address_len);


/**
 * We've received a PONG.  Check if it matches a pending PING and
 * mark the respective address as confirmed.
 *
 * @param sender peer sending the PONG
 * @param hdr the PONG
 * @param plugin_name name of plugin that received the PONG
 * @param sender_address address of the sender as known to the plugin, NULL
 *                       if we did not initiate the connection
 * @param sender_address_len number of bytes in sender_address
 */
void
GST_validation_handle_pong (const struct GNUNET_PeerIdentity *sender,
			    const struct GNUNET_MessageHeader *hdr,
			    const char *plugin_name,
			    const void *sender_address,
			    size_t sender_address_len);


/**
 * We've received a HELLO, check which addresses are new and trigger
 * validation.
 *
 * @param hello the HELLO we received
 */
void
GST_validation_handle_hello (const struct GNUNET_MessageHeader *hello);


/**
 * Opaque handle to stop incremental validation address callbacks.
 */
struct GST_ValidationIteratorContext;


/**
 * Function called for each address (or address status change) that
 * the validation module is aware of (for the given target).
 *
 * @param cls closure
 * @param target peer this change is about, never NULL
 * @param last_validated_at is FOREVER if the address has not been validated (we're currently checking)
 *                          is ZERO if the address was validated a long time ago (from PEERINFO)
 *                          is a time in the past if this process validated the address
 * @param validation_block  is FOREVER if the address is for an unsupported plugin (from PEERINFO)
 *                          is ZERO if the address is considered valid (no validation needed)
 *                          is a time in the future if we're currently denying re-validation
 * @param plugin_name name of the plugin
 * @param plugin_address binary address
 * @param plugin_address_len length of address
 */
typedef void (*GST_ValidationAddressCallback)(void *cls,
					      const struct GNUNET_PeerIdentity *target,
					      struct GNUNET_TIME_Absolute last_validated_at,
					      struct GNUNET_TIME_Absolute validation_block,
					      const char *plugin_name,
					      const void *plugin_address,
					      size_t plugin_address_len);


/**
 * Call the given function for each address for the given target.
 * Can either give a snapshot (synchronous API) or be continuous.
 *
 * @param target peer information is requested for
 * @param snapshot_only GNUNET_YES to iterate over addresses once, GNUNET_NO to
 *                      continue to give information about addresses as it evolves
 * @param cb function to call; will not be called after this function returns
 *                             if snapshot_only is GNUNET_YES
 * @param cb_cls closure for 'cb'
 * @return context to cancel, NULL if 'snapshot_only' is GNUNET_YES
 */
struct GST_ValidationIteratorContext *
GST_validation_get_addresses (const struct GNUNET_PeerIdentity *target,
			      int snapshot_only,
			      GST_ValidationAddressCallback cb,
			      void *cb_cls);


/**
 * Cancel an active validation address iteration.
 *
 * @param ctx the context of the operation that is cancelled
 */
void
GST_validation_get_addresses_cancel (struct GST_ValidationIteratorContext *ctx);



#endif
/* end of file gnunet-service-transport_validation.h */