This function is used to attach a hostname callback handler function. By default the mDNS sub-system provides a callback handler which attempts to acquire a unique hostname via monotonically increasing a suffix appended to the base hostname value, and automatically trying to claim the amended hostname. e.g. “ecospro” -> “ecospro-1”, “ecospro-2”, ... “ecospro-999”, ... etc. The application can over-ride this default behaviour by registering an alternative handler function using this API.
The DNS-SD standard Appendix D “Choice of Factory-Default Names” recommends that names are user-friendly, instead of, for example, having something like the 24-bit (non-OUI) MAC address appended. This however means that when a device is first connected to a network containing multiple similarly CDL configured devices then it can take some time to negotiate a unique name. It is the responsibility of the application, using whatever persistant storage schemes it has access to, to ideally store any claimed unique name for subsequent restarts of the device.
If the passed
then the code reverts to the default mDNS callback handler.
typedef void (*cyg_mdns_hostname_callback_fn)(void *private,cyg_bool success,const cyg_uint8 *hostname,cyg_uint8 len);
The callback function is executed from the main lwIP networking thread and should be implemented like an eCos DSR and must NEVER block, and should run for as little time as possible (for example by waking other threads to perform lengthier tasks).
The hostname callback function is called
success set to
when the name given has been successfully claimed. At this point an
application that has provided its own callback handler can, if
desired, record the new name in its persistent storage. The ability
for the application to track the last allocated name over reboots, and
to use a stored name with a call to
cyg_mdns_sethostname() on startup will
minimise subsequent delays claiming a name.
Note: The lifetime of the UTF-8
hostnamepointer is for the active call to the callback function only, and if required for later application use the contents should be copied into a suitable thread-safe buffer accordingly.
false then the
callback indicates that the given
hostname is not valid
and an alternative name should be requested (via another call to
cyg_mdns_sethostname() from a different thread as
appropriate). NOTE: The callback handler may be called
at any point whilst registered if the hostname is no
longer valid (e.g. due to a device appearing on the network and claiming the
hostname that was being used). If the callback is no longer required it should
be released by attaching a new callback, or by passing NULL for the default
handler to be re-instated. The callback function is executed similarly to an
eCos DSR and is limited in the operations it can perform and must never
block. If higher level processing is required by an application due to
hostname conflict then suitable eCos primitives
should be used to notify such code.
Note: The callback is implemented as described above (instead of, for example, returning an alternative name to its caller) so that the DSR-like nature of the function is made clear, and that any slow operations should (and can) be performed by higher application layers as needed. It is envisaged that application specific hostname conflict handlers will signal a controlling thread, which when re-scheduled will subsequently call
cyg_mdns_sethostname()with the next name to be tried.