#include <mupnp/control/control.h>
#include <mupnp/controlpoint.h>
#include <mupnp/device.h>
#include <mupnp/io/file.h>
#include <mupnp/net/interface.h>
#include <mupnp/net/url.h>
#include <mupnp/ssdp/ssdp.h>
#include <mupnp/ssdp/ssdp_server.h>
#include <mupnp/upnp_function.h>
#include <mupnp/upnp_limit.h>
#include <mupnp/util/log.h>
#include <mupnp/util/string.h>
#include <mupnp/util/time.h>

Functions
static void	mupnp_device_initchildnodes (mUpnpDevice *dev)

static void	mupnp_device_initdevicelist (mUpnpDevice *dev)

static void	mupnp_device_initservicelist (mUpnpDevice *dev)

static void	mupnp_device_initiconlist (mUpnpDevice *dev)

static void	mupnp_device_notifywait (mUpnpDevice *dev)

mUpnpDevice *	mupnp_device_new (void)
	Create a new UPnP device instance.

void	mupnp_device_delete (mUpnpDevice *dev)
	Delete a UPnP device and free all associated resources.

void	mupnp_device_clear (mUpnpDevice *dev)

void	mupnp_device_setdevicenode (mUpnpDevice dev, mUpnpXmlNode node)

mUpnpDevice *	mupnp_device_getrootdevice (mUpnpDevice *dev)

bool	mupnp_device_parsedescription (mUpnpDevice dev, const char desciption, size_t descriptionLen)

bool	mupnp_device_parsedescriptionurl (mUpnpDevice dev, mUpnpNetURL url)

bool	mupnp_device_updatefromssdppacket (mUpnpDevice dev, mUpnpSSDPPacket ssdpPkt)

char *	mupnp_devicetype_getidentifier (const char *deviceType)

char *	mupnp_devicetype_geturn (const char *deviceType)

char *	mupnp_devicetype_getdevice (const char *deviceType)

char *	mupnp_devicetype_gettype (const char *deviceType)

char *	mupnp_devicetype_getschematype (const char *deviceType)

char *	mupnp_devicetype_getversion (const char *deviceType)

mUpnpDevice *	mupnp_device_getdevicebytype (mUpnpDevice dev, const char type)

mUpnpDevice *	mupnp_device_getdevicebyexacttype (mUpnpDevice dev, const char exacttype)

mUpnpDevice *	mupnp_device_getdevicebyudn (mUpnpDevice dev, const char udn)

mUpnpDevice *	mupnp_device_getdevicebydescriptionuri (mUpnpDevice dev, const char url)

const char *	mupnp_device_getlocationurl (mUpnpDevice dev, const char host, char *buf, int bufSize)

char *	mupnp_device_getnotifydevicent (mUpnpDevice dev, char buf, int bufSize)

char *	mupnp_device_getnotifydeviceusn (mUpnpDevice dev, char buf, int bufSize)

char *	mupnp_device_getnotifydevicetypent (mUpnpDevice dev, char buf, int bufSize)

char *	mupnp_device_getnotifydevicetypeusn (mUpnpDevice dev, char buf, int bufSize)

bool	mupnp_device_announcefrom (mUpnpDevice dev, char bindAddr)

void	mupnp_device_announce (mUpnpDevice *dev)

bool	mupnp_device_byebyefrom (mUpnpDevice dev, char bindAddr)

void	mupnp_device_byebye (mUpnpDevice *dev)

bool	mupnp_device_postsearchresponse (mUpnpDevice dev, mUpnpSSDPPacket ssdpPkt, const char st, const char usn)

bool	mupnp_device_start (mUpnpDevice *dev)
	Start a UPnP device and begin advertising on the network.

bool	mupnp_device_ipchanged (mUpnpDevice *dev)

bool	mupnp_device_stop (mUpnpDevice *dev)
	Stop a UPnP device and cease network advertising.

bool	mupnp_device_isrunning (mUpnpDevice *dev)

mUpnpService *	mupnp_device_getservicebyserviceid (mUpnpDevice dev, const char serviceId)

