Statistics
| Branch: | Revision:

grapes / include / topmanager.h @ a31e4a4b

History | View | Annotate | Download (3.35 KB)

1
#ifndef TOPMAN_H
2
#define TOPMAN_H
3

    
4
/** @file topmanager.h 
5
 *
6
 * This is the Topology Manager interface. See @link topology_test.c
7
 * topology_test.c @endlink for an usage example
8
 *
9
 */
10

    
11
/** @example topology_test.c
12
 * 
13
 * A test program showing how to use the Topology Manager API.
14
 *
15
 */
16

    
17

    
18
/**
19
  @brief Get the peer's neighbourhood.
20

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

26
  @param n pointer to an integer where the neighbourhood size is returned.
27
           Is set to -1 in case of error, or 0 if the neighbourhood is empty.
28
  @return a pointer to an array of nodeID describing the neighbourhood. NULL
29
          in case of error, or if the neighbourhood is empty.
30
*/
31
const struct nodeID **topGetNeighbourhood(int *n);
32

    
33
/**
34
  @brief Increase the neighbourhood size.
35

36
  This function can be used to increase the number of neighbours (that is,
37
       the degree of the overlay graph) by a specified amount.
38
  @param n number of peers by which the neighbourhood size must be incremented.
39
  @return the new neighbourhood size in case of success; -1 in case of error.
40
*/
41
int topGrowNeighbourhood(int n);
42

    
43
/**
44
  @brief Decrease the neighbourhood size.
45

46
  This function can be used to reduce the number of neighbours (that is,
47
       the degree of the overlay graph) by a specified amount.
48
  @param n number of peers by which the neighbourhood size must be decreased.
49
  @return the new neighbourhood size in case of success; -1 in case of error.
50
*/
51
int topShrinkNeighbourhood(int n);
52

    
53
/**
54
  @brief Remove a peer from the neighbourhood.
55

56
  This function can be used to remove a specified neighbour from the
57
  neighbourhood. Note that the requested neighbourhood size is not
58
  modified, so the peer will be soon replaced by a different one.
59
  @param neighbour the id of the peer to be removed from the
60
         neighbourhood.
61
  @return 0 in case of success; -1 in case of error.
62
*/
63
int topRemoveNeighbour(struct nodeID *neighbour);
64

    
65
/**
66
  @brief Initialise the Topology Manager.
67

68
  @param myID the ID of this peer.
69
  @return 0 in case of success; -1 in case of error.
70
*/
71
int topInit(struct nodeID *myID);
72

    
73

    
74
/**
75
  @brief Insert a peer in the neighbourhood.
76

77
  This function can be used to add a specified neighbour to the
78
  neighbourhood. It is useful in the bootstrap phase.
79
  @param neighbour the id of the peer to be added to the
80
         neighbourhood.
81
  @return 0 in case of success; -1 in case of error.
82
*/
83
int topAddNeighbour(struct nodeID *neighbour);
84

    
85
/**
86
  @brief Pass a received packet to the Topology Manager.
87

88
  This function passes to the Topology Manager a packet that has
89
  been received from the network. The Topology Manager will parse
90
  such packet and run the protocol, adding or removing peers to the
91
  neighbourhood, and sending overlay management messages to other peers.
92
  @param buff a memory buffer containing the received message.
93
  @param len the size of such a memory buffer.
94
  @return 0 in case of success; -1 in case of error.
95
*/
96
int topParseData(const uint8_t *buff, int len);
97

    
98
/*
99
//const struct peer* topGetNeighbour(PeerID?) ???
100
//void topRegAddListener(void (*NewNeighbourCB)(const struct peer ))
101
//void topRegDelListener(void (*DeadNeighbourCB)(const struct peer ))
102
*/
103

    
104
#endif /* TOPMAN_H */