From 8c4483baa593205c3eaecebe0738d1455025777c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 9 May 2007 19:45:54 +0000 Subject: [PATCH] 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 --- Makefile.am | 5 +- avahi-client/client.h | 18 +++- avahi-client/lookup.h | 210 +++++++++++++++++++++++------------------ avahi-client/publish.h | 14 +++ 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 +++++++-- avahi-ui/avahi-ui.h | 32 ++++++- 10 files changed, 346 insertions(+), 149 deletions(-) diff --git a/Makefile.am b/Makefile.am index 0411c74..2071916 100644 --- a/Makefile.am +++ b/Makefile.am @@ -76,16 +76,15 @@ SUBDIRS = \ DX_INPUT = \ $(srcdir)/avahi-common/address.h \ + $(srcdir)/avahi-common/malloc.h \ $(srcdir)/avahi-common/strlst.h \ $(srcdir)/avahi-common/alternative.h \ $(srcdir)/avahi-common/defs.h \ $(srcdir)/avahi-common/error.h \ - $(srcdir)/avahi-common/malloc.h \ $(srcdir)/avahi-common/domain.h \ $(srcdir)/avahi-common/watch.h \ $(srcdir)/avahi-common/simple-watch.h \ - $(srcdir)/avahi-common/thread-watch.h \ - $(srcdir)/avahi-common/timeval.h + $(srcdir)/avahi-common/thread-watch.h DX_EXAMPLE_PATH = $(srcdir)/examples DX_EXAMPLE_PATTERNS = *.c diff --git a/avahi-client/client.h b/avahi-client/client.h index 6a12e9a..2f86d02 100644 --- a/avahi-client/client.h +++ b/avahi-client/client.h @@ -58,6 +58,8 @@ typedef void (*AvahiClientCallback) ( AvahiClientState state /**< The new state of the client */, void* userdata /**< The user data that was passed to avahi_client_new() */); +/** @{ \name Construction and destruction */ + /** Creates a new client instance */ AvahiClient* avahi_client_new ( const AvahiPoll *poll_api /**< The abstract event loop API to use */, @@ -71,6 +73,10 @@ AvahiClient* avahi_client_new ( * to such objects become invalid! */ void avahi_client_free(AvahiClient *client); +/** @} */ + +/** @{ \name Properties */ + /** Get the version of the server */ const char* avahi_client_get_version_string (AvahiClient*); @@ -89,15 +95,25 @@ const char* avahi_client_get_host_name_fqdn (AvahiClient*); /** Get state */ AvahiClientState avahi_client_get_state(AvahiClient *client); -/** Get the last error number */ +/** @{ \name Error Handling */ + +/** Get the last error number. See avahi_strerror() for converting this error code into a human readable string. */ int avahi_client_errno (AvahiClient*); +/** @} */ + +/** \cond fulldocs */ /** Return the local service cookie. returns AVAHI_SERVICE_COOKIE_INVALID on failure. */ uint32_t avahi_client_get_local_service_cookie(AvahiClient *client); +/** \endcond */ + +/** @{ \name Libc NSS Support */ /** Return 1 if gethostbyname() supports mDNS lookups, 0 otherwise. \since 0.6.5 */ int avahi_nss_support(void); +/** @} */ + AVAHI_C_DECL_END #endif diff --git a/avahi-client/lookup.h b/avahi-client/lookup.h index e7dec49..3e8210a 100644 --- a/avahi-client/lookup.h +++ b/avahi-client/lookup.h @@ -40,27 +40,11 @@ AVAHI_C_DECL_BEGIN +/** @{ \name Domain Browser */ + /** A domain browser object */ typedef struct AvahiDomainBrowser AvahiDomainBrowser; -/** A service browser object */ -typedef struct AvahiServiceBrowser AvahiServiceBrowser; - -/** A service type browser object */ -typedef struct AvahiServiceTypeBrowser AvahiServiceTypeBrowser; - -/** A service resolver object */ -typedef struct AvahiServiceResolver AvahiServiceResolver; - -/** A service resolver object */ -typedef struct AvahiHostNameResolver AvahiHostNameResolver; - -/** An address resolver object */ -typedef struct AvahiAddressResolver AvahiAddressResolver; - -/** A record browser object */ -typedef struct AvahiRecordBrowser AvahiRecordBrowser; - /** The function prototype for the callback of an AvahiDomainBrowser */ typedef void (*AvahiDomainBrowserCallback) ( AvahiDomainBrowser *b, @@ -71,98 +55,76 @@ typedef void (*AvahiDomainBrowserCallback) ( AvahiLookupResultFlags flags, void *userdata); -/** The function prototype for the callback of an AvahiServiceBrowser */ -typedef void (*AvahiServiceBrowserCallback) ( - AvahiServiceBrowser *b, +/** Browse for domains on the local network */ +AvahiDomainBrowser* avahi_domain_browser_new ( + AvahiClient *client, AvahiIfIndex interface, AvahiProtocol protocol, - AvahiBrowserEvent event, - const char *name, - const char *type, const char *domain, - AvahiLookupResultFlags flags, + AvahiDomainBrowserType btype, + AvahiLookupFlags flags, + AvahiDomainBrowserCallback callback, void *userdata); -/** The function prototype for the callback of an AvahiServiceTypeBrowser */ -typedef void (*AvahiServiceTypeBrowserCallback) ( - AvahiServiceTypeBrowser *b, +/** Get the parent client of an AvahiDomainBrowser object */ +AvahiClient* avahi_domain_browser_get_client (AvahiDomainBrowser *); + +/** Cleans up and frees an AvahiDomainBrowser object */ +int avahi_domain_browser_free (AvahiDomainBrowser *); + +/** @} */ + +/** @{ \name Service Browser */ + +/** A service browser object */ +typedef struct AvahiServiceBrowser AvahiServiceBrowser; + +/** The function prototype for the callback of an AvahiServiceBrowser */ +typedef void (*AvahiServiceBrowserCallback) ( + AvahiServiceBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, + const char *name, const char *type, const char *domain, AvahiLookupResultFlags flags, void *userdata); -/** The function prototype for the callback of an AvahiServiceResolver */ -typedef void (*AvahiServiceResolverCallback) ( - AvahiServiceResolver *r, +/** Browse for services of a type on the local network */ +AvahiServiceBrowser* avahi_service_browser_new ( + AvahiClient *client, AvahiIfIndex interface, AvahiProtocol protocol, - AvahiResolverEvent event, - const char *name, const char *type, const char *domain, - const char *host_name, - const AvahiAddress *a, - uint16_t port, - AvahiStringList *txt, - AvahiLookupResultFlags flags, + AvahiLookupFlags flags, + AvahiServiceBrowserCallback callback, void *userdata); -/** The function prototype for the callback of an AvahiHostNameResolver */ -typedef void (*AvahiHostNameResolverCallback) ( - AvahiHostNameResolver *r, - AvahiIfIndex interface, - AvahiProtocol protocol, - AvahiResolverEvent event, - const char *name, - const AvahiAddress *a, - AvahiLookupResultFlags flags, - void *userdata); +/** Get the parent client of an AvahiServiceBrowser object */ +AvahiClient* avahi_service_browser_get_client (AvahiServiceBrowser *); -/** The function prototype for the callback of an AvahiAddressResolver */ -typedef void (*AvahiAddressResolverCallback) ( - AvahiAddressResolver *r, - AvahiIfIndex interface, - AvahiProtocol protocol, - AvahiResolverEvent event, - const AvahiAddress *a, - const char *name, - AvahiLookupResultFlags flags, - void *userdata); +/** Cleans up and frees an AvahiServiceBrowser object */ +int avahi_service_browser_free (AvahiServiceBrowser *); -/** The function prototype for the callback of an AvahiRecordBrowser */ -typedef void (*AvahiRecordBrowserCallback) ( - AvahiRecordBrowser *b, - AvahiIfIndex interface, - AvahiProtocol protocol, - AvahiBrowserEvent event, - const char *name, - uint16_t clazz, - uint16_t type, - const void *rdata, - size_t size, - AvahiLookupResultFlags flags, - void *userdata); +/** @} */ -/** Browse for domains on the local network */ -AvahiDomainBrowser* avahi_domain_browser_new ( - AvahiClient *client, +/** \cond fulldocs */ +/** A service type browser object */ +typedef struct AvahiServiceTypeBrowser AvahiServiceTypeBrowser; + +/** The function prototype for the callback of an AvahiServiceTypeBrowser */ +typedef void (*AvahiServiceTypeBrowserCallback) ( + AvahiServiceTypeBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, + AvahiBrowserEvent event, + const char *type, const char *domain, - AvahiDomainBrowserType btype, - AvahiLookupFlags flags, - AvahiDomainBrowserCallback callback, + AvahiLookupResultFlags flags, void *userdata); -/** Get the parent client of an AvahiDomainBrowser object */ -AvahiClient* avahi_domain_browser_get_client (AvahiDomainBrowser *); - -/** Cleans up and frees an AvahiDomainBrowser object */ -int avahi_domain_browser_free (AvahiDomainBrowser *); - /** Browse for service types on the local network */ AvahiServiceTypeBrowser* avahi_service_type_browser_new ( AvahiClient *client, @@ -179,23 +141,29 @@ AvahiClient* avahi_service_type_browser_get_client (AvahiServiceTypeBrowser *); /** Cleans up and frees an AvahiServiceTypeBrowser object */ int avahi_service_type_browser_free (AvahiServiceTypeBrowser *); -/** Browse for services of a type on the local network */ -AvahiServiceBrowser* avahi_service_browser_new ( - AvahiClient *client, +/** \endcond */ + +/** @{ \name Service Resolver */ + +/** A service resolver object */ +typedef struct AvahiServiceResolver AvahiServiceResolver; + +/** The function prototype for the callback of an AvahiServiceResolver */ +typedef void (*AvahiServiceResolverCallback) ( + AvahiServiceResolver *r, AvahiIfIndex interface, AvahiProtocol protocol, + AvahiResolverEvent event, + const char *name, const char *type, const char *domain, - AvahiLookupFlags flags, - AvahiServiceBrowserCallback callback, + const char *host_name, + const AvahiAddress *a, + uint16_t port, + AvahiStringList *txt, + AvahiLookupResultFlags flags, void *userdata); -/** Get the parent client of an AvahiServiceBrowser object */ -AvahiClient* avahi_service_browser_get_client (AvahiServiceBrowser *); - -/** Cleans up and frees an AvahiServiceBrowser object */ -int avahi_service_browser_free (AvahiServiceBrowser *); - /** Create a new service resolver object. Please make sure to pass all * the service data you received via avahi_service_browser_new()'s * callback function, especially interface and protocol. */ @@ -217,6 +185,23 @@ AvahiClient* avahi_service_resolver_get_client (AvahiServiceResolver *); /** Free a service resolver object */ int avahi_service_resolver_free(AvahiServiceResolver *r); +/** @} */ + +/** \cond fulldocs */ +/** A service resolver object */ +typedef struct AvahiHostNameResolver AvahiHostNameResolver; + +/** The function prototype for the callback of an AvahiHostNameResolver */ +typedef void (*AvahiHostNameResolverCallback) ( + AvahiHostNameResolver *r, + AvahiIfIndex interface, + AvahiProtocol protocol, + AvahiResolverEvent event, + const char *name, + const AvahiAddress *a, + AvahiLookupResultFlags flags, + void *userdata); + /** Create a new hostname resolver object */ AvahiHostNameResolver * avahi_host_name_resolver_new( AvahiClient *client, @@ -234,6 +219,20 @@ AvahiClient* avahi_host_name_resolver_get_client (AvahiHostNameResolver *); /** Free a hostname resolver object */ int avahi_host_name_resolver_free(AvahiHostNameResolver *r); +/** An address resolver object */ +typedef struct AvahiAddressResolver AvahiAddressResolver; + +/** The function prototype for the callback of an AvahiAddressResolver */ +typedef void (*AvahiAddressResolverCallback) ( + AvahiAddressResolver *r, + AvahiIfIndex interface, + AvahiProtocol protocol, + AvahiResolverEvent event, + const AvahiAddress *a, + const char *name, + AvahiLookupResultFlags flags, + void *userdata); + /** Create a new address resolver object from an AvahiAddress object */ AvahiAddressResolver* avahi_address_resolver_new( AvahiClient *client, @@ -250,6 +249,27 @@ AvahiClient* avahi_address_resolver_get_client (AvahiAddressResolver *); /** Free a AvahiAddressResolver resolver object */ int avahi_address_resolver_free(AvahiAddressResolver *r); +/** \endcond */ + +/** @{ \name Record Browser */ + +/** A record browser object */ +typedef struct AvahiRecordBrowser AvahiRecordBrowser; + +/** The function prototype for the callback of an AvahiRecordBrowser */ +typedef void (*AvahiRecordBrowserCallback) ( + AvahiRecordBrowser *b, + AvahiIfIndex interface, + AvahiProtocol protocol, + AvahiBrowserEvent event, + const char *name, + uint16_t clazz, + uint16_t type, + const void *rdata, + size_t size, + AvahiLookupResultFlags flags, + void *userdata); + /** Browse for records of a type on the local network */ AvahiRecordBrowser* avahi_record_browser_new( AvahiClient *client, @@ -268,6 +288,8 @@ AvahiClient* avahi_record_browser_get_client(AvahiRecordBrowser *); /** Cleans up and frees an AvahiRecordBrowser object */ int avahi_record_browser_free(AvahiRecordBrowser *); +/** @} */ + AVAHI_C_DECL_END #endif diff --git a/avahi-client/publish.h b/avahi-client/publish.h index 98f4f98..1e40b18 100644 --- a/avahi-client/publish.h +++ b/avahi-client/publish.h @@ -50,6 +50,8 @@ typedef void (*AvahiEntryGroupCallback) ( AvahiEntryGroupState state /**< The new state of the entry group */, void* userdata /* The arbitrary user data pointer originally passed to avahi_entry_group_new()*/); +/** @{ \name Construction and destruction */ + /** Create a new AvahiEntryGroup object */ AvahiEntryGroup* avahi_entry_group_new( AvahiClient* c, @@ -59,6 +61,10 @@ AvahiEntryGroup* avahi_entry_group_new( /** Clean up and free an AvahiEntryGroup object */ int avahi_entry_group_free (AvahiEntryGroup *); +/** @} */ + +/** @{ \name State */ + /** Commit an AvahiEntryGroup. The entries in the entry group are now registered on the network. Commiting empty entry groups is considered an error. */ int avahi_entry_group_commit (AvahiEntryGroup*); @@ -74,6 +80,10 @@ int avahi_entry_group_is_empty (AvahiEntryGroup*); /** Get an AvahiEntryGroup's owning client instance */ AvahiClient* avahi_entry_group_get_client (AvahiEntryGroup*); +/** @} */ + +/** @{ \name Adding and updating entries */ + /** Add a service. Takes a variable NULL terminated list of TXT record strings as last arguments. Please note that this service is not announced on the network before avahi_entry_group_commit() is called. */ int avahi_entry_group_add_service( AvahiEntryGroup *group, @@ -133,6 +143,7 @@ int avahi_entry_group_update_service_txt_strlst( const char *domain, AvahiStringList *strlst); +/** \cond fulldocs */ /** Add a host/address pair */ int avahi_entry_group_add_address( AvahiEntryGroup *group, @@ -141,6 +152,7 @@ int avahi_entry_group_add_address( AvahiPublishFlags flags, const char *name /**< The FDQN of the new hostname to register */, const AvahiAddress *a /**< The address this host name shall map to */); +/** \endcond */ /** Add an arbitrary record. I hope you know what you do. */ int avahi_entry_group_add_record( @@ -155,6 +167,8 @@ int avahi_entry_group_add_record( const void *rdata, size_t size); +/** @} */ + AVAHI_C_DECL_END #endif 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 diff --git a/avahi-ui/avahi-ui.h b/avahi-ui/avahi-ui.h index 592d09b..b314957 100644 --- a/avahi-ui/avahi-ui.h +++ b/avahi-ui/avahi-ui.h @@ -66,6 +66,8 @@ GType aui_service_dialog_get_type(void) G_GNUC_CONST; /** The GTK service dialog structure */ typedef struct _AuiServiceDialog AuiServiceDialog; +/** @{ \name Construction */ + /** Create a new service browser dialog with the specific title, * parent window and the speicified buttons. The buttons are specified * in a similar way to GtkFileChooserDialog. Please note that at least @@ -75,13 +77,17 @@ GtkWidget* aui_service_dialog_new( GtkWindow *parent, const gchar *first_button_text, ...) G_GNUC_NULL_TERMINATED; -#ifndef DOXYGEN_SHOULD_SKIP_THIS +/** \cond fulldocs */ GtkWidget *aui_service_dialog_new_valist( gchar *title, GtkWindow *parent, const gchar *first_button_text, va_list varargs); -#endif +/** \endcond } + +/** @} */ + +/** @{ \name Service types to browse for */ /** Select the service types to browse for. Takes a NULL terminated list of DNS-SD service types. i.e. _http._tcp */ void aui_service_dialog_set_browse_service_types(AuiServiceDialog *d, const gchar *type, ...) G_GNUC_NULL_TERMINATED; @@ -90,11 +96,19 @@ void aui_service_dialog_set_browse_service_typesv(AuiServiceDialog *d, const gch /** Return the service types currently browsed for. i.e. what was previously set with aui_service_dialog_set_browse_service_types() */ const gchar*const* aui_service_dialog_get_browse_service_types(AuiServiceDialog *d); +/** @} */ + +/** @{ \name Domain to browse in */ + /** Set the domain to browse in */ void aui_service_dialog_set_domain(AuiServiceDialog *d, const gchar *domain); /** Query the domain that is browsed in */ const gchar* aui_service_dialog_get_domain(AuiServiceDialog *d); +/** @} */ + +/** @{ \name Selected service item */ + /** Set the service type for the service to select */ void aui_service_dialog_set_service_type(AuiServiceDialog *d, const gchar *name); @@ -107,6 +121,10 @@ void aui_service_dialog_set_service_name(AuiServiceDialog *d, const gchar *name) /** Query the service name of the currently select service */ const gchar* aui_service_dialog_get_service_name(AuiServiceDialog *d); +/** @} */ + +/** @{ \name Resolved service information */ + /** Return the IP address of the selected service. (Only valid if host name resolving has not been disabled via aui_service_dialog_set_resolve_host_name()) */ const AvahiAddress* aui_service_dialog_get_address(AuiServiceDialog *d); @@ -119,6 +137,10 @@ const gchar* aui_service_dialog_get_host_name(AuiServiceDialog *d); /** Return the TXT metadata of the selected service */ const AvahiStringList *aui_service_dialog_get_txt_data(AuiServiceDialog *d); +/** @} */ + +/** @{ \name Resolving settings */ + /** Disable/Enable automatic service resolving. Disabling this feature * will require you to resolve the selected service on our own. I.e. the port * number, the TXT data and the host name/IP address will not be @@ -141,6 +163,10 @@ void aui_service_dialog_set_resolve_host_name(AuiServiceDialog *d, gboolean reso /** Query the last status of aui_service_dialog_set_resolve_host_name() */ gboolean aui_service_dialog_get_resolve_host_name(AuiServiceDialog *d); +/** @} */ + +/** @{ \name Address family */ + /** Select the address family to look for services of. This can be used to look only for IPv6 services or only for IPv4 services. By default avahi-ui will browse for both IPv4 and IPv6 services.*/ @@ -149,6 +175,8 @@ void aui_service_dialog_set_address_family(AuiServiceDialog *d, AvahiProtocol pr /** Query the address family we're looking for. */ AvahiProtocol aui_service_dialog_get_address_family(AuiServiceDialog *d); +/** @} */ + G_END_DECLS #endif -- 2.39.5