M2MB MDNS

This section describes the M2MB APIs to perform various multi-cast Domain Name System(mDNS) operations. More...

#define	M2MB_MDNS_MAX_TXT_RECORDS   10
enum	M2MB_MDNS_CONF_ID {   M2MB_MDNS_CONF_INVALID = 0,   M2MB_MDNS_CONF_SET_UPDATE_TXT = 1 }
	MDNS SET Configuration enumeration. More...
typedef struct M2MB_MDNS_TXT_RECORD	M2MB_MDNS_TXT_RECORD_T
	Structure for updating or adding a new text record. More...
typedef struct M2MB_MDNS_SVC_REG_STATUS	M2MB_MDNS_SVC_REG_STATUS_T
	Structure for registration status information. More...
typedef struct M2MB_MDNS_SVC_INFO	M2MB_MDNS_SVC_INFO_T
	Structure for registering the new service or advertising a service. More...
typedef struct M2MB_MDNS_TXT	M2MB_MDNS_TXT_T
typedef UINT32(*	M2MB_MDNS_CB_T) (VOID *arg)
	mDNS application callback. More...
typedef enum M2MB_MDNS_CONF_ID	M2MB_MDNS_CONF_ID_E
	MDNS SET Configuration enumeration. More...
typedef struct M2MB_MDNS_INIT_PARAMS	M2MB_MDNS_INIT_PARAMS_T
	MDNS initialization parameters. More...
typedef void(*	MDNS_NAME_RESULT_CB_T) (struct netif *netif, UINT8 result)
void	m2mb_mdns_resp_register_name_result_cb (MDNS_NAME_RESULT_CB_T cb)
M2MB_STATUS_T	m2mb_mdns_init (HANDLE *handle, M2MB_MDNS_INIT_PARAMS_T *init_params)
	m2mb_mdns_init is called to Start the mDNS service. More...
M2MB_STATUS_T	m2mb_mdns_set_hostname (HANDLE handle, const CHAR *host_name)
	Sets the hostname for mDNS. More...
M2MB_STATUS_T	m2mb_mdns_register_service (HANDLE handle, M2MB_MDNS_SVC_INFO_T *svc_info, UINT8 blocking)
	Registers a new service with mDNS. More...
M2MB_STATUS_T	m2mb_mdns_unregister_service (HANDLE handle, const CHAR *svc_name)
	unregisters a service with mDNS. More...
M2MB_STATUS_T	m2mb_mdns_set_cfg (HANDLE handle, M2MB_MDNS_CONF_ID_E conf_id, M2MB_MDNS_CONF_PARAMS_T *conf_params)
	SET the MDNS configuration parameters. More...
M2MB_STATUS_T	m2mb_mdns_deinit (HANDLE handle)
	m2mb_mdns_deinit API de-initializes the mDNS module. More...

Detailed Description

This section describes the M2MB APIs to perform various multi-cast Domain Name System(mDNS) operations.

mDNS

The mDNS module provides APIs to register service which can be discovered in the local network by other device using the mDNS protocol. User must call the below sequence of APIs in this module.

• User must call m2mb_mdns_init to initialize the mDNS module. It allocates resource for the mDNS module.
• To register the host name, user must call m2mb_mdns_set_hostname.
• Since mDNS uses multicast group (224.0.0.251), it registers to this multicast group using IGMP protocol.
• It tries to register the hostname and once done; it calls user callback. If it finds a collision in host name, it indicates failure.
• To add services user must call m2mb_mdns_service_register and to deregister the service it should call m2mb_mdns_unregister_service.
• To add/modify the text record for a service user can call m2mb_mdns_set_cfg API.
• User can de-initialize the mDNS module by calling m2mb_mdns_deinit API.

Macro Definition Documentation

M2MB_MDNS_MAX_TXT_RECORDS

#define M2MB_MDNS_MAX_TXT_RECORDS   10

Maximum text records in a service information structure.

Definition at line 67 of file m2mb_mdns.h.

Typedef Documentation

M2MB_MDNS_CB_T

typedef UINT32(* M2MB_MDNS_CB_T) (VOID *arg)

mDNS application callback.

Callback to be registered when the mDNS service is started. The callback will be invoked for all mDNS commands (Nonblocking mode) and for all asynchronous responses from mDNS.

UINT32 appln_mdns_cb( VOID *pCtx )
{
    M2MB_MDNS_SVC_REG_STATUS_T * reg_status_info = (M2MB_MDNS_SVC_REG_STATUS_T *)pCtx;
    ...
    if(reg_status_info->status < 0)
        // MDNS ERROR 
    else
        // SUCCESSFULL registration reg_status_info->svc_Name 
    ...
}

