USA.
***/
+/** \file defs.h Some common definitions */
+
#include <avahi-common/cdecl.h>
+/** \mainpage
+ *
+ * \section choose_api Choosing an API
+ *
+ * Avahi provides three programming APIs for integration of
+ * mDNS/DNS-SD features into your progams:
+ *
+ * \li avahi-core: an API for embedding a complete mDNS/DNS-SD stack
+ * into your software. This is intended for developers of embedded
+ * ampliances only. We dissuade from using this API in normal desktop
+ * applications since it is not a good idea to run multiple mDNS
+ * stacks simultaneously on the same host.
+ * \li The DBUS API: an extensive DBUS interface for browsing and
+ * registering mDNS/DNS-SD services using avahi-daemon. We recommend
+ * to use this API for software written in any language but
+ * C. (i.e. python)
+ * \li avahi-client: a simplifying C wrapper around the DBUS API. We
+ * recommend to use this API in C or C++ progams. The DBUS internals
+ * are hidden completely.
+ *
+ * All three APIs are very similar, however avahi-core is the most powerful.
+ *
+ * \section error_reporting Error Reporting
+ *
+ * Some notes on the Avahi error handling:
+ *
+ * - Error codes are negative integers and defined as AVAHI_ERR_xx
+ * - If a function returns some kind of non-negative integer value
+ * on success, a failure is indicated by returning the error code
+ * directly.
+ * - If a function returns a pointer of some kind on success, a
+ * failure is indicated by returning NULL
+ * - The last error number may be retrieved by calling
+ * avahi_server_errno() (for the server API) or avahi_client_errno()
+ * (for the client API)
+ * - Just like the libc errno variable the Avahi errno is NOT reset
+ * to AVAHI_OK if a function call succeeds.
+ * - You may convert a numeric error code into a human readable
+ * string using avahi_strerror()
+ * - The constructor functions avahi_server_new() and
+ * avahi_client_new() return the error code in a call-by-reference
+ * argument
+ *
+ * \section event_loop Event Loop Abstraction
+ *
+ * Avahi uses for both avahi-client and avahi-core a simple event loop
+ * abstraction layer.A table AvahiPoll which contains function
+ * pointers for user defined timeout and I/O condition event source
+ * implementations, needs to be passed to avahi_server_new() and
+ * avahi_client_new(). An adapter for this abstraction layer is
+ * available for the GLib main loop in the object AvahiGLibPoll. A
+ * simple stand-alone implementation is available under the name
+ * AvahiSimplePoll.
+ *
+ * \section good_publish How to Register Services
+ *
+ * - Subscribe to server state changes. Pass a callback function
+ * pointer to avahi_client_new()/avahi_server_new(). It will be called
+ * 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.
+ * - Remove your services when the server enters
+ * AVAHI_SERVER_COLLISION state. Your services may no be reachable
+ * anymore since the local host name is no longer 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())
+ * - 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
+ * services of the entry group are automatically removed from the
+ * server. You may immediately add your services back to the entry
+ * group (but with new names, perhaps using
+ * avahi_alternative_service_name()) and commit again. Please do not
+ * free the entry group and create a new one. This would inhibit some
+ * traffic limiting algorithms in mDNS.
+ * - When you need to modify your services, reset the entry group
+ * (i.e. avahi_entry_group_reset()) and add them back. Please do not
+ * free the entry group and create a new one. This would inhibit some
+ * traffic limiting algorithms in mDNS.
+ *
+ * The linked functions belong to avahi-client. They all have counterparts in the DBUS API and avahi-core.
+ *
+ * \section good_browse How to Browse for Services
+ *
+ * - 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
+ * name.
+ * - You can use avahi_domain_browser() 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 heavily.
+ * - There is no need to subscribe to server state changes.
+ *
+ * The linked functions belong to avahi-client. They all have counterparts in the DBUS API and avahi-core.
+ *
+ */
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
AVAHI_C_DECL_BEGIN
+#endif
/** States of an entry group object */
typedef enum {
- AVAHI_ENTRY_GROUP_UNCOMMITED = -1, /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
- AVAHI_ENTRY_GROUP_REGISTERING = 0, /**< The entries of the group are currently being registered */
- AVAHI_ENTRY_GROUP_ESTABLISHED, /**< The entries have successfully been established */
- AVAHI_ENTRY_GROUP_COLLISION /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
+ AVAHI_ENTRY_GROUP_UNCOMMITED, /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
+ AVAHI_ENTRY_GROUP_REGISTERING, /**< The entries of the group are currently being registered */
+ AVAHI_ENTRY_GROUP_ESTABLISHED, /**< The entries have successfully been established */
+ AVAHI_ENTRY_GROUP_COLLISION /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
} AvahiEntryGroupState;
/** The type of domain to browse for */
/** Type of callback event when browsing */
typedef enum {
- AVAHI_BROWSER_NEW = 0, /**< The object is new on the network */
- AVAHI_BROWSER_REMOVE = -1 /**< The object has been removed from the network */
+ AVAHI_BROWSER_NEW, /**< The object is new on the network */
+ AVAHI_BROWSER_REMOVE /**< The object has been removed from the network */
} AvahiBrowserEvent;
/** Type of callback event when resolving */
typedef enum {
- AVAHI_RESOLVER_FOUND = 0, /**< RR found, resolving successful */
- AVAHI_RESOLVER_TIMEOUT = -1 /**< Noone responded within the timeout, resolving failed */
+ AVAHI_RESOLVER_FOUND, /**< RR found, resolving successful */
+ AVAHI_RESOLVER_TIMEOUT /**< Noone responded within the timeout, resolving failed */
} AvahiResolverEvent;
/** States of a server object */
typedef enum {
- AVAHI_SERVER_INVALID = -1, /**< Invalid state (initial) */
- AVAHI_SERVER_REGISTERING = 0, /**< Host RRs are being registered */
+ 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() */
} AvahiServerState;
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
AVAHI_C_DECL_END
+#endif
#endif
projects / catta / blobdiff