From: Lennart Poettering Date: Sat, 25 Jun 2005 00:43:57 +0000 (+0000) Subject: * doxygen updates X-Git-Url: https://git.meshlink.io/?a=commitdiff_plain;h=ff4a54d9cda0146974fab1d4f8da52e26d252eed;p=catta * doxygen updates * reply to probe queries immediately git-svn-id: file:///home/lennart/svn/public/avahi/trunk@147 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe --- 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 #include + +/** 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 /** 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);