Manages UPnP event subscriptions and queued notifications for a DLNA device. More...

#include <SubscriptionMgrDevice.h>

Inheritance diagram for tiny_dlna::SubscriptionMgrDevice< ClientType >:

Public Member Functions
	SubscriptionMgrDevice ()=default
	Construct a new Subscription Manager.

	~SubscriptionMgrDevice ()
	Destroy the Subscription Manager.

Str	subscribe (DLNAServiceInfo &service, const char callbackUrl, const char sid=nullptr, uint32_t timeoutSec=1800) override
	Add or renew a subscription for a service.

bool	unsubscribe (DLNAServiceInfo &service, const char *sid) override
	Remove a subscription identified by SID.

void	addChange (DLNAServiceInfo &service, std::function< size_t(Print &, void )> changeWriter, void ref) override
	Enqueue a state-variable change for delivery.

int	publish () override
	Deliver queued notifications.

size_t	subscriptionsCount () override
	Number of active subscriptions.

size_t	pendingCount () override
	Number of queued pending notifications.

void	setSubscriptionsActive (bool flag) override
	Enable or disable subscription delivery.

void	end () override
	Convenience method to disable subscriptions at the end of the lifecycle.

bool	isSubscriptionsActive () override
	Query whether subscription delivery is active.

Protected Member Functions
void	removeExpired ()
	Remove expired subscriptions.

Str	renewSubscription (DLNAServiceInfo &service, const char sid, const char callbackUrl, uint32_t timeoutSec)
	Try to renew an existing subscription identified by SID for the given service. If successful the subscription's timeout/expiry (and optionally callback URL) are updated and the renewed SID is returned. If no matching subscription exists an empty Str is returned.

void	clear ()
	Clear all subscriptions and pending notifications.

bool	processSubscribeRequest (IHttpServer &server, DLNAServiceInfo &service) override
	Handle SUBSCRIBE request including HTTP response.

bool	processUnsubscribeRequest (IHttpServer &server, DLNAServiceInfo &service) override
	Handle UNSUBSCRIBE request including HTTP response.

Static Protected Member Functions
static size_t	createXML (Print &out, void *ref)
	Generate the propertyset XML for a single variable and write it to the provided Print instance. The inner event content is emitted via the provided `changeWriter` callback which must have signature `size_t(Print&, void*)`. The opaque `ref` pointer is passed through to the callback and may be used to access context (for example the `PendingNotification` that owns the fragment).

Protected Attributes
Vector< Subscription * >	subscriptions

Vector< PendingNotification >	pending_list

bool	is_active = true

Friends
template<typename >
class	DLNADevice

Detailed Description

template<typename ClientType>
class tiny_dlna::SubscriptionMgrDevice< ClientType >

Manages UPnP event subscriptions and queued notifications for a DLNA device.

The manager stores active subscriptions (allocated on the heap) and a queue of pending notifications that are delivered asynchronously via HTTP NOTIFY requests. Subscriptions are represented by Subscription objects; pending notifications reference subscriptions via a non-owning pointer (PendingNotification::p_subscription).

Responsibilities:

create and remove subscriptions (SID generation)
enqueue state-change notifications for delivery (addChange)
deliver queued notifications (publish) with retry/drop policy
purge expired subscriptions (removeExpired)

Note: p_subscription pointers may become invalid if a subscription is removed; removal routines attempt to clean up pending entries, but a stable UID approach is recommended for maximum robustness.

The template parameter defines the HTTP client type used when delivering notifications (e.g. WiFiClient); callers should pass the client that is compatible with their transport stack.

Template Parameters

ClientType Arduino Client implementation used for outgoing NOTIFY/SUBSCRIBE HTTP calls (e.g. WiFiClient, EthernetClient).

Constructor & Destructor Documentation

◆ SubscriptionMgrDevice()

template<typename ClientType >

tiny_dlna::SubscriptionMgrDevice< ClientType >::SubscriptionMgrDevice ( )

default

Construct a new Subscription Manager.

Initializes an empty manager. Subscriptions are owned by the manager (heap-allocated) and will be freed in the destructor.

◆ ~SubscriptionMgrDevice()

template<typename ClientType >

tiny_dlna::SubscriptionMgrDevice< ClientType >::~SubscriptionMgrDevice ( )

inline

Destroy the Subscription Manager.

