Statistics
| Branch: | Revision:

grapes / include / trade_sig_ha.h @ 2d4f54d6

History | View | Annotate | Download (5 KB)

1
/** @file trade_sig_ha.h
2
 *
3
 * @brief Chunk Signaling API - Higher Abstraction (HA).
4
 *
5
 * The trade signaling HA provides a set of primitives for chunks signaling negotiation with other peers, in order to collect information for the effective chunk exchange with other peers. This is a part of the Data Exchange Protocol which provides high level abstraction for chunks' negotiations, like requesting and proposing chunks.
6
 *
7
 */
8

    
9

    
10
#ifndef TRADE_SIG_HA_H
11
#define TRADE_SIG_HA_H
12

    
13
#include "net_helper.h"
14
#include "chunkidset.h"
15

    
16
enum signaling_type {
17
  sig_offer, sig_accept, sig_request, sig_deliver, sig_send_buffermap, sig_request_buffermap
18
};
19

    
20
/**
21
 * @brief Set current node identifier.
22
 *
23
 * Initialize the node identifier of the peer
24
 *
25
 * @param[in] current node indentifier.
26
 * @return 1 on success, <0 on error.
27
 */
28
int chunkSignalingInit(struct nodeID *myID);
29

    
30
/**
31
 * @brief Parse an incoming signaling message, providing the signal type and the information of the signaling message.
32
 *
33
 * Parse an incoming signaling message provided in the buffer, giving the information of the message received.
34
 *
35
 * @param[in] buffer containing the incoming message.
36
 * @param[in] buff_len length of the buffer.
37
 * @param[out] owner_id identifier of the node on which refer the message just received.
38
 * @param[out] cset array of chunkIDs.
39
 * @param[out] max_deliver deliver at most this number of Chunks.
40
 * @param[out] trans_id transaction number associated with this message.
41
 * @param[out] sig_type Type of signaling message.
42
 * @return 1 on success, <0 on error.
43
 */
44
int parseSignaling(uint8_t *buff, int buff_len, const struct nodeID *owner_id, struct chunkID_set **cset,
45
        int *max_deliver, int *trans_id, int *sig_type);
46

    
47
/**
48
 * @brief Request a set of chunks from a Peer.
49
 *
50
 * Request a set of Chunks towards a Peer, and specify the  maximum number of Chunks attempted to receive
51
 * (i.e., the number of chunks the destination peer would like to receive among those requested).
52
 *
53
 * @param[in] to target peer to request the ChunkIDs from.
54
 * @param[in] cset array of ChunkIDs.
55
 * @param[in] max_deliver deliver at most this number of Chunks.
56
 * @param[in] trans_id transaction number associated with this request.
57
 * @return 1 on success, <0 on error.
58
 */
59
int requestChunks(const struct nodeID *to, const struct chunkID_set *cset, int max_deliver, int trans_id);
60

    
61
/**
62
 * @brief Deliver a set of Chunks to a Peer as a reply of its previous request of Chunks.
63
 *
64
 * Announce to the Peer which sent a request of a set of Chunks, that we have these chunks (sub)set available
65
 * among all those requested and willing to deliver them.
66
 *
67
 * @param[in] to target peer to which deliver the ChunkIDs.
68
 * @param[in] cset array of ChunkIDs.  
69
 * @param[in] trans_id transaction number associated with this request.
70
 * @return 1 on success, <0 on error.
71
 */
72
int deliverChunks(const struct nodeID *to, struct chunkID_set *cset, int trans_id);
73

    
74
/**
75
 * @brief Offer a (sub)set of chunks to a Peer.
76
 *
77
 * Initiate a offer for a set of Chunks towards a Peer, and specify the  maximum number of Chunks attempted to deliver
78
 * (attempted to deliver: i.e., the sender peer should try to send at most this number of Chunks from the set).
79
 *
80
 * @param[in] to target peer to offer the ChunkIDs.
81
 * @param[in] cset array of ChunkIDs.
82
 * @param[in] max_deliver deliver at most this number of Chunks.
83
 * @param[in] trans_id transaction number associated with this request.
84
 * @return 1 on success, <0 on error.
85
 */
86
int offerChunks(const struct nodeID *to, struct chunkID_set *cset, int max_deliver, int trans_id);
87

    
88
/**
89
 * @brief Accept a (sub)set of chunks from a Peer.
90
 *
91
 * Announce to accept a (sub)set of Chunks from a Peer which sent a offer before, and specify the  maximum number of Chunks attempted to receive
92
 * (attempted to receive: i.e., the receiver peer would like to receive at most this number of Chunks from the set offered before).
93
 *
94
 * @param[in] to target peer to accept the ChunkIDs.
95
 * @param[in] cset array of ChunkIDs. 
96
 * @param[in] trans_id transaction number associated with this request.
97
 * @return 1 on success, <0 on error.
98
 */
99
int acceptChunks(const struct nodeID *to, struct chunkID_set *cset, int trans_id);
100

    
101
/**
102
 * @brief Send a BufferMap to a Peer.
103
 *
104
 * Send (our own or some other peer's) BufferMap to a third Peer.
105
 *
106
 * @param[in] to PeerID.
107
 * @param[in] owner Owner of the BufferMap to send.
108
 * @param[in] bmap the BufferMap to send.
109
 * @param[in] trans_id transaction number associated with this send.
110
 * @return 1 Success, <0 on error.
111
 */
112
int sendBufferMap(const struct nodeID *to, const struct nodeID *owner, struct chunkID_set *bmap, int trans_id);
113

    
114
/**
115
 * @brief Request a BufferMap to a Peer.
116
 *
117
 * Request (target peer or some other peer's) BufferMap to target Peer.
118
 *
119
 * @param[in] to PeerID.
120
 * @param[in] owner Owner of the BufferMap to request.
121
 * @param[in] trans_id transaction number associated with this request.
122
 * @return 1 Success, <0 on error.
123
 */
124
int requestBufferMap(const struct nodeID *to, const struct nodeID *owner, int trans_id);
125

    
126
#endif //TRADE_SIG_HA_H