int main()
{
    INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_MDNS_INIT_PARAMS_T init_params = {0};

    init_params.device_id = 1; // M2MB_WLAN_MODE_STA_UP
    init_params.ip_version = M2MB_SOCKET_BSD_AF_INET;

    init_params.app_cb = appln_mdns_cb;
    init_params.blocking = FALSE;
    
    status = m2mb_mdns_init( &handle, &init_params );
    if( status == M2MB_ERROR )
    {
            return M2MB_ERROR;
    }

    if( m2mb_mdns_set_hostname("Telit Host Name") != M2MB_OK )
      return M2MB_ERROR;

    svc_info.instance = "_MyDevice";
    svc_info.type     = "_http._tcp.local";
    svc_info.port     = 80;
    svc_info.txt[0]   =  "TEST:100";
    svc_info.txt[1]   = NULL;

    return m2mb_mdns_register_service( &svc_info, 0 );     
}

Definition at line 193 of file m2mb_mdns.h.

M2MB_MDNS_CONF_ID_E

typedef enum M2MB_MDNS_CONF_ID M2MB_MDNS_CONF_ID_E

MDNS SET Configuration enumeration.

This enum defines macros for various SET Configuration for MDNS module.

M2MB_MDNS_INIT_PARAMS_T

typedef struct M2MB_MDNS_INIT_PARAMS M2MB_MDNS_INIT_PARAMS_T

MDNS initialization parameters.

Contains information needed to initialize the MDNS module, such as user callback, user context and poll interval.

M2MB_MDNS_SVC_INFO_T

typedef struct M2MB_MDNS_SVC_INFO M2MB_MDNS_SVC_INFO_T

Structure for registering the new service or advertising a service.

This structure contains information related to an mdns service.

M2MB_MDNS_SVC_REG_STATUS_T

typedef struct M2MB_MDNS_SVC_REG_STATUS M2MB_MDNS_SVC_REG_STATUS_T

Structure for registration status information.

This structure contains the name of the service/hostname and status code to denote if the registration is successful or to report if there is a subsequent conflict of hostname/servicename. An application callback will receive this asynchronously in the following cases:

• Subsequent service/hostname conflict, after a service or hostname was successfully registered
• If Nonblocking mode is used for an operation.

M2MB_MDNS_TXT_RECORD_T

typedef struct M2MB_MDNS_TXT_RECORD M2MB_MDNS_TXT_RECORD_T

Structure for updating or adding a new text record.

This structure contains the text record in the format key=value and a service name that is already registered. If the key in the text record already exists for the given service name, the value is updated with the given value, otherwise, the text record is added as a new text record.

M2MB_MDNS_TXT_T

typedef struct M2MB_MDNS_TXT M2MB_MDNS_TXT_T

MDNS_NAME_RESULT_CB_T

typedef void(* MDNS_NAME_RESULT_CB_T) (struct netif *netif, UINT8 result)

Callback function to let application know the result of probing network for name uniqueness, called with result MDNS_PROBING_SUCCESSFUL if no other node claimed use for the name for the netif or a service and is safe to use, or MDNS_PROBING_CONFLICT if another node is already using it and mdns is disabled on this interface

Definition at line 247 of file m2mb_mdns.h.

Enumeration Type Documentation

M2MB_MDNS_CONF_ID

enum M2MB_MDNS_CONF_ID

MDNS SET Configuration enumeration.

This enum defines macros for various SET Configuration for MDNS module.

Enumerator
M2MB_MDNS_CONF_INVALID
M2MB_MDNS_CONF_SET_UPDATE_TXT	ONLY SET CONF, update the text record, maximum M2MB_MDNS_MAX_TXT_RECORDS supported

Definition at line 202 of file m2mb_mdns.h.

Function Documentation

m2mb_mdns_deinit()

M2MB_STATUS_T m2mb_mdns_deinit

(

HANDLE

handle

)

m2mb_mdns_deinit API de-initializes the mDNS module.

m2mb_mdns_deinit API de-initializes the mDNS module.

Parameters

[in]

handle

Specifies the pointer to the context handle initialized by m2mb_mdns_init API.

Returns

M2MB_OK on success, or an code on error.

Note

m2mb_mdns_stop();

UINT32 m2mb_profile_mdns_cb( VOID *pCtx )
{
    ...
}