Frees any remaining heap-allocated subscriptions and clears internal pending lists. This ensures no memory is leaked when the manager is destroyed.

Member Function Documentation

◆ addChange()

template<typename ClientType >

void tiny_dlna::SubscriptionMgrDevice< ClientType >::addChange	(	DLNAServiceInfo &	service,
		std::function< size_t(Print &, void *)>	changeWriter,
		void *	ref
	)

inlineoverridevirtual

Enqueue a state-variable change for delivery.

Adds a pending notification for all subscribers of service. Instead of passing a raw XML fragment, callers provide a small writer callback that emits the inner XML fragment when invoked. The manager will call this callback to compute the Content-Length (using a NullPrint) and later again when streaming the NOTIFY body. The opaque ref pointer is forwarded to the writer both during length calculation and at publish time.

Parameters

service	The DLNA service whose subscribers should be notified
changeWriter	Callback that writes the inner XML fragment. It must match the signature `size_t(Print&, void*)` and return the number of bytes written.
ref	Opaque pointer passed to `changeWriter` when it is invoked

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ clear()

template<typename ClientType >

void tiny_dlna::SubscriptionMgrDevice< ClientType >::clear ( )

inlineprotected

Clear all subscriptions and pending notifications.

◆ createXML()

template<typename ClientType >

static size_t tiny_dlna::SubscriptionMgrDevice< ClientType >::createXML	(	Print &	out,
		void *	ref
	)

inlinestaticprotected

Generate the propertyset XML for a single variable and write it to the provided Print instance. The inner event content is emitted via the provided changeWriter callback which must have signature size_t(Print&, void*). The opaque ref pointer is passed through to the callback and may be used to access context (for example the PendingNotification that owns the fragment).

Returns the number of bytes written.

◆ end()

template<typename ClientType >

void tiny_dlna::SubscriptionMgrDevice< ClientType >::end ( )

inlineoverridevirtual

Convenience method to disable subscriptions at the end of the lifecycle.

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ isSubscriptionsActive()

template<typename ClientType >

bool tiny_dlna::SubscriptionMgrDevice< ClientType >::isSubscriptionsActive ( )

inlineoverridevirtual

Query whether subscription delivery is active.

Returns: true if subscription delivery is enabled

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ pendingCount()

template<typename ClientType >

size_t tiny_dlna::SubscriptionMgrDevice< ClientType >::pendingCount ( )

inlineoverridevirtual

Number of queued pending notifications.

Returns: int count of pending notifications

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ processSubscribeRequest()

template<typename ClientType >

bool tiny_dlna::SubscriptionMgrDevice< ClientType >::processSubscribeRequest	(	IHttpServer &	server,
		DLNAServiceInfo &	service
	)

inlineoverrideprotectedvirtual

Handle SUBSCRIBE request including HTTP response.

Parses the CALLBACK, TIMEOUT, and SID headers from the HTTP request, processes the subscription, and sends the HTTP response back to the client. This method encapsulates all HTTP-specific logic for SUBSCRIBE requests.

Parameters

server	Reference to the HTTP server handling the request
service	Reference to the DLNA service to subscribe to

Returns: true if subscription was successful and response sent

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ processUnsubscribeRequest()

template<typename ClientType >

bool tiny_dlna::SubscriptionMgrDevice< ClientType >::processUnsubscribeRequest	(	IHttpServer &	server,
		DLNAServiceInfo &	service
	)

inlineoverrideprotectedvirtual

Handle UNSUBSCRIBE request including HTTP response.

Parses the SID header from the HTTP request, removes the subscription, and sends the appropriate HTTP response back to the client. This method encapsulates all HTTP-specific logic for UNSUBSCRIBE requests.

Parameters

server	Reference to the HTTP server handling the request
service	Reference to the DLNA service to unsubscribe from

Returns: true if unsubscribe was successful and response sent

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ publish()

template<typename ClientType >

int tiny_dlna::SubscriptionMgrDevice< ClientType >::publish ( )

inlineoverridevirtual

Deliver queued notifications.

Iterates the pending notification queue and attempts to deliver each notification via HTTP NOTIFY. Successful deliveries are removed from the queue. Failed attempts increment an error counter; entries that exceed MAX_NOTIFY_RETIES are dropped. Expired subscriptions are removed prior to delivery.

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ removeExpired()

template<typename ClientType >

void tiny_dlna::SubscriptionMgrDevice< ClientType >::removeExpired ( )

