git.meshlink.io Git - catta/blob - include/catta/publish.h

   1 #ifndef foopublishhfoo
   2 #define foopublishhfoo
   3
   4 /***
   5   This file is part of catta.
   6
   7   catta is free software; you can redistribute it and/or modify it
   8   under the terms of the GNU Lesser General Public License as
   9   published by the Free Software Foundation; either version 2.1 of the
  10   License, or (at your option) any later version.
  11
  12   catta is distributed in the hope that it will be useful, but WITHOUT
  13   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14   or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
  15   Public License for more details.
  16
  17   You should have received a copy of the GNU Lesser General Public
  18   License along with catta; if not, write to the Free Software
  19   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  20   USA.
  21 ***/
  22
  23 /** \file core/publish.h Functions for publising local services and RRs */
  24
  25 /** \example core-publish-service.c Example how to register a DNS-SD
  26  * service using an embedded mDNS stack. It behaves like a network
  27  * printer registering both an IPP and a BSD LPR service. */
  28
  29 /** A group of locally registered DNS RRs */
  30 typedef struct CattaSEntryGroup CattaSEntryGroup;
  31
  32 #include <catta/cdecl.h>
  33 #include <catta/core.h>
  34
  35 CATTA_C_DECL_BEGIN
  36
  37 /** Prototype for callback functions which are called whenever the state of an CattaSEntryGroup object changes */
  38 typedef void (*CattaSEntryGroupCallback) (CattaServer *s, CattaSEntryGroup *g, CattaEntryGroupState state, void* userdata);
  39
  40 /** Iterate through all local entries of the server. (when g is NULL)
  41  * or of a specified entry group. At the first call state should point
  42  * to a NULL initialized void pointer, That pointer is used to track
  43  * the current iteration. It is not safe to call any other
  44  * catta_server_xxx() function during the iteration. If the last entry
  45  * has been read, NULL is returned. */
  46 const CattaRecord *catta_server_iterate(CattaServer *s, CattaSEntryGroup *g, void **state);
  47
  48 /** Create a new entry group. The specified callback function is
  49  * called whenever the state of the group changes. Use entry group
  50  * objects to keep track of you RRs. Add new RRs to a group using
  51  * catta_server_add_xxx(). Make sure to call catta_s_entry_group_commit()
  52  * to start the registration process for your RRs */
  53 CattaSEntryGroup *catta_s_entry_group_new(CattaServer *s, CattaSEntryGroupCallback callback, void* userdata);
  54
  55 /** Free an entry group. All RRs assigned to the group are removed from the server */
  56 void catta_s_entry_group_free(CattaSEntryGroup *g);
  57
  58 /** Commit an entry group. This starts the probing and registration process for all RRs in the group */
  59 int catta_s_entry_group_commit(CattaSEntryGroup *g);
  60
  61 /** Remove all entries from the entry group and reset the state to CATTA_ENTRY_GROUP_UNCOMMITED. */
  62 void catta_s_entry_group_reset(CattaSEntryGroup *g);
  63
  64 /** Return 1 if the entry group is empty, i.e. has no records attached. */
  65 int catta_s_entry_group_is_empty(CattaSEntryGroup *g);
  66
  67 /** Return the current state of the specified entry group */
  68 CattaEntryGroupState catta_s_entry_group_get_state(CattaSEntryGroup *g);
  69
  70 /** Change the opaque user data pointer attached to an entry group object */
  71 void catta_s_entry_group_set_data(CattaSEntryGroup *g, void* userdata);
  72
  73 /** Return the opaque user data pointer currently set for the entry group object */
  74 void* catta_s_entry_group_get_data(CattaSEntryGroup *g);
  75
  76 /** Add a new resource record to the server. Returns 0 on success, negative otherwise. */
  77 int catta_server_add(
  78     CattaServer *s,           /**< The server object to add this record to */
  79     CattaSEntryGroup *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. */
  80     CattaIfIndex interface,   /**< A numeric index of a network interface to attach this record to, or CATTA_IF_UNSPEC to attach this record to all interfaces */
  81     CattaProtocol protocol,   /**< A protocol family to attach this record to. One of the CATTA_PROTO_xxx constants. Use CATTA_PROTO_UNSPEC to make this record available on all protocols (wich means on both IPv4 and IPv6). */
  82     CattaPublishFlags flags,    /**< Special flags for this record */
  83     CattaRecord *r            /**< The record to add. This function increases the reference counter of this object. */);
  84
  85 /** Add an IP address mapping to the server. This will add both the
  86  * host-name-to-address and the reverse mapping to the server. See
  87  * catta_server_add() for more information. If adding one of the RRs
  88  * fails, the function returns with an error, but it is not defined if
  89  * the other RR is deleted from the server or not. Therefore, you have
  90  * to free the CattaSEntryGroup and create a new one before
  91  * proceeding. */
  92 int catta_server_add_address(
  93     CattaServer *s,
  94     CattaSEntryGroup *g,
  95     CattaIfIndex interface,
  96     CattaProtocol protocol,
  97     CattaPublishFlags flags,
  98     const char *name,
  99     CattaAddress *a);
 100
 101 /** Add an DNS-SD service to the Server. This will add all required
 102  * RRs to the server. See catta_server_add() for more information.  If
 103  * adding one of the RRs fails, the function returns with an error,
 104  * but it is not defined if the other RR is deleted from the server or
 105  * not. Therefore, you have to free the CattaSEntryGroup and create a
 106  * new one before proceeding. */
 107 int catta_server_add_service(
 108     CattaServer *s,
 109     CattaSEntryGroup *g,
 110     CattaIfIndex interface,
 111     CattaProtocol protocol,
 112     CattaPublishFlags flags,
 113     const char *name,         /**< Service name, e.g. "Lennart's Files" */
 114     const char *type,         /**< DNS-SD type, e.g. "_http._tcp" */
 115     const char *domain,
 116     const char *host,         /**< Host name where this servcie resides, or NULL if on the local host */
 117     uint16_t port,              /**< Port number of the service */
 118     ...  /**< Text records, terminated by NULL */) CATTA_GCC_SENTINEL;
 119
 120 /** Mostly identical to catta_server_add_service(), but takes an CattaStringList object for the TXT records.  The CattaStringList object is copied. */
 121 int catta_server_add_service_strlst(
 122     CattaServer *s,
 123     CattaSEntryGroup *g,
 124     CattaIfIndex interface,
 125     CattaProtocol protocol,
 126     CattaPublishFlags flags,
 127     const char *name,
 128     const char *type,
 129     const char *domain,
 130     const char *host,
 131     uint16_t port,
 132     CattaStringList *strlst);
 133
 134 /** Add a subtype for an already existing service */
 135 int catta_server_add_service_subtype(
 136     CattaServer *s,
 137     CattaSEntryGroup *g,
 138     CattaIfIndex interface,
 139     CattaProtocol protocol,
 140     CattaPublishFlags flags,
 141     const char *name,         /**< Specify the name of main service you already added here */
 142     const char *type,         /**< Specify the main type of the service you already added here */
 143     const char *domain,       /**< Specify the main type of the service you already added here */
 144     const char *subtype       /**< The new subtype for the specified service */ );
 145
 146 /** Update the TXT record for a service with the data from the specified string list */
 147 int catta_server_update_service_txt_strlst(
 148     CattaServer *s,
 149     CattaSEntryGroup *g,
 150     CattaIfIndex interface,
 151     CattaProtocol protocol,
 152     CattaPublishFlags flags,
 153     const char *name,
 154     const char *type,
 155     const char *domain,
 156     CattaStringList *strlst);
 157
 158 /** Update the TXT record for a service with the NULL termonate list of strings */
 159 int catta_server_update_service_txt(
 160     CattaServer *s,
 161     CattaSEntryGroup *g,
 162     CattaIfIndex interface,
 163     CattaProtocol protocol,
 164     CattaPublishFlags flags,
 165     const char *name,
 166     const char *type,
 167     const char *domain,
 168     ...) CATTA_GCC_SENTINEL;
 169
 170 /** 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*/
 171 int catta_server_get_group_of_service(CattaServer *s, CattaIfIndex interface, CattaProtocol protocol, const char *name, const char *type, const char *domain, CattaSEntryGroup** ret_group);
 172
 173 CATTA_C_DECL_END
 174
 175 #endif