* doxygen updates

* reply to probe queries immediately


git-svn-id: file:///home/lennart/svn/public/avahi/trunk@147 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe

6 files changed, 94 insertions, 37 deletions

diff --git a/avahi-common/address.h b/avahi-common/address.h
index 4b5fb27..f304345 100644
--- a/avahi-common/address.h
+++ b/avahi-common/address.h
@@ -53,7 +53,7 @@ typedef struct {
     guint8 address[16]; /**< Address data */
 } AvahiIPv6Address;
 
-/** Protocol (address family) independant address structure */
+/** Protocol (address family) independent address structure */
 typedef struct {
     AvahiProtocol family; /**< Address family */
 
diff --git a/avahi-common/rr.h b/avahi-common/rr.h
index 13e6a4c..7a5c0e3 100644
--- a/avahi-common/rr.h
+++ b/avahi-common/rr.h
@@ -27,6 +27,8 @@
 #include <avahi-common/strlst.h>
 #include <avahi-common/address.h>
 
+
+/** DNS record types, see RFC 1035 */
 enum {
     AVAHI_DNS_TYPE_A = 0x01,
     AVAHI_DNS_TYPE_NS = 0x02,
@@ -38,14 +40,15 @@ enum {
     AVAHI_DNS_TYPE_TXT = 0x10,
     AVAHI_DNS_TYPE_AAAA = 0x1C,
     AVAHI_DNS_TYPE_SRV = 0x21,
-    AVAHI_DNS_TYPE_ANY = 0xFF
+    AVAHI_DNS_TYPE_ANY = 0xFF /**< Special query type for requesting all records */
 };
 
+/** DNS record classes, see RFC 1035 */
 enum {
-    AVAHI_DNS_CLASS_IN = 0x01,
-    AVAHI_DNS_CLASS_ANY = 0xFF,
-    AVAHI_DNS_CACHE_FLUSH = 0x8000,
-    AVAHI_DNS_UNICAST_RESPONSE = 0x8000
+    AVAHI_DNS_CLASS_IN = 0x01,          /**< Probably the only class we will ever use */
+    AVAHI_DNS_CLASS_ANY = 0xFF,         /**< Special query type for requesting all records */
+    AVAHI_DNS_CACHE_FLUSH = 0x8000,     /**< Not really a class but a bit which may be set in response packets, see mDNS spec for more information */
+    AVAHI_DNS_UNICAST_RESPONSE = 0x8000 /**< Not really a class but a bit which may be set in query packets, see mDNS spec for more information */
 };
 
 /** The default TTL for RRs which contain a host name of some kind. */
@@ -54,92 +57,143 @@ enum {
 /** The default TTL for all other records. */
 #define AVAHI_DEFAULT_TTL (75*60)
 
+/** Encapsulates a DNS query key consisting of class, type and
+    name. Use avahi_key_ref()/avahi_key_unref() for manipulating the
+    reference counter. The structure is intended to be treated as "immutable", no
+    changes should be imposed after creation */
 typedef struct {
-    guint ref;
-    gchar *name;
-    guint16 class;
-    guint16 type;
+    guint ref;         /**< Reference counter */
+    gchar *name;       /**< Record name */
+    guint16 class;     /**< Record class, one of the AVAHI_DNS_CLASS_xxx constants */
+    guint16 type;      /**< Record type, one of the AVAHI_DNS_TYPE_xxx constants */
 } AvahiKey;
 
+/** Encapsulates a DNS resource record. The structure is intended to
+ * be treated as "immutable", no changes should be imposed after
+ * creation. */
 typedef struct  {
-    guint ref;
-    AvahiKey *key;
+    guint ref;       /**< Reference counter */
+    AvahiKey *key;   /**< Reference to the query key of thsi record */
     
-    guint32 ttl;
+    guint32 ttl;     /**< DNS TTL of this record */
 
     union {
+
+        
         struct {
             gpointer data;
             guint16 size;
-        } generic;
+        } generic; /**< Generic record data for unknown types */
 
+        
         struct {
             guint16 priority;
             guint16 weight;
             guint16 port;
             gchar *name;
-        } srv;
+        } srv; /**< Data for SRV records */
 
         struct {
             gchar *name;
-        } ptr; /* and cname */
+        } ptr; /**< Data for PTR an CNAME records */
 
         struct {
             gchar *cpu;
             gchar *os;
-        } hinfo;
+        } hinfo; /**< Data for HINFO records */
 
         struct {
             AvahiStringList *string_list;
-        } txt;
+        } txt; /**< Data for TXT records */
 
         struct {
             AvahiIPv4Address address;
-        } a;
+        } a; /**< Data for A records */
 
         struct {
             AvahiIPv6Address address;
-        } aaaa;
+        } aaaa; /**< Data for AAAA records */
 
