*/
/**
- * @file consensus/gnunet-consensus.c
+ * @file consensus/gnunet-consensus-profiler.c
* @brief profiling tool for gnunet-consensus
* @author Florian Dold
*/
/**
- * Perform an asynchronous Lookup operation on the GNS.
+ * Perform an asynchronous lookup operation on the GNS.
*
* @param handle handle to the GNS service
* @param name the name to look up
* @param zone the zone to start the resolution in
* @param type the record type to look up
- * @param only_cached GNUNET_YES to only check locally not DHT for performance
- * @param shorten_key the private key of the shorten zone (can be NULL)
+ * @param only_cached #GNUNET_YES to only check locally (not in the DHT)
+ * @param shorten_zone_key the private key of the shorten zone (can be NULL)
* @param proc processor to call on result
* @param proc_cls closure for processor
* @return handle to the get request
const struct GNUNET_CRYPTO_EccPublicKey *zone,
int type,
int only_cached,
- const struct GNUNET_CRYPTO_EccPrivateKey *shorten_key,
+ const struct GNUNET_CRYPTO_EccPrivateKey *shorten_zone_key,
GNUNET_GNS_LookupResultProcessor proc,
void *proc_cls)
{
lookup_msg->only_cached = htonl (only_cached);
lookup_msg->zone = *zone;
lookup_msg->type = htonl (type);
- if (NULL != shorten_key)
+ if (NULL != shorten_zone_key)
{
lookup_msg->have_key = htonl (GNUNET_YES);
- lookup_msg->shorten_key = *shorten_key;
+ lookup_msg->shorten_key = *shorten_zone_key;
}
memcpy (&lookup_msg[1], name, strlen (name) + 1);
GNUNET_CONTAINER_DLL_insert_tail (handle->pending_head,
* Initialize the resolver
*
* @param nh the namestore handle
- * @param dh the dht handle
+ * @param dht the dht handle
* @param c configuration handle
* @param max_bg_queries maximum number of parallel background queries in dht
- * @param ignore_pending ignore records that still require user confirmation
- * on lookup
*/
void
GNS_resolver_init (struct GNUNET_NAMESTORE_Handle *nh,
- struct GNUNET_DHT_Handle *dh,
+ struct GNUNET_DHT_Handle *dht,
const struct GNUNET_CONFIGURATION_Handle *c,
unsigned long long max_bg_queries)
{
/**
* Cancel active resolution (i.e. client disconnected).
*
- * @param h resolution to abort
+ * @param rh resolution to abort
*/
void
-GNS_resolver_lookup_cancel (struct GNS_ResolverHandle *h);
-
+GNS_resolver_lookup_cancel (struct GNS_ResolverHandle *rh);
* Functions with this signature are called whenever a message is
* received or transmitted.
*
- * @param cls closure (set from GNUNET_CORE_connect)
+ * @param cls closure (set from #GNUNET_CORE_connect)
* @param peer the other peer involved (sender or receiver, NULL
* for loopback messages where we are both sender and receiver)
* @param message the actual message
- * @return GNUNET_OK to keep the connection open,
- * GNUNET_SYSERR to close connection to the peer (signal serious error)
+ * @return #GNUNET_OK to keep the connection open,
+ * #GNUNET_SYSERR to close connection to the peer (signal serious error)
*/
typedef int (*GNUNET_CORE_MessageCallback) (void *cls,
const struct GNUNET_PeerIdentity *
/**
- * Function called after GNUNET_CORE_connect has succeeded (or failed
+ * Function called after #GNUNET_CORE_connect has succeeded (or failed
* for good). Note that the private key of the peer is intentionally
* not exposed here; if you need it, your process should try to read
* the private key file directly (which should work if you are
* authorized...). Implementations of this function must not call
- * GNUNET_CORE_disconnect (other than by scheduling a new task to
+ * #GNUNET_CORE_disconnect (other than by scheduling a new task to
* do this later).
*
* @param cls closure
- * @param server handle to the server, NULL if we failed; TODO: consider removing this argument, it is redundant...
+ * @param server handle to the server, NULL if we failed;
+ * TODO: consider removing this argument, it is redundant...
* @param my_identity ID of this peer, NULL if we failed
*/
typedef void (*GNUNET_CORE_StartupCallback) (void *cls,
* specified event happens. The maximum number of queued
* notifications (queue length) is per client; the queue is shared
* across all types of notifications. So a slow client that registers
- * for 'outbound_notify' also risks missing 'inbound_notify' messages.
+ * for @a outbound_notify also risks missing @a inbound_notify messages.
* Certain events (such as connect/disconnect notifications) are not
* subject to queue size limitations.
*
* note that the core is allowed to drop notifications about inbound
* messages if the client does not process them fast enough (for this
* notification type, a bounded queue is used)
- * @param inbound_hdr_only set to GNUNET_YES if inbound_notify will only read the
+ * @param inbound_hdr_only set to #GNUNET_YES if @a inbound_notify will only read the
* GNUNET_MessageHeader and hence we do not need to give it the full message;
* can be used to improve efficiency, ignored if inbound_notify is NULL
* note that the core is allowed to drop notifications about inbound
* note that the core is allowed to drop notifications about outbound
* messages if the client does not process them fast enough (for this
* notification type, a bounded queue is used)
- * @param outbound_hdr_only set to GNUNET_YES if outbound_notify will only read the
+ * @param outbound_hdr_only set to #GNUNET_YES if @a outbound_notify will only read the
* GNUNET_MessageHeader and hence we do not need to give it the full message
* can be used to improve efficiency, ignored if outbound_notify is NULL
* note that the core is allowed to drop notifications about outbound
* note that the core is allowed to drop notifications about inbound
* messages if the client does not process them fast enough (for this
* notification type, a bounded queue is used)
- * @return handle to the core service (only useful for disconnect until 'init' is called),
+ * @return handle to the core service (only useful for disconnect until @a init is called),
* NULL on error (in this case, init is never called)
*/
struct GNUNET_CORE_Handle *
/**
* Disconnect from the core service. This function can only
- * be called *after* all pending 'GNUNET_CORE_notify_transmit_ready'
+ * be called *after* all pending #GNUNET_CORE_notify_transmit_ready
* requests have been explicitly cancelled.
*
* @param handle connection to core to disconnect
/**
- * Ask the core to call "notify" once it is ready to transmit the
- * given number of bytes to the specified "target". Must only be
+ * Ask the core to call @a notify once it is ready to transmit the
+ * given number of bytes to the specified @a target. Must only be
* called after a connection to the respective peer has been
* established (and the client has been informed about this). You may
* have one request of this type pending for each connected peer at
* any time. If a peer disconnects, the application MUST call
- * "GNUNET_CORE_notify_transmit_ready_cancel" on the respective
+ * #GNUNET_CORE_notify_transmit_ready_cancel on the respective
* transmission request, if one such request is pending.
*
* @param handle connection to core service
* will be called with NULL on timeout; clients MUST cancel
* all pending transmission requests DURING the disconnect
* handler
- * @param notify_cls closure for notify
+ * @param notify_cls closure for @a notify
* @return non-NULL if the notify callback was queued,
* NULL if we can not even queue the request (request already pending);
* if NULL is returned, "notify" will NOT be called.
*th);
-
-
-
/**
- * Iterate over all connected peers. Calls peer_cb with each
+ * Iterate over all connected peers. Calls @a peer_cb with each
* connected peer, and then once with NULL to indicate that all peers
* have been handled. Normal users of the CORE API are not expected
* to use this function. It is different in that it truly lists
*
* @param cfg configuration handle
* @param peer_cb function to call with the peer information
- * @param cb_cls closure for peer_cb
- * @return GNUNET_OK on success, GNUNET_SYSERR on errors
+ * @param cb_cls closure for @a peer_cb
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on errors
*/
int
GNUNET_CORE_iterate_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
* @param cfg configuration to use
* @param peer the specific peer to check for
* @param peer_cb function to call with the peer information
- * @param cb_cls closure for peer_cb
+ * @param cb_cls closure for @a peer_cb
* @return handle to cancel the operation
*/
struct GNUNET_CORE_ConnectTestHandle *
* Check if the given peer is currently connected. This function is for special
* cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
* expected to track which peers are connected based on the connect/disconnect
- * callbacks from GNUNET_CORE_connect. This function is NOT part of the
+ * callbacks from #GNUNET_CORE_connect. This function is NOT part of the
* 'versioned', 'official' API. The difference between this function and the
- * function GNUNET_CORE_is_peer_connected() is that this one returns
+ * function #GNUNET_CORE_is_peer_connected is that this one returns
* synchronously after looking in the CORE API cache. The function
- * GNUNET_CORE_is_peer_connected() sends a message to the CORE service and hence
+ * #GNUNET_CORE_is_peer_connected sends a message to the CORE service and hence
* its response is given asynchronously.
*
* @param h the core handle
* @param pid the identity of the peer to check if it has been connected to us
- * @return GNUNET_YES if the peer is connected to us; GNUNET_NO if not
+ * @return #GNUNET_YES if the peer is connected to us; #GNUNET_NO if not
*/
int
GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h,
/* **************** Functions and Macros ************* */
/**
- * Seed a weak random generator. Only GNUNET_CRYPTO_QUALITY_WEAK-mode generator
+ * Seed a weak random generator. Only #GNUNET_CRYPTO_QUALITY_WEAK-mode generator
* can be seeded.
*
* @param seed the seed to use
*
* @param sum current sum, initially 0
* @param buf buffer to calculate CRC over (must be 16-bit aligned)
- * @param len number of bytes in hdr, must be multiple of 2
+ * @param len number of bytes in @a buf, must be multiple of 2
* @return updated crc sum (must be subjected to GNUNET_CRYPTO_crc16_finish to get actual crc16)
*/
uint32_t
/**
* Calculate the checksum of a buffer in one step.
*
- * @param buf buffer to calculate CRC over (must be 16-bit aligned)
- * @param len number of bytes in hdr, must be multiple of 2
+ * @param buf buffer to calculate CRC over (must be 16-bit aligned)
+ * @param len number of bytes in @a buf, must be multiple of 2
* @return crc16 value
*/
uint16_t
* bytes of the buffer.
*
* @param buf the data over which we're taking the CRC
- * @param len the length of the buffer in bytes
+ * @param len the length of the buffer @buf in bytes
* @return the resulting CRC32 checksum
*/
int32_t
*
* @param mode desired quality of the random number
* @param i the upper limit (exclusive) for the random number
- * @return a random value in the interval [0,i) (exclusive).
+ * @return a random value in the interval [0,@a i) (exclusive).
*/
uint32_t
GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode, uint32_t i);
* Random on unsigned 64-bit values.
*
* @param mode desired quality of the random number
- * @param max value returned will be in range [0,max) (exclusive)
+ * @param max value returned will be in range [0,@a max) (exclusive)
* @return random 64-bit number
*/
uint64_t
/**
* Get an array with a random permutation of the
* numbers 0...n-1.
- * @param mode GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used, GNUNET_CRYPTO_QUALITY_WEAK otherwise
+ * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
+ * #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
* @param n the size of the array
* @return the permutation array (allocated from heap)
*/
* Convert ASCII encoding back to a 'struct GNUNET_HashCode'
*
* @param enc the encoding
- * @param enclen number of characters in 'enc' (without 0-terminator, which can be missing)
- * @param result where to store the GNUNET_CRYPTO_hash code
- * @return GNUNET_OK on success, GNUNET_SYSERR if result has the wrong encoding
+ * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
+ * @param result where to store the hash code
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
*/
int
GNUNET_CRYPTO_hash_from_string2 (const char *enc, size_t enclen,
- struct GNUNET_HashCode * result);
+ struct GNUNET_HashCode *result);
/**
* Convert ASCII encoding back to a 'struct GNUNET_CRYPTO_ShortHash'
*
* @param enc the encoding
- * @param enclen number of characters in 'enc' (without 0-terminator, which can be missing)
- * @param result where to store the GNUNET_CRYPTO_hash code
- * @return GNUNET_OK on success, GNUNET_SYSERR if result has the wrong encoding
+ * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
+ * @param result where to store the hash code
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
*/
int
GNUNET_CRYPTO_short_hash_from_string2 (const char *enc, size_t enclen,
*
* @param enc the encoding
* @param result where to store the GNUNET_CRYPTO_ShortHash
- * @return GNUNET_OK on success, GNUNET_SYSERR if result has the wrong encoding
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
*/
#define GNUNET_CRYPTO_short_hash_from_string(enc, result) \
GNUNET_CRYPTO_short_hash_from_string2 (enc, strlen(enc), result)
* Compute hash of a given block.
*
* @param block the data to hash
- * @param size size of the block
+ * @param size size of the @a block
* @param ret pointer to where to write the hashcode
*/
void
* Compute short (256-bit) hash of a given block.
*
* @param block the data to hash
- * @param size size of the block
+ * @param size size of the @a block
* @param ret pointer to where to write the hashcode
*/
void
*
* @param key secret key
* @param plaintext input plaintext
- * @param plaintext_len length of plaintext
+ * @param plaintext_len length of @a plaintext
* @param hmac where to store the hmac
*/
void
*
* @param a some hash code
* @param b some hash code
- * @param result set to b - a
+ * @param result set to @a b - @a a
*/
void
GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode * a,
*
* @param a some hash code
* @param delta some hash code
- * @param result set to a + delta
+ * @param result set to @a a + @a delta
*/
void
GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode * a,
*
* @param a some hash code
* @param b some hash code
- * @param result set to a ^ b
+ * @param result set to @a a ^ @a b
*/
void
GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode * a, const struct GNUNET_HashCode * b,
int
GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode * code, unsigned int bit);
+
/**
* Determine how many low order bits match in two
* struct GNUNET_HashCodes. i.e. - 010011 and 011111 share
*
* @param first the first hashcode
* @param second the hashcode to compare first to
- *
* @return the number of bits that match
*/
unsigned int
*
* @param cfg configuration to use
* @param dst pointer to where to write the peer identity
- * @return GNUNET_OK on success, GNUNET_SYSERR if the identity
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
* could not be retrieved
*/
int
* @param priv private key to use for the ECDH (x)
* @param pub public key to use for the ECDY (yG)
* @param key_material where to write the key material (xyG)
- * @return GNUNET_SYSERR on error, GNUNET_OK on success
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
*/
int
GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EccPrivateKey *priv,
* @param priv private key to use for the signing
* @param purpose what to sign (size, purpose)
* @param sig where to write the signature
- * @return GNUNET_SYSERR on error, GNUNET_OK on success
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
*/
int
GNUNET_CRYPTO_ecc_sign (const struct GNUNET_CRYPTO_EccPrivateKey *priv,
* @param validate block to validate (size, purpose, data)
* @param sig signature that is being validated
* @param pub public key of the signer
- * @returns GNUNET_OK if ok, GNUNET_SYSERR if invalid
+ * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
*/
int
GNUNET_CRYPTO_ecc_verify (uint32_t purpose,
* @param name the name to look up
* @param zone zone to look in
* @param type the GNS record type to look for
- * @param only_cached #GNUNET_NO to only check locally (not in the DHT)
+ * @param only_cached #GNUNET_YES to only check locally (not in the DHT)
* @param shorten_zone_key the private key of the shorten zone (can be NULL);
* specify to enable automatic shortening (given a PSEU
* record, if a given pseudonym is not yet used in the
Boston, MA 02111-1307, USA.
*/
/**
- * @file gnunet-gns-fcfsd.c
+ * @file gnunet-namestore-fcfsd.c
* @brief HTTP daemon that offers first-come-first-serve GNS domain registration
* @author Christian Grothoff
*
/**
- * A #GNUNET_NAMESTORE_BlockCallback for name lookups in #handle_lookup_name
+ * A #GNUNET_NAMESTORE_BlockCallback for name lookups in #handle_lookup_block
*
* @param cls a 'struct LookupNameContext *' with information about the request
* @param block the block
*
* @param cls struct ZoneIterationProcResult *proc
* @param zone_key the zone key
- * @param expire expiration time
* @param name name
* @param rd_count number of records for this name
* @param rd record data
- * @param signature block signature
*/
static void
zone_iteraterate_proc (void *cls,
*
* @param cls a 'struct ZoneMonitor *' with information about the monitor
* @param zone_key zone key of the zone
- * @param expire expiration time
* @param name name
* @param rd_count number of records
* @param rd array of records
- * @param signature signature
*/
static void
monitor_iterate_cb (void *cls,
struct RecordStoreMessage
{
/**
- * Type will be #GNUNET_MESSAGE_TYPE_NAMESTORE_LOOKUP_RECORD_STORE
+ * Type will be #GNUNET_MESSAGE_TYPE_NAMESTORE_RECORD_STORE
*/
struct GNUNET_NAMESTORE_Header gns_header;