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 /** A group of locally registered DNS RRs */
  32 typedef struct AvahiSEntryGroup AvahiSEntryGroup;
  33
  34 #include <avahi-common/cdecl.h>
  35 #include <avahi-core/core.h>
  36
  37 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  38 AVAHI_C_DECL_BEGIN
  39 #endif
  40
  41 /** Prototype for callback functions which are called whenever the state of an AvahiSEntryGroup object changes */
  42 typedef void (*AvahiSEntryGroupCallback) (AvahiServer *s, AvahiSEntryGroup *g, AvahiEntryGroupState state, void* userdata);
  43
  44 /** Iterate through all local entries of the server. (when g is NULL)
  45  * or of a specified entry group. At the first call state should point
  46  * to a NULL initialized void pointer, That pointer is used to track
  47  * the current iteration. It is not safe to call any other
  48  * avahi_server_xxx() function during the iteration. If the last entry
  49  * has been read, NULL is returned. */
  50 const AvahiRecord *avahi_server_iterate(AvahiServer *s, AvahiSEntryGroup *g, void **state);
  51
  52 /** Create a new entry group. The specified callback function is
  53  * called whenever the state of the group changes. Use entry group
  54  * objects to keep track of you RRs. Add new RRs to a group using
  55  * avahi_server_add_xxx(). Make sure to call avahi_s_entry_group_commit()
  56  * to start the registration process for your RRs */
  57 AvahiSEntryGroup *avahi_s_entry_group_new(AvahiServer *s, AvahiSEntryGroupCallback callback, void* userdata);
  58
  59 /** Free an entry group. All RRs assigned to the group are removed from the server */
  60 void avahi_s_entry_group_free(AvahiSEntryGroup *g);
  61
  62 /** Commit an entry group. This starts the probing and registration process for all RRs in the group */
  63 int avahi_s_entry_group_commit(AvahiSEntryGroup *g);
  64
  65 /** Remove all entries from the entry group and reset the state to AVAHI_ENTRY_GROUP_UNCOMMITED. */
  66 void avahi_s_entry_group_reset(AvahiSEntryGroup *g);
  67
  68 /** Return 1 if the entry group is empty, i.e. has no records attached. */
  69 int avahi_s_entry_group_is_empty(AvahiSEntryGroup *g);
  70
  71 /** Return the current state of the specified entry group */
  72 AvahiEntryGroupState avahi_s_entry_group_get_state(AvahiSEntryGroup *g);
  73
  74 /** Change the opaque user data pointer attached to an entry group object */
  75 void avahi_s_entry_group_set_data(AvahiSEntryGroup *g, void* userdata);
  76
  77 /** Return the opaque user data pointer currently set for the entry group object */
  78 void* avahi_s_entry_group_get_data(AvahiSEntryGroup *g);
  79
  80 /** Add a new resource record to the server. Returns 0 on success, negative otherwise. */
  81 int avahi_server_add(
  82     AvahiServer *s,           /**< The server object to add this record to */
  83     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. */
  84     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 */
  85     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). */
  86     AvahiPublishFlags flags,    /**< Special flags for this record */
  87     AvahiRecord *r            /**< The record to add. This function increases the reference counter of this object. */);
  88
  89 /** Add an IP address mapping to the server. This will add both the
  90  * host-name-to-address and the reverse mapping to the server. See
  91  * avahi_server_add() for more information. If adding one of the RRs
  92  * fails, the function returns with an error, but it is not defined if
  93  * the other RR is deleted from the server or not. Therefore, you have
  94  * to free the AvahiSEntryGroup and create a new one before
  95  * proceeding. */
  96 int avahi_server_add_address(
  97     AvahiServer *s,
  98     AvahiSEntryGroup *g,
  99     AvahiIfIndex interface,
 100     AvahiProtocol protocol,
 101     AvahiPublishFlags flags,
 102     const char *name,
 103     AvahiAddress *a);
 104
 105 /** Add an DNS-SD service to the Server. This will add all required
 106  * RRs to the server. See avahi_server_add() for more information.  If
 107  * adding one of the RRs fails, the function returns with an error,
 108  * but it is not defined if the other RR is deleted from the server or
 109  * not. Therefore, you have to free the AvahiSEntryGroup and create a
 110  * new one before proceeding. */
 111 int avahi_server_add_service(
 112     AvahiServer *s,
 113     AvahiSEntryGroup *g,
 114     AvahiIfIndex interface,
 115     AvahiProtocol protocol,
 116     AvahiPublishFlags flags,
 117     const char *name,         /**< Service name, e.g. "Lennart's Files" */
 118     const char *type,         /**< DNS-SD type, e.g. "_http._tcp" */
 119     const char *domain,
 120     const char *host,         /**< Host name where this servcie resides, or NULL if on the local host */
 121     uint16_t port,              /**< Port number of the service */
 122     ...  /**< Text records, terminated by NULL */) AVAHI_GCC_SENTINEL;
 123
 124 /** Mostly identical to avahi_server_add_service(), but takes an va_list for the TXT records. */
 125 int avahi_server_add_service_va(
 126     AvahiServer *s,
 127     AvahiSEntryGroup *g,
 128     AvahiIfIndex interface,
 129     AvahiProtocol protocol,
 130     AvahiPublishFlags flags,
 131     const char *name,
 132     const char *type,
 133     const char *domain,
 134     const char *host,
 135     uint16_t port,
 136     va_list va);
 137
 138 /** Mostly identical to avahi_server_add_service(), but takes an AvahiStringList object for the TXT records.  The AvahiStringList object is copied. */
 139 int avahi_server_add_service_strlst(
 140     AvahiServer *s,
 141     AvahiSEntryGroup *g,
 142     AvahiIfIndex interface,
 143     AvahiProtocol protocol,
 144     AvahiPublishFlags flags,
 145     const char *name,
 146     const char *type,
 147     const char *domain,
 148     const char *host,
 149     uint16_t port,
 150     AvahiStringList *strlst);
 151
 152 /** Add a subtype for an already existing service */
 153 int avahi_server_add_service_subtype(
 154     AvahiServer *s,
 155     AvahiSEntryGroup *g,
 156     AvahiIfIndex interface,
 157     AvahiProtocol protocol,
 158     AvahiPublishFlags flags,
 159     const char *name,         /**< Specify the name of main service you already added here */
 160     const char *type,         /**< Specify the main type of the service you already added here */
 161     const char *domain,       /**< Specify the main type of the service you already added here */
 162     const char *subtype       /**< The new subtype for the specified service */ );
 163
 164 /** Update the TXT record for a service with the data from the specified string list */
 165 int avahi_server_update_service_txt_strlst(
 166     AvahiServer *s,
 167     AvahiSEntryGroup *g,
 168     AvahiIfIndex interface,
 169     AvahiProtocol protocol,
 170     AvahiPublishFlags flags,
 171     const char *name,
 172     const char *type,
 173     const char *domain,
 174     AvahiStringList *strlst);
 175
 176 /** Update the TXT record for a service with the NULL terminated list of strings of the va_list. */
 177 int avahi_server_update_service_txt_va(
 178     AvahiServer *s,
 179     AvahiSEntryGroup *g,
 180     AvahiIfIndex interface,
 181     AvahiProtocol protocol,
 182     AvahiPublishFlags flags,
 183     const char *name,
 184     const char *type,
 185     const char *domain,
 186     va_list va);
 187
 188 /** Update the TXT record for a service with the NULL termonate list of strings */
 189 int avahi_server_update_service_txt(
 190     AvahiServer *s,
 191     AvahiSEntryGroup *g,
 192     AvahiIfIndex interface,
 193     AvahiProtocol protocol,
 194     AvahiPublishFlags flags,
 195     const char *name,
 196     const char *type,
 197     const char *domain,
 198     ...) AVAHI_GCC_SENTINEL;
 199
 200 /** Check if there is a service locally defined and return the entry group it is attached to. Returns NULL if the service isn't local*/
 201 int avahi_server_get_group_of_service(AvahiServer *s, AvahiIfIndex interface, AvahiProtocol protocol, const char *name, const char *type, const char *domain, AvahiSEntryGroup** ret_group);
 202
 203 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 204 AVAHI_C_DECL_END
 205 #endif
 206
 207 #endif