aboutsummaryrefslogtreecommitdiff
path: root/brandt.h
blob: 108e082dbd9609a9977ef29269a24044a384364a (plain) (blame)
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
201
/* 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.
 * @author Markus Teich
 */

#ifndef _BRANDT_BRANDT_H
#define _BRANDT_BRANDT_H

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

#include <gnunet/gnunet_util_lib.h>

/** defined in internals.h */
struct BRANDT_Auction;

/**
 * Functions of this type are called by libbrandt to broadcast messages to the
 * blackboard of a specific auction. They have to be sent using authenticated
 * encryption.
 *
 * @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_CbBroadcast)(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. They have to be sent using authenticated
 * encryption.
 *
 * @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_CbUnicast)(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: 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_CbResult)(void         *auction_closure,
                   unsigned int bidder_id,
                   int          status,
                   uint16_t     price);


void
BRANDT_init (struct GNUNET_CRYPTO_EccDlogContext *dlogctx);

/**
 * 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] result Pointer to the result callback function
 * @param[in] auction_closure Closure pointer representing the auction. This
 * will not be touched by libbrandt itself. It is only passed to the callbacks.
 * @param[in] auction_data The auction information data published by the seller.
 * This is 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 dereference/change it or the data it points to!
 */
struct BRANDT_Auction *
BRANDT_join (BRANDT_CbBroadcast broadcast,
             BRANDT_CbUnicast   unicast,
             BRANDT_CbResult    result,
             void               *auction_closure,
             const void         *auction_data,
             size_t             auction_data_len);
/* \todo: where do I specify my bid? */


/* \todo: Distinguish handles for seller/buyers */
/* \todo: have cancellation (BRANDT_join_cancel()) */
/* \todo: provide means to extract a hash from auction data to */
/*        tie cryptographic operations to application-readable proposal */
/* \todo: have separate function to export 'out' variables */
/* \todo: might want to specify timeout? How do we deal with time? */
/* \todo: 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] result Pointer to the result 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 dereference/change it or the data it points to!
 */
struct BRANDT_Auction *
BRANDT_new (BRANDT_CbBroadcast          broadcast,
            BRANDT_CbResult             result,
            void                        *auction_closure,
            void                        **auction_data,
            size_t                      *auction_data_len,
            struct GNUNET_TIME_Absolute time_start,
            struct GNUNET_TIME_Relative time_round,
            void                        *description,
            uint32_t                    description_len,
            uint16_t                    num_prices,
            uint16_t                    m,
            int                         outcome_public);


/**
 * Clean up this auction on shutdown.
 *
 * @param[in] auction The pointer returned by BRANDT_join() or BRANDT_new().
 * \todo: implement (de)serialization */
void
BRANDT_destroy (struct BRANDT_Auction *auction);


/**
 * Receive a message related to a specific auction.
 *
 * If the message is from a future round and cannot be processed yet, it is
 * cached in RAM. It will not be stored on disc until it can be used, since the
 * messages completing the previous round should all arrive relatively soon.
 *
 * @param[in] auction The pointer returned by BRANDT_join() or BRANDT_new() from
 * which message @a msg was received.
 * @param[in] sender The id of the sender.
 * @param[in] msg The message that was received.
 * @param[in] msg_len The length in bytes of @a msg.
 */
void
BRANDT_got_message (struct BRANDT_Auction *auction,
                    uint16_t              sender,
                    const unsigned char   *msg,
                    size_t                msg_len);


/**\todo: Error handling functions? */

#endif /* ifndef _BRANDT_BRANDT_H */