]> git.meshlink.io Git - catta/blob - include/catta/core.h
move wincompat headers to include path and add to make install
[catta] / include / catta / core.h
1 #ifndef foocorehfoo
2 #define foocorehfoo
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.h The Catta Multicast DNS and DNS Service Discovery implementation. */
24
25 /** An mDNS responder object */
26 typedef struct CattaServer CattaServer;
27
28 #include <catta/cdecl.h>
29 #include <catta/address.h>
30 #include <catta/defs.h>
31 #include <catta/watch.h>
32 #include <catta/timeval.h>
33 #include <catta/rr.h>
34
35 CATTA_C_DECL_BEGIN
36
37 /** Maximum number of defined DNS servers for wide area DNS */
38 #define CATTA_WIDE_AREA_SERVERS_MAX 4
39
40 /** Prototype for callback functions which are called whenever the state of an CattaServer object changes */
41 typedef void (*CattaServerCallback) (CattaServer *s, CattaServerState state, void* userdata);
42
43 /** Stores configuration options for a server instance */
44 typedef struct CattaServerConfig {
45     char *host_name;                  /**< Default host name. If left empty defaults to the result of gethostname(2) of the libc */
46     char *domain_name;                /**< Default domain name. If left empty defaults to .local */
47     int use_ipv4;                     /**< Enable IPv4 support */
48     int use_ipv6;                     /**< Enable IPv6 support */
49     CattaStringList *allow_interfaces;/**< Allow specific interface to be used for Catta */
50     CattaStringList *deny_interfaces; /**< Deny specific interfaces to be used for Catta */
51     int publish_hinfo;                /**< Register a HINFO record for the host containing the local OS and CPU type */
52     int publish_addresses;            /**< Register A, AAAA and PTR records for all local IP addresses */
53     int publish_no_reverse;           /**< Do not register PTR records */
54     int publish_workstation;          /**< Register a _workstation._tcp service */
55     int publish_domain;               /**< Announce the local domain for browsing */
56     int check_response_ttl;           /**< If enabled the server ignores all incoming responses with IP TTL != 255. Newer versions of the RFC do no longer contain this check, so it is disabled by default. */
57     int use_iff_running;              /**< Require IFF_RUNNING on local network interfaces. This is the official way to check for link beat. Unfortunately this doesn't work with all drivers. So bettere leave this off. */
58     int enable_reflector;             /**< Reflect incoming mDNS traffic to all local networks. This allows mDNS based network browsing beyond ethernet borders */
59     int reflect_ipv;                  /**< if enable_reflector is 1, enable/disable reflecting between IPv4 and IPv6 */
60     int add_service_cookie;           /**< Add magic service cookie to all locally generated records implicitly */
61     int enable_wide_area;             /**< Enable wide area support */
62     CattaAddress wide_area_servers[CATTA_WIDE_AREA_SERVERS_MAX]; /** Unicast DNS server to use for wide area lookup */
63     unsigned n_wide_area_servers;     /**< Number of servers in wide_area_servers[] */
64     int disallow_other_stacks;        /**< Make sure that only one mDNS responder is run at the same time on the local machine. If this is enable Catta will not set SO_REUSADDR on its sockets, effectively preventing other stacks from running on the local machine */
65     CattaStringList *browse_domains;  /**< Additional browsing domains */
66     int disable_publishing;           /**< Disable publishing of any record */
67     int allow_point_to_point;         /**< Enable publishing on POINTOPOINT interfaces */
68     int publish_a_on_ipv6;            /**< Publish an IPv4 A RR on IPv6 sockets */
69     int publish_aaaa_on_ipv4;         /**< Publish an IPv4 A RR on IPv6 sockets */
70     unsigned n_cache_entries_max;     /**< Maximum number of cache entries per interface */
71     CattaUsec ratelimit_interval;     /**< If non-zero, rate-limiting interval parameter. */
72     unsigned ratelimit_burst;         /**< If ratelimit_interval is non-zero, rate-limiting burst parameter. */
73 } CattaServerConfig;
74
75 /** Allocate a new mDNS responder object. */
76 CattaServer *catta_server_new(
77     const CattaPoll *api,          /**< The main loop adapter */
78     const CattaServerConfig *sc,   /**< If non-NULL a pointer to a configuration structure for the server. The server makes an internal deep copy of this structure, so you may free it using catta_server_config_done() immediately after calling this function. */
79     CattaServerCallback callback,  /**< A callback which is called whenever the state of the server changes */
80     void* userdata,                /**< An opaque pointer which is passed to the callback function */
81     int *error);
82
83 /** Free an mDNS responder object */
84 void catta_server_free(CattaServer* s);
85
86 /** Fill in default values for a server configuration structure. If you
87  * make use of an CattaServerConfig structure be sure to initialize
88  * it with this function for the sake of upwards library
89  * compatibility. This call may allocate strings on the heap. To
90  * release this memory make sure to call
91  * catta_server_config_done(). If you want to replace any strings in
92  * the structure be sure to free the strings filled in by this
93  * function with catta_free() first and allocate the replacements with
94  * g_malloc() (or g_strdup()).*/
95 CattaServerConfig* catta_server_config_init(
96    CattaServerConfig *c /**< A structure which shall be filled in */ );
97
98 /** Make a deep copy of the configuration structure *c to *ret. */
99 CattaServerConfig* catta_server_config_copy(
100     CattaServerConfig *ret /**< destination */,
101     const CattaServerConfig *c /**< source */);
102
103 /** Free the data in a server configuration structure. */
104 void catta_server_config_free(CattaServerConfig *c);
105
106 /** Return the currently chosen domain name of the server object. The
107  * return value points to an internally allocated string. Be sure to
108  * make a copy of the string before calling any other library
109  * functions. */
110 const char* catta_server_get_domain_name(CattaServer *s);
111
112 /** Return the currently chosen host name. The return value points to a internally allocated string. */
113 const char* catta_server_get_host_name(CattaServer *s);
114
115 /** Return the currently chosen host name as a FQDN ("fully qualified
116  * domain name", i.e. the concatenation of the host and domain
117  * name). The return value points to a internally allocated string. */
118 const char* catta_server_get_host_name_fqdn(CattaServer *s);
119
120 /** Change the host name of a running mDNS responder. This will drop
121 all automicatilly generated RRs and readd them with the new
122 name. Since the responder has to probe for the new RRs this function
123 takes some time to take effect altough it returns immediately. This
124 function is intended to be called when a host name conflict is
125 reported using CattaServerCallback. The caller should readd all user
126 defined RRs too since they otherwise continue to point to the outdated
127 host name..*/
128 int catta_server_set_host_name(CattaServer *s, const char *host_name);
129
130 /** Change the domain name of a running mDNS responder. The same rules
131  * as with catta_server_set_host_name() apply. */
132 int catta_server_set_domain_name(CattaServer *s, const char *domain_name);
133
134 /** Return the opaque user data pointer attached to a server object */
135 void* catta_server_get_data(CattaServer *s);
136
137 /** Change the opaque user data pointer attached to a server object */
138 void catta_server_set_data(CattaServer *s, void* userdata);
139
140 /** Return the current state of the server object */
141 CattaServerState catta_server_get_state(CattaServer *s);
142
143 /** Callback prototype for catta_server_dump() */
144 typedef void (*CattaDumpCallback)(const char *text, void* userdata);
145
146 /** Dump the current server status by calling "callback" for each line.  */
147 int catta_server_dump(CattaServer *s, CattaDumpCallback callback, void* userdata);
148
149 /** Return the last error code */
150 int catta_server_errno(CattaServer *s);
151
152 /** Return the local service cookie */
153 uint32_t catta_server_get_local_service_cookie(CattaServer *s);
154
155 /** Set the wide area DNS servers */
156 int catta_server_set_wide_area_servers(CattaServer *s, const CattaAddress *a, unsigned n);
157
158 /** Set the browsing domains */
159 int catta_server_set_browse_domains(CattaServer *s, CattaStringList *domains);
160
161 /** Return the current configuration of the server \since 0.6.17 */
162 const CattaServerConfig* catta_server_get_config(CattaServer *s);
163
164 CATTA_C_DECL_END
165
166 #endif