-    } data;
+    } data; /**< Record data */
     
 } AvahiRecord;
 
+/** Create a new AvahiKey object. The reference counter will be set to 1. */
 AvahiKey *avahi_key_new(const gchar *name, guint16 class, guint16 type);
+
+/** Increase the reference counter of an AvahiKey object by one */
 AvahiKey *avahi_key_ref(AvahiKey *k);
+
+/** Decrease the reference counter of an AvahiKey object by one */
 void avahi_key_unref(AvahiKey *k);
 
-gboolean avahi_key_equal(const AvahiKey *a, const AvahiKey *b);  /* Treat AVAHI_DNS_CLASS_ANY like any other type */
-gboolean avahi_key_pattern_match(const AvahiKey *pattern, const AvahiKey *k); /* If pattern.type is AVAHI_DNS_CLASS_ANY, k.type is ignored */
+/** Check whether two AvahiKey object contain the same
+ * data. AVAHI_DNS_CLASS_ANY/AVAHI_DNS_TYPE_ANY are treated like any
+ * other class/type. */
+gboolean avahi_key_equal(const AvahiKey *a, const AvahiKey *b); 
+
+/** Match a key to a key pattern. The pattern has a type of
+AVAHI_DNS_CLASS_ANY, the classes are taken to be equal. Same for the
+type. If the pattern has neither class nor type with ANY constants,
+this function is identical to avahi_key_equal(). In contrast to
+avahi_equal() this function is not commutative. */
+gboolean avahi_key_pattern_match(const AvahiKey *pattern, const AvahiKey *k);
 
+/** Check whether a key is a pattern key, i.e. the class/type has a
+ * value of AVAHI_DNS_CLASS_ANY/AVAHI_DNS_TYPE_ANY */
 gboolean avahi_key_is_pattern(const AvahiKey *k);
 
+/** Return a numeric hash value for a key for usage in hash tables. */
 guint avahi_key_hash(const AvahiKey *k);
 
+/** Create a new record object. Record data should be filled in right after creation. The reference counter is set to 1. */
 AvahiRecord *avahi_record_new(AvahiKey *k, guint32 ttl);
+
+/** Create a new record object. Record data should be filled in right after creation. The reference counter is set to 1. */
 AvahiRecord *avahi_record_new_full(const gchar *name, guint16 class, guint16 type, guint32 ttl);
+
+/** Increase the reference counter of an AvahiRecord by one. */
 AvahiRecord *avahi_record_ref(AvahiRecord *r);
+
+/** Decrease the reference counter of an AvahiRecord by one. */
 void avahi_record_unref(AvahiRecord *r);
 
+/** Return a textual representation of the specified DNS class. The
+ * returned pointer points to a read only internal string. */
 const gchar *avahi_dns_class_to_string(guint16 class);
+
+/** Return a textual representation of the specified DNS class. The
+ * returned pointer points to a read only internal string. */
 const gchar *avahi_dns_type_to_string(guint16 type);
 
