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