comments

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,
+struct BRANDT_Auction *
-                                          BRANDT_cb_unicast_seller unicast,
+BRANDT_join (BRANDT_BroadcastCallback broadcast,
-                                          BRANDT_cb_report_result report,
+             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,
+struct BRANDT_Auction *
-                                         BRANDT_cb_report_result report,
+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,
-                                         uint16_t m,
+            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?