/* 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.
* @author Markus Teich
*/
#ifndef _BRANDT_BRANDT_H
#define _BRANDT_BRANDT_H
#include
#include
#include
/** defined in internals.h */
struct BRANDT_Auction;
/**
* Functions of this type are called by libbrandt when the auction should be
* started. The application has to announce the ordered list of all bidders to
* them and must return the amount of bidders. After this function is called no
* more new bidders may be accepted by the application. This callback is only
* used if the auction is in seller mode.
*
* @param[in] auction_closure Closure pointer representing the respective
* auction. This is the Pointer given to BRANDT_new().
* @return The amount of bidders participating in the auction.
*/
typedef uint16_t
(*BRANDT_CbStart)(void *auction_closure);
/**
* 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 / outcome.
*
* @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, negative if erroneous behaviour was detected. Check the result_code
* enum for more information.
* @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,
int32_t bidder_id,
int status,
uint16_t price);
void
BRANDT_init (struct GNUNET_CRYPTO_EccDlogContext *dlogctx);
/**
* Verify an auction description blob and parse it's fields. See BRANDT_new()
* for an explanation of the different auction description fields.
*
* @param[in] auction_desc The auction description blob published by the seller.
* @param[in] auction_desc_len Length of @a auction_desc in bytes.
* @param[in] description The description text in application choosen format.
* @param[in] description_len Length of @a description in bytes.
* @param[out] time_start Starting time of the auction. May be NULL.
* @param[out] time_round Maximum round time of the auction. May be NULL.
* @param[out] num_prices Amount of possible prices. May be NULL.
* @param[out] m Auction mode. May be NULL.
* @param[out] outcome_public Outcome setting. May be NULL.
*/
int
BRANDT_verify_desc (const void *auction_desc,
size_t auction_desc_len,
const void *description,
uint32_t description_len,
struct GNUNET_TIME_Absolute *time_start,
struct GNUNET_TIME_Relative *time_round,
uint16_t *num_prices,
uint16_t *m,
uint16_t *outcome_public);
/**
* Join an auction described by the @a auction_desc 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_desc 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_desc_len The length in bytes of the @a auction_desc
* 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_CbResult result,
BRANDT_CbBroadcast broadcast,
BRANDT_CbUnicast unicast,
void *auction_closure,
const void *auction_desc,
size_t auction_desc_len,
const void *description,
uint32_t description_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_desc 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_desc 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_desc_len The length in bytes of the @a auction_desc
* 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_CbResult result,
BRANDT_CbBroadcast broadcast,
BRANDT_CbStart start,
void *auction_closure,
void **auction_desc,
size_t *auction_desc_len,
const void *description,
uint32_t description_len,
struct GNUNET_TIME_Absolute time_start,
struct GNUNET_TIME_Relative time_round,
uint16_t num_prices,
uint16_t m,
int outcome_public);
/**
* This function must be called when bidding after receipt of the start
* notification.
*
* @param[in] auction The pointer returned by BRANDT_join().
* @param[in] n The amount of bidders (from the start announcement message).
void
BRANDT_start (struct BRANDT_Auction *auction,
uint16_t n);
/**
* 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 */