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
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 */,
* 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*);
/** 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
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,
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,
/** 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. */
/** 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,
/** 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,
/** 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,
/** Cleans up and frees an AvahiRecordBrowser object */
int avahi_record_browser_free(AvahiRecordBrowser *);
+/** @} */
+
AVAHI_C_DECL_END
#endif
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,
/** 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*);
/** 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,
const char *domain,
AvahiStringList *strlst);
+/** \cond fulldocs */
/** Add a host/address pair */
int avahi_entry_group_add_address(
AvahiEntryGroup *group,
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(
const void *rdata,
size_t size);
+/** @} */
+
AVAHI_C_DECL_END
#endif
} 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);
/** 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
* \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
* 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
*
* 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
* 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
*
* - 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
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() */
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 {
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;
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 */
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
/** 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 {
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)
/** 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);
* 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);
/** 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 */
/** 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
/** 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
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
/** 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. */
/** 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. */
* 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);
/** 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);
/** 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
/** 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
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;
/** 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);
/** 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);
/** 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
/** 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.*/
/** Query the address family we're looking for. */
AvahiProtocol aui_service_dialog_get_address_family(AuiServiceDialog *d);
+/** @} */
+
G_END_DECLS
#endif
projects / catta / commitdiff