Description

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 fn is NULL 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 with success set to true 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 the cyg_mdns_sethostname() on startup will minimise subsequent delays claiming a name.

	Note
	The lifetime of the UTF-8 hostname pointer 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.

If success is 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 a 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.