git.meshlink.io Git - catta/blob - avahi-core/publish.h

   1 #ifndef foopublishhfoo
   2 #define foopublishhfoo
   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 core/publish.h Functions for publising local services and RRs */
  26
  27 /** \example core-publish-service.c Example how to register a DNS-SD
  28  * service using an embedded mDNS stack. It behaves like a network
  29  * printer registering both an IPP and a BSD LPR service. */
  30
  31 #include <avahi-common/cdecl.h>
  32
  33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  34 AVAHI_C_DECL_BEGIN
  35 #endif
  36
  37 /** A group of locally registered DNS RRs */
  38 typedef struct AvahiSEntryGroup AvahiSEntryGroup;
  39
  40 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  41 AVAHI_C_DECL_END
  42 #endif
  43
  44 #include "core.h"
  45
  46 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  47 AVAHI_C_DECL_BEGIN
  48 #endif
  49
  50 /** Prototype for callback functions which are called whenever the state of an AvahiSEntryGroup object changes */
  51 typedef void (*AvahiSEntryGroupCallback) (AvahiServer *s, AvahiSEntryGroup *g, AvahiEntryGroupState state, void* userdata);
  52
  53 /** Iterate through all local entries of the server. (when g is NULL)
  54  * or of a specified entry group. At the first call state should point
  55  * to a NULL initialized void pointer, That pointer is used to track
  56  * the current iteration. It is not safe to call any other
  57  * avahi_server_xxx() function during the iteration. If the last entry
  58  * has been read, NULL is returned. */
  59 const AvahiRecord *avahi_server_iterate(AvahiServer *s, AvahiSEntryGroup *g, void **state);
  60
  61 /** Create a new entry group. The specified callback function is
  62  * called whenever the state of the group changes. Use entry group
  63  * objects to keep track of you RRs. Add new RRs to a group using
  64  * avahi_server_add_xxx(). Make sure to call avahi_s_entry_group_commit()
  65  * to start the registration process for your RRs */
  66 AvahiSEntryGroup *avahi_s_entry_group_new(AvahiServer *s, AvahiSEntryGroupCallback callback, void* userdata);
  67
  68 /** Free an entry group. All RRs assigned to the group are removed from the server */
  69 void avahi_s_entry_group_free(AvahiSEntryGroup *g);
  70
  71 /** Commit an entry group. This starts the probing and registration process for all RRs in the group */
  72 int avahi_s_entry_group_commit(AvahiSEntryGroup *g);
  73
  74 /** Remove all entries from the entry group and reset the state to AVAHI_ENTRY_GROUP_UNCOMMITED. */
  75 void avahi_s_entry_group_reset(AvahiSEntryGroup *g);
  76
  77 /** Return 1 if the entry group is empty, i.e. has no records attached. */
  78 int avahi_s_entry_group_is_empty(AvahiSEntryGroup *g);
  79
  80 /** Return the current state of the specified entry group */
  81 AvahiEntryGroupState avahi_s_entry_group_get_state(AvahiSEntryGroup *g);
  82
  83 /** Change the opaque user data pointer attached to an entry group object */
  84 void avahi_s_entry_group_set_data(AvahiSEntryGroup *g, void* userdata);
  85
  86 /** Return the opaque user data pointer currently set for the entry group object */
  87 void* avahi_s_entry_group_get_data(AvahiSEntryGroup *g);
  88
  89 /** Add a new resource record to the server. Returns 0 on success, negative otherwise. */
  90 int avahi_server_add(
  91     AvahiServer *s,           /**< The server object to add this record to */
  92     AvahiSEntryGroup *g,       /**< An entry group object if this new record shall be attached to one, or NULL. If you plan to remove the record sometime later you a required to pass an entry group object here. */
  93     AvahiIfIndex interface,   /**< A numeric index of a network interface to attach this record to, or AVAHI_IF_UNSPEC to attach this record to all interfaces */
  94     AvahiProtocol protocol,   /**< A protocol family to attach this record to. One of the AVAHI_PROTO_xxx constants. Use AVAHI_PROTO_UNSPEC to make this record available on all protocols (wich means on both IPv4 and IPv6). */
  95     AvahiPublishFlags flags,    /**< Special flags for this record */
  96     AvahiRecord *r            /**< The record to add. This function increases the reference counter of this object. */);
  97
  98
  99 /** Add a PTR RR to the server. See avahi_server_add() for more information. */
 100 int avahi_server_add_ptr(
 101     AvahiServer *s,
 102     AvahiSEntryGroup *g,
 103     AvahiIfIndex interface,
 104     AvahiProtocol protocol,
 105     AvahiPublishFlags flags,
 106     uint32_t ttl,             /**< DNS TTL for this record */
 107     const char *name,       /**< PTR record name */
 108     const char *dest        /**< pointer destination */  );
 109
 110 /** Add a PTR RR to the server. See avahi_server_add() for more information. */
 111 int avahi_server_add_txt(
 112     AvahiServer *s,
 113     AvahiSEntryGroup *g,
 114     AvahiIfIndex interface,
 115     AvahiProtocol protocol,
 116     AvahiPublishFlags flags,
 117     uint32_t ttl,             /**< DNS TTL for this record */
 118     const char *name,       /**< TXT record name */
 119     ... /**< Text record data, terminated by NULL */) AVAHI_GCC_SENTINEL;
 120
 121 /** Add a PTR RR to the server. Mostly identical to
 122  * avahi_server_add_text but takes a va_list instead of a variable
 123  * number of arguments */
 124 int avahi_server_add_txt_va(
 125     AvahiServer *s,
 126     AvahiSEntryGroup *g,
 127     AvahiIfIndex interface,
 128     AvahiProtocol protocol,
 129     AvahiPublishFlags flags,
 130     uint32_t ttl,
 131     const char *name,
 132     va_list va);
 133
 134 /** Add a PTR RR to the server. Mostly identical to
 135  * avahi_server_add_text but takes an AvahiStringList record instead of a variable
 136  * number of arguments. */
 137 int avahi_server_add_txt_strlst(
 138     AvahiServer *s,
 139     AvahiSEntryGroup *g,
 140     AvahiIfIndex interface,
 141     AvahiProtocol protocol,
 142     AvahiPublishFlags flags,
 143     uint32_t ttl,
 144     const char *name,
 145     AvahiStringList *strlst  /**< TXT decord data as a AvahiString. This routine makes a deep copy of this object. */ );
 146
 147 /** Add an IP address mapping to the server. This will add both the
 148  * host-name-to-address and the reverse mapping to the server. See
 149  * avahi_server_add() for more information. If adding one of the RRs
 150  * fails, the function returns with an error, but it is not defined if
 151  * the other RR is deleted from the server or not. Therefore, you have
 152  * to free the AvahiSEntryGroup and create a new one before
 153  * proceeding. */
 154 int avahi_server_add_address(
 155     AvahiServer *s,
 156     AvahiSEntryGroup *g,
 157     AvahiIfIndex interface,
 158     AvahiProtocol protocol,
 159     AvahiPublishFlags flags,
 160     const char *name,
 161     AvahiAddress *a);
 162
 163 /** Add an DNS-SD service to the Server. This will add all required
 164  * RRs to the server. See avahi_server_add() for more information.  If
 165  * adding one of the RRs fails, the function returns with an error,
 166  * but it is not defined if the other RR is deleted from the server or
 167  * not. Therefore, you have to free the AvahiSEntryGroup and create a
 168  * new one before proceeding. */
 169 int avahi_server_add_service(
 170     AvahiServer *s,
 171     AvahiSEntryGroup *g,
 172     AvahiIfIndex interface,
 173     AvahiProtocol protocol,
 174     AvahiPublishFlags flags,
 175     const char *name,         /**< Service name, e.g. "Lennart's Files" */
 176     const char *type,         /**< DNS-SD type, e.g. "_http._tcp" */
 177     const char *domain,
 178     const char *host,         /**< Host name where this servcie resides, or NULL if on the local host */
 179     uint16_t port,              /**< Port number of the service */
 180     ...  /**< Text records, terminated by NULL */) AVAHI_GCC_SENTINEL;
 181
 182 /** Mostly identical to avahi_server_add_service(), but takes an va_list for the TXT records. */
 183 int avahi_server_add_service_va(
 184     AvahiServer *s,
 185     AvahiSEntryGroup *g,
 186     AvahiIfIndex interface,
 187     AvahiProtocol protocol,
 188     AvahiPublishFlags flags,
 189     const char *name,
 190     const char *type,
 191     const char *domain,
 192     const char *host,
 193     uint16_t port,
 194     va_list va);
 195
 196 /** Mostly identical to avahi_server_add_service(), but takes an AvahiStringList object for the TXT records.  The AvahiStringList object is copied. */
 197 int avahi_server_add_service_strlst(
 198     AvahiServer *s,
 199     AvahiSEntryGroup *g,
 200     AvahiIfIndex interface,
 201     AvahiProtocol protocol,
 202     AvahiPublishFlags flags,
 203     const char *name,
 204     const char *type,
 205     const char *domain,
 206     const char *host,
 207     uint16_t port,
 208     AvahiStringList *strlst);
 209
 210 /** Add a subtype for an already existing service */
 211 int avahi_server_add_service_subtype(
 212     AvahiServer *s,
 213     AvahiSEntryGroup *g,
 214     AvahiIfIndex interface,
 215     AvahiProtocol protocol,
 216     AvahiPublishFlags flags,
 217     const char *name,         /**< Specify the name of main service you already added here */
 218     const char *type,         /**< Specify the main type of the service you already added here */
 219     const char *domain,       /**< Specify the main type of the service you already added here */
 220     const char *subtype       /**< The new subtype for the specified service */ );
 221
 222 /** Update the TXT record for a service with the data from the specified string list */
 223 int avahi_server_update_service_txt_strlst(
 224     AvahiServer *s,
 225     AvahiSEntryGroup *g,
 226     AvahiIfIndex interface,
 227     AvahiProtocol protocol,
 228     AvahiPublishFlags flags,
 229     const char *name,
 230     const char *type,
 231     const char *domain,
 232     AvahiStringList *strlst);
 233
 234 /** Update the TXT record for a service with the NULL terminated list of strings of the va_list. */
 235 int avahi_server_update_service_txt_va(
 236     AvahiServer *s,
 237     AvahiSEntryGroup *g,
 238     AvahiIfIndex interface,
 239     AvahiProtocol protocol,
 240     AvahiPublishFlags flags,
 241     const char *name,
 242     const char *type,
 243     const char *domain,
 244     va_list va);
 245
 246 /** Update the TXT record for a service with the NULL termonate list of strings */
 247 int avahi_server_update_service_txt(
 248     AvahiServer *s,
 249     AvahiSEntryGroup *g,
 250     AvahiIfIndex interface,
 251     AvahiProtocol protocol,
 252     AvahiPublishFlags flags,
 253     const char *name,
 254     const char *type,
 255     const char *domain,
 256     ...) AVAHI_GCC_SENTINEL;
 257
 258 /** The type of DNS server */
 259 typedef enum {
 260     AVAHI_DNS_SERVER_RESOLVE,         /**< Unicast DNS servers for normal resolves (_domain._udp)*/
 261     AVAHI_DNS_SERVER_UPDATE,           /**< Unicast DNS servers for updates (_dns-update._udp)*/
 262     AVAHI_DNS_SERVER_MAX
 263 } AvahiDNSServerType;
 264
 265 /** Publish the specified unicast DNS server address via mDNS. You may
 266  * browse for records create this way wit
 267  * avahi_s_dns_server_browser_new(). */
 268 int avahi_server_add_dns_server_address(
 269     AvahiServer *s,
 270     AvahiSEntryGroup *g,
 271     AvahiIfIndex interface,
 272     AvahiProtocol protocol,
 273     AvahiPublishFlags flags,
 274     const char *domain,
 275     AvahiDNSServerType type,
 276     const AvahiAddress *address,
 277     uint16_t port /** should be 53 */);
 278
 279 /** Similar to avahi_server_add_dns_server_address(), but specify a
 280 host name instead of an address. The specified host name should be
 281 resolvable via mDNS */
 282 int avahi_server_add_dns_server_name(
 283     AvahiServer *s,
 284     AvahiSEntryGroup *g,
 285     AvahiIfIndex interface,
 286     AvahiProtocol protocol,
 287     AvahiPublishFlags flags,
 288     const char *domain,
 289     AvahiDNSServerType type,
 290     const char *name,
 291     uint16_t port /** should be 53 */);
 292
 293
 294 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 295 AVAHI_C_DECL_END
 296 #endif
 297
 298 #endif