1gensio_mdns(3) Library Functions Manual gensio_mdns(3)
2
6 gensio_alloc_mdns, gensio_free_mdns, gensio_mdns_add_service, gen‐
7 sio_mdns_remove_service, gensio_mdns_add_watch, gensio_mdns_re‐
8 move_watch - Functions for doing mDNS operations
9
11 #include <gensio/gensio_mdns.h>
12 typedef void (*gensio_mdns_done)(struct gensio_mdns *m,
14 void *userdata);
15 int gensio_alloc_mdns(struct gensio_os_funcs *o,
17 struct gensio_mdns **m);
18 int gensio_free_mdns(struct gensio_mdns *m, gensio_mdns_done done,
20 void *userdata);
21 int gensio_mdns_add_service(struct gensio_mdns *m, int interface,
23 int ipdomain, const char *name, const char *type,
24 const char *domain, const char *host,
25 int port, const char *txt[],
26 struct gensio_mdns_service **s);
27 typedef void (*gensio_mdns_service_cb)(struct gensio_mdns_service *ser‐
29 vice,
30 enum gensio_mdns_service_event ev,
31 const char *info,
32 void *cb_data);
33 int gensio_mdns_add_service2(struct gensio_mdns *m, int interface,
35 int ipdomain, const char *name, const char *type,
36 const char *domain, const char *host,
37 int port, const char *txt[],
38 gensio_mdns_service_cb cb, void *cb_data,
39 struct gensio_mdns_service **s);
40 int gensio_mdns_remove_service(struct gensio_mdns_service *s);
42 typedef void gensio_mdns_watch_cb(struct gensio_mdns_watch *w,
44 enum gensio_mdns_data_state state,
45 int interface, int ipdomain,
46 const char *name, const char *type,
47 const char *domain, const char *host,
48 const struct gensio_addr *addr, const char *txt[],
49 void *userdata);
50 int gensio_mdns_add_watch(struct gensio_mdns *m, int interface,
52 int ipdomain, const char *name, const char *type,
53 const char *domain, const char *host,
54 gensio_mdns_watch_cb callback, void *userdata,
55 struct gensio_mdns_watch **w);
56 int gensio_mdns_remove_watch(struct gensio_mdns_watch *w);
58
60 These functions and type deal with mDNS (Multicast DNS) discovery of
61 services on a local network. They can be used to advertise services or
62 find services. These provide a powerful and easy to use interface to
63 mDNS capabilities.
64 To do these things, you must first use gensio_alloc_mdns to allocate an
66 mdns structure with the standard gensio OS functions structure. You
67 must, of course, do the standard OS functions wait loops and such.
68 When you are finished, you should free the mdns structure with gen‐
69 sio_free_mdns. Note that code may still be in mdns callbacks when the
70 free returns, you have to make sure to wait until the done callback is
71 called to know the code is out of all callbacks. The done callback is
72 optional if you don't care. Also note that the mdns will not be freed
73 (and done not called) until all the services and watches are freed for
74 it.
75 For the remaining functions, the interface parameter is the system in‐
77 terface number of the network device, and may be -1 to specify all in‐
78 terfaces. The ipdomain parameter is one of:
79 GENSIO_NETTYPE_UNSPEC
81 Do both IPV4 and IPV4
82 GENSIO_NETTYPE_IPV4
84 IPV4 only
85 GENSIO_NETTYPE_IPV6
87 IPV6 only
88 The name, type, domain, and host parameters are the standard mDNS
90 fields, see documentation on mDNS for details. The txt parameter is
91 for mDNS text fields, and is a standard argv-like array.
92 Once you have an mdns structure, you can advertise a service on the net
94 with it using gensio_mdns_add_service2. That service will continue to
95 be advertised until you call gensio_mdns_remove_service on it or your
96 program terminates. The domain and host parameters should generally be
97 NULL to take the system defaults. The txt parameter may be NULL if you
98 don't have any.
99 gensio_mdns_add_service2 takes a callback, it will be called when the
101 service has been registered, and possible with a new name if there was
102 a name conflict. You may pass in a NULL for the callback if you don't
103 care. The callback parameter can take the following values:
104 GENSIO_MDNS_SERVICE_READY
106 The service is now registered, and the name is the same as the
107 name you passed in.
108 GENSIO_MDNS_SERVICE_READY_NEW_NAME
110 The service is now registered, but the name was changed, it will
111 be in the info parameter.
112 GENSIO_MDNS_SERVICE_REMOVED
114 You requested the service be removed, the remove is now complete
115 and the callback will not be called again.
116 GENSIO_MDNS_SERVICE_ERROR
118 An error occurred as part of service registration.
119 There is a gensio_mdns_add_service function for backwards compatibil‐
121 ity, it is equivalent to calling gensio_mdns_add_service2 with a NULL
122 callback. Don't use it in new code.
123 To find services on the network, you add a watch with gen‐
125 sio_mdns_add_watch. Any service that matches your query will be re‐
126 ported with the callback functions and all fields will be provided in
127 the callback. Once you are done with a watch, you may call gen‐
128 sio_mdns_remove_watch Note that code may still be in mdns callbacks
129 when the remove returns, you have to make sure to wait until the done
130 callback is called to know the code is out of all callbacks. The done
131 callback is optional if you don't care.
132 Some MDNS libraries do not support an NULL type for the watch, and some
134 do. For portable code, always specify the watch. If the library does
135 not support a null type the function will return GE_INCONSISTENT.
136 The watch callback state has three possible values:
138 GENSIO_MDNS_WATCH_NEW_DATA
140 This is a new entry being reported.
141 GENSIO_MDNS_WATCH_DATA_GONE
143 An entry that was previously reported as gone away.
144 GENSIO_MDNS_WATCH_ALL_FOR_NOW
146 This is called one time after the watch is created, it reports
147 that all currently known entries have been reported. New ones
148 may be reported in the future, but those will have been dynami‐
149 cally added later.
150 In the watch callback, you must make copies of all the strings and ad‐
152 dresses passed to you to keep them. Their continued existence is not
153 guaranteed.
154 In watches, all of the string fields may be NULL, meaning you want to
156 take anything in that field. So if all the strings are NULL and the
157 interface is -1 and the ipdomain is GENSIO_NETTYPE_UNSPEC you will get
158 all of the fields.
159
161 The string values to the watch add function may use regular expres‐
162 sions. If the string starts with '%', then the data after it is
163 treated as a regular expression and fields are matched against that.
164 See the regex(7) man page for details.
165 Globs are supported on some platforms, but their use is discouraged be‐
167 cause they aren't available on some platforms. If the string starts
168 with '@', the the data after it is treated as a standard glob. See the
169 glob(7) man page for details. An error will be returned if the plat‐
170 form doesn't have glob matching.
171 If the string starts with '=', an exact comparison is done with the
173 data after it.
174 If the string starts with a-z0-9_ or a space, then an exact string com‐
176 parison is done, including the first character.
177 The behavior of matching for any other starting character is undefined.
179 In general, you should always use '@', '%', or '=' as the starting
180 character of all your query strings to be sure.
181
183 Zero is returned on success, or a gensio error on failure.
184
186 gensio_err(3), gensio_os_funcs(3), regex(7), glob(7)
187 15 Oct 2020 gensio_mdns(3)