Lightweight DLNA control point manager. More...

#include <DLNAControlPoint.h>

Public Member Functions
	DLNAControlPoint ()
	Default constructor w/o Notifications.

	DLNAControlPoint (HttpServer &server, int port=80)
	Constructor supporting Notifications.

void	setParseDevice (bool flag)
	Requests the parsing of the device information.

void	setLocalURL (Url url)
	Defines the local url (needed for subscriptions)

void	setSearchRepeatMs (int repeatMs)
	Sets the repeat interval for M-SEARCH requests (define before begin)

void	setReference (void *ref)
	Attach an opaque reference pointer (optional, for caller context)

void	setDeviceIndex (int idx)
	Selects the default device by index.

void	setSubscribeInterval (int repeatSec=3600)
	Activates event notification subscription with repeat interval in seconds.

void	onNotification (std::function< void(void reference, const char sid, const char varName, const char newValue)> cb)
	Register a callback that will be invoked for incoming event notification.

void	setHttpServer (HttpServer &server, int port=80)
	Set HttpServer instance and register the notify handler.

void	onResultNode (std::function< void(const char nodeName, const char text, const char *attributes)> cb)

bool	begin (DLNAHttpRequest &http, IUDPService &udp, const char *searchTarget="ssdp:all", uint32_t minWaitMs=3000, uint32_t maxWaitMs=60000)
	Start discovery by sending M-SEARCH requests and process replies.

bool	subscribeNotifications ()
	Subscribes to event notifications for the selected device.

void	end ()
	Stops the processing and releases the resources.

ActionRequest &	addAction (ActionRequest act)
	Registers a method that will be called.

ActionReply &	executeActions ()
	Executes all registered methods.

bool	loop ()

DLNAServiceInfo &	getService (const char *id)
	Provide addess to the service information.

DLNADeviceInfo &	getDevice ()
	Provides the device information of the actually selected device.

DLNADeviceInfo &	getDevice (int idx)
	Provides the device information by index.

DLNADeviceInfo &	getDevice (DLNAServiceInfo &service)
	Provides the device for a service.

DLNADeviceInfo &	getDevice (Url location)
	Get a device for a Url.

Vector< DLNADeviceInfo > &	getDevices ()

bool	addDevice (DLNADeviceInfo dev)
	Adds a new device.

bool	addDevice (Url url)
	Adds the device from the device xml url if it does not already exist.

void	setActive (bool flag)
	We can activate/deactivate the scheduler.

bool	isActive ()
	Checks if the scheduler is active.

void	setAllowLocalhost (bool flag)
	Defines if localhost devices should be allowed.

ActionReply &	getLastReply ()
	Provides the last reply.

Protected Member Functions
void	attachHttpServer (HttpServer &server)

bool	matches (const char *usn)
	checks if the usn contains the search target

bool	processBye (Str &usn)
	processes a bye-bye message

size_t	createXML (ActionRequest &action)

ActionReply &	postAllActions ()

ActionReply &	postAction (ActionRequest &action)

void	buildActionBody (ActionRequest &action, StrPrint &out)
	Build the SOAP XML request body for the action into `out`

const char *	nullStr (const char str, const char empty="(null)")

const char *	nullStr (Str &str, const char *empty="(null)")

ActionReply &	processActionHttpPost (Url &post_url, StrPrint &requestBody, const char *soapAction)

const char *	getUrl (DLNADeviceInfo &device, const char suffix, const char buffer, int len)

bool	subscribeNotifications (DLNADeviceInfo &device, int timeoutSeconds=1800)
	Subscribe to changes for all device services.

bool	subscribeNotifications (DLNAServiceInfo &service, int timoutSeconds=1800)
	Subscribe to changes for defined device service.

Static Protected Member Functions
static void	notifyHandler (HttpServer server, const char requestPath, HttpRequestHandlerLine *hl)

static bool	handleNotifyByebye (Str &usn)

static bool	isUdnKnown (const char usn_c, DLNADeviceInfo &outDev)

static bool	handleNotifyAlive (NotifyReplyCP &data)

static bool	processDevice (NotifyReplyCP &data)

static bool	processMSearchReply (MSearchReplyCP &data)
	Processes an M-SEARCH HTTP 200 reply and attempts to add the device.

Protected Attributes
Scheduler	scheduler

DLNAHttpRequest *	p_http = nullptr

