gensio_mdns(3)

💖 gensio_mdns — the mDNS bestie 💖

okay so this is a page from the Library Functions Manual, section 3, and it's all about gensio_mdns. mDNS discovery but make it slay. let's get into it 🦋

---

✨ NAME ✨

gensio_alloc_mdns, gensio_free_mdns, gensio_mdns_add_service, gensio_mdns_remove_service, gensio_mdns_add_watch, gensio_mdns_remove_watch — functions for doing mDNS operations 🎀

---

🌈 SYNOPSIS 🌈

#include <gensio/gensio_mdns.h>

typedef void (*gensio_mdns_done)(struct gensio_mdns *m,
                    void *userdata);

int gensio_alloc_mdns(struct gensio_os_funcs *o,
                    struct gensio_mdns **m);

int gensio_free_mdns(struct gensio_mdns *m, gensio_mdns_done done,
                    void *userdata);

int gensio_mdns_add_service(struct gensio_mdns *m, int interface,
                    int ipdomain, const char *name, const char *type,
                    const char *domain, const char *host,
                    int port, const char *txt[],
                    struct gensio_mdns_service **s);

typedef void (*gensio_mdns_service_cb)(struct gensio_mdns_service
*service,
                    enum gensio_mdns_service_event ev,
                    const char *info,
                    void *cb_data);

int gensio_mdns_add_service2(struct gensio_mdns *m, int interface,
                    int ipdomain, const char *name, const char *type,
                    const char *domain, const char *host,
                    int port, const char *txt[],
                    gensio_mdns_service_cb cb, void *cb_data,
                    struct gensio_mdns_service **s);

int gensio_mdns_remove_service(struct gensio_mdns_service *s);

typedef void gensio_mdns_watch_cb(struct gensio_mdns_watch *w,
                    enum gensio_mdns_data_state state,
                    int interface, int ipdomain,
                    const char *name, const char *type,
                    const char *domain, const char *host,
                    const struct gensio_addr *addr, const char *txt[],
                    void *userdata);

int gensio_mdns_add_watch(struct gensio_mdns *m, int interface,
                    int ipdomain, const char *name, const char *type,
                    const char *domain, const char *host,
                    gensio_mdns_watch_cb callback, void *userdata,
                    struct gensio_mdns_watch **w);

int gensio_mdns_remove_watch(struct gensio_mdns_watch *w);

---

💅 DESCRIPTION 💅

