* 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
+ * \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
* 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
+ * \li <b>the D-Bus API</b>: an extensive D-Bus 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
+ * C. (i.e. Python)
+ * \li <b>avahi-client</b>: a simplifying C wrapper around the D-Bus API. We
+ * recommend to use this API in C or C++ progams. The D-Bus internals
* are hidden completely.
*
* All three APIs are very similar, however avahi-core is the most powerful.
* 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 one of them!
+ * programs to avahi-client!
*
* \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
+ * - 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
+ * avahi_client_errno()
+ * - 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 function avahi_client_new() returns 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 uses a simple event loop abstraction laye. A table AvahiPoll
+ * which contains function pointers for user defined timeout and I/O
+ * condition event source implementations needs to be passed to
* 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.
+ * AvahiSimplePoll. An adpater for the Qt main loop is available from
+ * avahi_qt_poll_get().
*
* \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
+ * pointer to avahi_client_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.
+ * AVAHI_SERVER_COLLISION or AVAHI_SERVER_REGISTERING state. Your
+ * services may no be reachable anymore since the local host name is
+ * no longer established or is currently in the process of being
+ * 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())
* 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, use the AVAHI_PUBLISH_UPDATE flag. 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.
+ * - When you need to modify your services (i.e. change the TXT data
+ * or the port number), use the AVAHI_PUBLISH_UPDATE flag. Please do
+ * not free the entry group and create a new one. This would inhibit
+ * some traffic limiting algorithms in mDNS. When changing just the
+ * TXT data avahi_entry_group_update_txt() is a shortcut for
+ * AVAHI_PUBLISH_UPDATE. Please note that you cannot use
+ * AVAHI_PUBLISH_UPDATE when changing the service name! Renaming a
+ * DNS-SD service is identical to deleting and creating a new one, and
+ * that's exactly what you should do in that case. First call
+ * avahi_entry_group_reset() to remove it and than readd it normally.
*
* \section good_browse How to Browse for Services
*
* - 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.
+ * 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.
- *
- * The linked functions belong to avahi-client. They all have counterparts in the DBUS API and avahi-core.
- *
+ *
+ * \section daemon_dies How to Write a Client That Can Deal with Daemon Restarts
+ *
+ * With Avahi it is possible to write client applications that can
+ * deal with Avahi daemon restarts. To accomplish that make sure to
+ * pass AVAHI_CLIENT_NO_FAIL to avahi_client_new()'s flags
+ * parameter. That way avahi_client_new() will succeed even when the
+ * daemon is not running. In that case the object will enter
+ * AVAHI_CLIENT_CONNECTING state. As soon as the daemon becomes
+ * available the object will enter one of the AVAHI_CLIENT_S_xxx
+ * states. Make sure to not create browsers or entry groups before the
+ * client object has entered one of those states. As usual you will be
+ * informed about state changes with the callback function supplied to
+ * avahi_client_new(). If the client is forced to disconnect from the
+ * server it will enter AVAHI_CLIENT_FAILURE state with
+ * avahi_client_errno() == AVAHI_ERR_DISCONNECTED. Free the
+ * AvahiClient object in that case and reconnect to the server anew -
+ * again with passing AVAHI_CLIENT_NO_FAIL to avahi_client_new().
+ *
+ * We encourage to implement this in all software where service
+ * discovery is not an integral part of application. e.g. use it in
+ * all kinds of background daemons, but not in software like iChat
+ * compatible IM software.
+ *
+ * For now AVAHI_CLIENT_NO_FAIL cannot deal with D-Bus daemon restarts.
+ *
+ * \section domains How to Deal Properly with Browsing Domains
+ *
+ * Due to the introduction of wide-area DNS-SD the correct handling of
+ * domains becomes more important for Avahi enabled applications. All
+ * applications that offer the user a list of services discovered with
+ * Avahi should offer some kind of editable drop down box where the
+ * user can either enter his own domain or select one of those offered
+ * by AvahiDomainBrowser. The default domain to browse should be the
+ * one returned by avahi_client_get_domain_name(). The list of domains
+ * returned by AvahiDomainBrowser is assembled by the browsing domains
+ * configured in the daemon's configuration file, the domains
+ * announced inside the default domain, the domains set with the
+ * environment variable $AVAHI_BROWSE_DOMAINS (colon-seperated) on the
+ * client side and the domains set in the XDG configuration file
+ * ~/.config/avahi/browse-domains on the client side (seperated by
+ * newlines). File managers offering some kind of "Network
+ * Neighborhood" folder should show the entries of the default domain
+ * right inside that and offer subfolders for the browsing domains
+ * returned by AvahiDomainBrowser.
*/
AVAHI_C_DECL_BEGIN
/** The type of domain to browse for */
typedef enum {
- 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, /**< 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;
AVAHI_PUBLISH_ALLOW_MULTIPLE = 8, /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */
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 */
- AVAHI_PUBLISH_UPDATE = 64 /**< Update existing records instead of adding new ones */
+ AVAHI_PUBLISH_UPDATE = 64, /**< Update existing records instead of adding new ones */
+ 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 */
} AvahiPublishFlags;
/** Some flags for lookup functions */
AVAHI_LOOKUP_RESULT_WIDE_AREA = 2, /**< This response originates from wide area DNS */
AVAHI_LOOKUP_RESULT_MULTICAST = 4, /**< This response originates from multicast DNS */
AVAHI_LOOKUP_RESULT_LOCAL = 8, /**< This record/service resides on and was announced by the local host. Only available in service and record browsers and only on AVAHI_BROWSER_NEW. */
- AVAHI_LOOKUP_RESULT_OUR_OWN = 16 /**< This service belongs to the same local client as the browser object. Only available in avahi-client, and only for service browsers and only on AVAHI_BROWSER_NEW. */
+ AVAHI_LOOKUP_RESULT_OUR_OWN = 16, /**< This service belongs to the same local client as the browser object. Only available in avahi-client, and only for service browsers and only on AVAHI_BROWSER_NEW. */
+ AVAHI_LOOKUP_RESULT_STATIC = 32 /**< The returned data has been defined statically by some configuration option */
} AvahiLookupResultFlags;
/** Type of callback event when browsing */
/** In invalid cookie as special value */
#define AVAHI_SERVICE_COOKIE_INVALID (0)
+/** DNS record types, see RFC 1035 */
+enum {
+ AVAHI_DNS_TYPE_A = 0x01,
+ AVAHI_DNS_TYPE_NS = 0x02,
+ AVAHI_DNS_TYPE_CNAME = 0x05,
+ AVAHI_DNS_TYPE_SOA = 0x06,
+ AVAHI_DNS_TYPE_PTR = 0x0C,
+ AVAHI_DNS_TYPE_HINFO = 0x0D,
+ AVAHI_DNS_TYPE_MX = 0x0F,
+ AVAHI_DNS_TYPE_TXT = 0x10,
+ AVAHI_DNS_TYPE_AAAA = 0x1C,
+ AVAHI_DNS_TYPE_SRV = 0x21,
+};
+
+/** DNS record classes, 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)
+
+/** The default TTL for all other records. */
+#define AVAHI_DEFAULT_TTL (75*60)
+
AVAHI_C_DECL_END
#endif
projects / catta / blobdiff