aboutsummaryrefslogtreecommitdiff
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
downloadlibbrandt-5fc3e848cebe923dcbddab46cc352de5d2971c46.tar.gz
libbrandt-5fc3e848cebe923dcbddab46cc352de5d2971c46.zip
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 @@
1/* This file is part of libbrandt.
2 * (C) 2016 Markus Teich
3 *
4 * libbrandt is free software: you can redistribute it and/or modify it under
5 * the terms of the GNU General Public License as published by the Free Software
6 * Foundation, either version 3 of the License, or (at your option) any later
7 * version.
8 *
9 * libbrandt is distributed in the hope that it will be useful, but WITHOUT ANY
10 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
11 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along with
14 * libbrandt. If not, see <http://www.gnu.org/licenses/>.
15 */
16
17/**
18 * @file brandt.h
19 * @brief This Header defines the external interface of libbrandt.
20 */
21
22#ifndef _BRANDT_BRANDT_H
23#define _BRANDT_BRANDT_H
24
25struct brandt_auction;
26
27/**
28 * Functions of this type are called by libbrandt to broadcast messages to the
29 * blackboard of a specific auction.
30 *
31 * TODO: how must the message be handled? (encryption, auth, reliability, …)
32 *
33 * @param[in] auction_closure Closure pointer representing the respective
34 * auction. This is the Pointer given to brandt_join().
35 * @param[in] msg The message to be broadcast to all participants of
36 * @a auction_closure.
37 * @param[in] msg_len The length of the message @a msg in bytes.
38 * @return 1 on success, 0 on failure.
39 */
40typedef int (*brandt_cb_broadcast)(void *auction_closure, const void *msg, size_t msg_len);
41
42/**
43 * Functions of this type are called by libbrandt to unicast messages to the
44 * seller of a specific auction.
45 *
46 * TODO: how must the message be handled? (encryption, auth, reliability, …)
47 *
48 * @param[in] auction_closure Closure pointer representing the respective
49 * 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.
51 * @param[in] msg_len The length of the message @a msg in bytes.
52 * @return 1 on success, 0 on failure.
53 */
54typedef int (*brandt_cb_unicast_seller)(void *auction_closure, const void *msg, size_t msg_len);
55
56/**
57 * Functions of this type are called by libbrandt to report the auction outcome
58 * to the user.
59 *
60 * TODO: update price type. Don't do this notification as a callback?
61 *
62 * @param[in] auction_closure Closure pointer representing the respective
63 * auction. This is the Pointer given to brandt_join().
64 * @param[in] won 1 if the user has won the auction, 0 otherwise.
65 * @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.
67 */
68typedef void (*brandt_cb_report_result)(void *auction_closure, int won, uint16_t price);
69
70/**
71 * Join an auction described by the @a auction_data parameter.
72 * @param[in] broadcast Pointer to the broadcast callback function
73 * @param[in] unicast Pointer to the unicast callback function
74 * @param[in] report Pointer to the report callback function
75 * @param[in] auction_closure Closure pointer representing the auction. This
76 * will not be touched by libbrandt. It is only passed to the callbacks.
77 * @param[in] auction_data The auction information data a an opaque data
78 * structure. It will be parsed and checked by brandt_join.
79 * @param[in] auction_data_len The length in bytes of the @a auction_data
80 * structure.
81 * @return A pointer, which should only be remembered and passed to
82 * 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!
84 */
85const struct brandt_auction *brandt_join(brandt_cb_broadcast broadcast,
86 brandt_cb_unicast_seller unicast,
87 brandt_cb_report_result report,
88 const void *auction_closure,
89 const void *auction_data,
90 size_t auction_data_len);
91
92/**
93 * Create a new auction described by the @a auction_data parameter.
94 * @param[in] broadcast Pointer to the broadcast callback function
95 * @param[in] report Pointer to the report callback function
96 * @param[in] auction_closure Closure pointer representing the auction. This
97 * will not be touched by libbrandt. It is only passed to the callbacks.
98 * @param[out] auction_data The auction information data a an opaque data
99 * structure. It will be generated by brandt_new and should be distributed to
100 * all possibly interested bidders.
101 * @param[out] auction_data_len The length in bytes of the @a auction_data
102 * structure. Will be filled by brandt_new.
103 * @param[in] num_prices The amount of possible valuations for the sold item(s).
104 * If 0, a default of 256 will be used. TODO: what about 1, does it work with
105 * second price auctions?
106 * @param[in] m The mode of the auction. If 0, it will be a first price auction
107 * where the winner has to pay the price of his bid. If >0 it will be a second
108 * price auction selling exactly that amount of items and each winner has to pay
109 * 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
111 * to all participants, if 0, this information will only be revealed to the
112 * winner and the seller.
113 * @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
115 * black-box pointer, do NOT access/change it or the data it points to!
116 */
117const struct brandt_auction *brandt_new(brandt_cb_broadcast broadcast,
118 brandt_cb_report_result report,
119 const void *auction_closure,
120 const void **auction_data,
121 size_t *auction_data_len,
122 uint16_t num_prices,
123 uint16_t m,
124 int outcome_public);
125
126/**
127 * Receive a broadcast message related to a specific auction.
128 * @param[in] auction The pointer returned by brandt_join() or brandt_new() from
129 * which message @a msg was received.
130 * @param[in] msg The message that was received.
131 * @param[in] msg_len The length in bytes of @a msg.
132 */
133void brandt_got_broadcast(struct brandt_auction *auction, void *msg, size_t msg_len);
134
135/**
136 * Receive a unicast message from a bidder related to a specific auction.
137 * @param[in] auction The pointer returned by brandt_new() from which message
138 * @a msg was received.
139 * @param[in] msg The message that was received.
140 * @param[in] msg_len The length in bytes of @a msg.
141 * TODO: how to link message to sender id within auction?
142 */
143void brandt_got_unicast(struct brandt_auction *auction, void *msg, size_t msg_len);
144
145///TODO: Error handling functions?
146
147#endif