int main()
{
    INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_MDNS_INIT_PARAMS_T init_params = {0};

    init_params.device_id = 1; // M2MB_WLAN_MODE_STA_UP
    init_params.ip_version = M2MB_SOCKET_BSD_AF_INET;


    init_params.app_cb = m2mb_profile_mdns_cb;
    init_params.blocking = TRUE;

    status = m2mb_mdns_init( &handle, &init_params );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...
    ...
    ...

    status = m2mb_mdns_deinit( &handle );
    if( status == M2MB_OK )
    {
        return M2MB_OK;
    }
    else
    {
      return M2MB_ERROR;
    }
}  

m2mb_mdns_init()

M2MB_STATUS_T m2mb_mdns_init	(	HANDLE *	handle,
		M2MB_MDNS_INIT_PARAMS_T *	init_params
	)

m2mb_mdns_init is called to Start the mDNS service.

m2mb_mdns_init starts the mDNS service

Parameters

[in]	handle	Specifies the pointer to the context handle that can be used by other MDNS APIs.
[in]	init_params	Pointer to the initialization parameters required for MDNS module initialization.

Returns

M2MB_OK on success, or an code on error.

Note

This API has to be called before any other DNS server API is called.

m2mb_mdns_init( &handle, &init_params );

UINT32 m2mb_profile_mdns_cb( VOID *pCtx )
{
    ...
}

int main()
{
    INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_MDNS_INIT_PARAMS_T init_params = {0};

    init_params.device_id = 1; // M2MB_WLAN_MODE_STA_UP
    init_params.ip_version = M2MB_SOCKET_BSD_AF_INET;


    init_params.app_cb = m2mb_profile_mdns_cb;
    init_params.blocking = TRUE;

    status = m2mb_mdns_init( &handle, &init_params );
    if( status == M2MB_OK )
    {
        return M2MB_OK;
    }
    else
    {
            return M2MB_ERROR;
    }
}

m2mb_mdns_register_service()

M2MB_STATUS_T m2mb_mdns_register_service	(	HANDLE	handle,
		M2MB_MDNS_SVC_INFO_T *	svc_info,
		UINT8	blocking
	)

Registers a new service with mDNS.

m2mb_mdns_register_service registers a service with the mDNS module

Parameters

[in]	handle	Specifies the pointer to the context handle initialized by m2mb_mdns_init API.
[in]	svc_info	Service information, such as name, type, port, txt records, etc.
[in]	blocking	Flag fLAG to indicate if the service registration is blocking or nonblocking. If the flag = 1, service registration will block until complete (success or failure). If the flag = 0, service registration will be nonblocking and will invoke the app callback to return the result of the operation.

Returns

M2MB_OK on success, or an code on error.

Note

m2mb_mdns_register_service( &svc_info, 0 );

UINT32 m2mb_profile_mdns_cb( VOID *pCtx )
{
    ...
}

int main()
{
    INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_MDNS_INIT_PARAMS_T init_params = {0};

    init_params.device_id = 1; // M2MB_WLAN_MODE_STA_UP
    init_params.ip_version = M2MB_SOCKET_BSD_AF_INET;


    init_params.app_cb = m2mb_profile_mdns_cb;
    init_params.blocking = TRUE;
    
    status = m2mb_mdns_init( &handle, &init_params );
    if( status == M2MB_ERROR )
    {
            return M2MB_ERROR;
    }

    if( m2mb_mdns_set_hostname("Telit Host Name") != M2MB_OK )
      return M2MB_ERROR;

    svc_info.instance = "_MyDevice";
    svc_info.type     = "_http._tcp.local";
    svc_info.port     = 80;
    svc_info.txt[0]   = "Val=100";

    return m2mb_mdns_register_service( &svc_info, 0 );          
}  

m2mb_mdns_resp_register_name_result_cb()

void m2mb_mdns_resp_register_name_result_cb

(

MDNS_NAME_RESULT_CB_T

cb

)

m2mb_mdns_set_cfg()

M2MB_STATUS_T m2mb_mdns_set_cfg	(	HANDLE	handle,
		M2MB_MDNS_CONF_ID_E	conf_id,
		M2MB_MDNS_CONF_PARAMS_T *	conf_params
	)

SET the MDNS configuration parameters.

This API is called to configure the MDNS module based on the conf IDs.

Parameters

[in]	handle	Specifies the pointer to the context handle initialized by m2mb_mdns_init API.
[in]	conf_id	SET configuration ID form enum M2MB_MDNS_CONF_ID_E.
[in]	conf_params	configuration params to be passed according to the configuration to be done.

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure.

Note

This API has to be called after m2mb_mdns_init API is called. Example

