diff options
author | Christian Grothoff <christian@grothoff.org> | 2016-05-17 23:52:56 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2016-05-17 23:52:56 +0200 |
commit | 7db11d76da117e63822ebc02b2dd9c0d95186fa5 (patch) | |
tree | d857036e80e654c3b931cc5f716aecc3bacfee52 | |
parent | 2ab5ca586051afdf64a01994f40e8380c67ca90e (diff) | |
download | libbrandt-7db11d76da117e63822ebc02b2dd9c0d95186fa5.tar.gz libbrandt-7db11d76da117e63822ebc02b2dd9c0d95186fa5.zip |
comments
-rw-r--r-- | brandt.h | 92 |
1 files changed, 69 insertions, 23 deletions
@@ -22,7 +22,10 @@ | |||
22 | #ifndef _BRANDT_BRANDT_H | 22 | #ifndef _BRANDT_BRANDT_H |
23 | #define _BRANDT_BRANDT_H | 23 | #define _BRANDT_BRANDT_H |
24 | 24 | ||
25 | struct BRANDT_auction; | 25 | /** |
26 | * FIXME. | ||
27 | */ | ||
28 | struct BRANDT_Auction; | ||
26 | 29 | ||
27 | /** | 30 | /** |
28 | * Functions of this type are called by libbrandt to broadcast messages to the | 31 | * Functions of this type are called by libbrandt to broadcast messages to the |
@@ -35,9 +38,13 @@ struct BRANDT_auction; | |||
35 | * @param[in] msg The message to be broadcast to all participants of | 38 | * @param[in] msg The message to be broadcast to all participants of |
36 | * @a auction_closure. | 39 | * @a auction_closure. |
37 | * @param[in] msg_len The length of the message @a msg in bytes. | 40 | * @param[in] msg_len The length of the message @a msg in bytes. |
38 | * @return 1 on success, 0 on failure. | 41 | * @return 1 on success, 0 on failure. FIXME: unusual definition |
39 | */ | 42 | */ |
40 | typedef int (*BRANDT_cb_broadcast) (void *auction_closure, const void *msg, size_t msg_len); | 43 | typedef int |
44 | (*BRANDT_BroadcastCallback) (void *auction_closure, | ||
45 | const void *msg, | ||
46 | size_t msg_len); | ||
47 | |||
41 | 48 | ||
42 | /** | 49 | /** |
43 | * Functions of this type are called by libbrandt to unicast messages to the | 50 | * Functions of this type are called by libbrandt to unicast messages to the |
@@ -49,9 +56,13 @@ typedef int (*BRANDT_cb_broadcast) (void *auction_closure, const void *msg, size | |||
49 | * auction. This is the Pointer given to BRANDT_join(). | 56 | * auction. This is the Pointer given to BRANDT_join(). |
50 | * @param[in] msg The message to be sent to the seller of @a auction_closure. | 57 | * @param[in] msg The message to be sent to the seller of @a auction_closure. |
51 | * @param[in] msg_len The length of the message @a msg in bytes. | 58 | * @param[in] msg_len The length of the message @a msg in bytes. |
52 | * @return 1 on success, 0 on failure. | 59 | * @return 1 on success, 0 on failure. FIXME: unusual definition |
53 | */ | 60 | */ |
54 | typedef int (*BRANDT_cb_unicast_seller) (void *auction_closure, const void *msg, size_t msg_len); | 61 | typedef int |
62 | (*BRANDT_UnicastSellerCallback) (void *auction_closure, | ||
63 | const void *msg, | ||
64 | size_t msg_len); | ||
65 | |||
55 | 66 | ||
56 | /** | 67 | /** |
57 | * Functions of this type are called by libbrandt to report the auction outcome | 68 | * Functions of this type are called by libbrandt to report the auction outcome |
@@ -65,10 +76,18 @@ typedef int (*BRANDT_cb_unicast_seller) (void *auction_closure, const void *msg, | |||
65 | * @param[in] price The price, the winner has to pay or 0 if the auction result | 76 | * @param[in] price The price, the winner has to pay or 0 if the auction result |
66 | * is private and the user did not win. | 77 | * is private and the user did not win. |
67 | */ | 78 | */ |
68 | typedef void (*BRANDT_cb_report_result) (void *auction_closure, int won, uint16_t price); | 79 | typedef void |
80 | (*BRANDT_ReportResultCallback) (void *auction_closure, | ||
81 | int won, | ||
82 | uint16_t price); | ||
83 | // FIXME: the above callback does not work for the seller, | ||
84 | // but seems to be used for the seller right now. | ||
85 | // FIXME: also need way to be told about malicious/erroneous participants | ||
86 | |||
69 | 87 | ||
70 | /** | 88 | /** |
71 | * Join an auction described by the @a auction_data parameter. | 89 | * Join an auction described by the @a auction_data parameter. |
90 | * | ||
72 | * @param[in] broadcast Pointer to the broadcast callback function | 91 | * @param[in] broadcast Pointer to the broadcast callback function |
73 | * @param[in] unicast Pointer to the unicast callback function | 92 | * @param[in] unicast Pointer to the unicast callback function |
74 | * @param[in] report Pointer to the report callback function | 93 | * @param[in] report Pointer to the report callback function |
@@ -82,15 +101,28 @@ typedef void (*BRANDT_cb_report_result) (void *auction_closure, int won, uint16_ | |||
82 | * libbrandt functions when the client needs to refer to this auction. This is a | 101 | * libbrandt functions when the client needs to refer to this auction. This is a |
83 | * black-box pointer, do NOT access/change it or the data it points to! | 102 | * black-box pointer, do NOT access/change it or the data it points to! |
84 | */ | 103 | */ |
85 | const struct BRANDT_auction *BRANDT_join (BRANDT_cb_broadcast broadcast, | 104 | struct BRANDT_Auction * |
86 | BRANDT_cb_unicast_seller unicast, | 105 | BRANDT_join (BRANDT_BroadcastCallback broadcast, |
87 | BRANDT_cb_report_result report, | 106 | BRANDT_UnicastSellerCallback unicast, |
88 | const void *auction_closure, | 107 | BRANDT_ReportResultCallback report, |
89 | const void *auction_data, | 108 | const void *auction_closure, |
90 | size_t auction_data_len); | 109 | const void *auction_data, |
110 | size_t auction_data_len); | ||
111 | // FIXME: where do I specify my bid? | ||
112 | |||
91 | 113 | ||
114 | // FIXME: Distinguish handles for seller/buyers | ||
115 | // FIXME: have cancellation (BRANDT_join_cancel()) | ||
116 | // FIXME: provide means to extract a hash from auction data to | ||
117 | // tie cryptographic operations to application-readable proposal | ||
118 | // FIXME: have separate function to export 'out' variables | ||
119 | // FIXME: might want to specify timeout? How do we deal with time? | ||
120 | // FIXME: separate creating an auction from starting it; initial | ||
121 | // setup needs more auction proposal details (hash, timeout, | ||
122 | // bid structure), later we need to know # participants | ||
92 | /** | 123 | /** |
93 | * Create a new auction described by the @a auction_data parameter. | 124 | * Create a new auction described by the @a auction_data parameter. |
125 | * | ||
94 | * @param[in] broadcast Pointer to the broadcast callback function | 126 | * @param[in] broadcast Pointer to the broadcast callback function |
95 | * @param[in] report Pointer to the report callback function | 127 | * @param[in] report Pointer to the report callback function |
96 | * @param[in] auction_closure Closure pointer representing the auction. This | 128 | * @param[in] auction_closure Closure pointer representing the auction. This |
@@ -109,38 +141,52 @@ const struct BRANDT_auction *BRANDT_join (BRANDT_cb_broadcast broadcast, | |||
109 | * the price of the highest loosing bid. TODO: what if bidders < m? | 141 | * the price of the highest loosing bid. TODO: what if bidders < m? |
110 | * @param[in] outcome_public If 1, the auction winner and price will be public | 142 | * @param[in] outcome_public If 1, the auction winner and price will be public |
111 | * to all participants, if 0, this information will only be revealed to the | 143 | * to all participants, if 0, this information will only be revealed to the |
112 | * winner and the seller. | 144 | * winner and the seller. => FIXME: Turn into AuctionMode bit flag! |
113 | * @return A pointer, which should only be remembered and passed to | 145 | * @return A pointer, which should only be remembered and passed to |
114 | * libbrandt functions when the client needs to refer to this auction. This is a | 146 | * libbrandt functions when the client needs to refer to this auction. This is a |
115 | * black-box pointer, do NOT access/change it or the data it points to! | 147 | * black-box pointer, do NOT access/change it or the data it points to! |
116 | */ | 148 | */ |
117 | const struct BRANDT_auction *BRANDT_new (BRANDT_cb_broadcast broadcast, | 149 | struct BRANDT_Auction * |
118 | BRANDT_cb_report_result report, | 150 | BRANDT_new (BRANDT_BroadcastCallback broadcast, |
119 | const void *auction_closure, | 151 | BRANDT_ReportResultCallback report, |
120 | const void **auction_data, | 152 | const void *auction_closure, |
121 | size_t *auction_data_len, | 153 | const void **auction_data, |
122 | uint16_t num_prices, | 154 | size_t *auction_data_len, |
123 | uint16_t m, | 155 | uint16_t num_prices, |
124 | int outcome_public); | 156 | enum BRANDT_AuctionMode m, |
157 | int outcome_public); | ||
158 | |||
125 | 159 | ||
126 | /** | 160 | /** |
127 | * Receive a broadcast message related to a specific auction. | 161 | * Receive a broadcast message related to a specific auction. |
162 | * | ||
128 | * @param[in] auction The pointer returned by BRANDT_join() or BRANDT_new() from | 163 | * @param[in] auction The pointer returned by BRANDT_join() or BRANDT_new() from |
129 | * which message @a msg was received. | 164 | * which message @a msg was received. |
130 | * @param[in] msg The message that was received. | 165 | * @param[in] msg The message that was received. |
131 | * @param[in] msg_len The length in bytes of @a msg. | 166 | * @param[in] msg_len The length in bytes of @a msg. |
132 | */ | 167 | */ |
133 | void BRANDT_got_broadcast (struct BRANDT_auction *auction, void *msg, size_t msg_len); | 168 | void |
169 | BRANDT_got_broadcast (struct BRANDT_Auction *auction, | ||
170 | void *msg, | ||
171 | size_t msg_len); | ||
172 | |||
134 | 173 | ||
135 | /** | 174 | /** |
136 | * Receive a unicast message from a bidder related to a specific auction. | 175 | * Receive a unicast message from a bidder related to a specific auction. |
176 | * | ||
137 | * @param[in] auction The pointer returned by BRANDT_new() from which message | 177 | * @param[in] auction The pointer returned by BRANDT_new() from which message |
138 | * @a msg was received. | 178 | * @a msg was received. |
139 | * @param[in] msg The message that was received. | 179 | * @param[in] msg The message that was received. |
140 | * @param[in] msg_len The length in bytes of @a msg. | 180 | * @param[in] msg_len The length in bytes of @a msg. |
141 | * TODO: how to link message to sender id within auction? | 181 | * TODO: how to link message to sender id within auction? |
182 | * ANSWER: on start, know that we have 'n' participants, here give | ||
183 | * participant number (1..n) | ||
142 | */ | 184 | */ |
143 | void BRANDT_got_unicast (struct BRANDT_auction *auction, void *msg, size_t msg_len); | 185 | void |
186 | BRANDT_got_unicast (struct BRANDT_Auction *auction, | ||
187 | void *msg, | ||
188 | size_t msg_len); | ||
189 | |||
144 | 190 | ||
145 | ///TODO: Error handling functions? | 191 | ///TODO: Error handling functions? |
146 | 192 | ||