Statistics
| Branch: | Revision:

napa-baselibs / include / neighborlist.h @ 507372bb

History | View | Annotate | Download (3.11 KB)

1
#ifndef _NEIGHBORLIST_H
2
#define _NEIGHBORLIST_H
3

    
4
/** @file neighborlist.h
5
 *
6
 * @brief Neighbor List API.
7
 *
8
 * The NeighborList maintains a repository-based list of PeerIDs. These PeerIDs are periodically updated via
9
 * repository queries. Tuning of these queries is done via the NeighborList manager's API.
10
 * The list of PeerIDs provided by the NeighborList might be used to initialize one Peer's trading neighborhood,
11
 * or to extend it with PeerIDs obtained from Repositories (i.e. not via gossiping or other non-centralized manner).
12
 * Several intances of NeighborList might be running at the same time in order to facilitate different
13
 * Active Peer data for different channels. 
14
 * Typically one NeighborList is created for each channel.
15
 *
16
 * A background NeighborList process takes care of communicating the Repositories, and updating the list.
17
 * 
18
 */
19

    
20
#include        "napa.h"
21

    
22
/** A NeighborListEntry holds information for Peers in the NeighborList */
23
typedef struct {
24
        /** ID of the Peer */
25
        char peer[64];
26
        /** last time this entry was updated */
27
        struct timeval update_timestamp;
28
} NeighborListEntry;
29

    
30
/** Notifier callback for informing that the list has changed 
31

32
  @param h Handle to the NeighborList instance generating the notification.
33
  @param cbarg arbitrary user-provided parameter for the callback
34
*/
35
typedef void (*cb_NeighborListChange)(HANDLE rep, void *cbarg);
36

    
37
/**
38
  Initialize the NeighborList instance.
39

40
  @param[in] som a handle to repoclient instance to be used.
41
  @param[in] desired_size desired size of the NeighborList
42
  @param[in] update_freq how often (in seconds) should the list updated
43
  @param[in] channel channel filter (NULL for any channel)
44
  @param[in] notifier function to be called if the list changes (may be NULL)
45
  @param[in] notifier_arg cbarg to be passed on notifier call
46

47
  @returns a Handle to this instance.
48
*/
49
HANDLE neighborlist_init(HANDLE rep, int desired_size, int update_freq, const char *channel, cb_NeighborListChange notifier, void *notifier_arg);
50

    
51
/**
52
  Close this NeighborList instance and deallocate all associated resources.
53

54
  @param h Handle to the NeighborList instance to be closed.
55
*/
56
void neighborlist_close(HANDLE h);
57

    
58
/**
59
  Query a list of peers from the NeighborList.
60

61
  The function returns a COPY of the current NeighborList.
62
  @param[in] h Handle to the NeighborList instance.
63
  @param[in] result a sufficiently sized array to hold the results.
64
  @param n [in] return at most n records [out] the number of records returned.
65
  @return 0 on success, <0 on error
66
*/
67
int neighborlist_query(HANDLE h, NeighborListEntry *result, int *n);
68

    
69
/**
70
  Count the number of entries in the NeighborList.
71

72
  @param[in] h Handle to the NeighborList instance.
73
  @return number of NeighborList Entries the instance has.
74
*/
75
int neighborlist_count(HANDLE h);
76

    
77
/**
78
  Get the record for a given peer.
79

80
  @param[in] h Handle to the NeighborList instance.
81
  @param[in] peer PeerID of the peer to be queried.
82
  @param[out] result the corresponding NeighborListEntry is copied into the memory buffer provided.
83
  @return 1 if the record was found, 0 if not.
84
*/
85
int neighborlist_get(HANDLE h, char *peer, NeighborListEntry *result);
86

    
87
#endif