UINT32 m2mb_profile_mdns_cb( VOID *pCtx )
{
    ...
}

int main()
{
    INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_MDNS_INIT_PARAMS_T init_params = {0};

    init_params.device_id = 1; // M2MB_WLAN_MODE_STA_UP
    init_params.ip_version = M2MB_SOCKET_BSD_AF_INET;


    init_params.app_cb = m2mb_profile_mdns_cb;
    init_params.blocking = TRUE;
    
    status = m2mb_mdns_init( &handle, &init_params );
    if( status == M2MB_ERROR )
    {
            return M2MB_ERROR;
    }

    //To add the hostname
    status = m2mb_mdns_set_hostname( handle, "Telit Host Name" );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    //To register the service
    M2MB_MDNS_SVC_INFO_T svc_info = { 0 };    

    svc_info.instance = "_MyDevice";
    svc_info.type     = "_http._tcp.local";
    svc_info.port     = 80;
    svc_info.txt[0]   = "VAL1=1200";

    status = m2mb_mdns_register_service(handle, &svc_info, 0)
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...

    M2MB_MDNS_CONF_PARAMS_T mdns_conf = {0};
    M2MB_MDNS_TXT_T txt_update  = {0};
    txt_update.svc_Name = "_MyDevice";
    txt_update.txt[0]   = "VAL1=1234";
    mdns_conf.txt_update = &txt_update;
    status = m2mb_mdns_set_cfg( handle, M2MB_MDNS_CONF_SET_UPDATE_TXT, &mdns_conf );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...

}  

m2mb_mdns_set_hostname()

M2MB_STATUS_T m2mb_mdns_set_hostname	(	HANDLE	handle,
		const CHAR *	host_name
	)

Sets the hostname for mDNS.

m2mb_mdns_set_hostname sets the mDNS hostname

Parameters

[in]	handle	Specifies the pointer to the context handle initialized by m2mb_mdns_init API.
[in]	host_name	Hostname to be set for mDNS. This is the host-name that Will be used by querier to query for an IP address or a record.

Returns

M2MB_OK on success, or an code on error.

Note

m2mb_mdns_set_hostname("Telit Host Name");

UINT32 m2mb_profile_mdns_cb( VOID *pCtx )
{
    ...
}

int main()
{
     INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_MDNS_INIT_PARAMS_T init_params = {0};

    init_params.device_id = 1; // M2MB_WLAN_MODE_STA_UP
    init_params.ip_version = M2MB_SOCKET_BSD_AF_INET;


    init_params.app_cb = m2mb_profile_mdns_cb;
    init_params.blocking = TRUE;
    
    status = m2mb_mdns_init( &handle, &init_params );
    if( status == M2MB_ERROR )
    {
            return M2MB_ERROR;
    }

    return m2mb_mdns_set_hostname("Telit Host Name");
}  

m2mb_mdns_unregister_service()

M2MB_STATUS_T m2mb_mdns_unregister_service	(	HANDLE	handle,
		const CHAR *	svc_name
	)

unregisters a service with mDNS.

m2mb_mdns_unregister_service unregisters a service with the mDNS module

Parameters

[in]	handle	Specifies the pointer to the context handle initialized by m2mb_mdns_init API.
[in]	svc_name	Name of the service to be unregistered.

Returns

M2MB_OK on success, or an code on error.

Note

m2mb_mdns_unregister_service( "_MyDevice._http._tcp.local" );

UINT32 m2mb_profile_mdns_cb( VOID *pCtx )
{
    ...
}

int main()
{
    INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_MDNS_INIT_PARAMS_T init_params = {0};

    init_params.device_id = 1; // M2MB_WLAN_MODE_STA_UP
    init_params.ip_version = M2MB_SOCKET_BSD_AF_INET;


    init_params.app_cb = m2mb_profile_mdns_cb;
    init_params.blocking = TRUE;
    
    status = m2mb_mdns_init( &handle, &init_params );
    if( status == M2MB_ERROR )
    {
            return M2MB_ERROR;
    }

    if( m2mb_mdns_set_hostname("Telit Host Name") != M2MB_OK )
      return M2MB_ERROR;

    svc_info.instance = "_MyDevice";
    svc_info.type     = "_http._tcp.local";
    svc_info.port     = 80;
    svc_info.txt[0]   = "Testing Text";

    if( m2mb_mdns_register_service( &svc_info, 0 ) != M2MB_OK )
      return M2MB_ERROR;

    ...

    return m2mb_mdns_unregister_service( "_MyDevice._http._tcp.local" );
}