cyg_mdns_discovery_callback_register

Name

cyg_mdns_discovery_callback_register -- Register DNS-SD response callback

Synopsis

#include <mdns.h>

cyg_mdns_discovery_context *cyg_mdns_discovery_callback_register(const cyg_uint8 * const *name, cyg_mdns_discovery_callback_fn fn, void *private);

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:

Table 175-1. state flags

Flag Description
MDNS_DISCOVERY_CB_NOMORE Set to indicate no more data available for the active mDNS response being processed. When this flag is set NO actual Resource Record is actually being supplied. This call allows application that require, for example, a U/I update to be notified that a complete response has been processed and no more records are available for the callback. It may be used by a callback that has been caching information whilst constructing a “complete” image of a service to pass the data gathered to another client component.
MDNS_DISCOVERY_CB_ADDITIONAL Set when the callback is being passed an Additional record, and not a direct Answer record.
MDNS_DISCOVERY_CB_FLUSH Informational flag indicating whether this is a “unique” response and any cache should be flushed. See RFC 6762 section 10.2 for more information.

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.

2017-02-09
Documentation license for this page: eCosPro License