mUpnpService *	mupnp_device_getservicebyexacttype (mUpnpDevice dev, const char type)

mUpnpService *	mupnp_device_getservicebytype (mUpnpDevice dev, const char type)

mUpnpService *	mupnp_device_getservicebyscpdurl (mUpnpDevice dev, const char url)

mUpnpService *	mupnp_device_getservicebycontrolurl (mUpnpDevice dev, const char url)

mUpnpService *	mupnp_device_getservicebysid (mUpnpDevice dev, const char sid)

void	mupnp_device_setactionlistener (mUpnpDevice *dev, MUPNP_ACTION_LISTNER actionListner)

void	mupnp_device_setquerylistener (mUpnpDevice *dev, MUPNP_STATEVARIABLE_LISTNER queryListner)

mUpnpService *	mupnp_device_getservicebyeventsuburl (mUpnpDevice dev, const char url)

mUpnpIcon *	mupnp_device_getsmallesticonbymimetype (mUpnpDevice dev, const char mimeType)

mUpnpIcon *	mupnp_device_getsmallesticon (mUpnpDevice *dev)

bool	mupnp_device_getabsoluteiconurl (mUpnpDevice dev, mUpnpIcon icon, mUpnpString *buf)

mUpnpAction *	mupnp_device_getactionbyname (mUpnpDevice dev, const char name)

mUpnpStateVariable *	mupnp_device_getstatevariablebyname (mUpnpDevice dev, const char name)

bool	mupnp_device_addicon (mUpnpDevice dev, mUpnpIcon icon)

void	mupnp_device_updateudn (mUpnpDevice *dev)

void	mupnp_device_setpresentationlistener (mUpnpDevice *dev, MUPNP_PRESENTATION_LISTNER func)

Function Documentation

◆ mupnp_device_addicon()

bool mupnp_device_addicon	(	mUpnpDevice *	dev,
		mUpnpIcon *	icon )

Get a smallest icon

Parameters

dev	Device in question
icon	Icon to add

◆ mupnp_device_announce()

void mupnp_device_announce ( mUpnpDevice * dev )

Broadcast an SSDP:alive to notify control points that the device is available.

Parameters

dev	Device in question

◆ mupnp_device_announcefrom()

bool mupnp_device_announcefrom	(	mUpnpDevice *	dev,
		char *	bindAddr )

◆ mupnp_device_byebye()

void mupnp_device_byebye ( mUpnpDevice * dev )

Broadcast an SSDP:byebye message to notify control points that the device is no longer available.

Parameters

dev	Device in question

◆ mupnp_device_byebyefrom()

bool mupnp_device_byebyefrom	(	mUpnpDevice *	dev,
		char *	bindAddr )

◆ mupnp_device_clear()

void mupnp_device_clear ( mUpnpDevice * dev )

Clear a UPnP device structure. This is an internal function and should not be called from outside.

Parameters

dev	Device in question

◆ mupnp_device_delete()

void mupnp_device_delete ( mUpnpDevice * dev )

Delete a UPnP device and free all associated resources.

Releases all resources associated with the device, including:

Device description (XML nodes)
All services and their state tables
All embedded (child) devices
Icon list
Network servers (HTTP, SSDP) if running
Internal mutexes and threads

If the device is still running (started) when this function is called, it will be stopped automatically before resources are freed.

Parameters

dev	The device to destroy. May be NULL (no-op if NULL).

Note: After calling this function, the dev pointer is invalid and must not be used.; This function will block until all internal threads have terminated.; Thread-safe: Must not be called concurrently with other operations on the same device. The caller is responsible for ensuring exclusive access.

Warning: Do not call this function while holding locks or from within listener callbacks, as this may cause deadlocks.

See also: mupnp_device_new(); mupnp_device_stop()

◆ mupnp_device_getabsoluteiconurl()

bool mupnp_device_getabsoluteiconurl	(	mUpnpDevice *	dev,
		mUpnpIcon *	icon,
		mUpnpString *	buf )

Get an icon by its index from the device's list of icons

Parameters

dev	Device in question
icon	Icon in question
buf	Buffer to return the full icon's url

Returns: true if the absolute url is created, otherwise false.