-gchar *avahi_key_to_string(const AvahiKey *k); /* g_free() the result! */
-gchar *avahi_record_to_string(const AvahiRecord *r);  /* g_free() the result! */
+/** Create a textual representation of the specified key. g_free() the
+ * result! */
+gchar *avahi_key_to_string(const AvahiKey *k);
+
+/** Create a textual representation of the specified record, similar
+ * in style to BIND zone file data. g_free() the result! */
+gchar *avahi_record_to_string(const AvahiRecord *r); 
 
+/** Check whether two records are equal (regardless of the TTL */
 gboolean avahi_record_equal_no_ttl(const AvahiRecord *a, const AvahiRecord *b);
 
+/** Make a deep copy of an AvahiRecord object */
 AvahiRecord *avahi_record_copy(AvahiRecord *r);
 
-/* returns a maximum estimate for the space that is needed to store
- * this key in a DNS packet */
+/** Returns a maximum estimate for the space that is needed to store
+ * this key in a DNS packet. */
 guint avahi_key_get_estimate_size(AvahiKey *k);
 
-/* ditto */
+/** Returns a maximum estimate for the space that is needed to store
+ * the record in a DNS packet. */
 guint avahi_record_get_estimate_size(AvahiRecord *r);
 
+/** Do a mDNS spec conforming lexicographical comparison of the two
+ * records. Return a negative value if a < b, a positive if a > b,
+ * zero if equal. */
 gint avahi_record_lexicographical_compare(AvahiRecord *a, AvahiRecord *b);
 
+/** Return TRUE if the specified record is an mDNS goodbye record. i.e. TTL is zero. */
 gboolean avahi_record_is_goodbye(AvahiRecord *r);
 
 #endif
diff --git a/avahi-common/strlst.h b/avahi-common/strlst.h
index 4fde8eb..13a6b2a 100644
--- a/avahi-common/strlst.h
+++ b/avahi-common/strlst.h
@@ -25,7 +25,7 @@
 #include <glib.h>
 
 /** Linked list of strings that can contain any number of binary
- * characters, include NUL bytes. An empty list is created by
+ * characters, including NUL bytes. An empty list is created by
  * assigning a NULL to a pointer to AvahiStringList. The string list
  * is stored in reverse order, so that appending to the string list is
  * effectively a prepending to the linked list.  This object is used
diff --git a/avahi-core/announce.c b/avahi-core/announce.c
index 3374ada..0b7af8d 100644
--- a/avahi-core/announce.c
+++ b/avahi-core/announce.c
@@ -158,7 +158,7 @@ static void next_state(AvahiAnnouncement *a) {
         else
             avahi_server_prepare_response(a->server, a->interface, a->entry, FALSE, FALSE);
 
-        avahi_server_generate_response(a->server, a->interface, NULL, NULL, 0, FALSE);
+        avahi_server_generate_response(a->server, a->interface, NULL, NULL, 0, FALSE, FALSE);
 
         if (++a->n_iteration >= 4) {
 /*             gchar *t; */
