Ubuntu Manpage: gensio_alloc_mdns, gensio_free_mdns, gensio_mdns_add_service, gensio_mdns_remove

Provided by: libgensio-dev_2.3.5-1build2_amd64

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);

       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

These functions and type deal with mDNS (Multicast DNS) discovery of services on a local network. They
can be used to advertise services or find services. These provide a powerful and easy to use interface
to mDNS capabilities.

To do these things, you must first use gensio_alloc_mdns to allocate an mdns structure with the standard
gensio OS functions structure. You must, of course, do the standard OS functions wait loops and such.
When you are finished, you should free the mdns structure with gensio_free_mdns. Note that code may
still be in mdns callbacks when the free 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.
Also note that the mdns will not be freed (and done not called) until all the services and watches are
freed for it.

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

GENSIO_NETTYPE_UNSPEC
Do both IPV4 and IPV4

GENSIO_NETTYPE_IPV4
IPV4 only

GENSIO_NETTYPE_IPV6
IPV6 only

The name, type, domain, and host parameters are the standard mDNS fields, see documentation on mDNS for
details. The txt parameter is for mDNS text fields, and is a standard argv-like array.

Once you have an mdns structure, you can advertise a service on the net with it using
gensio_mdns_add_service. That service will continue to be advertised until you call
gensio_mdns_remove_service on it or your program 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.

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 are done with a watch, you may call gensio_mdns_remove_watch Note that 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.

The watch callback state has three possible values:

GENSIO_MDNS_NEW_DATA
This is a new entry being reported.

GENSIO_MDNS_DATA_GONE
An entry that was previously reported as gone away.

GENSIO_MDNS_ALL_FOR_NOW
This is called one time after the watch is created, 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.

In the watch callback, you must make copies of all the strings and addresses passed to you to keep them.
Their continued existance is not guaranteed.

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 or globs.  If the  string  starts
       with  '%', then the data after it is treated as a regular expression and fields are matched against that.
       If the string starts with '@', the the data after it is treated as a standard glob.  See the regex(7) and
       glob(7) man pages for details.

       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.

RETURN VALUES

       Zero is returned on success, or a gensio error on failure.

NAME

SYNOPSIS

DESCRIPTION

STRING VALUES FOR WATCHES

RETURN VALUES

SEE ALSO