From 8c4483baa593205c3eaecebe0738d1455025777c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 9 May 2007 19:45:54 +0000 Subject: Doxygen documentation cleanups: * Hide a few irrelevant header files and definitions from doxygen to make the docs shorter * Update some texts * Put functions into categories git-svn-id: file:///home/lennart/svn/public/avahi/trunk@1477 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe --- avahi-common/address.h | 16 +++++++- avahi-common/defs.h | 105 +++++++++++++++++++++++++++++++++++-------------- avahi-common/domain.h | 47 ++++++++++++++++------ avahi-common/malloc.h | 2 + avahi-common/strlst.h | 46 ++++++++++++++++++---- 5 files changed, 167 insertions(+), 49 deletions(-) (limited to 'avahi-common') diff --git a/avahi-common/address.h b/avahi-common/address.h index b8706ee..5c2f580 100644 --- a/avahi-common/address.h +++ b/avahi-common/address.h @@ -79,19 +79,31 @@ typedef struct AvahiAddress { } data; } AvahiAddress; +/** @{ \name Comparison */ + /** Compare two addresses. Returns 0 when equal, a negative value when a < b, a positive value when a > b. */ int avahi_address_cmp(const AvahiAddress *a, const AvahiAddress *b); +/** @} */ + +/** @{ \name String conversion */ + /** Convert the specified address *a to a human readable character string, use AVAHI_ADDRESS_STR_MAX to allocate an array of the right size */ char *avahi_address_snprint(char *ret_s, size_t length, const AvahiAddress *a); -/** Convert the specifeid human readable character string to an +/** Convert the specified human readable character string to an * address structure. Set af to AVAHI_UNSPEC for automatic address * family detection. */ AvahiAddress *avahi_address_parse(const char *s, AvahiProtocol af, AvahiAddress *ret_addr); +/** @} */ + +/** \cond fulldocs */ /** Generate the DNS reverse lookup name for an IPv4 or IPv6 address. */ char* avahi_reverse_lookup_name(const AvahiAddress *a, char *ret_s, size_t length); +/** \endcond */ + +/** @{ \name Protocol/address family handling */ /** Map AVAHI_PROTO_xxx constants to Unix AF_xxx constants */ int avahi_proto_to_af(AvahiProtocol proto); @@ -102,6 +114,8 @@ AvahiProtocol avahi_af_to_proto(int af); /** Return a textual representation of the specified protocol number. i.e. "IPv4", "IPv6" or "UNSPEC" */ const char* avahi_proto_to_string(AvahiProtocol proto); +/** @} */ + AVAHI_C_DECL_END #endif diff --git a/avahi-common/defs.h b/avahi-common/defs.h index 4efa5ad..59bf271 100644 --- a/avahi-common/defs.h +++ b/avahi-common/defs.h @@ -31,7 +31,7 @@ * \section choose_api Choosing an API * * Avahi provides three programming APIs for integration of - * mDNS/DNS-SD features into your progams: + * mDNS/DNS-SD features into your C progams: * * \li avahi-core: an API for embedding a complete mDNS/DNS-SD stack * into your software. This is intended for developers of embedded @@ -51,16 +51,41 @@ * In addition to the three APIs described above Avahi supports two * compatibility libraries: * - * \li avahi-compat-libdns_sd: the original Bonjour API as documented + * \li avahi-compat-libdns_sd: the original Bonjour API as documented * in the header file "dns_sd.h" by Apple Computer, Inc. * - * \li avahi-compat-howl: the HOWL API as released with HOWL 0.9.8 by + * \li avahi-compat-howl: the HOWL API as released with HOWL 0.9.8 by * Porchdog Software. * * Please note that these compatibility layers are incomplete and * generally a waste of resources. We strongly encourage everyone to * use our native APIs for newly written programs and to port older * programs to avahi-client! + * + * The native APIs (avahi-client and avahi-core) can be integrated + * into external event loops. We provide adapters for the following + * event loop implementations: + * + * \li avahi-glib: The GLIB main loop as used by GTk+/GNOME + * + * \li avahi-qt: The Qt main loop as used by Qt/KDE + * + * Finally, we provide a high-level Gtk+ GUI dialog called + * avahi-ui for user-friendly browsing for services. + * + * The doxygen-generated API documentation covers avahi-client + * (including its auxiliary APIs), the event loop adapters and + * avahi-ui. For the other APIs please consult the original + * documentation (for the compatibility APIs) or the header files. + * + * Please note that the doxygen-generated API documentation of the + * native Avahi API is not complete. A few definitions that are part + * of the Avahi API have been removed from this documentation, either + * because they are only relevant in a very few low-level applications + * or because they are considered obsolete. Please consult the C header + * files for all definitions that are part of the Avahi API. Please + * note that these hidden definitions are considered part of the Avahi + * API and will stay available in the API in the future. * * \section error_reporting Error Reporting * @@ -99,8 +124,8 @@ * whenever the server state changes. * - Only register your services when the server is in state * AVAHI_SERVER_RUNNING. If you register your services in other server - * states they might not be accessible since the local host name is - * not established. + * states they might not be accessible since the local host name might not necessarily + * be established. * - Remove your services when the server enters * AVAHI_SERVER_COLLISION or AVAHI_SERVER_REGISTERING state. Your * services may no be reachable anymore since the local host name is @@ -108,7 +133,7 @@ * established. * - When registering services, use the following algorithm: * - Create a new entry group (i.e. avahi_entry_group_new()) - * - Add your service(s)/additional host names (i.e. avahi_entry_group_add_service()) + * - Add your service(s)/additional RRs/subtypes (e.g. avahi_entry_group_add_service()) * - Commit the entry group (i.e. avahi_entry_group_commit()) * - Subscribe to entry group state changes. * - If the entry group enters AVAHI_ENTRY_GROUP_COLLISION state the @@ -133,17 +158,11 @@ * * - For normal applications you need to call avahi_service_browser_new() * for the service type you want to browse for. Use - * avahi_client_resolve_service() to acquire service data for a a service + * avahi_service_resolver_new() to acquire service data for a service * name. * - You can use avahi_domain_browser_new() to get a list of announced * browsing domains. Please note that not all domains whith services * on the LAN are mandatorily announced. - * - Network monitor software may use avahi_service_type_browser_new() - * to browse for the list of available service types on the LAN. This - * API should NOT be used in normal software since it increases - * traffic immensly. In addition not all DNS-SD implementations - * announce their services in away that they can be found with - * avahi_server_type_browser_new(). * - There is no need to subscribe to server state changes. * * \section daemon_dies How to Write a Client That Can Deal with Daemon Restarts @@ -194,6 +213,17 @@ AVAHI_C_DECL_BEGIN +/** @{ \name States */ + +/** States of a server object */ +typedef enum { + AVAHI_SERVER_INVALID, /**< Invalid state (initial) */ + AVAHI_SERVER_REGISTERING, /**< Host RRs are being registered */ + AVAHI_SERVER_RUNNING, /**< All host RRs have been established */ + AVAHI_SERVER_COLLISION, /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */ + AVAHI_SERVER_FAILURE /**< Some fatal failure happened, the server is unable to proceed */ +} AvahiServerState; + /** States of an entry group object */ typedef enum { AVAHI_ENTRY_GROUP_UNCOMMITED, /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */ @@ -203,15 +233,9 @@ typedef enum { AVAHI_ENTRY_GROUP_FAILURE /**< Some kind of failure happened, the entries have been withdrawn */ } AvahiEntryGroupState; -/** The type of domain to browse for */ -typedef enum { - AVAHI_DOMAIN_BROWSER_BROWSE, /**< Browse for a list of available browsing domains */ - AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT, /**< Browse for the default browsing domain */ - AVAHI_DOMAIN_BROWSER_REGISTER, /**< Browse for a list of available registering domains */ - AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT, /**< Browse for the default registering domain */ - AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY, /**< Legacy browse domain - see DNS-SD spec for more information */ - AVAHI_DOMAIN_BROWSER_MAX -} AvahiDomainBrowserType; +/** @} */ + +/** @{ \name Flags */ /** Some flags for publishing functions */ typedef enum { @@ -219,17 +243,23 @@ typedef enum { AVAHI_PUBLISH_NO_PROBE = 2, /**< For raw records: Though the RRset is intended to be unique no probes shall be sent */ AVAHI_PUBLISH_NO_ANNOUNCE = 4, /**< For raw records: Do not announce this RR to other hosts */ AVAHI_PUBLISH_ALLOW_MULTIPLE = 8, /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */ +/** \cond fulldocs */ AVAHI_PUBLISH_NO_REVERSE = 16, /**< For address records: don't create a reverse (PTR) entry */ AVAHI_PUBLISH_NO_COOKIE = 32, /**< For service records: do not implicitly add the local service cookie to TXT data */ +/** \endcond */ AVAHI_PUBLISH_UPDATE = 64, /**< Update existing records instead of adding new ones */ +/** \cond fulldocs */ AVAHI_PUBLISH_USE_WIDE_AREA = 128, /**< Register the record using wide area DNS (i.e. unicast DNS update) */ AVAHI_PUBLISH_USE_MULTICAST = 256 /**< Register the record using multicast DNS */ +/** \endcond */ } AvahiPublishFlags; /** Some flags for lookup functions */ typedef enum { +/** \cond fulldocs */ AVAHI_LOOKUP_USE_WIDE_AREA = 1, /**< Force lookup via wide area DNS */ AVAHI_LOOKUP_USE_MULTICAST = 2, /**< Force lookup via multicast DNS */ +/** \endcond */ AVAHI_LOOKUP_NO_TXT = 4, /**< When doing service resolving, don't lookup TXT record */ AVAHI_LOOKUP_NO_ADDRESS = 8 /**< When doing service resolving, don't lookup A/AAAA record */ } AvahiLookupFlags; @@ -244,6 +274,10 @@ typedef enum { AVAHI_LOOKUP_RESULT_STATIC = 32 /**< The returned data has been defined statically by some configuration option */ } AvahiLookupResultFlags; +/** @} */ + +/** @{ \name Events */ + /** Type of callback event when browsing */ typedef enum { AVAHI_BROWSER_NEW, /**< The object is new on the network */ @@ -259,15 +293,23 @@ typedef enum { AVAHI_RESOLVER_FAILURE /**< Resolving failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */ } AvahiResolverEvent; -/** States of a server object */ +/** @} */ + +/** @{ \name Other definitions */ + +/** The type of domain to browse for */ typedef enum { - AVAHI_SERVER_INVALID, /**< Invalid state (initial) */ - AVAHI_SERVER_REGISTERING, /**< Host RRs are being registered */ - AVAHI_SERVER_RUNNING, /**< All host RRs have been established */ - AVAHI_SERVER_COLLISION, /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */ - AVAHI_SERVER_FAILURE /**< Some fatal failure happened, the server is unable to proceed */ -} AvahiServerState; + AVAHI_DOMAIN_BROWSER_BROWSE, /**< Browse for a list of available browsing domains */ + AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT, /**< Browse for the default browsing domain */ + AVAHI_DOMAIN_BROWSER_REGISTER, /**< Browse for a list of available registering domains */ + AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT, /**< Browse for the default registering domain */ + AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY, /**< Legacy browse domain - see DNS-SD spec for more information */ + AVAHI_DOMAIN_BROWSER_MAX +} AvahiDomainBrowserType; +/** @} */ + +/** \cond fulldocs */ /** For every service a special TXT item is implicitly added, which * contains a random cookie which is private to the local daemon. This * can be used by clients to determine if two services on two @@ -276,6 +318,9 @@ typedef enum { /** In invalid cookie as special value */ #define AVAHI_SERVICE_COOKIE_INVALID (0) +/** \endcond fulldocs */ + +/** @{ \name DNS RR definitions */ /** DNS record types, see RFC 1035 */ enum { @@ -296,6 +341,8 @@ enum { AVAHI_DNS_CLASS_IN = 0x01, /**< Probably the only class we will ever use */ }; +/** @} */ + /** The default TTL for RRs which contain a host name of some kind. */ #define AVAHI_DEFAULT_TTL_HOST_NAME (120) diff --git a/avahi-common/domain.h b/avahi-common/domain.h index 7073e1c..14d069d 100644 --- a/avahi-common/domain.h +++ b/avahi-common/domain.h @@ -45,6 +45,8 @@ AVAHI_C_DECL_BEGIN /** Maximum size of an unescaped label */ #define AVAHI_LABEL_MAX 64 +/** @{ \name Normalization */ + /** Normalize a domain name into canonical form. This drops trailing * dots and removes useless backslash escapes. */ char *avahi_normalize_name(const char *s, char *ret_s, size_t size); @@ -54,9 +56,20 @@ char *avahi_normalize_name(const char *s, char *ret_s, size_t size); * result! */ char *avahi_normalize_name_strdup(const char *s); +/** @} */ + +/** @{ \name Comparison */ + /** Return 1 when the specified domain names are equal, 0 otherwise */ int avahi_domain_equal(const char *a, const char *b); +/** Return some kind of hash value for the domain, useful for using domains as hash table keys. */ +unsigned avahi_domain_hash(const char *name); + +/** @} */ + +/** @{ \name Escaping */ + /** Read the first label from the textual domain name *name, unescape * it and write it to dest, *name is changed to point to the next label*/ char *avahi_unescape_label(const char **name, char *dest, size_t size); @@ -64,26 +77,28 @@ char *avahi_unescape_label(const char **name, char *dest, size_t size); /** Escape the domain name in *src and write it to *ret_name */ char *avahi_escape_label(const char* src, size_t src_length, char **ret_name, size_t *ret_size); -/** Return a pointer to the type section of a subtype i.e. _foo._sub._bar._tcp => _bar._tcp */ -const char *avahi_get_type_from_subtype(const char *t); +/** @} */ -/** Return 1 when the specified string contains a valid generic +/** @{ \name Validity Checks */ + +/** Return 1 when the specified string contains a valid generic DNS-SD * service type (i.e. a series of words starting with "_"), 0 * otherwise */ int avahi_is_valid_service_type_generic(const char *t); -/** Return 1 when the specified string contains a valid strict service - * type (i.e. consisting of only two words, the latter being either - * _udp or _tcp), 0 otherwise */ +/** Return 1 when the specified string contains a valid strict DNS-SD + * service type (i.e. consisting of only two words, the latter being + * either _udp or _tcp), 0 otherwise */ int avahi_is_valid_service_type_strict(const char *t); -/** Return 1 when the specified string contains a valid service subtype, 0 otherwise */ +/** Return 1 when the specified string contains a valid DNS-SD service + * subtype, 0 otherwise */ int avahi_is_valid_service_subtype(const char *t); /** Return 1 when the specified string contains a valid domain name, 0 otherwise */ int avahi_is_valid_domain_name(const char *t); -/** Return 1 when the specified string contains a valid service name, 0 otherwise */ +/** Return 1 when the specified string contains a valid DNS-SD service name, 0 otherwise */ int avahi_is_valid_service_name(const char *t); /** Return 1 when the specified string contains a valid non-FQDN host name (i.e. without dots), 0 otherwise */ @@ -92,15 +107,25 @@ int avahi_is_valid_host_name(const char *t); /** Return 1 when the specified string contains a valid FQDN host name (i.e. with more than one label and non-numerical), 0 otherwise. \since 0.6.9 */ int avahi_is_valid_fqdn(const char *t); -/** Return some kind of hash value for the domain, useful for using domains as hash table keys. */ -unsigned avahi_domain_hash(const char *name); +/** @} */ -/** Construct a valid complete service name from a name, a type and a domain */ +/** @{ \name DNS-SD service name handling */ + +/** Construct a valid complete DNS-SD service name from a name, a type and a domain */ int avahi_service_name_join(char *p, size_t size, const char *name, const char *type, const char *domain); /** Split a full service name into name, type and domain */ int avahi_service_name_split(const char *p, char *name, size_t name_size, char *type, size_t type_size, char *domain, size_t domain_size); +/** @} */ + +/** @{ \name DNS-SD Subtype handling */ + +/** Return a pointer to the type section of a subtype i.e. _foo._sub._bar._tcp => _bar._tcp */ +const char *avahi_get_type_from_subtype(const char *t); + +/** @} */ + AVAHI_C_DECL_END #endif diff --git a/avahi-common/malloc.h b/avahi-common/malloc.h index 40b6272..2430199 100644 --- a/avahi-common/malloc.h +++ b/avahi-common/malloc.h @@ -88,8 +88,10 @@ void avahi_set_allocator(const AvahiAllocator *a); /** Like sprintf() but store the result in a freshly allocated buffer. Free this with avahi_free() */ char *avahi_strdup_printf(const char *fmt, ... ) AVAHI_GCC_PRINTF_ATTR12; +/** \cond fulldocs */ /** Same as avahi_strdup_printf() but take a va_list instead of varargs */ char *avahi_strdup_vprintf(const char *fmt, va_list ap); +/** \endcond */ AVAHI_C_DECL_END diff --git a/avahi-common/strlst.h b/avahi-common/strlst.h index 26708a5..119e416 100644 --- a/avahi-common/strlst.h +++ b/avahi-common/strlst.h @@ -45,13 +45,17 @@ typedef struct AvahiStringList { uint8_t text[1]; /**< Character data */ } AvahiStringList; +/** @{ \name Construction and destruction */ + /** Create a new string list by taking a variable list of NUL * terminated strings. The strings are copied using g_strdup(). The * argument list must be terminated by a NULL pointer. */ AvahiStringList *avahi_string_list_new(const char *txt, ...) AVAHI_GCC_SENTINEL; +/** \cond fulldocs */ /** Same as avahi_string_list_new() but pass a va_list structure */ AvahiStringList *avahi_string_list_new_va(va_list va); +/** \endcond */ /** Create a new string list from a string array. The strings are * copied using g_strdup(). length should contain the length of the @@ -61,6 +65,10 @@ AvahiStringList *avahi_string_list_new_from_array(const char **array, int length /** Free a string list */ void avahi_string_list_free(AvahiStringList *l); +/** @} */ + +/** @{ \name Adding strings */ + /** Append a NUL terminated string to the specified string list. The * passed string is copied using g_strdup(). Returns the new list * start. */ @@ -69,8 +77,10 @@ AvahiStringList *avahi_string_list_add(AvahiStringList *l, const char *text); /** Append a new NUL terminated formatted string to the specified string list */ AvahiStringList *avahi_string_list_add_printf(AvahiStringList *l, const char *format, ...) AVAHI_GCC_PRINTF_ATTR23; +/** \cond fulldocs */ /** Append a new NUL terminated formatted string to the specified string list */ AvahiStringList *avahi_string_list_add_vprintf(AvahiStringList *l, const char *format, va_list va); +/** \endcond */ /** Append an arbitrary length byte string to the list. Returns the * new list start. */ @@ -88,21 +98,29 @@ AvahiStringList*avahi_string_list_add_anonymous(AvahiStringList *l, size_t size) * NULL pointer. Returns the new list start. */ AvahiStringList *avahi_string_list_add_many(AvahiStringList *r, ...) AVAHI_GCC_SENTINEL; +/** \cond fulldocs */ /** Same as avahi_string_list_add_many(), but use a va_list * structure. Returns the new list start. */ AvahiStringList *avahi_string_list_add_many_va(AvahiStringList *r, va_list va); +/** \endcond */ + +/** @} */ + +/** @{ \name String list operations */ /** Convert the string list object to a single character string, * seperated by spaces and enclosed in "". avahi_free() the result! This * function doesn't work well with string that contain NUL bytes. */ char* avahi_string_list_to_string(AvahiStringList *l); +/** \cond fulldocs */ /** Serialize the string list object in a way that is compatible with * the storing of DNS TXT records. Strings longer than 255 bytes are truncated. */ size_t avahi_string_list_serialize(AvahiStringList *l, void * data, size_t size); /** Inverse of avahi_string_list_serialize() */ int avahi_string_list_parse(const void *data, size_t size, AvahiStringList **ret); +/** \endcond */ /** Compare to string lists */ int avahi_string_list_equal(const AvahiStringList *a, const AvahiStringList *b); @@ -116,6 +134,23 @@ AvahiStringList* avahi_string_list_reverse(AvahiStringList *l); /** Return the number of elements in the string list */ unsigned avahi_string_list_length(const AvahiStringList *l); +/** @} */ + +/** @{ \name Accessing items */ + +/** Returns the next item in the string list */ +AvahiStringList *avahi_string_list_get_next(AvahiStringList *l); + +/** Returns the text for the current item */ +uint8_t *avahi_string_list_get_text(AvahiStringList *l); + +/** Returns the size of the current text */ +size_t avahi_string_list_get_size(AvahiStringList *l); + +/** @} */ + +/** @{ \name DNS-SD TXT pair handling */ + /** Find the string list entry for the given DNS-SD TXT key */ AvahiStringList *avahi_string_list_find(AvahiStringList *l, const char *key); @@ -133,18 +168,13 @@ AvahiStringList *avahi_string_list_add_pair(AvahiStringList *l, const char *key, /** Same as avahi_string_list_add_pair() but allow strings containing NUL bytes in *value. */ AvahiStringList *avahi_string_list_add_pair_arbitrary(AvahiStringList *l, const char *key, const uint8_t *value, size_t size); -/** Returns the next item in the string list */ -AvahiStringList *avahi_string_list_get_next(AvahiStringList *l); - -/** Returns the text for the current item */ -uint8_t *avahi_string_list_get_text(AvahiStringList *l); - -/** Returns the size of the current text */ -size_t avahi_string_list_get_size(AvahiStringList *l); +/** @} */ +/** \cond fulldocs */ /** Try to find a magic service cookie in the specified DNS-SD string * list. Or return AVAHI_SERVICE_COOKIE_INVALID if none is found. */ uint32_t avahi_string_list_get_service_cookie(AvahiStringList *l); +/** \endcond */ AVAHI_C_DECL_END -- cgit