grapes / include / peerset.h @ 82438fe3
History | View | Annotate | Download (3.67 KB)
1 |
/** @file peerset.h
|
---|---|
2 |
*
|
3 |
* @brief Structure containing a set of peers.
|
4 |
*
|
5 |
* The Peer Set is an abstract data structure that can contain a set of
|
6 |
* peer structures. It handles peers by their nodeIDs. Peer structures
|
7 |
* are created and accessed based on their nodeID (i.e. unique address).
|
8 |
*
|
9 |
*/
|
10 |
|
11 |
#ifndef PEERSET_H
|
12 |
#define PEERSET_H
|
13 |
|
14 |
|
15 |
/**
|
16 |
* Opaque data type representing a Peer Set
|
17 |
*/
|
18 |
typedef struct peerset PeerSet; |
19 |
|
20 |
/**
|
21 |
* @brief Allocate a peer set.
|
22 |
*
|
23 |
* Create an empty peer set, and return a pointer to it.
|
24 |
*
|
25 |
* @param config a string containing tags which describe the peerset.
|
26 |
* For example, the "size" tag indicates the expected
|
27 |
* number of peers that will be stored in the set;
|
28 |
* 0 or not present if such a number is not known.
|
29 |
* @return the pointer to the new set on success, NULL on error
|
30 |
*/
|
31 |
struct peerset *peerset_init(const char *config); |
32 |
|
33 |
/**
|
34 |
* @brief Add a peer to the set.
|
35 |
*
|
36 |
* Insert a peer to the set, creating the peer structure. If the peer
|
37 |
* is already in the set, nothing happens.
|
38 |
*
|
39 |
* @param h a pointer to the set where the peer has to be added
|
40 |
* @param id the ID of the peer to be inserted in the set
|
41 |
* @return > 0 if the peer is correctly inserted in the set, 0 if a peer with
|
42 |
* the same nodeID is already in the set, < 0 on error
|
43 |
*/
|
44 |
int peerset_add_peer(struct peerset *h, struct nodeID *id); |
45 |
|
46 |
/**
|
47 |
* @brief Add peers to the set.
|
48 |
*
|
49 |
* Comodity function to add several peers at the same time to the set.
|
50 |
* See peerset_add_peer
|
51 |
*
|
52 |
* @param h a pointer to the set where the peer has to be added
|
53 |
* @param ids the IDs of the peers to be inserted in the set
|
54 |
* @param n length of the its array
|
55 |
*/
|
56 |
void peerset_add_peers(struct peerset *h, struct nodeID **ids, int n); |
57 |
|
58 |
/**
|
59 |
* @brief Remove a peer from the set.
|
60 |
*
|
61 |
* Remove a peer from the set, distroying all associated data.
|
62 |
* If peer exists, pointers of peerset_get_peers move backwards.
|
63 |
*
|
64 |
* @param h a pointer to the set where the peer has to be added
|
65 |
* @param id the ID of the peer to be removed from the set
|
66 |
* @return > 0 if the peer is correctly removed from the set,
|
67 |
* < 0 on error
|
68 |
*/
|
69 |
int peerset_remove_peer(struct peerset *h, const struct nodeID *id); |
70 |
|
71 |
/**
|
72 |
* @brief Get a peer if it is in the set
|
73 |
*
|
74 |
* @param h a pointer to the set
|
75 |
* @param id the nodeID we are searching for
|
76 |
* @return a pointer to the peer if it is present in the set,
|
77 |
* NULL if the peer is not in the set
|
78 |
*/
|
79 |
struct peer *peerset_get_peer(const struct peerset *h, const struct nodeID *id); |
80 |
|
81 |
/**
|
82 |
* @brief Get the set size
|
83 |
*
|
84 |
* Return the number of peers present in a set.
|
85 |
*
|
86 |
* @param h a pointer to the set
|
87 |
* @return the number of peers in the set, or < 0 on error
|
88 |
*/
|
89 |
int peerset_size(const struct peerset *h); |
90 |
|
91 |
/**
|
92 |
* @brief Get a peer from a set
|
93 |
*
|
94 |
* Return the peers of the set. The peer's priority is
|
95 |
* assumed to depend on i.
|
96 |
*
|
97 |
* @param h a pointer to the set
|
98 |
* @return the list of peer structures
|
99 |
*/
|
100 |
struct peer **peerset_get_peers(const struct peerset *h); |
101 |
|
102 |
/**
|
103 |
* @brief Check if a peer is in a set
|
104 |
*
|
105 |
* @param h a pointer to the set
|
106 |
* @param id the nodeID we are searching for
|
107 |
* @return the position of the peer if it is present in the set,
|
108 |
* < 0 on error or if the peer is not in the set
|
109 |
*/
|
110 |
int peerset_check(const struct peerset *h, const struct nodeID *id); |
111 |
|
112 |
|
113 |
/**
|
114 |
* @brief Clear a set
|
115 |
*
|
116 |
* Remove all the peers from a set.
|
117 |
*
|
118 |
* @param h a pointer to the set
|
119 |
* @param size the expected number of peers that will be stored
|
120 |
* in the set; 0 if such a number is not known.
|
121 |
*/
|
122 |
void peerset_clear(struct peerset *h, int size); |
123 |
|
124 |
#endif /* PEERSET_H */ |