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 */ |