summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2007-05-09 19:45:54 +0000
committerLennart Poettering <lennart@poettering.net>2007-05-09 19:45:54 +0000
commit8c4483baa593205c3eaecebe0738d1455025777c (patch)
tree27bf97150091d6aa17c1c7fac9fe11bec34115fe
parent2d33502402a44a5eed21d633e03e65a0511d5ff2 (diff)
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
-rw-r--r--Makefile.am5
-rw-r--r--avahi-client/client.h18
-rw-r--r--avahi-client/lookup.h210
-rw-r--r--avahi-client/publish.h14
-rw-r--r--avahi-common/address.h16
-rw-r--r--avahi-common/defs.h105
-rw-r--r--avahi-common/domain.h47
-rw-r--r--avahi-common/malloc.h2
-rw-r--r--avahi-common/strlst.h46
-rw-r--r--avahi-ui/avahi-ui.h32
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 <b>avahi-core</b>: 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 <b>avahi-compat-libdns_sd</b>: 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 <b>avahi-compat-howl</b>: 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 <b>avahi-glib</b>: The GLIB main loop as used by GTk+/GNOME
+ *
+ * \li <b>avahi-qt</b>: The Qt main loop as used by Qt/KDE
+ *
+ * Finally, we provide a high-level Gtk+ GUI dialog called
+ * <b>avahi-ui</b> 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