summaryrefslogtreecommitdiff
path: root/brandt.h
blob: a8a2dffc86b4d7b6372f900ea131d376a7c38490 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
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