Statistics
| Branch: | Revision:

grapes / include / trade_sig_ha.h @ f217ce38

History | View | Annotate | Download (5.94 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
/** Types of signalling message
17
  *
18
  * This enum is returned by parseSignaling, and describes the kind of
19
  * signalling message that has been parsed.
20
  */
21
enum signaling_type {
22
  sig_offer, sig_accept, sig_request, sig_deliver, sig_send_buffermap, sig_request_buffermap, sig_ack,
23
};
24

    
25
/**
26
 * @brief Set current node identifier.
27
 *
28
 * Initialize the node identifier of the peer
29
 *
30
 * @param[in] myID current node indentifier.
31
 * @return 1 on success, < 0 on error.
32
 */
33
int chunkSignalingInit(struct nodeID *myID);
34

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

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

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

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

    
94
/**
95
 * @brief Accept a (sub)set of chunks from a Peer.
96
 *
97
 * 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
98
 * (attempted to receive: i.e., the receiver peer would like to receive at most this number of Chunks from the set offered before).
99
 *
100
 * @param[in] to target peer to accept the ChunkIDs.
101
 * @param[in] cset array of ChunkIDs. 
102
 * @param[in] trans_id transaction number associated with this request.
103
 * @return 1 on success, <0 on error.
104
 */
105
int acceptChunks(const struct nodeID *localID, const struct nodeID *to, struct chunkID_set *cset, uint16_t trans_id);
106

    
107
/**
108
 * @brief Send a BufferMap to a Peer.
109
 *
110
 * Send (our own or some other peer's) BufferMap to a third Peer.
111
 *
112
 * @param[in] to PeerID.
113
 * @param[in] owner Owner of the BufferMap to send.
114
 * @param[in] bmap the BufferMap to send.
115
 * @param[in] cb_size the size of the chunk buffer (not the size of the buffer map sent, but that of the chunk buffer).
116
 * @param[in] trans_id transaction number associated with this send.
117
 * @return 1 Success, <0 on error.
118
 */
119
int sendBufferMap(const struct nodeID *localID, const struct nodeID *to, const struct nodeID *owner, struct chunkID_set *bmap, int cb_size, uint16_t trans_id);
120

    
121
/**
122
 * @brief Request a BufferMap to a Peer.
123
 *
124
 * Request (target peer or some other peer's) BufferMap to target Peer.
125
 *
126
 * @param[in] to PeerID.
127
 * @param[in] owner Owner of the BufferMap to request.
128
 * @param[in] trans_id transaction number associated with this request.
129
 * @return 1 Success, <0 on error.
130
 */
131
int requestBufferMap(const struct nodeID *localID, const struct nodeID *to, const struct nodeID *owner, uint16_t trans_id);
132

    
133
/**
134
 * @brief Send an Acknoledgement to a Peer.
135
 *
136
 * Send (our own or some other peer's) BufferMap to a third Peer.
137
 *
138
 * @param[in] to PeerID.
139
 * @param[in] cset array of ChunkIDs. 
140
 * @param[in] trans_id transaction number associated with this send.
141
 * @return 1 Success, <0 on error.
142
 */
143
int sendAck(const struct nodeID *localID, const struct nodeID *to, struct chunkID_set *cset, uint16_t trans_id);
144

    
145
#endif //TRADE_SIG_HA_H