Description

This function is used to attach a callback handler function to be called when (by default) ANSWER, and optionally ADDITIONAL, responses matching the supplied name are received. The cyg_mdns_discovery_callback_flags() function can be used to update the control flags from the default ANSWERS-only configuration once the callback has been registered.

	Note
	This function is not available if the system is not configured with CYGIMP_NET_MDNS_DNSSD enabled.

The name is an encoded string-table specifying the name that will be matched against mDNS responses when deciding if the registered callback function fn should be called. For example to match “_http._tcp.local”:

const cyg_uint8 label_http[] = { 0x05,'_','h','t','t','p' };
const cyg_uint8 * const services_http[] = { label_http, cyg_mdns_label_tcp, cyg_mdns_label_local, NULL };

The private value is used to pass data (if needed) to the callback function, and is never interpreted by the callback API.

The <mdns.h> header defines the function prototype for the callback fn function:

typedef void (*cyg_mdns_discovery_callback_fn)( void *private, cyg_uint32 state, const cyg_mdns_resource *phrr,
                                                struct pbuf *p, cyg_uint16 offname, cyg_uint16 offdata );

The private is the same value as supplied when registering the callback function, and is used by the client to hold any state needed to implement any interaction between the DSR-alike callback function and the application foreground client code.

The state parameter is a bitmask of flags and are used by the callback to determine what processing is required. The currently defined flags are:

The phrr pointer references a structure containing, primarily, the type of Resource Record that the callback is being passed, and the TTL (Time-To-Live) of the record, where a TTL value of zero indicates a service is no longer available.

typedef struct cyg_mdns_resource {
    cyg_uint16 type;
    cyg_uint16 class;
    cyg_uint32 ttl;
    cyg_uint16 rdlength;
} cyg_mdns_resource;

The p pointer references the lwIP packet buffer containing the Resource Record entry to be processed by the callback, with the offname and offdata indices referencing, respectively, the offsets to the resource name and Resource Record type (phrr->type) specific data if relevant. The callback should NEVER modify the referenced lwIP packet buffer, and should use the available Support API routines to extract the (possibly) compressed data from the lwIP packet buffer for local processing/caching as required. This is because the packet buffer may be shared by multiple Resource Record responses, and other callbacks may also be executed as a result of a single mDNS response as well as the mDNS Responder requirements.

By default only ANSWER records are passed through, but if needed the cyg_mdns_discovery_callback_flags() function can be used to manipulate the control flags used to decide which response records are passed to the callback.

When the callback is no longer required it can be detached by using the cyg_mdns_discovery_callback_unregister() function. It is the responsibility of the controlling application to ensure that any resources owned by the callback routine are in a safe state prior to unregistering the callback.

	Note
	The callback function registered should NEVER block and should be treated like a DSR function. The function is called within the context of the mDNS lwIP handler as the result of low-level mDNS packet processing.

Return value

A non-NULL pointer to an abstract handle used for subsequent interaction with the successfully registered callback, or NULL on failure. For example, the call may fail if all the available callback slots are currently in use.

	Note
	The number of concurrently registered callbacks is controlled by the CYGNUM_MDNS_DNSSD_NUM_CALLBACKS configuration option.