◆ mupnp_device_getactionbyname()

mUpnpAction * mupnp_device_getactionbyname	(	mUpnpDevice *	dev,
		const char *	name )

Find an action from a device by its name

Parameters

dev	Device in question
name	Name of the action

◆ mupnp_device_getdevicebydescriptionuri()

mUpnpDevice * mupnp_device_getdevicebydescriptionuri	(	mUpnpDevice *	dev,
		const char *	url )

Find a child device by its description URI.

Parameters

dev	Device in question
url	Description URI

◆ mupnp_device_getdevicebyexacttype()

mUpnpDevice * mupnp_device_getdevicebyexacttype	(	mUpnpDevice *	dev,
		const char *	exacttype )

Find a device from the device's children by the type of the device. This function searches for devices, whose complete type string matches the given string, including version number. For example: "urn:schemas-upnp-org:device:FooDevice:1". If you need to disregard the version number, use mupnp_device_getdevicebytype

Parameters

dev	Device in question
exacttype	Type of the device

◆ mupnp_device_getdevicebytype()

mUpnpDevice * mupnp_device_getdevicebytype	(	mUpnpDevice *	dev,
		const char *	type )

Find a device from the device's children by the type of the device. This function searches for devices, whose type part (i.e. not including the version) of the device type string matches the given string. For example: "urn:schemas-upnp-org:device:FooDevice". If you need to know the version of a device, use mupnp_devicetype_getversion

Parameters

dev	Device in question
type	Type of the device

◆ mupnp_device_getdevicebyudn()

mUpnpDevice * mupnp_device_getdevicebyudn	(	mUpnpDevice *	dev,
		const char *	udn )

Find a device from the device's children by the UDN of the device.

Parameters

dev	Device in question
udn	Type of the device

◆ mupnp_device_getlocationurl()

const char * mupnp_device_getlocationurl	(	mUpnpDevice *	dev,
		const char *	host,
		char *	buf,
		int	bufSize )

Get device's location URL. Transforms the given <host> address to URL form: "http://<host>:<port>/description.xml". Port is usually 80 or 38400. If <host> is an IPv6 address, the address is "http://[<host>]:<port>/description.xml".

Parameters

dev	Device in question
host	The device host
buf	Buffer to store the resulting URL
bufSize	Buffer length

◆ mupnp_device_getnotifydevicent()

char * mupnp_device_getnotifydevicent	(	mUpnpDevice *	dev,
		char *	buf,
		int	bufSize )

Get the device's Notification Type (NT). For the root device this is "upnp:rootdevice", otherwise the device's UDN (Unique Device Name).

Parameters

dev	The device in question
buf	Buffer for the Notification Type
bufSize	Buffer length

◆ mupnp_device_getnotifydevicetypent()

char * mupnp_device_getnotifydevicetypent	(	mUpnpDevice *	dev,
		char *	buf,
		int	bufSize )

Get the device type

Parameters

dev	The device in question
buf	Buffer for the device type
bufSize	Buffer length

◆ mupnp_device_getnotifydevicetypeusn()

char * mupnp_device_getnotifydevicetypeusn	(	mUpnpDevice *	dev,
		char *	buf,
		int	bufSize )

Get the device's USN (Unique Service Name). For the root device this is "<UDN>::upnp:rootdevice", otherwise the UDN (Unique Device Name).

Parameters

dev	The device in question
buf	Buffer where USN is stored after call
bufSize	Buffer size

Returns: Pointer to buf

◆ mupnp_device_getnotifydeviceusn()

char * mupnp_device_getnotifydeviceusn	(	mUpnpDevice *	dev,
		char *	buf,
		int	bufSize )

Get the device's USN (Unique Service Name). For the root device this is "<UDN>::upnp:rootdevice", otherwise the UDN (Unique Device Name).

Parameters

dev	The device in question

◆ mupnp_device_getrootdevice()

mUpnpDevice * mupnp_device_getrootdevice ( mUpnpDevice * dev )

Return the root (i.e. the topmost) device in the device structure

Parameters

dev	Traverses the device tree upwards starting from this device

