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