IUDPService *	p_udp = nullptr

Vector< DLNADeviceInfo >	devices

Vector< ActionRequest >	actions

ActionReply	reply

XMLPrinter	xml

int	default_device_idx = 0

int	msearch_repeat_ms = 10000

uint64_t	subscribe_timeout = 0

int	subscribe_repeat_sec = 3600

bool	is_active = false

bool	is_parse_device = false

DLNADeviceInfo	NO_DEVICE {false}

const char *	search_target

StringRegistry	strings

Url	local_url

bool	allow_localhost = false

HttpServer *	p_http_server = nullptr

int	http_server_port = 0

void *	reference = nullptr

std::function< void(const char nodeName, const char text, const char *attributes)>	result_callback

std::function< void(void reference, const char sid, const char varName, const char newValue)>	event_callback

Detailed Description

Lightweight DLNA control point manager.

This class implements a compact, embeddable DLNA/UPnP control point suitable for small devices and emulators. It provides the core responsibilities a control point needs in order to discover devices, subscribe to service events, and invoke actions on services:

Discover devices using SSDP M-SEARCH and collect device/service descriptions (HTTP GET + XML parsing).
Maintain a list of discovered DLNADevice objects and their DLNAServiceInfo entries.
Subscribe to service event notifications (SUBSCRIBE) and accept incoming NOTIFY requests via an attached HttpServer.
Parse event property-change XML and dispatch callbacks to the application (via onNotification).
Execute SOAP actions on services (builds and posts SOAP XML).

Notes and usage:

To receive HTTP-based event notifications register an HttpServer with setHttpServer() (or construct with a server). The server's request handler will forward NOTIFY bodies to this manager.
Register an application callback with onNotification() to receive parsed property updates. An opaque reference pointer may be stored with setReference() and will be passed back with the callback.
Call begin() to start discovery and loop() frequently (e.g. from the device main loop) to process incoming network events and scheduled tasks.

The class is intentionally small and avoids dynamic STL-heavy constructs so it can run in constrained environments. It is not a full-featured UPnP stack but provides the common features required by many DLNA control point use cases.

Author: Phil Schatzmann

Constructor & Destructor Documentation

◆ DLNAControlPoint() [1/2]

tiny_dlna::DLNAControlPoint::DLNAControlPoint ( )

inline

Default constructor w/o Notifications.

◆ DLNAControlPoint() [2/2]

tiny_dlna::DLNAControlPoint::DLNAControlPoint	(	HttpServer &	server,
		int	port = `80`
	)

inline

Constructor supporting Notifications.

Member Function Documentation

◆ addAction()

ActionRequest & tiny_dlna::DLNAControlPoint::addAction ( ActionRequest act )

inline

Registers a method that will be called.

◆ addDevice() [1/2]

bool tiny_dlna::DLNAControlPoint::addDevice ( DLNADeviceInfo dev )

inline

Adds a new device.

◆ addDevice() [2/2]

bool tiny_dlna::DLNAControlPoint::addDevice ( Url url )

inline

Adds the device from the device xml url if it does not already exist.

◆ attachHttpServer()

void tiny_dlna::DLNAControlPoint::attachHttpServer ( HttpServer & server )

inlineprotected

Attach an HttpServer so the control point can receive HTTP NOTIFY event messages. This registers a handler at the configured local URL path (see local_url) which will extract the SID header and body and call parseAndDispatchEvent() to dispatch property changes.

◆ begin()

bool tiny_dlna::DLNAControlPoint::begin	(	DLNAHttpRequest &	http,
		IUDPService &	udp,
		const char *	searchTarget = `"ssdp:all"`,
		uint32_t	minWaitMs = `3000`,
		uint32_t	maxWaitMs = `60000`
	)

inline

Start discovery by sending M-SEARCH requests and process replies.

searchTarget: the SSDP search target (e.g. "ssdp:all", device/service urn) minWaitMs: minimum time in milliseconds to wait before returning a result (default: 3000 ms) maxWaitMs: maximum time in milliseconds to wait for replies (M-SEARCH window) (default: 60000 ms) Behavior: the function will wait at least minWaitMs and at most maxWaitMs. If a device is discovered after minWaitMs elapsed the function will return early; otherwise it will block until maxWaitMs.

◆ buildActionBody()

