Statistics
| Branch: | Revision:

grapes / include / topmanager.h @ edd2bc82

History | View | Annotate | Download (5.2 KB)

1 480921a6 Luca Abeni
#ifndef TOPMAN_H
2
#define TOPMAN_H
3 73ff9d3b Luca Abeni
4
/** @file topmanager.h 
5
 *
6
 * @brief Topology Manager interface.
7
 *
8
 * This is the Topology Manager interface. See @link topology_test.c
9
 * topology_test.c @endlink for an usage example
10
 *
11
 */
12
13
/** @example topology_test.c
14
 * 
15
 * A test program showing how to use the Topology Manager API.
16
 *
17
 */
18
19
20
/**
21
  @brief Get the peer's neighbourhood.
22

23
  This function returns the current neighbourhood (i.e., the set of
24
  known peers) of a peer, and its size. Note that the current neighbourhood
25
  size can be different from the requested one, because of how the overlay
26
  management protocols work. 
27

28
  @param n pointer to an integer where the neighbourhood size is returned.
29
           Is set to -1 in case of error, or 0 if the neighbourhood is empty.
30
  @return a pointer to an array of nodeID describing the neighbourhood. NULL
31
          in case of error, or if the neighbourhood is empty.
32
*/
33 651ed37d Luca
const struct nodeID **topGetNeighbourhood(int *n);
34 4d9b08d1 Luca Abeni
35
/**
36
  @brief Get the peer's metadata.
37

38
  Each peer in the neighbourhood can have some opaque metadata attached to
39
  it, and such metadata is gossiped together with the nodeIDs.
40
  This function returns the metadata currently associated to the
41
  neighbours of a peer, and the size of each object composing the metadata
42
  (metadata have the same structure for all the peers, so such size is
43
  constant). The neighbourhood size can be known by calling
44
  topGetNeighbourhood().
45

46
  @param metadata_size pointer to an integer where the size of the metadata
47
         associated to each peer is returned.
48
         Is set to -1 in case of error, or 0 if the neighbourhood is empty.
49
  @return a pointer to an array of metadata (ordered as the peers returned
50
          by topGetNeighbourhood()).
51
          NULL in case of error, or if the neighbourhood is empty.
52
*/
53 49121eee Luca Abeni
const void *topGetMetadata(int *metadata_size);
54 73ff9d3b Luca Abeni
55
/**
56
  @brief Increase the neighbourhood size.
57

58
  This function can be used to increase the number of neighbours (that is,
59
       the degree of the overlay graph) by a specified amount.
60
  @param n number of peers by which the neighbourhood size must be incremented.
61
  @return the new neighbourhood size in case of success; -1 in case of error.
62
*/
63 480921a6 Luca Abeni
int topGrowNeighbourhood(int n);
64 73ff9d3b Luca Abeni
65
/**
66
  @brief Decrease the neighbourhood size.
67

68
  This function can be used to reduce the number of neighbours (that is,
69
       the degree of the overlay graph) by a specified amount.
70
  @param n number of peers by which the neighbourhood size must be decreased.
71
  @return the new neighbourhood size in case of success; -1 in case of error.
72
*/
73 480921a6 Luca Abeni
int topShrinkNeighbourhood(int n);
74 73ff9d3b Luca Abeni
75
/**
76
  @brief Remove a peer from the neighbourhood.
77

78
  This function can be used to remove a specified neighbour from the
79
  neighbourhood. Note that the requested neighbourhood size is not
80
  modified, so the peer will be soon replaced by a different one.
81
  @param neighbour the id of the peer to be removed from the
82
         neighbourhood.
83
  @return 0 in case of success; -1 in case of error.
84
*/
85 651ed37d Luca
int topRemoveNeighbour(struct nodeID *neighbour);
86 b4b86e94 Luca Abeni
87 a40a8d81 MarcoBiazzini
88
/**
89
  @brief Change the metadata.
90

91
  This function can be used to modify/update the metadata for a
92
  peer. Because of security concerns, only the metadata for the
93
  local peer can be modified.
94
  @param peer the id of the peer for which the metadata should be updated
95
         (only the local peer is acceptable).
96
  @param metadata pointer to the new metadata associated to the peer (will be
97
         gossiped).
98
  @param metadata_size size of the metadata associated to the peer (must
99
         be the same as for the other peers).
100
  @return 0 in case of success; -1 in case of error.
101
*/
102 90cea048 Luca
int topChangeMetadata(struct nodeID *peer, void *metadata, int metadata_size);
103 b4b86e94 Luca Abeni
104 73ff9d3b Luca Abeni
/**
105
  @brief Initialise the Topology Manager.
106

107
  @param myID the ID of this peer.
108 4d9b08d1 Luca Abeni
  @param metadata pointer to the metadata associated to this peer (will be
109
         gossiped).
110
  @param metadata_size size of the metadata associated to this peer.
111 73ff9d3b Luca Abeni
  @return 0 in case of success; -1 in case of error.
112
*/
113 04df3b0f Luca
int topInit(struct nodeID *myID, void *metadata, int metadata_size, const char *config);
114 73ff9d3b Luca Abeni
115
/**
116
  @brief Insert a peer in the neighbourhood.
117

118
  This function can be used to add a specified neighbour to the
119
  neighbourhood. It is useful in the bootstrap phase.
120
  @param neighbour the id of the peer to be added to the
121
         neighbourhood.
122 4d9b08d1 Luca Abeni
  @param metadata pointer to the metadata associated to the new peer (will be
123
         gossiped).
124
  @param metadata_size size of the metadata associated to the new peer (must
125
         be the same as for the other peers).
126 73ff9d3b Luca Abeni
  @return 0 in case of success; -1 in case of error.
127
*/
128 005954ae Luca Abeni
int topAddNeighbour(struct nodeID *neighbour, void *metadata, int metadata_size);
129 73ff9d3b Luca Abeni
130
/**
131
  @brief Pass a received packet to the Topology Manager.
132

133
  This function passes to the Topology Manager a packet that has
134
  been received from the network. The Topology Manager will parse
135
  such packet and run the protocol, adding or removing peers to the
136
  neighbourhood, and sending overlay management messages to other peers.
137
  @param buff a memory buffer containing the received message.
138
  @param len the size of such a memory buffer.
139
  @return 0 in case of success; -1 in case of error.
140
*/
141 b4b86e94 Luca Abeni
int topParseData(const uint8_t *buff, int len);
142
143 480921a6 Luca Abeni
#endif /* TOPMAN_H */