aboutsummaryrefslogtreecommitdiff
path: root/brandt.h
diff options
context:
space:
mode:
Diffstat (limited to 'brandt.h')
-rw-r--r--brandt.h92
1 files changed, 69 insertions, 23 deletions
diff --git a/brandt.h b/brandt.h
index 28ae3ca..39c77ee 100644
--- a/brandt.h
+++ b/brandt.h
@@ -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
25struct BRANDT_auction; 25/**
26 * FIXME.
27 */
28struct 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 */
40typedef int (*BRANDT_cb_broadcast) (void *auction_closure, const void *msg, size_t msg_len); 43typedef 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 */
54typedef int (*BRANDT_cb_unicast_seller) (void *auction_closure, const void *msg, size_t msg_len); 61typedef 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 */
68typedef void (*BRANDT_cb_report_result) (void *auction_closure, int won, uint16_t price); 79typedef 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 */
85const struct BRANDT_auction *BRANDT_join (BRANDT_cb_broadcast broadcast, 104struct BRANDT_Auction *
86 BRANDT_cb_unicast_seller unicast, 105BRANDT_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 */
117const struct BRANDT_auction *BRANDT_new (BRANDT_cb_broadcast broadcast, 149struct BRANDT_Auction *
118 BRANDT_cb_report_result report, 150BRANDT_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 */
133void BRANDT_got_broadcast (struct BRANDT_auction *auction, void *msg, size_t msg_len); 168void
169BRANDT_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 */
143void BRANDT_got_unicast (struct BRANDT_auction *auction, void *msg, size_t msg_len); 185void
186BRANDT_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