void tiny_dlna::DLNAControlPoint::buildActionBody	(	ActionRequest &	action,
		StrPrint &	out
	)

inlineprotected

Build the SOAP XML request body for the action into out

◆ createXML()

size_t tiny_dlna::DLNAControlPoint::createXML ( ActionRequest & action )

inlineprotected

Creates the Action Soap XML request. E.g "<?xml version=\"1.0\"?>\r\n" "<s:Envelope xmlns:s=\"http://schemas.xmlsoap.org/soap/envelope/\"\r\n" "s:encodingStyle=\"http://schemas.xmlsoap.org/soap/encoding/\">\r\n" "<s:Body>\r\n" "<u:SetTarget " "xmlns:u=\"urn:schemas-upnp-org:service:SwitchPower:1\">\r\n" "<newTargetValue>1</newTargetValue>\r\n" "</u:SetTarget>\r\n" "</s:Body>\r\n" "</s:Envelope>\r\n";

◆ end()

void tiny_dlna::DLNAControlPoint::end ( )

inline

Stops the processing and releases the resources.

◆ executeActions()

ActionReply & tiny_dlna::DLNAControlPoint::executeActions ( )

inline

Executes all registered methods.

◆ getDevice() [1/4]

DLNADeviceInfo & tiny_dlna::DLNAControlPoint::getDevice ( )

inline

Provides the device information of the actually selected device.

◆ getDevice() [2/4]

DLNADeviceInfo & tiny_dlna::DLNAControlPoint::getDevice ( DLNAServiceInfo & service )

inline

Provides the device for a service.

◆ getDevice() [3/4]

DLNADeviceInfo & tiny_dlna::DLNAControlPoint::getDevice ( int idx )

inline

Provides the device information by index.

◆ getDevice() [4/4]

DLNADeviceInfo & tiny_dlna::DLNAControlPoint::getDevice ( Url location )

inline

Get a device for a Url.

◆ getDevices()

Vector< DLNADeviceInfo > & tiny_dlna::DLNAControlPoint::getDevices ( )

inline

◆ getLastReply()

ActionReply & tiny_dlna::DLNAControlPoint::getLastReply ( )

inline

Provides the last reply.

◆ getService()

DLNAServiceInfo & tiny_dlna::DLNAControlPoint::getService ( const char * id )

inline

Provide addess to the service information.

◆ getUrl()

const char * tiny_dlna::DLNAControlPoint::getUrl	(	DLNADeviceInfo &	device,
		const char *	suffix,
		const char *	buffer,
		int	len
	)

inlineprotected

◆ handleNotifyAlive()

static bool tiny_dlna::DLNAControlPoint::handleNotifyAlive ( NotifyReplyCP & data )

inlinestaticprotected

◆ handleNotifyByebye()

static bool tiny_dlna::DLNAControlPoint::handleNotifyByebye ( Str & usn )

inlinestaticprotected

Processes a NotifyReplyCP message Note: split into smaller helpers for clarity and testability.

◆ isActive()

bool tiny_dlna::DLNAControlPoint::isActive ( )

inline

Checks if the scheduler is active.

◆ isUdnKnown()

static bool tiny_dlna::DLNAControlPoint::isUdnKnown	(	const char *	usn_c,
		DLNADeviceInfo *&	outDev
	)

inlinestaticprotected

Returns true and sets outDev if a device with the UDN part of usn_c is already present in the device list.

◆ loop()

bool tiny_dlna::DLNAControlPoint::loop ( )

inline

call this method in the Arduino loop as often as possible: the processes all replys

◆ matches()

bool tiny_dlna::DLNAControlPoint::matches ( const char * usn )

inlineprotected

checks if the usn contains the search target

◆ notifyHandler()

static void tiny_dlna::DLNAControlPoint::notifyHandler	(	HttpServer *	server,
		const char *	requestPath,
		HttpRequestHandlerLine *	hl
	)

inlinestaticprotected

Static HTTP handler for incoming NOTIFY event callbacks. The HttpServer will pass the control point instance as context[0] so we can retrieve the instance and forward the event to parseAndDispatchEvent().

Parse body

Activate callback

◆ nullStr() [1/2]

const char * tiny_dlna::DLNAControlPoint::nullStr	(	const char *	str,
		const char *	empty = `"(null)"`
	)

inlineprotected

◆ nullStr() [2/2]

