194 lines
7.7 KiB
C
194 lines
7.7 KiB
C
/* 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
|
|
|
|
/**
|
|
* 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 1 on success, 0 on failure. FIXME: unusual definition
|
|
*/
|
|
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 1 on success, 0 on failure. FIXME: unusual definition
|
|
*/
|
|
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
|
|
* 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_ReportResultCallback) (void *auction_closure,
|
|
int won,
|
|
uint16_t price);
|
|
// FIXME: the above callback does not work for the seller,
|
|
// but seems to be used for the seller right now.
|
|
// FIXME: also need way to be told about malicious/erroneous participants
|
|
|
|
|
|
/**
|
|
* 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
|