Home | History | Annotate | Download | only in avahi-common
      1 #ifndef foodefshfoo
      2 #define foodefshfoo
      3 
      4 /***
      5   This file is part of avahi.
      6 
      7   avahi is free software; you can redistribute it and/or modify it
      8   under the terms of the GNU Lesser General Public License as
      9   published by the Free Software Foundation; either version 2.1 of the
     10   License, or (at your option) any later version.
     11 
     12   avahi is distributed in the hope that it will be useful, but WITHOUT
     13   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
     14   or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
     15   Public License for more details.
     16 
     17   You should have received a copy of the GNU Lesser General Public
     18   License along with avahi; if not, write to the Free Software
     19   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
     20   USA.
     21 ***/
     22 
     23 /** \file defs.h Some common definitions */
     24 
     25 #include <avahi-common/cdecl.h>
     26 
     27 /** \mainpage
     28  *
     29  * \section choose_api Choosing an API
     30  *
     31  * Avahi provides three programming APIs for integration of
     32  * mDNS/DNS-SD features into your C progams:
     33  *
     34  * \li <b>avahi-core</b>: an API for embedding a complete mDNS/DNS-SD stack
     35  * into your software. This is intended for developers of embedded
     36  * appliances only. We dissuade from using this API in normal desktop
     37  * applications since it is not a good idea to run multiple mDNS
     38  * stacks simultaneously on the same host.
     39  * \li <b>the D-Bus API</b>: an extensive D-Bus interface for browsing and
     40  * registering mDNS/DNS-SD services using avahi-daemon. We recommend
     41  * using this API for software written in any language other than
     42  * C (e.g. Python).
     43  * \li <b>avahi-client</b>: a simplifying C wrapper around the D-Bus API. We
     44  * recommend using this API in C or C++ progams. The D-Bus internals
     45  * are hidden completely.
     46  * \li <b>avahi-gobject</b>: an object-oriented C wrapper based on
     47  * GLib's GObject. We recommd using this API for GNOME/Gtk programs.
     48  *
     49  * All three APIs are very similar, however avahi-core is the most powerful.
     50  *
     51  * In addition to the three APIs described above Avahi supports two
     52  * compatibility libraries:
     53  *
     54  * \li <b>avahi-compat-libdns_sd</b>: the original Bonjour API as documented
     55  * in the header file "dns_sd.h" by Apple Computer, Inc.
     56  *
     57  * \li <b>avahi-compat-howl</b>: the HOWL API as released with HOWL 0.9.8 by
     58  * Porchdog Software.
     59  *
     60  * Please note that these compatibility layers are incomplete and
     61  * generally a waste of resources. We strongly encourage everyone to
     62  * use our native APIs for newly written programs and to port older
     63  * programs to avahi-client!
     64  *
     65  * The native APIs (avahi-client and avahi-core) can be integrated
     66  * into external event loops. We provide adapters for the following
     67  * event loop implementations:
     68  *
     69  * \li <b>avahi-glib</b>: The GLIB main loop as used by GTk+/GNOME
     70  *
     71  * \li <b>avahi-qt</b>: The Qt main loop as used by Qt/KDE
     72  *
     73  * Finally, we provide a high-level Gtk+ GUI dialog called
     74  * <b>avahi-ui</b> for user-friendly browsing for services.
     75  *
     76  * The doxygen-generated API documentation covers avahi-client
     77  * (including its auxiliary APIs), the event loop adapters and
     78  * avahi-ui. For the other APIs please consult the original
     79  * documentation (for the compatibility APIs) or the header files.
     80  *
     81  * Please note that the doxygen-generated API documentation of the
     82  * native Avahi API is not complete. A few definitions that are part
     83  * of the Avahi API have been removed from this documentation, either
     84  * because they are only relevant in a very few low-level applications
     85  * or because they are considered obsolete. Please consult the C header
     86  * files for all definitions that are part of the Avahi API. Please
     87  * note that these hidden definitions are considered part of the Avahi
     88  * API and will stay available in the API in the future.
     89  *
     90  * \section error_reporting Error Reporting
     91  *
     92  * Some notes on the Avahi error handling:
     93  *
     94  * - Error codes are negative integers and defined as AVAHI_ERR_xx
     95  * - If a function returns some kind of non-negative integer value on
     96  * success, a failure is indicated by returning the error code
     97  * directly.
     98  * - If a function returns a pointer of some kind on success, a
     99  * failure is indicated by returning NULL
    100  * - The last error number may be retrieved by calling
    101  * avahi_client_errno()
    102  * - Just like the libc errno variable the Avahi errno is NOT reset to
    103  * AVAHI_OK if a function call succeeds.
    104  * - You may convert a numeric error code into a human readable string
    105  * using avahi_strerror()
    106  * - The constructor function avahi_client_new() returns the error
    107  * code in a call-by-reference argument
    108  *
    109  * \section event_loop Event Loop Abstraction
    110  *
    111  * Avahi uses a simple event loop abstraction layer. A table AvahiPoll
    112  * which contains function pointers for user defined timeout and I/O
    113  * condition event source implementations needs to be passed to
    114  * avahi_client_new(). An adapter for this abstraction layer is
    115  * available for the GLib main loop in the object AvahiGLibPoll. A
    116  * simple stand-alone implementation is available under the name
    117  * AvahiSimplePoll. An adpater for the Qt main loop is available from
    118  * avahi_qt_poll_get().
    119  *
    120  * \section good_publish How to Register Services
    121  *
    122  * - Subscribe to server state changes. Pass a callback function
    123  * pointer to avahi_client_new(). It will be called
    124  * whenever the server state changes.
    125  * - Only register your services when the server is in state
    126  * AVAHI_SERVER_RUNNING. If you register your services in other server
    127  * states they might not be accessible since the local host name might not necessarily
    128  * be established.
    129  * - Remove your services when the server enters
    130  * AVAHI_SERVER_COLLISION or AVAHI_SERVER_REGISTERING state. Your
    131  * services may not be reachable anymore since the local host name is
    132  * no longer established or is currently in the process of being
    133  * established.
    134  * - When registering services, use the following algorithm:
    135  *   - Create a new entry group (i.e. avahi_entry_group_new())
    136  *   - Add your service(s)/additional RRs/subtypes (e.g. avahi_entry_group_add_service())
    137  *   - Commit the entry group (i.e. avahi_entry_group_commit())
    138  * - Subscribe to entry group state changes.
    139  * - If the entry group enters AVAHI_ENTRY_GROUP_COLLISION state the
    140  * services of the entry group are automatically removed from the
    141  * server. You may immediately add your services back to the entry
    142  * group (but with new names, perhaps using
    143  * avahi_alternative_service_name()) and commit again. Please do not
    144  * free the entry group and create a new one. This would inhibit some
    145  * traffic limiting algorithms in mDNS.
    146  * - When you need to modify your services (i.e. change the TXT data
    147  * or the port number), use the AVAHI_PUBLISH_UPDATE flag. Please do
    148  * not free the entry group and create a new one. This would inhibit
    149  * some traffic limiting algorithms in mDNS. When changing just the
    150  * TXT data avahi_entry_group_update_txt() is a shortcut for
    151  * AVAHI_PUBLISH_UPDATE. Please note that you cannot use
    152  * AVAHI_PUBLISH_UPDATE when changing the service name! Renaming a
    153  * DNS-SD service is identical to deleting and creating a new one, and
    154  * that's exactly what you should do in that case. First call
    155  * avahi_entry_group_reset() to remove it and then read it normally.
    156  *
    157  * \section good_browse How to Browse for Services
    158  *
    159  * - For normal applications you need to call avahi_service_browser_new()
    160  * for the service type you want to browse for. Use
    161  * avahi_service_resolver_new() to acquire service data for a service
    162  * name.
    163  * - You can use avahi_domain_browser_new() to get a list of announced
    164  * browsing domains. Please note that not all domains whith services
    165  * on the LAN are mandatorily announced.
    166  * - There is no need to subscribe to server state changes.
    167  *
    168  * \section daemon_dies How to Write a Client That Can Deal with Daemon Restarts
    169  *
    170  * With Avahi it is possible to write client applications that can
    171  * deal with Avahi daemon restarts. To accomplish that make sure to
    172  * pass AVAHI_CLIENT_NO_FAIL to avahi_client_new()'s flags
    173  * parameter. That way avahi_client_new() will succeed even when the
    174  * daemon is not running. In that case the object will enter
    175  * AVAHI_CLIENT_CONNECTING state. As soon as the daemon becomes
    176  * available the object will enter one of the AVAHI_CLIENT_S_xxx
    177  * states. Make sure to not create browsers or entry groups before the
    178  * client object has entered one of those states. As usual you will be
    179  * informed about state changes with the callback function supplied to
    180  * avahi_client_new(). If the client is forced to disconnect from the
    181  * server it will enter AVAHI_CLIENT_FAILURE state with
    182  * avahi_client_errno() == AVAHI_ERR_DISCONNECTED. Free the
    183  * AvahiClient object in that case (and all its associated objects
    184  * such as entry groups and browser objects prior to that) and
    185  * reconnect to the server anew - again with passing
    186  * AVAHI_CLIENT_NO_FAIL to avahi_client_new().
    187  *
    188  * We encourage implementing this in all software where service
    189  * discovery is not an integral part of application. e.g. use it in
    190  * all kinds of background daemons, but not necessarily in software
    191  * like iChat compatible IM software.
    192  *
    193  * For now AVAHI_CLIENT_NO_FAIL cannot deal with D-Bus daemon restarts.
    194  *
    195  * \section domains How to Deal Properly with Browsing Domains
    196  *
    197  * Due to the introduction of wide-area DNS-SD the correct handling of
    198  * domains becomes more important for Avahi enabled applications. All
    199  * applications that offer the user a list of services discovered with
    200  * Avahi should offer some kind of editable drop down box where the
    201  * user can either enter his own domain or select one of those offered
    202  * by AvahiDomainBrowser. The default domain to browse should be the
    203  * one returned by avahi_client_get_domain_name(). The list of domains
    204  * returned by AvahiDomainBrowser is assembled by the browsing domains
    205  * configured in the daemon's configuration file, the domains
    206  * announced inside the default domain, the domains set with the
    207  * environment variable $AVAHI_BROWSE_DOMAINS (colon-seperated) on the
    208  * client side and the domains set in the XDG configuration file
    209  * ~/.config/avahi/browse-domains on the client side (seperated by
    210  * newlines). File managers offering some kind of "Network
    211  * Neighborhood" folder should show the entries of the default domain
    212  * right inside that and offer subfolders for the browsing domains
    213  * returned by AvahiDomainBrowser.
    214  */
    215 
    216 AVAHI_C_DECL_BEGIN
    217 
    218 /** @{ \name States */
    219 
    220 /** States of a server object */
    221 typedef enum {
    222     AVAHI_SERVER_INVALID,          /**< Invalid state (initial) */
    223     AVAHI_SERVER_REGISTERING,      /**< Host RRs are being registered */
    224     AVAHI_SERVER_RUNNING,          /**< All host RRs have been established */
    225     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() */
    226     AVAHI_SERVER_FAILURE           /**< Some fatal failure happened, the server is unable to proceed */
    227 } AvahiServerState;
    228 
    229 /** States of an entry group object */
    230 typedef enum {
    231     AVAHI_ENTRY_GROUP_UNCOMMITED,    /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
    232     AVAHI_ENTRY_GROUP_REGISTERING,   /**< The entries of the group are currently being registered */
    233     AVAHI_ENTRY_GROUP_ESTABLISHED,   /**< The entries have successfully been established */
    234     AVAHI_ENTRY_GROUP_COLLISION,     /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
    235     AVAHI_ENTRY_GROUP_FAILURE        /**< Some kind of failure happened, the entries have been withdrawn */
    236 } AvahiEntryGroupState;
    237 
    238 /** @} */
    239 
    240 /** @{ \name Flags */
    241 
    242 /** Some flags for publishing functions */
    243 typedef enum {
    244     AVAHI_PUBLISH_UNIQUE = 1,           /**< For raw records: The RRset is intended to be unique */
    245     AVAHI_PUBLISH_NO_PROBE = 2,         /**< For raw records: Though the RRset is intended to be unique no probes shall be sent */
    246     AVAHI_PUBLISH_NO_ANNOUNCE = 4,      /**< For raw records: Do not announce this RR to other hosts */
    247     AVAHI_PUBLISH_ALLOW_MULTIPLE = 8,   /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */
    248 /** \cond fulldocs */
    249     AVAHI_PUBLISH_NO_REVERSE = 16,      /**< For address records: don't create a reverse (PTR) entry */
    250     AVAHI_PUBLISH_NO_COOKIE = 32,       /**< For service records: do not implicitly add the local service cookie to TXT data */
    251 /** \endcond */
    252     AVAHI_PUBLISH_UPDATE = 64,          /**< Update existing records instead of adding new ones */
    253 /** \cond fulldocs */
    254     AVAHI_PUBLISH_USE_WIDE_AREA = 128,  /**< Register the record using wide area DNS (i.e. unicast DNS update) */
    255     AVAHI_PUBLISH_USE_MULTICAST = 256   /**< Register the record using multicast DNS */
    256 /** \endcond */
    257 } AvahiPublishFlags;
    258 
    259 /** Some flags for lookup functions */
    260 typedef enum {
    261 /** \cond fulldocs */
    262     AVAHI_LOOKUP_USE_WIDE_AREA = 1,    /**< Force lookup via wide area DNS */
    263     AVAHI_LOOKUP_USE_MULTICAST = 2,    /**< Force lookup via multicast DNS */
    264 /** \endcond */
    265     AVAHI_LOOKUP_NO_TXT = 4,           /**< When doing service resolving, don't lookup TXT record */
    266     AVAHI_LOOKUP_NO_ADDRESS = 8        /**< When doing service resolving, don't lookup A/AAAA record */
    267 } AvahiLookupFlags;
    268 
    269 /** Some flags for lookup callback functions */
    270 typedef enum {
    271     AVAHI_LOOKUP_RESULT_CACHED = 1,         /**< This response originates from the cache */
    272     AVAHI_LOOKUP_RESULT_WIDE_AREA = 2,      /**< This response originates from wide area DNS */
    273     AVAHI_LOOKUP_RESULT_MULTICAST = 4,      /**< This response originates from multicast DNS */
    274     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. */
    275     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. */
    276     AVAHI_LOOKUP_RESULT_STATIC = 32         /**< The returned data has been defined statically by some configuration option */
    277 } AvahiLookupResultFlags;
    278 
    279 /** @} */
    280 
    281 /** @{ \name Events */
    282 
    283 /** Type of callback event when browsing */
    284 typedef enum {
    285     AVAHI_BROWSER_NEW,               /**< The object is new on the network */
    286     AVAHI_BROWSER_REMOVE,            /**< The object has been removed from the network */
    287     AVAHI_BROWSER_CACHE_EXHAUSTED,   /**< One-time event, to notify the user that all entries from the caches have been sent */
    288     AVAHI_BROWSER_ALL_FOR_NOW,       /**< One-time event, to notify the user that more records will probably not show up in the near future, i.e. all cache entries have been read and all static servers been queried */
    289     AVAHI_BROWSER_FAILURE            /**< Browsing failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */
    290 } AvahiBrowserEvent;
    291 
    292 /** Type of callback event when resolving */
    293 typedef enum {
    294     AVAHI_RESOLVER_FOUND,          /**< RR found, resolving successful */
    295     AVAHI_RESOLVER_FAILURE         /**< Resolving failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */
    296 } AvahiResolverEvent;
    297 
    298 /** @} */
    299 
    300 /** @{ \name Other definitions */
    301 
    302 /** The type of domain to browse for */
    303 typedef enum {
    304     AVAHI_DOMAIN_BROWSER_BROWSE,            /**< Browse for a list of available browsing domains */
    305     AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT,    /**< Browse for the default browsing domain */
    306     AVAHI_DOMAIN_BROWSER_REGISTER,          /**< Browse for a list of available registering domains */
    307     AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT,  /**< Browse for the default registering domain */
    308     AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY,     /**< Legacy browse domain - see DNS-SD spec for more information */
    309     AVAHI_DOMAIN_BROWSER_MAX
    310 } AvahiDomainBrowserType;
    311 
    312 /** @} */
    313 
    314 /** \cond fulldocs */
    315 /** For every service a special TXT item is implicitly added, which
    316  * contains a random cookie which is private to the local daemon. This
    317  * can be used by clients to determine if two services on two
    318  * different subnets are effectively the same. */
    319 #define AVAHI_SERVICE_COOKIE "org.freedesktop.Avahi.cookie"
    320 
    321 /** In invalid cookie as special value */
    322 #define AVAHI_SERVICE_COOKIE_INVALID (0)
    323 /** \endcond fulldocs */
    324 
    325 /** @{ \name DNS RR definitions */
    326 
    327 /** DNS record types, see RFC 1035 */
    328 enum {
    329     AVAHI_DNS_TYPE_A = 0x01,
    330     AVAHI_DNS_TYPE_NS = 0x02,
    331     AVAHI_DNS_TYPE_CNAME = 0x05,
    332     AVAHI_DNS_TYPE_SOA = 0x06,
    333     AVAHI_DNS_TYPE_PTR = 0x0C,
    334     AVAHI_DNS_TYPE_HINFO = 0x0D,
    335     AVAHI_DNS_TYPE_MX = 0x0F,
    336     AVAHI_DNS_TYPE_TXT = 0x10,
    337     AVAHI_DNS_TYPE_AAAA = 0x1C,
    338     AVAHI_DNS_TYPE_SRV = 0x21
    339 };
    340 
    341 /** DNS record classes, see RFC 1035 */
    342 enum {
    343     AVAHI_DNS_CLASS_IN = 0x01          /**< Probably the only class we will ever use */
    344 };
    345 
    346 /** @} */
    347 
    348 /** The default TTL for RRs which contain a host name of some kind. */
    349 #define AVAHI_DEFAULT_TTL_HOST_NAME (120)
    350 
    351 /** The default TTL for all other records. */
    352 #define AVAHI_DEFAULT_TTL (75*60)
    353 
    354 AVAHI_C_DECL_END
    355 
    356 #endif
    357