const char * tiny_dlna::DLNAControlPoint::nullStr	(	Str &	str,
		const char *	empty = `"(null)"`
	)

inlineprotected

◆ onNotification()

void tiny_dlna::DLNAControlPoint::onNotification ( std::function< void(void *reference, const char *sid, const char *varName, const char *newValue)> cb )

inline

Register a callback that will be invoked for incoming event notification.

◆ onResultNode()

void tiny_dlna::DLNAControlPoint::onResultNode ( std::function< void(const char *nodeName, const char *text, const char *attributes)> cb )

inline

Register a callback that will be invoked when parsing SOAP/Action results Signature: void(const char* nodeName, const char* text, const char* attributes)

◆ postAction()

ActionReply & tiny_dlna::DLNAControlPoint::postAction ( ActionRequest & action )

inlineprotected

◆ postAllActions()

ActionReply & tiny_dlna::DLNAControlPoint::postAllActions ( )

inlineprotected

◆ processActionHttpPost()

ActionReply & tiny_dlna::DLNAControlPoint::processActionHttpPost	(	Url &	post_url,
		StrPrint &	requestBody,
		const char *	soapAction
	)

inlineprotected

response body is written into responseOut (an XMLParserPrint). Returns the HTTP rc.

◆ processBye()

bool tiny_dlna::DLNAControlPoint::processBye ( Str & usn )

inlineprotected

processes a bye-bye message

◆ processDevice()

static bool tiny_dlna::DLNAControlPoint::processDevice ( NotifyReplyCP & data )

inlinestaticprotected

◆ processMSearchReply()

static bool tiny_dlna::DLNAControlPoint::processMSearchReply ( MSearchReplyCP & data )

inlinestaticprotected

Processes an M-SEARCH HTTP 200 reply and attempts to add the device.

◆ setActive()

void tiny_dlna::DLNAControlPoint::setActive ( bool flag )

inline

We can activate/deactivate the scheduler.

◆ setAllowLocalhost()

void tiny_dlna::DLNAControlPoint::setAllowLocalhost ( bool flag )

inline

Defines if localhost devices should be allowed.

◆ setDeviceIndex()

void tiny_dlna::DLNAControlPoint::setDeviceIndex ( int idx )

inline

Selects the default device by index.

◆ setHttpServer()

void tiny_dlna::DLNAControlPoint::setHttpServer	(	HttpServer &	server,
		int	port = `80`
	)

inline

Set HttpServer instance and register the notify handler.

◆ setLocalURL()

void tiny_dlna::DLNAControlPoint::setLocalURL ( Url url )

inline

Defines the local url (needed for subscriptions)

◆ setParseDevice()

void tiny_dlna::DLNAControlPoint::setParseDevice ( bool flag )

inline

Requests the parsing of the device information.

◆ setReference()

void tiny_dlna::DLNAControlPoint::setReference ( void * ref )

inline

Attach an opaque reference pointer (optional, for caller context)

◆ setSearchRepeatMs()

void tiny_dlna::DLNAControlPoint::setSearchRepeatMs ( int repeatMs )

inline

Sets the repeat interval for M-SEARCH requests (define before begin)

◆ setSubscribeInterval()

void tiny_dlna::DLNAControlPoint::setSubscribeInterval ( int repeatSec = 3600 )

inline

Activates event notification subscription with repeat interval in seconds.

◆ subscribeNotifications() [1/3]

bool tiny_dlna::DLNAControlPoint::subscribeNotifications ( )

inline

Subscribes to event notifications for the selected device.

◆ subscribeNotifications() [2/3]

bool tiny_dlna::DLNAControlPoint::subscribeNotifications	(	DLNADeviceInfo &	device,
		int	timeoutSeconds = `1800`
	)

inlineprotected

Subscribe to changes for all device services.

◆ subscribeNotifications() [3/3]

bool tiny_dlna::DLNAControlPoint::subscribeNotifications	(	DLNAServiceInfo &	service,
		int	timoutSeconds = `1800`
	)

inlineprotected

Subscribe to changes for defined device service.

Member Data Documentation

◆ actions

Vector<ActionRequest> tiny_dlna::DLNAControlPoint::actions

protected

◆ allow_localhost

bool tiny_dlna::DLNAControlPoint::allow_localhost = false

protected

◆ default_device_idx

