home | help 
gensio_mdns(3)		    Library Functions Manual		  gensio_mdns(3)

NAME
     gensio_alloc_mdns,    gensio_free_mdns,	gensio_mdns_add_service,    gen-
     sio_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
     These  functions  and type deal with mDNS (Multicast DNS) discovery of ser-
     vices 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 capa-
     bilities.

     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 inter-
     face 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_service2.	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.

     gensio_mdns_add_service2  takes a callback, it will be called when the ser-
     vice has been registered, and possible 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, it will 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.

     GENSIO_MDNS_SERVICE_ERROR
	    An error occurred as part of service registration.

     There is a gensio_mdns_add_service function for backwards compatibility, it
     is equivalent to calling gensio_mdns_add_service2	with  a  NULL  callback.
     Don't use it in new code.

     To   find	 services   on	 the   network,   you  add  a  watch  with  gen-
     sio_mdns_add_watch.  Any service that matches your query will  be	reported
     with  the	callback  functions and all fields will be provided in the call-
     back.  Once you are  done	with  a  watch,  you  may  call  gensio_mdns_re-
     move_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.

     Some MDNS libraries do not support an NULL type for the watch, and some do.
     For  portable code, always specify the watch.  If the library does not sup-
     port 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 as gone away.

     GENSIO_MDNS_WATCH_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 re-
	    ported  in	the  future,  but those will have been dynamically added
	    later.

     In the watch callback, you must make copies of  all  the  strings	and  ad-
     dresses passed to you to keep them.  Their continued existence is not guar-
     anteed.

     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 regu-
     lar  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  '@',
     the  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 compari-
     son 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.

SEE ALSO
     gensio_err(3), gensio_os_funcs(3), regex(7), glob(7)

				   15 Oct 2020			  gensio_mdns(3)
home | help