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
 100 /** Add a PTR RR to the server. See avahi_server_add() for more information. */
 101 int avahi_server_add_txt(
 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,       /**< TXT record name */
 109     ... /**< Text record data, terminated by NULL */) AVAHI_GCC_SENTINEL;
 110
 111 /** Add a PTR RR to the server. Mostly identical to
 112  * avahi_server_add_text but takes a va_list instead of a variable
 113  * number of arguments */
 114 int avahi_server_add_txt_va(
 115     AvahiServer *s,
 116     AvahiSEntryGroup *g,
 117     AvahiIfIndex interface,
 118     AvahiProtocol protocol,
 119     AvahiPublishFlags flags,
 120     uint32_t ttl,
 121     const char *name,
 122     va_list va);
 123
 124 /** Add a PTR RR to the server. Mostly identical to
 125  * avahi_server_add_text but takes an AvahiStringList record instead of a variable
 126  * number of arguments. */
 127 int avahi_server_add_txt_strlst(
 128     AvahiServer *s,
 129     AvahiSEntryGroup *g,
 130     AvahiIfIndex interface,
 131     AvahiProtocol protocol,
 132     AvahiPublishFlags flags,
 133     uint32_t ttl,
 134     const char *name,
 135     AvahiStringList *strlst  /**< TXT decord data as a AvahiString. This routine makes a deep copy of this object. */ );
 136
 137 /** Add an IP address mapping to the server. This will add both the
 138  * host-name-to-address and the reverse mapping to the server. See
 139  * avahi_server_add() for more information. If adding one of the RRs
 140  * fails, the function returns with an error, but it is not defined if
 141  * the other RR is deleted from the server or not. Therefore, you have
 142  * to free the AvahiSEntryGroup and create a new one before
 143  * proceeding. */
 144 int avahi_server_add_address(
 145     AvahiServer *s,
 146     AvahiSEntryGroup *g,
 147     AvahiIfIndex interface,
 148     AvahiProtocol protocol,
 149     AvahiPublishFlags flags,
 150     const char *name,
 151     AvahiAddress *a);
 152
 153 /** Add an DNS-SD service to the Server. This will add all required
 154  * RRs to the server. See avahi_server_add() for more information.  If
 155  * adding one of the RRs fails, the function returns with an error,
 156  * but it is not defined if the other RR is deleted from the server or
 157  * not. Therefore, you have to free the AvahiSEntryGroup and create a
 158  * new one before proceeding. */
 159 int avahi_server_add_service(
 160     AvahiServer *s,
 161     AvahiSEntryGroup *g,
 162     AvahiIfIndex interface,
 163     AvahiProtocol protocol,
 164     AvahiPublishFlags flags,
 165     const char *name,         /**< Service name, e.g. "Lennart's Files" */
 166     const char *type,         /**< DNS-SD type, e.g. "_http._tcp" */
 167     const char *domain,
 168     const char *host,         /**< Host name where this servcie resides, or NULL if on the local host */
 169     uint16_t port,              /**< Port number of the service */
 170     ...  /**< Text records, terminated by NULL */) AVAHI_GCC_SENTINEL;
 171
 172 /** Mostly identical to avahi_server_add_service(), but takes an va_list for the TXT records. */
 173 int avahi_server_add_service_va(
 174     AvahiServer *s,
 175     AvahiSEntryGroup *g,
 176     AvahiIfIndex interface,
 177     AvahiProtocol protocol,
 178     AvahiPublishFlags flags,
 179     const char *name,
 180     const char *type,
 181     const char *domain,
 182     const char *host,
 183     uint16_t port,
 184     va_list va);
 185
 186 /** Mostly identical to avahi_server_add_service(), but takes an AvahiStringList object for the TXT records.  The AvahiStringList object is copied. */
 187 int avahi_server_add_service_strlst(
 188     AvahiServer *s,
 189     AvahiSEntryGroup *g,
 190     AvahiIfIndex interface,
 191     AvahiProtocol protocol,
 192     AvahiPublishFlags flags,
 193     const char *name,
 194     const char *type,
 195     const char *domain,
 196     const char *host,
 197     uint16_t port,
 198     AvahiStringList *strlst);
 199
 200 /** Add a subtype for an already existing service */
 201 int avahi_server_add_service_subtype(
 202     AvahiServer *s,
 203     AvahiSEntryGroup *g,
 204     AvahiIfIndex interface,
 205     AvahiProtocol protocol,
 206     AvahiPublishFlags flags,
 207     const char *name,         /**< Specify the name of main service you already added here */
 208     const char *type,         /**< Specify the main type of the service you already added here */
 209     const char *domain,       /**< Specify the main type of the service you already added here */
 210     const char *subtype       /**< The new subtype for the specified service */ );
 211
 212 /** Update the TXT record for a service with the data from the specified string list */
 213 int avahi_server_update_service_txt_strlst(
 214     AvahiServer *s,
 215     AvahiSEntryGroup *g,
 216     AvahiIfIndex interface,
 217     AvahiProtocol protocol,
 218     AvahiPublishFlags flags,
 219     const char *name,
 220     const char *type,
 221     const char *domain,
 222     AvahiStringList *strlst);
 223
 224 /** Update the TXT record for a service with the NULL terminated list of strings of the va_list. */
 225 int avahi_server_update_service_txt_va(
 226     AvahiServer *s,
 227     AvahiSEntryGroup *g,
 228     AvahiIfIndex interface,
 229     AvahiProtocol protocol,
 230     AvahiPublishFlags flags,
 231     const char *name,
 232     const char *type,
 233     const char *domain,
 234     va_list va);
 235
 236 /** Update the TXT record for a service with the NULL termonate list of strings */
 237 int avahi_server_update_service_txt(
 238     AvahiServer *s,
 239     AvahiSEntryGroup *g,
 240     AvahiIfIndex interface,
 241     AvahiProtocol protocol,
 242     AvahiPublishFlags flags,
 243     const char *name,
 244     const char *type,
 245     const char *domain,
 246     ...) AVAHI_GCC_SENTINEL;
 247
 248 /** The type of DNS server */
 249 typedef enum {
 250     AVAHI_DNS_SERVER_RESOLVE,         /**< Unicast DNS servers for normal resolves (_domain._udp)*/
 251     AVAHI_DNS_SERVER_UPDATE,           /**< Unicast DNS servers for updates (_dns-update._udp)*/
 252     AVAHI_DNS_SERVER_MAX
 253 } AvahiDNSServerType;
 254
 255 /** Publish the specified unicast DNS server address via mDNS. You may
 256  * browse for records create this way wit
 257  * avahi_s_dns_server_browser_new(). */
 258 int avahi_server_add_dns_server_address(
 259     AvahiServer *s,
 260     AvahiSEntryGroup *g,
 261     AvahiIfIndex interface,
 262     AvahiProtocol protocol,
 263     AvahiPublishFlags flags,
 264     const char *domain,
 265     AvahiDNSServerType type,
 266     const AvahiAddress *address,
 267     uint16_t port /** should be 53 */);
 268
 269 /** Similar to avahi_server_add_dns_server_address(), but specify a
 270 host name instead of an address. The specified host name should be
 271 resolvable via mDNS */
 272 int avahi_server_add_dns_server_name(
 273     AvahiServer *s,
 274     AvahiSEntryGroup *g,
 275     AvahiIfIndex interface,
 276     AvahiProtocol protocol,
 277     AvahiPublishFlags flags,
 278     const char *domain,
 279     AvahiDNSServerType type,
 280     const char *name,
 281     uint16_t port /** should be 53 */);
 282
 283
 284 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 285 AVAHI_C_DECL_END
 286 #endif
 287
 288 #endif