int tiny_dlna::DLNAControlPoint::default_device_idx = 0

protected

◆ devices

Vector<DLNADeviceInfo> tiny_dlna::DLNAControlPoint::devices

protected

◆ event_callback

std::function<void(void* reference, const char* sid, const char* varName, const char* newValue)> tiny_dlna::DLNAControlPoint::event_callback

protected

◆ http_server_port

int tiny_dlna::DLNAControlPoint::http_server_port = 0

protected

◆ is_active

bool tiny_dlna::DLNAControlPoint::is_active = false

protected

◆ is_parse_device

bool tiny_dlna::DLNAControlPoint::is_parse_device = false

protected

◆ local_url

Url tiny_dlna::DLNAControlPoint::local_url

protected

◆ msearch_repeat_ms

int tiny_dlna::DLNAControlPoint::msearch_repeat_ms = 10000

protected

◆ NO_DEVICE

DLNADeviceInfo tiny_dlna::DLNAControlPoint::NO_DEVICE {false}

protected

◆ p_http

DLNAHttpRequest* tiny_dlna::DLNAControlPoint::p_http = nullptr

protected

◆ p_http_server

HttpServer* tiny_dlna::DLNAControlPoint::p_http_server = nullptr

protected

◆ p_udp

IUDPService* tiny_dlna::DLNAControlPoint::p_udp = nullptr

protected

◆ reference

void* tiny_dlna::DLNAControlPoint::reference = nullptr

protected

◆ reply

ActionReply tiny_dlna::DLNAControlPoint::reply

protected

◆ result_callback

std::function<void(const char* nodeName, const char* text, const char* attributes)> tiny_dlna::DLNAControlPoint::result_callback

protected

◆ scheduler

Scheduler tiny_dlna::DLNAControlPoint::scheduler

protected

◆ search_target

const char* tiny_dlna::DLNAControlPoint::search_target

protected

◆ strings

StringRegistry tiny_dlna::DLNAControlPoint::strings

protected

◆ subscribe_repeat_sec

int tiny_dlna::DLNAControlPoint::subscribe_repeat_sec = 3600

protected

◆ subscribe_timeout

uint64_t tiny_dlna::DLNAControlPoint::subscribe_timeout = 0

protected

◆ xml

XMLPrinter tiny_dlna::DLNAControlPoint::xml

protected

The documentation for this class was generated from the following file:

src/dlna/DLNAControlPoint.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DLNAControlPoint() [1/2]

◆ DLNAControlPoint() [2/2]

Member Function Documentation

◆ addAction()

◆ addDevice() [1/2]

◆ addDevice() [2/2]

◆ attachHttpServer()

◆ begin()

◆ buildActionBody()

◆ createXML()

◆ end()

◆ executeActions()

◆ getDevice() [1/4]

◆ getDevice() [2/4]

◆ getDevice() [3/4]

◆ getDevice() [4/4]

◆ getDevices()

◆ getLastReply()

◆ getService()

◆ getUrl()

◆ handleNotifyAlive()

◆ handleNotifyByebye()

◆ isActive()

◆ isUdnKnown()

◆ loop()

◆ matches()

◆ notifyHandler()

◆ nullStr() [1/2]

◆ nullStr() [2/2]

◆ onNotification()

◆ onResultNode()

◆ postAction()

◆ postAllActions()

◆ processActionHttpPost()

◆ processBye()

◆ processDevice()

◆ processMSearchReply()

◆ setActive()

◆ setAllowLocalhost()

◆ setDeviceIndex()

◆ setHttpServer()

◆ setLocalURL()

◆ setParseDevice()

◆ setReference()

◆ setSearchRepeatMs()

◆ setSubscribeInterval()

◆ subscribeNotifications() [1/3]

◆ subscribeNotifications() [2/3]

◆ subscribeNotifications() [3/3]

Member Data Documentation

◆ actions

◆ allow_localhost

◆ default_device_idx

◆ devices

◆ event_callback

◆ http_server_port

◆ is_active

◆ is_parse_device

◆ local_url

◆ msearch_repeat_ms

◆ NO_DEVICE

◆ p_http

◆ p_http_server

◆ p_udp

◆ reference

◆ reply

◆ result_callback

◆ scheduler

◆ search_target

◆ strings

◆ subscribe_repeat_sec

◆ subscribe_timeout

◆ xml