◆ mupnp_device_getservicebycontrolurl()

mUpnpService * mupnp_device_getservicebycontrolurl	(	mUpnpDevice *	dev,
		const char *	url )

Find a service from a device by its control URL

Parameters

dev	Device in question
url	Control URL

◆ mupnp_device_getservicebyeventsuburl()

mUpnpService * mupnp_device_getservicebyeventsuburl	(	mUpnpDevice *	dev,
		const char *	url )

Find a service from a device by its event subscription URL

Parameters

dev	Device in question
url	Event Subscription URL

◆ mupnp_device_getservicebyexacttype()

mUpnpService * mupnp_device_getservicebyexacttype	(	mUpnpDevice *	dev,
		const char *	type )

Find a service from the device by the type of the service. This function searches for services, whose complete type string matches the given string, including version number. For example: "urn:schemas-upnp-org:service:ContentDirectory:1". If you need to know the version of a service, use mupnp_servicetype_getversion

Parameters

dev	Device in question
type	Type of the service

◆ mupnp_device_getservicebyscpdurl()

mUpnpService * mupnp_device_getservicebyscpdurl	(	mUpnpDevice *	dev,
		const char *	url )

Find a service from the device by the SCPD (Service Control Protocol Definition) URL of the service.

Parameters

dev	Device in question
url	SCPD URL

◆ mupnp_device_getservicebyserviceid()

mUpnpService * mupnp_device_getservicebyserviceid	(	mUpnpDevice *	dev,
		const char *	serviceId )

Find service from the device by a given serviceId. This function searches recursively device and its subdevices for a service with a given serviceId

Parameters

dev	Device in question
serviceId	serviceId of the service

Returns: service matching the given serviceId

◆ mupnp_device_getservicebysid()

mUpnpService * mupnp_device_getservicebysid	(	mUpnpDevice *	dev,
		const char *	sid )

Find a service from its Subscription ID

Parameters

dev	Device in question
char*	Subscription-ID (SID)

◆ mupnp_device_getservicebytype()

mUpnpService * mupnp_device_getservicebytype	(	mUpnpDevice *	dev,
		const char *	type )

Find a service from the device by the type of the service. This function searches for services, whose type part (i.e. not including the version) of the service type string matches the given string. For example: "urn:schemas-upnp-org:service:ContentDirectory". If you need to know the version of a service, use mupnp_servicetype_getversion

Parameters

dev	Device in question
type	Type of the service

◆ mupnp_device_getsmallesticon()

mUpnpIcon * mupnp_device_getsmallesticon ( mUpnpDevice * dev )

Get a smallest icon

Parameters

dev	Device in question

Returns: A smallest icon.

◆ mupnp_device_getsmallesticonbymimetype()

mUpnpIcon * mupnp_device_getsmallesticonbymimetype	(	mUpnpDevice *	dev,
		const char *	mimeType )

Get a smallest icon of a specified mime type

Parameters

dev	Device in question
mimeType	Mime type to get

Returns: A smallest icon.

◆ mupnp_device_getstatevariablebyname()

mUpnpStateVariable * mupnp_device_getstatevariablebyname	(	mUpnpDevice *	dev,
		const char *	name )

Find a state variable from a device by its name

Parameters

dev	Device in question
name	Name of the state variable

◆ mupnp_device_initchildnodes()

static void mupnp_device_initchildnodes ( mUpnpDevice * dev )

static

◆ mupnp_device_initdevicelist()

static void mupnp_device_initdevicelist ( mUpnpDevice * dev )

static

◆ mupnp_device_initiconlist()

static void mupnp_device_initiconlist ( mUpnpDevice * dev )

static

◆ mupnp_device_initservicelist()

static void mupnp_device_initservicelist ( mUpnpDevice * dev )

static

◆ mupnp_device_ipchanged()

bool mupnp_device_ipchanged ( mUpnpDevice * dev )

Notify device that IP address of the host has been changed.

Parameters

dev	dev The device in question

Returns: success of changing used interfaces

◆ mupnp_device_isrunning()

bool mupnp_device_isrunning ( mUpnpDevice * dev )

Check if the device] has been started

