summaryrefslogtreecommitdiff
path: root/brandt.h
diff options
context:
space:
mode:
authorMarkus Teich <markus.teich@stusta.mhn.de>2016-05-17 22:03:26 +0200
committerMarkus Teich <markus.teich@stusta.mhn.de>2016-05-17 22:03:26 +0200
commit5fc3e848cebe923dcbddab46cc352de5d2971c46 (patch)
tree0eb12e64e78de11aa94fee426db260f3e5676a85 /brandt.h
initial commit
Diffstat (limited to 'brandt.h')
-rw-r--r--brandt.h147
1 files changed, 147 insertions, 0 deletions
diff --git a/brandt.h b/brandt.h
new file mode 100644
index 0000000..47afcfc
--- /dev/null
+++ b/brandt.h
@@ -0,0 +1,147 @@
+/* This file is part of libbrandt.
+ * (C) 2016 Markus Teich
+ *
+ * libbrandt is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * libbrandt is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * libbrandt. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * @file brandt.h
+ * @brief This Header defines the external interface of libbrandt.
+ */
+
+#ifndef _BRANDT_BRANDT_H
+#define _BRANDT_BRANDT_H
+
+struct brandt_auction;
+
+/**
+ * Functions of this type are called by libbrandt to broadcast messages to the
+ * blackboard of a specific auction.
+ *
+ * TODO: how must the message be handled? (encryption, auth, reliability, …)
+ *
+ * @param[in] auction_closure Closure pointer representing the respective
+ * auction. This is the Pointer given to brandt_join().
+ * @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.
+ */
+typedef int (*brandt_cb_broadcast)(void *auction_closure, const void *msg, size_t msg_len);
+
+/**
+ * Functions of this type are called by libbrandt to unicast messages to the
+ * seller of a specific auction.
+ *
+ * TODO: how must the message be handled? (encryption, auth, reliability, …)
+ *
+ * @param[in] auction_closure Closure pointer representing the respective
+ * 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.
+ */
+typedef int (*brandt_cb_unicast_seller)(void *auction_closure, const void *msg, size_t msg_len);
+
+/**
+ * Functions of this type are called by libbrandt to report the auction outcome
+ * to the user.
+ *
+ * TODO: update price type. Don't do this notification as a callback?
+ *
+ * @param[in] auction_closure Closure pointer representing the respective
+ * auction. This is the Pointer given to brandt_join().
+ * @param[in] won 1 if the user has won the auction, 0 otherwise.
+ * @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);
+
+/**
+ * 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
+ * @param[in] auction_closure Closure pointer representing the auction. This
+ * will not be touched by libbrandt. It is only passed to the callbacks.
+ * @param[in] auction_data The auction information data a an opaque data
+ * structure. It will be parsed and checked by brandt_join.
+ * @param[in] auction_data_len The length in bytes of the @a auction_data
+ * structure.
+ * @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_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);
+
+/**
+ * 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
+ * will not be touched by libbrandt. It is only passed to the callbacks.
+ * @param[out] auction_data The auction information data a an opaque data
+ * structure. It will be generated by brandt_new and should be distributed to
+ * all possibly interested bidders.
+ * @param[out] auction_data_len The length in bytes of the @a auction_data
+ * structure. Will be filled by brandt_new.
+ * @param[in] num_prices The amount of possible valuations for the sold item(s).
+ * If 0, a default of 256 will be used. TODO: what about 1, does it work with
+ * second price auctions?
+ * @param[in] m The mode of the auction. If 0, it will be a first price auction
+ * where the winner has to pay the price of his bid. If >0 it will be a second
+ * price auction selling exactly that amount of items and each winner has to pay
+ * 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.
+ * @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);
+
+/**
+ * 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);
+
+/**
+ * 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?
+ */
+void brandt_got_unicast(struct brandt_auction *auction, void *msg, size_t msg_len);
+
+///TODO: Error handling functions?
+
+#endif