inlineprotected

Remove expired subscriptions.

Walks the subscription list and unsubscribes any entry whose expires_at timestamp has passed. This also removes pending notifications related to the unsubscribed entries.

◆ renewSubscription()

template<typename ClientType >

Str tiny_dlna::SubscriptionMgrDevice< ClientType >::renewSubscription	(	DLNAServiceInfo &	service,
		const char *	sid,
		const char *	callbackUrl,
		uint32_t	timeoutSec
	)

inlineprotected

Try to renew an existing subscription identified by SID for the given service. If successful the subscription's timeout/expiry (and optionally callback URL) are updated and the renewed SID is returned. If no matching subscription exists an empty Str is returned.

◆ setSubscriptionsActive()

template<typename ClientType >

void tiny_dlna::SubscriptionMgrDevice< ClientType >::setSubscriptionsActive ( bool flag )

inlineoverridevirtual

Enable or disable subscription delivery.

When disabled the manager will not attempt to publish pending notifications. Disabling also clears the pending queue to avoid delivering stale notifications when re-enabled. Use isSubscriptionsActive() to query the current state.

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ subscribe()

template<typename ClientType >

Str tiny_dlna::SubscriptionMgrDevice< ClientType >::subscribe	(	DLNAServiceInfo &	service,
		const char *	callbackUrl,
		const char *	sid = `nullptr`,
		uint32_t	timeoutSec = `1800`
	)

inlineoverridevirtual

Add or renew a subscription for a service.

Creates a new subscription for the given service and callback URL, or renews an existing one if a non-empty sid is provided and a matching subscription exists for the service. When renewing, the existing SID is returned and the timeout/expiry is updated. This mirrors UPnP semantics where clients may SUBSCRIBE with an existing SID to renew.

Parameters

service	Reference to the DLNA service to subscribe to
callbackUrl	The CALLBACK URL provided by the subscriber. May be empty when renewing via SID.
sid	Optional SID to renew; pass nullptr or empty to create a new subscription
timeoutSec	Requested subscription timeout in seconds (default 1800)

Returns: Str Assigned or renewed SID for the subscription

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ subscriptionsCount()

template<typename ClientType >

size_t tiny_dlna::SubscriptionMgrDevice< ClientType >::subscriptionsCount ( )

inlineoverridevirtual

Number of active subscriptions.

Returns: int count of subscriptions

Implements tiny_dlna::ISubscriptionMgrDevice.

◆ unsubscribe()

template<typename ClientType >

bool tiny_dlna::SubscriptionMgrDevice< ClientType >::unsubscribe	(	DLNAServiceInfo &	service,
		const char *	sid
	)

inlineoverridevirtual

Remove a subscription identified by SID.

Removes the subscription for the specified service and SID. Pending notifications targeting the subscription are also removed. The subscription object is deleted and the method returns true on success.

Parameters

service	Reference to the DLNA service
sid	Subscription identifier to remove

Returns: true if the subscription was found and removed; false if no matching subscription exists

Implements tiny_dlna::ISubscriptionMgrDevice.

Friends And Related Function Documentation

◆ DLNADevice

template<typename ClientType >

template<typename >

friend class DLNADevice

friend

Member Data Documentation

◆ is_active

template<typename ClientType >

bool tiny_dlna::SubscriptionMgrDevice< ClientType >::is_active = true

protected

◆ pending_list

template<typename ClientType >

Vector<PendingNotification> tiny_dlna::SubscriptionMgrDevice< ClientType >::pending_list

protected

◆ subscriptions

template<typename ClientType >

Vector<Subscription*> tiny_dlna::SubscriptionMgrDevice< ClientType >::subscriptions

protected

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

src/dlna/devices/SubscriptionMgrDevice.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ SubscriptionMgrDevice()

◆ ~SubscriptionMgrDevice()

Member Function Documentation

◆ addChange()

◆ clear()

◆ createXML()

◆ end()

◆ isSubscriptionsActive()

◆ pendingCount()

◆ processSubscribeRequest()

◆ processUnsubscribeRequest()

◆ publish()

◆ removeExpired()

◆ renewSubscription()

◆ setSubscriptionsActive()

◆ subscribe()

◆ subscriptionsCount()

◆ unsubscribe()

Friends And Related Function Documentation

◆ DLNADevice

Member Data Documentation

◆ is_active

◆ pending_list

◆ subscriptions