/**
- * Current state of a validation process
+ * Current state of a validation process.
+ *
+ * FIXME: what state is used to indicate that a validation
+ * was successful? If that is clarified/determined, "UGH" in
+ * ~gnunet-peerinfo-gtk.c:1103 should be resolved.
*/
enum GNUNET_TRANSPORT_ValidationState
{
/**
- * Function to call with a textual representation of an address.
- * This function will be called several times with different possible
- * textual representations, and a last time with NULL to signal the end
- * of the iteration.
+ * Function to call with a textual representation of an address. This
+ * function will be called several times with different possible
+ * textual representations, and a last time with @address being NULL
+ * to signal the end of the iteration. Note that @address NULL
+ * always is the last call, regardless of the value in @a res.
*
* @param cls closure
- * @param address NULL on error or end of iteration,
- * otherwise 0-terminated printable UTF-8 string
+ * @param address NULL on end of iteration,
+ * otherwise 0-terminated printable UTF-8 string,
+ * in particular an empty string if @a res is #GNUNET_NO
+ * @param res result of the address to string conversion:
+ * if #GNUNET_OK: conversion successful
+ * if #GNUNET_NO: address was invalid (or not supported)
+ * if #GNUNET_SYSERR: communication error (IPC error)
*/
typedef void
(*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls,
- const char *address);
+ const char *address,
+ int res);
/**
* Cancel the request to transport to try a connect
* Callback will not be called
*
- * @param tch GNUNET_TRANSPORT_TryConnectHandle handle to cancel
+ * @param tch handle to cancel
*/
void
GNUNET_TRANSPORT_try_connect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *tch);
*/
struct GNUNET_TRANSPORT_TryConnectHandle *
GNUNET_TRANSPORT_try_disconnect (struct GNUNET_TRANSPORT_Handle *handle,
- const struct GNUNET_PeerIdentity *target,
- GNUNET_TRANSPORT_TryConnectCallback cb,
- void *cb_cls);
+ const struct GNUNET_PeerIdentity *target,
+ GNUNET_TRANSPORT_TryConnectCallback cb,
+ void *cb_cls);
/**
* Cancel the request to transport to try a disconnect
* Callback will not be called
*
- * @param tch GNUNET_TRANSPORT_TryConnectHandle handle to cancel
+ * @param tch handle for operation to cancel
*/
void
GNUNET_TRANSPORT_try_disconnect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *tch);
GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh);
+/**
+ * Handle for a #GNUNET_TRANSPORT_offer_hello operation
+ */
struct GNUNET_TRANSPORT_OfferHelloHandle;
/**
const char *
GNUNET_TRANSPORT_vs2s (enum GNUNET_TRANSPORT_ValidationState state);
+
+/**
+ * Handle for a #GNUNET_TRANSPORT_monitor_peers operation.
+ */
struct GNUNET_TRANSPORT_PeerMonitoringContext;
/**
GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringContext *pic);
+/**
+ * Handle for a #GNUNET_TRANSPORT_monitor_validation_entries() operation.
+ */
struct GNUNET_TRANSPORT_ValidationMonitoringContext;
/**