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