diff options
author | Markus Teich <markus.teich@stusta.mhn.de> | 2016-05-17 22:03:26 +0200 |
---|---|---|
committer | Markus Teich <markus.teich@stusta.mhn.de> | 2016-05-17 22:03:26 +0200 |
commit | 5fc3e848cebe923dcbddab46cc352de5d2971c46 (patch) | |
tree | 0eb12e64e78de11aa94fee426db260f3e5676a85 /brandt.h | |
download | libbrandt-5fc3e848cebe923dcbddab46cc352de5d2971c46.tar.gz libbrandt-5fc3e848cebe923dcbddab46cc352de5d2971c46.zip |
initial commit
Diffstat (limited to 'brandt.h')
-rw-r--r-- | brandt.h | 147 |
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 | |||
25 | struct 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 | */ | ||
40 | typedef 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 | */ | ||
54 | typedef 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 | */ | ||
68 | typedef 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 | */ | ||
85 | const 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 | */ | ||
117 | const 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 | */ | ||
133 | void 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 | */ | ||
143 | void brandt_got_unicast(struct brandt_auction *auction, void *msg, size_t msg_len); | ||
144 | |||
145 | ///TODO: Error handling functions? | ||
146 | |||
147 | #endif | ||