libbrandt/brandt.h

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

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