summaryrefslogtreecommitdiff
path: root/brandt.h
blob: b7ebf5b8953016481831de2f6c070e48ffd37e29 (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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
/* This file is part of libbrandt.
 * Copyright (C) 2016 GNUnet e.V.
 *
 * 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

#include <unistd.h>
#include <stdint.h>

/**
 * FIXME.
 */
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 0 on success, -1 on failure.
 */
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
 * 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 0 on success, -1 on failure.
 */
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
 * or malicious/erroneous participants.
 *
 * TODO: update price type.
 * TODO: export proof of erroneous behaviour.
 *
 * @param[in] auction_closure Closure pointer representing the respective
 * auction. This is the Pointer given to BRANDT_join() / BRANDT_new().
 * @param[in] bidder_id The numeric Id of the bidder this report refers to.
 * @param[in] status 1 if the user @a bidder_id has won the auction, 0 if he has
 * lost, -1 if erroneous behaviour was detected.
 * @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_ReportResultCallback)(void *       auction_closure,
                               unsigned int bidder_id,
                               int          status,
                               uint16_t     price);


void
BRANDT_init ();

/**
 * 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!
 */
struct BRANDT_Auction *
BRANDT_join (BRANDT_BroadcastCallback     broadcast,
             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
 * 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. => 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!
 */
struct BRANDT_Auction *
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,
            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);


/**
 * 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);


/**TODO: Error handling functions? */

#endif /* ifndef _BRANDT_BRANDT_H */