Statistics
| Branch: | Revision:

grapes / include / trade_sig_ha.h @ 5033613a

History | View | Annotate | Download (5.13 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, struct nodeID **owner_id,
45
                   struct chunkID_set **cset, int *max_deliver, int *trans_id,
46
                   enum signaling_type *sig_type);
47

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

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

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

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

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

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

    
128
#endif //TRADE_SIG_HA_H