so these functions and types are literally all about mDNS (that's Multicast DNS, bestie) discovery of services on a local network. you can use them to advertise services OR to find services. it's giving powerful and easy-to-use interface to mDNS capabilities, no cap. 🔥

first things first: you gotta call gensio_alloc_mdns to allocate an mdns structure, using the standard gensio OS functions structure. and yeah, you do have to do the standard OS functions wait loops and all that, that part is not optional babe. when you're done, free the mdns structure with gensio_free_mdns.

⚠️ important, don't skip this: code may still be in mdns callbacks when the free returns. so you have to make sure to wait until the done callback is called to know the code is out of all callbacks. the done callback is optional if you don't care.

🫶 also note: the mdns will not be freed (and done will not be called) until all the services and watches are freed for it. so like. clean up after yourself.

for the rest of the functions: the interface parameter is the system interface number of the network device, and it may be -1 to specify all interfaces. the ipdomain parameter is one of:

• GENSIO_NETTYPE_UNSPEC — do both IPV4 and IPV4 (yes, that's exactly what the original says, i'm just the messenger 💀)
• GENSIO_NETTYPE_IPV4 — IPV4 only
• GENSIO_NETTYPE_IPV6 — IPV6 only

the name, type, domain, and host parameters are the standard mDNS fields — go read the mDNS docs for the details, i'm not gonna reinvent the wheel here. the txt parameter is for mDNS text fields, and it's a standard argv-like array. 🍓

---

🎀 advertising, aka putting yourself out there 🎀

once you have an mdns structure, you can advertise a service on the net with gensio_mdns_add_service2. that service will keep being advertised until you call gensio_mdns_remove_service on it, or your program just... terminates. 💀

the domain and host parameters should generally be NULL to take the system defaults. the txt parameter may be NULL if you don't have any. (iconic behavior honestly)

gensio_mdns_add_service2 takes a callback, and it'll get called when the service has been registered — and possibly with a new name if there was a name conflict. you may pass in a NULL for the callback if you don't care. the callback parameter can take the following values:

• GENSIO_MDNS_SERVICE_READY — the service is now registered, and the name is the same as the name you passed in. ✨
• GENSIO_MDNS_SERVICE_READY_NEW_NAME — the service is now registered, but the name was changed, and it'll be in the info parameter. 🙈
• GENSIO_MDNS_SERVICE_REMOVED — you requested the service be removed, the remove is now complete, and the callback will not be called again. periodt.
• GENSIO_MDNS_SERVICE_ERROR — an error occurred as part of service registration. 😭

there's also a gensio_mdns_add_service function for backwards compatibility — it's equivalent to calling gensio_mdns_add_service2 with a NULL callback.

🚫 don't use it in new code. it's giving legacy. it's giving deprecated. leave it in the past bestie.

---

🦋 watching, aka finding your people 🦋

to find services on the network, you add a watch with gensio_mdns_add_watch. any service that matches your query will be reported with the callback functions, and all fields will be provided in the callback. once you're done with a watch, you may call gensio_mdns_remove_watch.

⚠️ same deal as before: code may still be in mdns callbacks when the remove returns. you have to make sure to wait until the done callback is called to know the code is out of all callbacks. the done callback is optional if you don't care.

some MDNS libraries do not support a NULL type for the watch, and some do. for portable code, always specify the watch. if the library does not support a null type, the function will return GE_INCONSISTENT.

the watch callback state has three possible values:

• GENSIO_MDNS_WATCH_NEW_DATA — this is a new entry being reported. 🎉
• GENSIO_MDNS_WATCH_DATA_GONE — an entry that was previously reported has gone away. 💔
• GENSIO_MDNS_WATCH_ALL_FOR_NOW — this is called one time after the watch is created, and it reports that all currently known entries have been reported. new ones may be reported in the future, but those will have been dynamically added later.

🚨 listen up: in the watch callback, you must make copies of all the strings and addresses passed to you to keep them. their continued existence is not guaranteed. like, don't just hold onto the pointer and hope for the best, that's not the vibe.

in watches, all of the string fields may be NULL, meaning you want to take anything in that field. so if all the strings are NULL and the interface is -1 and the ipdomain is GENSIO_NETTYPE_UNSPEC, you will get all of the fields. 🌈

---

🌸 STRING VALUES FOR WATCHES 🌸

the string values to the watch add function may use regular expressions. if the string starts with '%', then the data after it is treated as a regular expression and fields are matched against that. see the regex(7) man page for details. 👑

Globs are supported on some platforms, but their use is discouraged because they aren't available on some platforms. if the string starts with '@', then the data after it is treated as a standard glob. see the glob(7) man page for details. an error will be returned if the platform doesn't have glob matching. 🫠

if the string starts with '=', an exact comparison is done with the data after it.

if the string starts with a-z0-9_ or a space, then an exact string comparison is done, including the first character.

💀 the behavior of matching for any other starting character is undefined. in general, you should always use '@', '%', or '=' as the starting character of all your query strings to be sure. don't be chaotic about it bestie, we're not doing undefined behavior today.

---

⭐ RETURN VALUES ⭐

Zero is returned on success, or a gensio error on failure. simple as that, slay. 💖

---

👑 SEE ALSO 👑

• gensio_err(3)
• gensio_os_funcs(3)
• regex(7)
• glob(7)

---

and that's the whole page, bestie!! 🎀 this was gensio_mdns(3) from the Library Functions Manual, dated 15 Oct 2020 — thanks for reading, mwah, go advertise some services responsibly 💅✨🦋

💖 stay iconic, stay portable, always specify your watch 💖