diff --git a/avahi-core/server.c b/avahi-core/server.c
index 719f9a9..668e098 100644
--- a/avahi-core/server.c
+++ b/avahi-core/server.c
@@ -249,9 +249,9 @@ static void incoming_probe(AvahiServer *s, AvahiRecord *record, AvahiInterface *
     if (!ours) {
 
         if (won)
-            avahi_log_debug("xxx Recieved conflicting probe [%s]. Local host won.", t);
+            avahi_log_debug("Recieved conflicting probe [%s]. Local host won.", t);
         else if (lost) {
-            avahi_log_debug("yyy Recieved conflicting probe [%s]. Local host lost. Withdrawing.", t);
+            avahi_log_debug("Recieved conflicting probe [%s]. Local host lost. Withdrawing.", t);
             withdraw_rrset(s, record->key);
         }
     }
@@ -361,7 +361,7 @@ static void append_aux_records_to_list(AvahiServer *s, AvahiInterface *i, AvahiR
     avahi_server_enumerate_aux_records(s, i, r, append_aux_callback, &unicast_response);
 }
 
-void avahi_server_generate_response(AvahiServer *s, AvahiInterface *i, AvahiDnsPacket *p, const AvahiAddress *a, guint16 port, gboolean legacy_unicast) {
+void avahi_server_generate_response(AvahiServer *s, AvahiInterface *i, AvahiDnsPacket *p, const AvahiAddress *a, guint16 port, gboolean legacy_unicast, gboolean immediately) {
 
     g_assert(s);
     g_assert(i);
@@ -405,7 +405,7 @@ void avahi_server_generate_response(AvahiServer *s, AvahiInterface *i, AvahiDnsP
         
         while ((r = avahi_record_list_next(s->record_list, &flush_cache, &unicast_response, &auxiliary))) {
                         
-            if (!avahi_interface_post_response(i, r, flush_cache, a, !tc && flush_cache && !auxiliary) && unicast_response) {
+            if (!avahi_interface_post_response(i, r, flush_cache, a, immediately || (flush_cache && !tc && !auxiliary)) && unicast_response) {
 
                 append_aux_records_to_list(s, i, r, unicast_response);
                 
@@ -539,6 +539,7 @@ static void reflect_probe(AvahiServer *s, AvahiInterface *i, AvahiRecord *r) {
 
 static void handle_query_packet(AvahiServer *s, AvahiDnsPacket *p, AvahiInterface *i, const AvahiAddress *a, guint16 port, gboolean legacy_unicast) {
     guint n;
+    gboolean is_probe;
     
     g_assert(s);
     g_assert(p);
@@ -548,6 +549,8 @@ static void handle_query_packet(AvahiServer *s, AvahiDnsPacket *p, AvahiInterfac
 /*     avahi_log_debug("query"); */
 
     g_assert(avahi_record_list_empty(s->record_list));
+
+    is_probe = avahi_dns_packet_get_field(p, AVAHI_DNS_FIELD_NSCOUNT) > 0;
     
     /* Handle the questions */
     for (n = avahi_dns_packet_get_field(p, AVAHI_DNS_FIELD_QDCOUNT); n > 0; n --) {
@@ -609,7 +612,7 @@ static void handle_query_packet(AvahiServer *s, AvahiDnsPacket *p, AvahiInterfac
     }
 
     if (!avahi_record_list_empty(s->record_list))
-        avahi_server_generate_response(s, i, p, a, port, legacy_unicast);
+        avahi_server_generate_response(s, i, p, a, port, legacy_unicast, is_probe);
 
     return;
     
@@ -657,7 +660,7 @@ static void handle_response_packet(AvahiServer *s, AvahiDnsPacket *p, AvahiInter
        records have been scheduling for sending. We need to flush them
        here. */
     if (!avahi_record_list_empty(s->record_list))
-        avahi_server_generate_response(s, i, NULL, NULL, 0, FALSE);
+        avahi_server_generate_response(s, i, NULL, NULL, 0, FALSE, TRUE);
 }
 
 static AvahiLegacyUnicastReflectSlot* allocate_slot(AvahiServer *s) {
diff --git a/avahi-core/server.h b/avahi-core/server.h
index ad8576d..9a1fca3 100644
--- a/avahi-core/server.h
+++ b/avahi-core/server.h
@@ -137,7 +137,7 @@ void avahi_server_post_query(AvahiServer *s, gint interface, guchar protocol, Av
 
 void avahi_server_prepare_response(AvahiServer *s, AvahiInterface *i, AvahiEntry *e, gboolean unicast_response, gboolean auxiliary);
 void avahi_server_prepare_matching_responses(AvahiServer *s, AvahiInterface *i, AvahiKey *k, gboolean unicast_response);
-void avahi_server_generate_response(AvahiServer *s, AvahiInterface *i, AvahiDnsPacket *p, const AvahiAddress *a, guint16 port, gboolean legacy_unicast);
+void avahi_server_generate_response(AvahiServer *s, AvahiInterface *i, AvahiDnsPacket *p, const AvahiAddress *a, guint16 port, gboolean legacy_unicast, gboolean is_probe);
 
 void avahi_entry_group_change_state(AvahiEntryGroup *g, AvahiEntryGroupState state);