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