From 079c419ce7eabda110f1e21981f3175ce9240bc0 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sat, 20 Aug 2005 15:21:50 +0000 Subject: * doxygen update git-svn-id: file:///home/lennart/svn/public/avahi/trunk@359 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe --- avahi-common/defs.h | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++ avahi-common/error.h | 15 ------- 2 files changed, 108 insertions(+), 15 deletions(-) diff --git a/avahi-common/defs.h b/avahi-common/defs.h index fff11f0..1475a43 100644 --- a/avahi-common/defs.h +++ b/avahi-common/defs.h @@ -26,7 +26,113 @@ #include +/** \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 { @@ -66,6 +172,8 @@ typedef enum { 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 diff --git a/avahi-common/error.h b/avahi-common/error.h index dc3f333..f8d6c35 100644 --- a/avahi-common/error.h +++ b/avahi-common/error.h @@ -26,21 +26,6 @@ #include -/** \mainpage - * - * \section Error Reporting - * - * Some notes on the Avahai erro handling: - * - * \li Error codes are negative integers and defined in the enum AVAHI_ERR_xx - * \li If a function returns some kind of non-negative integer value on success, a failure is indicated by returning the error code directly. - * \li If a function returns a pointer of some kind on success, a failure is indicated by returning NULL - * \li The last error number may be retrieved by calling avahi_server_errno() (for the server API) or avahi_client_errno() (for the client API) - * \li Just like the libc errno the Avahi errno is NOT reset to AVAHI_OK if a function call succeeds. - * \li You may convert a numeric error code into a human readable string using avahi_strerror.c - * - */ - #ifndef DOXYGEN_SHOULD_SKIP_THIS AVAHI_C_DECL_BEGIN #endif -- cgit