Parameters

dev	Device that is being advertised

◆ mupnp_device_new()

mUpnpDevice * mupnp_device_new ( void )

Create a new UPnP device instance.

Allocates and initializes a new UPnP device object for use as either:

A device implementation (to be advertised on the network)
A device representation (discovered by a control point)

The function initializes:

Device description node (XML representation)
Service list (empty)
Icon list (empty)
Embedded device list (empty)
Internal mutex for thread safety
Default values (e.g., lease time, HTTP port)

After creation, populate the device description using one of:

mupnp_device_parsedescription() - from XML string
mupnp_device_parsedescriptionurl() - from HTTP URL
mupnp_device_loaddescriptionfile() - from file (if MUPNP_USE_CFILE defined)
Manual setter functions (mupnp_device_setfriendlyname(), etc.)

Returns: A newly-created mUpnpDevice on success, or NULL if memory allocation fails.

Note: The returned device must be freed with mupnp_device_delete() when no longer needed to avoid memory leaks.; Thread-safe: This function can be called concurrently from multiple threads.; The device is initially inactive. Use mupnp_device_start() to activate it and begin advertising (for device implementations).

See also: mupnp_device_delete(); mupnp_device_parsedescription(); mupnp_device_start()

◆ mupnp_device_notifywait()

static void mupnp_device_notifywait ( mUpnpDevice * dev )

static

◆ mupnp_device_parsedescription()

bool mupnp_device_parsedescription	(	mUpnpDevice *	dev,
		const char *	desciption,
		size_t	descriptionLen )

Parse the device description XML document.

Parameters

dev	Device in question
description	Buffer containing the device description in XML format
descriptionLen	Buffer length

Returns: true, if the buffer was successfully parsed; otherwise false

◆ mupnp_device_parsedescriptionurl()

bool mupnp_device_parsedescriptionurl	(	mUpnpDevice *	dev,
		mUpnpNetURL *	url )

Fetch and parse the device description XML file, located in the given URL.

Parameters

dev	Device in question
url	An internet resource

Returns: true, if the buffer was successfully parsed; otherwise false

◆ mupnp_device_postsearchresponse()

bool mupnp_device_postsearchresponse	(	mUpnpDevice *	dev,
		mUpnpSSDPPacket *	ssdpPkt,
		const char *	st,
		const char *	usn )

Post a response to an SSDP search message

Parameters

dev	The device in question
ssdpPkt	Received SSDP packet
st	Service Type (ST)
usn	Unique Service Name (USN)

◆ mupnp_device_setactionlistener()

void mupnp_device_setactionlistener	(	mUpnpDevice *	dev,
		MUPNP_ACTION_LISTNER	actionListner )

Set an action listener to the device. Actions are basically commands, that the device (service) responds to.

Parameters

dev	Device in question
actionListener	The action listener

◆ mupnp_device_setdevicenode()

void mupnp_device_setdevicenode	(	mUpnpDevice *	dev,
		mUpnpXmlNode *	node )

Set the device description node and initialise its child nodes

Parameters

dev	Device in question
node	The XML structure to be set as the device's description

◆ mupnp_device_setpresentationlistener()

void mupnp_device_setpresentationlistener	(	mUpnpDevice *	dev,
		MUPNP_PRESENTATION_LISTNER	func )

◆ mupnp_device_setquerylistener()

void mupnp_device_setquerylistener	(	mUpnpDevice *	dev,
		MUPNP_STATEVARIABLE_LISTNER	queryListner )

Set a query listener to the device. Queries are meant for state variables.

Parameters

dev	Device in question
actionListener	The query listener

◆ mupnp_device_start()

bool mupnp_device_start ( mUpnpDevice * dev )

Start a UPnP device and begin advertising on the network.

Activates the device and starts all required network services:

HTTP server for device description, SOAP control, and eventing (default port: 38400, or as set by mupnp_device_sethttpport())
SSDP multicast listener for M-SEARCH discovery requests
SSDP advertisement broadcaster (sends periodic ssdp:alive messages)
Sends initial ssdp:alive notifications for the device and all its services

After successful startup, the device will:

