git.meshlink.io Git - catta/blob - avahi-common/defs.h

   1 #ifndef foodefshfoo
   2 #define foodefshfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of avahi.
   8
   9   avahi is free software; you can redistribute it and/or modify it
  10   under the terms of the GNU Lesser General Public License as
  11   published by the Free Software Foundation; either version 2.1 of the
  12   License, or (at your option) any later version.
  13
  14   avahi is distributed in the hope that it will be useful, but WITHOUT
  15   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  16   or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
  17   Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public
  20   License along with avahi; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 /** \file defs.h Some common definitions */
  26
  27 #include <avahi-common/cdecl.h>
  28
  29 /** \mainpage
  30  *
  31  * \section choose_api Choosing an API
  32  *
  33  * Avahi provides three programming APIs for integration of
  34  * mDNS/DNS-SD features into your progams:
  35  *
  36  * \li avahi-core: an API for embedding a complete mDNS/DNS-SD stack
  37  * into your software. This is intended for developers of embedded
  38  * ampliances only. We dissuade from using this API in normal desktop
  39  * applications since it is not a good idea to run multiple mDNS
  40  * stacks simultaneously on the same host.
  41  * \li The DBUS API: an extensive DBUS interface for browsing and
  42  * registering mDNS/DNS-SD services using avahi-daemon. We recommend
  43  * to use this API for software written in any language but
  44  * C. (i.e. python)
  45  * \li avahi-client: a simplifying C wrapper around the DBUS API. We
  46  * recommend to use this API in C or C++ progams. The DBUS internals
  47  * are hidden completely.
  48  *
  49  * All three APIs are very similar, however avahi-core is the most powerful.
  50  *
  51  * \section error_reporting Error Reporting
  52  *
  53  * Some notes on the Avahi error handling:
  54  *
  55  * - Error codes are negative integers and defined as AVAHI_ERR_xx
  56  * - If a function returns some kind of non-negative integer value
  57  * on success, a failure is indicated by returning the error code
  58  * directly.
  59  * - If a function returns a pointer of some kind on success, a
  60  * failure is indicated by returning NULL
  61  * - The last error number may be retrieved by calling
  62  * avahi_server_errno() (for the server API) or avahi_client_errno()
  63  * (for the client API)
  64  * - Just like the libc errno variable the Avahi errno is NOT reset
  65  * to AVAHI_OK if a function call succeeds.
  66  * - You may convert a numeric error code into a human readable
  67  * string using avahi_strerror()
  68  * - The constructor functions avahi_server_new() and
  69  * avahi_client_new() return the error code in a call-by-reference
  70  * argument
  71  *
  72  * \section event_loop Event Loop Abstraction
  73  *
  74  * Avahi uses for both avahi-client and avahi-core a simple event loop
  75  * abstraction layer.A table AvahiPoll which contains function
  76  * pointers for user defined timeout and I/O condition event source
  77  * implementations, needs to be passed to avahi_server_new() and
  78  * avahi_client_new(). An adapter for this abstraction layer is
  79  * available for the GLib main loop in the object AvahiGLibPoll. A
  80  * simple stand-alone implementation is available under the name
  81  * AvahiSimplePoll.
  82  *
  83  * \section good_publish How to Register Services
  84  *
  85  * - Subscribe to server state changes. Pass a callback function
  86  * pointer to avahi_client_new()/avahi_server_new(). It will be called
  87  * whenever the server state changes.
  88  * - Only register your services when the server is in state
  89  * AVAHI_SERVER_RUNNING. If you register your services in other server
  90  * states they might not be accessible since the local host name is
  91  * not established.
  92  * - Remove your services when the server enters
  93  * AVAHI_SERVER_COLLISION state. Your services may no be reachable
  94  * anymore since the local host name is no longer established.
  95  * - When registering services, use the following algorithm:
  96  *   - Create a new entry group (i.e. avahi_entry_group_new())
  97  *   - Add your service(s)/additional host names (i.e. avahi_entry_group_add_service())
  98  *   - Commit the entry group (i.e. avahi_entry_group_commit())
  99  * - Subscribe to entry group state changes.
 100  * - If the entry group enters AVAHI_ENTRY_GROUP_COLLISION state the
 101  * services of the entry group are automatically removed from the
 102  * server. You may immediately add your services back to the entry
 103  * group (but with new names, perhaps using
 104  * avahi_alternative_service_name()) and commit again. Please do not
 105  * free the entry group and create a new one. This would inhibit some
 106  * traffic limiting algorithms in mDNS.
 107  * - When you need to modify your services, reset the entry group
 108  * (i.e. avahi_entry_group_reset()) and add them back. Please do not
 109  * free the entry group and create a new one. This would inhibit some
 110  * traffic limiting algorithms in mDNS.
 111  *
 112  * The linked functions belong to avahi-client. They all have counterparts in the DBUS API and avahi-core.
 113  *
 114  * \section good_browse How to Browse for Services
 115  *
 116  * - For normal applications you need to call avahi_service_browser_new()
 117  * for the service type you want to browse for. Use
 118  * avahi_client_resolve_service() to acquire service data for a a service
 119  * name.
 120  * - You can use avahi_domain_browser() to get a list of announced
 121  * browsing domains. Please note that not all domains whith services
 122  * on the LAN are mandatorily announced.
 123  * - Network monitor software may use avahi_service_type_browser_new()
 124  * to browse for the list of available service types on the LAN. This
 125  * API should NOT be used in normal software since it increases
 126  * traffic heavily.
 127  * - There is no need to subscribe to server state changes.
 128  *
 129  * The linked functions belong to avahi-client. They all have counterparts in the DBUS API and avahi-core.
 130  *
 131  */
 132
 133 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 134 AVAHI_C_DECL_BEGIN
 135 #endif
 136
 137 /** States of an entry group object */
 138 typedef enum {
 139     AVAHI_ENTRY_GROUP_UNCOMMITED,    /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
 140     AVAHI_ENTRY_GROUP_REGISTERING,   /**< The entries of the group are currently being registered */
 141     AVAHI_ENTRY_GROUP_ESTABLISHED,   /**< The entries have successfully been established */
 142     AVAHI_ENTRY_GROUP_COLLISION      /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
 143 } AvahiEntryGroupState;
 144
 145 /** The type of domain to browse for */
 146 typedef enum {
 147     AVAHI_DOMAIN_BROWSER_REGISTER,          /**< Browse for a list of available registering domains */
 148     AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT,  /**< Browse for the default registering domain */
 149     AVAHI_DOMAIN_BROWSER_BROWSE,            /**< Browse for a list of available browsing domains */
 150     AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT,    /**< Browse for the default browsing domain */
 151     AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY,     /**< Legacy browse domain - see DNS-SD spec for more information */
 152     AVAHI_DOMAIN_BROWSER_MAX
 153 } AvahiDomainBrowserType;
 154
 155 /** Type of callback event when browsing */
 156 typedef enum {
 157     AVAHI_BROWSER_NEW,            /**< The object is new on the network */
 158     AVAHI_BROWSER_REMOVE          /**< The object has been removed from the network */
 159 } AvahiBrowserEvent;
 160
 161 /** Type of callback event when resolving */
 162 typedef enum {
 163     AVAHI_RESOLVER_FOUND,         /**< RR found, resolving successful */
 164     AVAHI_RESOLVER_TIMEOUT        /**< Noone responded within the timeout, resolving failed */
 165 } AvahiResolverEvent;
 166
 167 /** States of a server object */
 168 typedef enum {
 169     AVAHI_SERVER_INVALID,          /**< Invalid state (initial) */
 170     AVAHI_SERVER_REGISTERING,      /**< Host RRs are being registered */
 171     AVAHI_SERVER_RUNNING,          /**< All host RRs have been established */
 172     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() */
 173 } AvahiServerState;
 174
 175 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 176 AVAHI_C_DECL_END
 177 #endif
 178
 179 #endif