-implementing new DNS client API

[oweals/gnunet.git] / src / include / gnunet_hello_lib.h

diff --git a/src/include/gnunet_hello_lib.h b/src/include/gnunet_hello_lib.h
index 0ec1be7d1233f8255685e9996fd2485d1df1b929..ffddb0ba25f3b7d88612b46c824e636396967e51 100644 (file)
--- a/src/include/gnunet_hello_lib.h
+++ b/src/include/gnunet_hello_lib.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2001, 2002, 2003, 2004, 2005, 2006, 2010 Christian Grothoff (and other contributing authors)
+     (C) 2001, 2002, 2003, 2004, 2005, 2006, 2010, 2011 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -38,6 +38,95 @@ extern "C"
 #include "gnunet_common.h"
 #include "gnunet_crypto_lib.h"
 
+
+/**
+ * An address for communicating with a peer.  We frequently
+ * need this tuple and the components cannot really be
+ * separated.  This is NOT the format that would be used
+ * on the wire.
+ */
+struct GNUNET_HELLO_Address
+{
+
+  /**
+   * For which peer is this an address?
+   */
+  struct GNUNET_PeerIdentity peer;
+
+  /**
+   * Name of the transport plugin enabling the communication using
+   * this address.
+   */
+  const char *transport_name;
+
+  /**
+   * Binary representation of the address (plugin-specific).
+   */
+  const void *address;
+
+  /**
+   * Number of bytes in 'address'.
+   */
+  size_t address_length;
+
+};
+
+
+/**
+ * Allocate an address struct.
+ *
+ * @param peer the peer
+ * @param transport_name plugin name
+ * @param address binary address
+ * @param address_length number of bytes in 'address'
+ * @return the address struct
+ */
+struct GNUNET_HELLO_Address *
+GNUNET_HELLO_address_allocate (const struct GNUNET_PeerIdentity *peer,
+                               const char *transport_name, const void *address,
+                               size_t address_length);
+
+
+/**
+ * Copy an address struct.
+ *
+ * @param address address to copy
+ * @return a copy of the address struct
+ */
+struct GNUNET_HELLO_Address *
+GNUNET_HELLO_address_copy (const struct GNUNET_HELLO_Address *address);
+
+
+/**
+ * Compare two addresses.  Does NOT compare the peer identity,
+ * that is assumed already to match!
+ *
+ * @param a1 first address
+ * @param a2 second address
+ * @return 0 if the addresses are equal, -1 if a1<a2, 1 if a1>a2.
+ */
+int
+GNUNET_HELLO_address_cmp (const struct GNUNET_HELLO_Address *a1,
+                          const struct GNUNET_HELLO_Address *a2);
+
+
+/**
+ * Get the size of an address struct.
+ *
+ * @param address address
+ * @return the size
+ */
+size_t
+GNUNET_HELLO_address_get_size (const struct GNUNET_HELLO_Address *address);
+
+/**
+ * Free an address.
+ *
+ * @param addr address to free
+ */
+#define GNUNET_HELLO_address_free(addr) GNUNET_free(addr)
+
+
 /**
  * A HELLO message is used to exchange information about
  * transports with other peers.  This struct is guaranteed
@@ -51,19 +140,16 @@ struct GNUNET_HELLO_Message;
  * Copy the given address information into
  * the given buffer using the format of HELLOs.
  *
- * @param tname name of the transport plugin
+ * @param address address to add
  * @param expiration expiration for the address
- * @param addr the address
- * @param addr_len length of the address in bytes
  * @param target where to copy the address
  * @param max maximum number of bytes to copy to target
  * @return number of bytes copied, 0 if
  *         the target buffer was not big enough.
  */
 size_t
-GNUNET_HELLO_add_address (const char *tname,
-                          struct GNUNET_TIME_Absolute expiration,
-                          const void *addr, uint16_t addr_len, char *target,
+GNUNET_HELLO_add_address (const struct GNUNET_HELLO_Address *address,
+                          struct GNUNET_TIME_Absolute expiration, char *target,
                           size_t max);
 
 
@@ -146,18 +232,27 @@ GNUNET_HELLO_equals (const struct GNUNET_HELLO_Message *h1,
  * Iterator callback to go over all addresses.
  *
  * @param cls closure
- * @param tname name of the transport
+ * @param address the address
  * @param expiration expiration time
- * @param addr the address
- * @param addrlen length of the address
  * @return GNUNET_OK to keep the address,
  *         GNUNET_NO to delete it from the HELLO
  *         GNUNET_SYSERR to stop iterating (but keep current address)
  */
-typedef int (*GNUNET_HELLO_AddressIterator) (void *cls, const char *tname,
+typedef int (*GNUNET_HELLO_AddressIterator) (void *cls,
+                                             const struct GNUNET_HELLO_Address *
+                                             address,
                                              struct GNUNET_TIME_Absolute
-                                             expiration, const void *addr,
-                                             uint16_t addrlen);
+                                             expiration);
+
+
+/**
+ * When does the last address in the given HELLO expire?
+ *
+ * @param msg HELLO to inspect
+ * @return time the last address expires, 0 if there are no addresses in the HELLO
+ */
+struct GNUNET_TIME_Absolute
+GNUNET_HELLO_get_last_expiration (const struct GNUNET_HELLO_Message *msg);
 
 
 /**