Respond to M-SEARCH discovery requests from control points
Periodically advertise its presence via ssdp:alive (based on lease time)
Accept action invocations via SOAP
Accept event subscriptions and send notifications

The device description must be properly configured before calling this function (friendly name, UDN, services, etc.).

Parameters

dev	The device to start. Must not be NULL and must have a valid description with at least a UDN and device type.

Return values

true	Successfully started all services
false	Failed to start due to: NULL parameter HTTP port already in use Network error (e.g., cannot bind to multicast address) Invalid or incomplete device description Insufficient permissions

Note: This function may fail if the HTTP port is already in use. Configure an alternative port with mupnp_device_sethttpport() if needed.; Thread-safe: Can be called from any thread, but must not be called concurrently on the same device.; Calling this function on an already-running device has no effect and returns true.; Side effect: Sends SSDP advertisements to the network immediately and starts the advertisement thread.

Warning

On some platforms, binding to multicast addresses may require elevated privileges.

Ensure proper firewall configuration to allow:

Incoming TCP on HTTP port
Outgoing UDP to SSDP multicast address (239.255.255.250:1900)
Incoming UDP on SSDP port (1900)

See also: mupnp_device_stop(); mupnp_device_isrunning(); mupnp_device_sethttpport(); mupnp_device_setleasetime()

// Example: Create and start a simple device
mUpnpDevice* dev = mupnp_device_new();
 
// Configure device description
mupnp_device_setdevicetype(dev, "urn:schemas-upnp-org:device:Basic:1");
mupnp_device_setfriendlyname(dev, "My UPnP Device");
mupnp_device_setmanufacturer(dev, "Example Corp");
mupnp_device_setmodelname(dev, "Model 1");
mupnp_device_updateudn(dev); // Generate a UDN
 
// Set action and query listeners
mupnp_device_setactionlistener(dev, my_action_listener);
mupnp_device_setquerylistener(dev, my_query_listener);
 
// Start the device
if (mupnp_device_start(dev)) {
    printf("Device started and advertising\n");
} else {
    fprintf(stderr, "Failed to start device\n");
    mupnp_device_delete(dev);
}

◆ mupnp_device_stop()

bool mupnp_device_stop ( mUpnpDevice * dev )

Stop a UPnP device and cease network advertising.

Gracefully shuts down all network services:

Sends ssdp:byebye notifications for the device and all its services, informing control points that the device is leaving the network
Stops the HTTP server (no longer accepts connections)
Closes SSDP multicast listener
Terminates the advertisement broadcaster thread

After stopping, the device will no longer:

Respond to M-SEARCH discovery requests
Accept action invocations
Send periodic advertisements
Accept event subscriptions or send notifications

The device description and configuration are retained. The device can be restarted with mupnp_device_start().

Parameters

dev	The device to stop. Must not be NULL.

Return values

true	Successfully stopped all services and sent byebye notifications
false	Failed to stop (unlikely), or dev is NULL

Note

This function blocks until:

ssdp:byebye messages are sent (a few hundred milliseconds)
All listener threads have terminated (may take a few seconds)

Calling this function on an already-stopped device has no effect and returns true.

Thread-safe: Can be called from any thread, but must not be called concurrently on the same device.

Side effect: Sends SSDP byebye messages to the network, which should prompt control points to remove the device from their lists.

Active event subscriptions are not explicitly cancelled. Subscribed control points will detect the device is unavailable when subscriptions expire or when they attempt to renew.

See also: mupnp_device_start(); mupnp_device_isrunning(); mupnp_device_delete()

◆ mupnp_device_updatefromssdppacket()

bool mupnp_device_updatefromssdppacket	(	mUpnpDevice *	dev,
		mUpnpSSDPPacket *	ssdpPkt )

Update the device's contents from an SSDP packet if necessary.

Parameters

dev	The device to potentially update
ssdpPkt	The SSDP packet to make decisions on

Returns: true if the device was updated; otherwise false

◆ mupnp_device_updateudn()

void mupnp_device_updateudn ( mUpnpDevice * dev )

Update new Unique Device Name (UDN)

Parameters

dev	Device in question