From 7db11d76da117e63822ebc02b2dd9c0d95186fa5 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 17 May 2016 23:52:56 +0200 Subject: comments --- brandt.h | 92 ++++++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 69 insertions(+), 23 deletions(-) (limited to 'brandt.h') diff --git a/brandt.h b/brandt.h index 28ae3ca..39c77ee 100644 --- a/brandt.h +++ b/brandt.h @@ -22,7 +22,10 @@ #ifndef _BRANDT_BRANDT_H #define _BRANDT_BRANDT_H -struct BRANDT_auction; +/** + * FIXME. + */ +struct BRANDT_Auction; /** * Functions of this type are called by libbrandt to broadcast messages to the @@ -35,9 +38,13 @@ struct BRANDT_auction; * @param[in] msg The message to be broadcast to all participants of * @a auction_closure. * @param[in] msg_len The length of the message @a msg in bytes. - * @return 1 on success, 0 on failure. + * @return 1 on success, 0 on failure. FIXME: unusual definition */ -typedef int (*BRANDT_cb_broadcast) (void *auction_closure, const void *msg, size_t msg_len); +typedef int +(*BRANDT_BroadcastCallback) (void *auction_closure, + const void *msg, + size_t msg_len); + /** * 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 * auction. This is the Pointer given to BRANDT_join(). * @param[in] msg The message to be sent to the seller of @a auction_closure. * @param[in] msg_len The length of the message @a msg in bytes. - * @return 1 on success, 0 on failure. + * @return 1 on success, 0 on failure. FIXME: unusual definition */ -typedef int (*BRANDT_cb_unicast_seller) (void *auction_closure, const void *msg, size_t msg_len); +typedef int +(*BRANDT_UnicastSellerCallback) (void *auction_closure, + const void *msg, + size_t msg_len); + /** * 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, * @param[in] price The price, the winner has to pay or 0 if the auction result * is private and the user did not win. */ -typedef void (*BRANDT_cb_report_result) (void *auction_closure, int won, uint16_t price); +typedef void +(*BRANDT_ReportResultCallback) (void *auction_closure, + int won, + uint16_t price); +// FIXME: the above callback does not work for the seller, +// but seems to be used for the seller right now. +// FIXME: also need way to be told about malicious/erroneous participants + /** * Join an auction described by the @a auction_data parameter. + * * @param[in] broadcast Pointer to the broadcast callback function * @param[in] unicast Pointer to the unicast callback function * @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_ * libbrandt functions when the client needs to refer to this auction. This is a * black-box pointer, do NOT access/change it or the data it points to! */ -const struct BRANDT_auction *BRANDT_join (BRANDT_cb_broadcast broadcast, - BRANDT_cb_unicast_seller unicast, - BRANDT_cb_report_result report, - const void *auction_closure, - const void *auction_data, - size_t auction_data_len); +struct BRANDT_Auction * +BRANDT_join (BRANDT_BroadcastCallback broadcast, + BRANDT_UnicastSellerCallback unicast, + BRANDT_ReportResultCallback report, + const void *auction_closure, + const void *auction_data, + size_t auction_data_len); +// FIXME: where do I specify my bid? + +// FIXME: Distinguish handles for seller/buyers +// FIXME: have cancellation (BRANDT_join_cancel()) +// FIXME: provide means to extract a hash from auction data to +// tie cryptographic operations to application-readable proposal +// FIXME: have separate function to export 'out' variables +// FIXME: might want to specify timeout? How do we deal with time? +// FIXME: separate creating an auction from starting it; initial +// setup needs more auction proposal details (hash, timeout, +// bid structure), later we need to know # participants /** * Create a new auction described by the @a auction_data parameter. + * * @param[in] broadcast Pointer to the broadcast callback function * @param[in] report Pointer to the report callback function * @param[in] auction_closure Closure pointer representing the auction. This @@ -109,38 +141,52 @@ const struct BRANDT_auction *BRANDT_join (BRANDT_cb_broadcast broadcast, * the price of the highest loosing bid. TODO: what if bidders < m? * @param[in] outcome_public If 1, the auction winner and price will be public * to all participants, if 0, this information will only be revealed to the - * winner and the seller. + * winner and the seller. => FIXME: Turn into AuctionMode bit flag! * @return A pointer, which should only be remembered and passed to * libbrandt functions when the client needs to refer to this auction. This is a * black-box pointer, do NOT access/change it or the data it points to! */ -const struct BRANDT_auction *BRANDT_new (BRANDT_cb_broadcast broadcast, - BRANDT_cb_report_result report, - const void *auction_closure, - const void **auction_data, - size_t *auction_data_len, - uint16_t num_prices, - uint16_t m, - int outcome_public); +struct BRANDT_Auction * +BRANDT_new (BRANDT_BroadcastCallback broadcast, + BRANDT_ReportResultCallback report, + const void *auction_closure, + const void **auction_data, + size_t *auction_data_len, + uint16_t num_prices, + enum BRANDT_AuctionMode m, + int outcome_public); + /** * Receive a broadcast message related to a specific auction. + * * @param[in] auction The pointer returned by BRANDT_join() or BRANDT_new() from * which message @a msg was received. * @param[in] msg The message that was received. * @param[in] msg_len The length in bytes of @a msg. */ -void BRANDT_got_broadcast (struct BRANDT_auction *auction, void *msg, size_t msg_len); +void +BRANDT_got_broadcast (struct BRANDT_Auction *auction, + void *msg, + size_t msg_len); + /** * Receive a unicast message from a bidder related to a specific auction. + * * @param[in] auction The pointer returned by BRANDT_new() from which message * @a msg was received. * @param[in] msg The message that was received. * @param[in] msg_len The length in bytes of @a msg. * TODO: how to link message to sender id within auction? + * ANSWER: on start, know that we have 'n' participants, here give + * participant number (1..n) */ -void BRANDT_got_unicast (struct BRANDT_auction *auction, void *msg, size_t msg_len); +void +BRANDT_got_unicast (struct BRANDT_Auction *auction, + void *msg, + size_t msg_len); + ///TODO: Error handling functions? -- cgit v1.2.3