controlpoint.h File Reference

#include <mupnp/net/interface.h>
#include <mupnp/util/cond.h>
#include <mupnp/util/mutex.h>
#include <mupnp/util/string.h>
#include <mupnp/xml/xml.h>
#include <mupnp/argument.h>
#include <mupnp/device.h>
#include <mupnp/event/event.h>
#include <mupnp/event/notify.h>
#include <mupnp/ssdp/ssdp_server.h>
#include <mupnp/upnp_status.h>

Data Structures
struct	_mUpnpControlPoint

Macros
#define	MUPNP_CONTROLPOINT_SSDP_DEFAULT_SEARCH_MX   3
#define	MUPNP_CONTROLPOINT_SSDP_MIN_DELAY   20
#define	MUPNP_CONTROLPOINT_SSDP_RESPONSE_DEFAULT_PORT   39400
#define	MUPNP_CONTROLPOINT_SSDP_RESPONSE_PORT_MAX_TRIES_INDEX   80
#define	MUPNP_CONTROLPOINT_HTTP_EVENT_DEFAULT_PORT   39500
#define	MUPNP_CONTROLPOINT_HTTP_EVENTSUB_URI   "/eventSub"
#define	mupnp_controlpoint_getssdpserverlist(ctrlPoint)
#define	mupnp_controlpoint_getssdpresponseserverlist(ctrlPoint)
#define	mupnp_controlpoint_gethttpserverlist(ctrlPoint)
#define	mupnp_controlpoint_setssdplistener(ctrlPoint, func)
#define	mupnp_controlpoint_getssdplistener(ctrlPoint)
#define	mupnp_controlpoint_setssdpresponselistener(ctrlPoint, func)
#define	mupnp_controlpoint_getssdpresponselistener(ctrlPoint)
#define	mupnp_controlpoint_setdevicelistener(ctrlPoint, func)
#define	mupnp_controlpoint_getdevicelistener(ctrlPoint)
#define	mupnp_controlpoint_addeventlistener(ctrlPoint, listener)
#define	mupnp_controlpoint_removeeventlistener(ctrlPoint, listener)
#define	mupnp_controlpoint_geteventlistener(ctrlPoint)
#define	mupnp_controlpoint_geteventlisteners(ctrlPoint)
#define	mupnp_controlpoint_setssdpresponseport(ctrlPoint, port)
#define	mupnp_controlpoint_getssdpresponseport(ctrlPoint)
#define	mupnp_controlpoint_seteventport(ctrlPoint, port)
#define	mupnp_controlpoint_geteventport(ctrlPoint)
#define	mupnp_controlpoint_seteventsuburi(ctrlPoint, uri)
#define	mupnp_controlpoint_geteventsuburi(ctrlPoint)
#define	mupnp_controlpoint_setssdpsearchmx(ctrlPoint, value)
#define	mupnp_controlpoint_getssdpsearchmx(ctrlPoint)
#define	mupnp_controlpoint_sethttplistener(ctrlPoint, func)
#define	mupnp_controlpoint_gethttplistener(ctrlPoint)
#define	mupnp_controlpoint_setuserdata(ctrlPoint, value)
#define	mupnp_controlpoint_getuserdata(ctrlPoint)
#define	mupnp_controlpoint_getdevices(ctrlPoint)
#define	mupnp_controlpoint_getndevices(ctrlPoint)
#define	mupnp_controlpoint_getdevice(ctrlPoint, index)
#define	mupnp_controlpoint_adddevice(ctrlPoint, dev)

Typedefs
typedef enum _mUpnpDeviceStatus	mUpnpDeviceStatus
typedef struct _mUpnpControlPoint	mUpnpControlPoint
typedef void(*	MUPNP_DEVICE_LISTENER) (mUpnpControlPoint *ctrlPoint, const char *udn, mUpnpDeviceStatus status)

Enumerations
enum	_mUpnpDeviceStatus { mUpnpDeviceStatusAdded = 0 , mUpnpDeviceStatusUpdated , mUpnpDeviceStatusInvalid , mUpnpDeviceStatusRemoved }

Functions
mUpnpControlPoint *	mupnp_controlpoint_new (void)
	Create a new control point instance.
void	mupnp_controlpoint_delete (mUpnpControlPoint *ctrlPoint)
	Destroy a control point and free all associated resources.
bool	mupnp_controlpoint_start (mUpnpControlPoint *ctrlPoint)
	Activate the control point and start network listeners.
bool	mupnp_controlpoint_stop (mUpnpControlPoint *ctrlPoint)
	Stop the control point and shut down network listeners.
bool	mupnp_controlpoint_isrunning (mUpnpControlPoint *ctrlPoint)
	Check if the control point is currently active.
bool	mupnp_controlpoint_lock (mUpnpControlPoint *ctrlPoint)
bool	mupnp_controlpoint_unlock (mUpnpControlPoint *ctrlPoint)
mUpnpDevice *	mupnp_controlpoint_getdevicebyexacttype (mUpnpControlPoint *ctrlPoint, const char *exacttype)
	Find a device by exact type string including version.
mUpnpDevice *	mupnp_controlpoint_getdevicebytype (mUpnpControlPoint *ctrlPoint, const char *type)
	Find a device by type, ignoring version number.
mUpnpDevice *	mupnp_controlpoint_getdevicebyudn (mUpnpControlPoint *ctrlPoint, const char *udn)
	Find a device by its Unique Device Name (UDN)
bool	mupnp_controlpoint_seteventlistener (mUpnpControlPoint *ctrlPoint, MUPNP_EVENT_LISTENER evlistener)
bool	mupnp_controlpoint_search (mUpnpControlPoint *ctrlPoint, const char *target)
	Send an M-SEARCH multicast message to discover UPnP devices.
void	mupnp_controlpoint_httprequestreceived (mUpnpHttpRequest *httpReq)
void	mupnp_controlpoint_updatestatetablefromproperty (mUpnpService *service, mUpnpProperty *prop)
bool	mupnp_controlpoint_parsescservicescpd (mUpnpService *service)
bool	mupnp_controlpoint_parseservicesfordevice (mUpnpDevice *dev, mUpnpSSDPPacket *ssdpPkt)
void	mupnp_controlpoint_adddevicebyssdppacket (mUpnpControlPoint *ctrlPoint, mUpnpSSDPPacket *ssdpPkt)
void	mupnp_controlpoint_removedevicebyssdppacket (mUpnpControlPoint *ctrlPoint, mUpnpSSDPPacket *ssdpPkt)
bool	mupnp_controlpoint_subscribe (mUpnpControlPoint *ctrlPoint, mUpnpService *service, long timeout)
	Subscribe to a UPnP service's event notifications.
bool	mupnp_controlpoint_resubscribe (mUpnpControlPoint *ctrlPoint, mUpnpService *service, long timeout)
bool	mupnp_controlpoint_unsubscribe (mUpnpControlPoint *ctrlPoint, mUpnpService *service)
bool	mupnp_controlpoint_subscribeall (mUpnpControlPoint *ctrlPoint, mUpnpDevice *dev, long timeout)
bool	mupnp_controlpoint_resubscribeall (mUpnpControlPoint *ctrlPoint, mUpnpDevice *dev, long timeout)
bool	mupnp_controlpoint_unsubscribeall (mUpnpControlPoint *ctrlPoint, mUpnpDevice *dev)
void	mupnp_controlpoint_expirationhandler (mUpnpThread *thread)
bool	mupnp_controlpoint_ipchanged (mUpnpControlPoint *ctrlpoint)
const char *	mupnp_controlpoint_geteventsubcallbackurl (mUpnpControlPoint *ctrlPoint, char *ifaddr, char *buf, size_t bufLen)

Macro Definition Documentation

mupnp_controlpoint_adddevice

#define mupnp_controlpoint_adddevice	(		ctrlPoint,
			dev )

Value:

mupnp_devicelist_add(ctrlPoint->deviceList, dev)

Add a device to the control point's list of devices. Do not call this from user applications.

Parameters

ctrlPoint	The control point in use
dev	The device to add

mupnp_controlpoint_addeventlistener

#define mupnp_controlpoint_addeventlistener	(		ctrlPoint,
			listener )

Value:

(mupnp_eventlistenerlist_add(ctrlPoint->eventListeners, listener))

Set an event listener for the control point. Use this function to get event notifications to user-space applications.

Parameters

ctrlPoint	The control point in question
listener	A callback function that is of type MUPNP_EVENT_LISTENER

mupnp_controlpoint_getdevice

#define mupnp_controlpoint_getdevice	(		ctrlPoint,
			index )

Value:

mupnp_devicelist_get(ctrlPoint->deviceList, index)

Get the head of the control point's list of devices (use for iteration)

Parameters

ctrlPoint	The control point in use
index	The index of the device to get

Returns

The specified device

mupnp_controlpoint_getdevicelistener

#define mupnp_controlpoint_getdevicelistener

(

ctrlPoint

)

Value:

(ctrlPoint->deviceListener)

Get the device listener for the control point.

Parameters

ctrlPoint

The control point in question

Returns

A callback function that is of type MUPNP_DEVICE_LISTENER or NULL

mupnp_controlpoint_getdevices

#define mupnp_controlpoint_getdevices

(

ctrlPoint

)

Value:

mupnp_devicelist_gets(ctrlPoint->deviceList)

Get the head of the control point's list of devices (use for iteration)

Parameters

ctrlPoint

The control point in use

Returns

The head of the device list

mupnp_controlpoint_geteventlistener

#define mupnp_controlpoint_geteventlistener

(

ctrlPoint

)

Value:

(ctrlPoint->eventListeners->next->listener)

Get the single event listener for the control point.

Parameters

ctrlPoint

The control point in question

Returns

The callback function, that is of type MUPNP_EVENT_LISTENER, or NULL if there is no listener

mupnp_controlpoint_geteventlisteners

#define mupnp_controlpoint_geteventlisteners

(

ctrlPoint

)

Value:

(ctrlPoint->eventListeners)

Get the list of event listeners for the control point.

Parameters

ctrlPoint

The control point in question

Returns

List of MUPNP_EVENT_LISTENER functions

mupnp_controlpoint_geteventport

#define mupnp_controlpoint_geteventport

(

ctrlPoint

)

Value:

(ctrlPoint->httpEventPort)

Get the IP port number for the control point's event reception

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_geteventsuburi

#define mupnp_controlpoint_geteventsuburi

(

ctrlPoint

)

Value:

mupnp_string_getvalue(ctrlPoint->httpEventURI)

Get the URI used for the control point's event subscription notifications

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_gethttplistener

#define mupnp_controlpoint_gethttplistener

(

ctrlPoint

)

Value:

(ctrlPoint->httpListener)

Get the HTTP listener function for the control point.

Parameters

ctrlPoint

The control point in question

Returns

The listener function, that is of type MUPNP_HTTP_LISTENER

mupnp_controlpoint_gethttpserverlist

#define mupnp_controlpoint_gethttpserverlist

(

ctrlPoint

)

Value:

(ctrlPoint->httpServerList)

Get the list of HTTP servers associated to the control point

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_getndevices

#define mupnp_controlpoint_getndevices

(

ctrlPoint

)

Value:

mupnp_devicelist_size(ctrlPoint->deviceList)

Get the number of devices known by the control point

Parameters

ctrlPoint

The control point in use

Returns

The number of devices in the control point's device list

mupnp_controlpoint_getssdplistener

#define mupnp_controlpoint_getssdplistener

(

ctrlPoint

)

Value:

(ctrlPoint->ssdpListener)

Get the SSDP message listener for the control point.

Parameters

ctrlPoint

The control point in question

Returns

A callback function that is of type MUPNP_SSDP_LISTNER or NULL

mupnp_controlpoint_getssdpresponselistener

#define mupnp_controlpoint_getssdpresponselistener

(

ctrlPoint

)

Value:

(ctrlPoint->ssdpResListener)

Get the SSDP response listener for the control point.

Parameters

ctrlPoint

The control point in question

Returns

A callback function that is of type MUPNP_SSDP_RESPONSE_LISTNER or NULL

mupnp_controlpoint_getssdpresponseport

#define mupnp_controlpoint_getssdpresponseport

(

ctrlPoint

)

Value:

(ctrlPoint->ssdpResPort)

Get the IP port number used for the control point's SSDP responses

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_getssdpresponseserverlist

#define mupnp_controlpoint_getssdpresponseserverlist

(

ctrlPoint

)

Value:

(ctrlPoint->ssdpResServerList)

Get the list of SSDP response servers associated to the control point

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_getssdpsearchmx

#define mupnp_controlpoint_getssdpsearchmx

(

ctrlPoint

)

Value:

(ctrlPoint->ssdpSearchMx)

Get the MX-parameter used for SSDP searches

Parameters

ctrlPoint

The control point in question

Returns

value MX; Time to wait

mupnp_controlpoint_getssdpserverlist

#define mupnp_controlpoint_getssdpserverlist

(

ctrlPoint

)

Value:

(ctrlPoint->ssdpServerList)

Get the list of SSDP servers associated to the control point

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_getuserdata

#define mupnp_controlpoint_getuserdata

(

ctrlPoint

)

Value:

(ctrlPoint->userData)

Get the user data pointer (arbitrary user data) from the control point.

Parameters

ctrlPoint

The control point in question

Returns

Pointer to user data or NULL

MUPNP_CONTROLPOINT_HTTP_EVENT_DEFAULT_PORT

#define MUPNP_CONTROLPOINT_HTTP_EVENT_DEFAULT_PORT   39500

Definition for HTTP event default port

MUPNP_CONTROLPOINT_HTTP_EVENTSUB_URI

#define MUPNP_CONTROLPOINT_HTTP_EVENTSUB_URI   "/eventSub"

Definition for default controlpoint event callback "location"

mupnp_controlpoint_removeeventlistener

#define mupnp_controlpoint_removeeventlistener	(		ctrlPoint,
			listener )

Value:

(mupnp_eventlistenerlist_remove(ctrlPoint->eventListeners, listener))

Remove an event listener from the control point.

Parameters

ctrlPoint	The control point in question
listener	The callback function to remove, that is of type MUPNP_EVENT_LISTENER

mupnp_controlpoint_setdevicelistener

#define mupnp_controlpoint_setdevicelistener	(		ctrlPoint,
			func )

Value:

(ctrlPoint->deviceListener = func)

Set device listener for the control point.

Parameters

ctrlPoint	The control point
func	A callback function that is type MUPNP_DEVICE_LISTENER or NULL

mupnp_controlpoint_seteventport

#define mupnp_controlpoint_seteventport	(		ctrlPoint,
			port )

Value:

(ctrlPoint->httpEventPort = port)

Set the IP port number for the control point's event reception

Parameters

ctrlPoint	The control point in question
port	The IP port number

mupnp_controlpoint_seteventsuburi

#define mupnp_controlpoint_seteventsuburi	(		ctrlPoint,
			uri )

Value:

mupnp_string_setvalue(ctrlPoint->httpEventURI, uri)

Set the URI used for the control point's event subscription notifications

Parameters

ctrlPoint	The control point in question
uri	The URI to set

mupnp_controlpoint_sethttplistener

#define mupnp_controlpoint_sethttplistener	(		ctrlPoint,
			func )

Value:

(ctrlPoint->httpListener = func)

Set an HTTP listener function to the control point. Use this function to get HTTP requests to user-space applications.

Parameters

ctrlPoint	The control point in question
func	The listener function, that is of type MUPNP_HTTP_LISTENER

mupnp_controlpoint_setssdplistener

#define mupnp_controlpoint_setssdplistener	(		ctrlPoint,
			func )

Value:

(ctrlPoint->ssdpListener = func)

Set an SSDP message listener for the control point. Use this function to get SSDP messages to user-space applications.

Parameters

ctrlPoint	The control point in question
func	A callback function that is of type MUPNP_SSDP_LISTNER

mupnp_controlpoint_setssdpresponselistener

#define mupnp_controlpoint_setssdpresponselistener	(		ctrlPoint,
			func )

Value:

(ctrlPoint->ssdpResListener = func)

Set an SSDP response listener for the control point. Use this function to get SSDP responses to user-space applications.

Parameters

ctrlPoint	The control point in question
func	A callback function that is of type MUPNP_SSDP_RESPONSE_LISTNER

mupnp_controlpoint_setssdpresponseport

#define mupnp_controlpoint_setssdpresponseport	(		ctrlPoint,
			port )

Value:

(ctrlPoint->ssdpResPort = port)

Set the IP port number used for the control point's SSDP responses

Parameters

ctrlPoint	The control point in question
port	The IP port number

mupnp_controlpoint_setssdpsearchmx

#define mupnp_controlpoint_setssdpsearchmx	(		ctrlPoint,
			value )

Value:

(ctrlPoint->ssdpSearchMx = value)

Set the MX-parameter used for SSDP searches i.e. Set the time to wait (in seconds) for device responses to an M-SEARCH

Parameters

ctrlPoint	The control point in question
value	MX; Time to wait

mupnp_controlpoint_setuserdata

#define mupnp_controlpoint_setuserdata	(		ctrlPoint,
			value )

Value:

(ctrlPoint->userData = value)

Set the user data pointer (arbitrary user data) to the control point.

Parameters

ctrlPoint	The control point in question
value	Arbitrary user data

MUPNP_CONTROLPOINT_SSDP_DEFAULT_SEARCH_MX

#define MUPNP_CONTROLPOINT_SSDP_DEFAULT_SEARCH_MX   3

Definition for SSDP default search MX

MUPNP_CONTROLPOINT_SSDP_MIN_DELAY

#define MUPNP_CONTROLPOINT_SSDP_MIN_DELAY   20

Definition for control point SSDP minimum delay

MUPNP_CONTROLPOINT_SSDP_RESPONSE_DEFAULT_PORT

#define MUPNP_CONTROLPOINT_SSDP_RESPONSE_DEFAULT_PORT   39400

Definition for control point default response port

MUPNP_CONTROLPOINT_SSDP_RESPONSE_PORT_MAX_TRIES_INDEX

#define MUPNP_CONTROLPOINT_SSDP_RESPONSE_PORT_MAX_TRIES_INDEX   80

Definition for numeric constant to specify the max tries to open a SSDP Response Port (rosfran.borges)

Typedef Documentation

MUPNP_DEVICE_LISTENER

typedef void(* MUPNP_DEVICE_LISTENER) (mUpnpControlPoint *ctrlPoint, const char *udn, mUpnpDeviceStatus status)

mUpnpControlPoint

typedef struct _mUpnpControlPoint mUpnpControlPoint

Prototype for control point's device listener callback.

Parameters

udn	The UDN of the device, that the status update concerns
status	The new status

mUpnpDeviceStatus

typedef enum _mUpnpDeviceStatus mUpnpDeviceStatus

Device listener status parameters.

mUpnpDeviceStatusAdded means a device has been added to local cache. mUpnpDeviceStatusUpdated means a device description has been updated because its IP address or description has changed. The user should renew any active subscriptions if this has been received.

mUpnpDeviceStatusInvalid is basically the same as mUpnpDeviceStatusRemoved, but mUpnpDeviceStatusRemoved is sent only when a device leaves the network in a proper way (i.e. with UPnP ByeBye messages). The user should immediately cease using the device, because it will be removed in both cases.

Enumeration Type Documentation

_mUpnpDeviceStatus

enum _mUpnpDeviceStatus

Device listener status parameters.

mUpnpDeviceStatusAdded means a device has been added to local cache. mUpnpDeviceStatusUpdated means a device description has been updated because its IP address or description has changed. The user should renew any active subscriptions if this has been received.

mUpnpDeviceStatusInvalid is basically the same as mUpnpDeviceStatusRemoved, but mUpnpDeviceStatusRemoved is sent only when a device leaves the network in a proper way (i.e. with UPnP ByeBye messages). The user should immediately cease using the device, because it will be removed in both cases.

Enumerator
mUpnpDeviceStatusAdded
mUpnpDeviceStatusUpdated
mUpnpDeviceStatusInvalid
mUpnpDeviceStatusRemoved

Function Documentation

mupnp_controlpoint_adddevicebyssdppacket()

void mupnp_controlpoint_adddevicebyssdppacket	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpSSDPPacket *	ssdpPkt )

Add a device on the basis of an SSDP packet. Do not call this from user applications.

Parameters

ctrlPoint	The control point, whose device list to handle
ssdpPkt	The received SSDP packet

mupnp_controlpoint_delete()

void mupnp_controlpoint_delete

(

mUpnpControlPoint *

ctrlPoint

)

Destroy a control point and free all associated resources.

Releases all resources associated with the control point, including:

• All discovered devices and their descriptions
• Network listeners (SSDP, HTTP)
• Internal mutexes and threads
• Cached network interface information

If the control point is still running when this function is called, it will be stopped automatically before resources are freed.

Parameters

ctrlPoint

The control point to destroy. May be NULL (no-op if NULL).

Note

After calling this function, the ctrlPoint 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 control point. The caller is responsible for ensuring exclusive access.

Warning

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

See also

mupnp_controlpoint_new()

mupnp_controlpoint_stop()

Destroy the given control point

Parameters

ctrlPoint

The control point struct to destroy

mupnp_controlpoint_expirationhandler()

void mupnp_controlpoint_expirationhandler

(

mUpnpThread *

thread

)

Worker thread for handling expirations.

Parameters

thread

the thread in question

mupnp_controlpoint_getdevicebyexacttype()

mUpnpDevice * mupnp_controlpoint_getdevicebyexacttype	(	mUpnpControlPoint *	ctrlPoint,
		const char *	exacttype )

Find a device by exact type string including version.

Searches the control point's device list for a device whose complete type string matches the given type, including the version number. This performs an exact string comparison.

The search includes embedded devices (child devices within root devices).

Parameters

ctrlPoint	The control point to search. Must not be NULL.
exacttype	The exact device type to match, including version. Must not be NULL. Format: "urn:schemas-upnp-org:device:<deviceType>:<ver>" Example: "urn:schemas-upnp-org:device:MediaServer:2"

Returns

Pointer to the first matching device, or NULL if not found or if parameters are NULL.

Note

Thread-safe: The control point should be locked with mupnp_controlpoint_lock() before calling this function and accessing the returned device pointer. Release with mupnp_controlpoint_unlock() as soon as possible.

Do not cache the returned pointer. Devices may be removed from the list at any time when the control point is unlocked.

If multiple devices match, only the first one found is returned.

Warning

The returned pointer is only valid while the control point is locked.

See also

mupnp_controlpoint_getdevicebytype()

mupnp_controlpoint_getdevicebyudn()

mupnp_controlpoint_lock()

// Example: Find and use a device safely
mupnp_controlpoint_lock(ctrlPoint);
 
mUpnpDevice* dev = mupnp_controlpoint_getdevicebyexacttype(
    ctrlPoint, "urn:schemas-upnp-org:device:MediaServer:2");
 
if (dev != NULL) {
    const char* friendlyName = mupnp_device_getfriendlyname(dev);
    printf("Found device: %s\n", friendlyName);
}
 
mupnp_controlpoint_unlock(ctrlPoint);
// dev pointer is now invalid

Find a device from the control point by the exact 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, use mupnp_controlpoint_getdevicebytype

Parameters

ctrlPoint	Controlpoint in question
exacttype	Type of the device

mupnp_controlpoint_getdevicebytype()

mUpnpDevice * mupnp_controlpoint_getdevicebytype	(	mUpnpControlPoint *	ctrlPoint,
		const char *	type )

Find a device by type, ignoring version number.

Searches the control point's device list for a device whose type matches the given string, excluding the version suffix. This allows matching devices regardless of their version number.

The search includes embedded devices (child devices within root devices).

Parameters

ctrlPoint	The control point to search. Must not be NULL.
type	The device type to match, without version. Must not be NULL. Format: "urn:schemas-upnp-org:device:<deviceType>" Example: "urn:schemas-upnp-org:device:MediaServer" This will match "...MediaServer:1", "...MediaServer:2", etc.

Returns

Pointer to the first matching device, or NULL if not found or if parameters are NULL.

Note

Thread-safe: The control point should be locked with mupnp_controlpoint_lock() before calling this function.

To get the actual version of the matched device, use mupnp_devicetype_getversion() on the device's type string.

If multiple devices of different versions match, the first one found is returned (no specific ordering guaranteed).

See also

mupnp_controlpoint_getdevicebyexacttype()

mupnp_devicetype_getversion()

mupnp_controlpoint_lock()

Find a device from the controlpoint 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

ctrlPoint	Controlpoint in question
type	Type of the device

mupnp_controlpoint_getdevicebyudn()

mUpnpDevice * mupnp_controlpoint_getdevicebyudn	(	mUpnpControlPoint *	ctrlPoint,
		const char *	udn )

Find a device by its Unique Device Name (UDN)

Searches the control point's device list for a device with the specified UDN. The UDN uniquely identifies a device instance, even if multiple devices of the same type exist on the network.

The search includes embedded devices (child devices within root devices).

Parameters

ctrlPoint	The control point to search. Must not be NULL.
udn	The Unique Device Name to search for. Must not be NULL. Format: "uuid:<device-UUID>" Example: "uuid:12345678-1234-1234-1234-123456789abc"

Returns

Pointer to the matching device, or NULL if not found or if parameters are NULL.

Note

Thread-safe: The control point should be locked with mupnp_controlpoint_lock() before calling this function.

UDNs are unique per device instance, so at most one device will match.

The UDN persists across device restarts if properly implemented by the device manufacturer.

See also

mupnp_controlpoint_getdevicebytype()

mupnp_device_getudn()

mupnp_controlpoint_lock()

Find a device from the controlpoint by the UDN of the device.

Parameters

ctrlPoint	Controlpoint in question
udn	Type of the device

mupnp_controlpoint_geteventsubcallbackurl()

const char * mupnp_controlpoint_geteventsubcallbackurl	(	mUpnpControlPoint *	ctrlPoint,
		char *	ifaddr,
		char *	buf,
		size_t	bufLen )

Get the event subscription callback URI

Parameters

ctrlPoint

The control point in question

Get the event subscription callback URI

Parameters

ctrlPoint	The control point in question
ifaddr	Interface address
buf	Buffer used to store callback url
bufLen	Buffer length

Returns

Event callback url (pointer to buf)

mupnp_controlpoint_httprequestreceived()

void mupnp_controlpoint_httprequestreceived

(

mUpnpHttpRequest *

httpReq

)

The function that calls all HTTP listener callback functions. Do not call this from applications.

Parameters

httpReq

The received HTTP request

mupnp_controlpoint_ipchanged()

bool mupnp_controlpoint_ipchanged

(

mUpnpControlPoint *

ctrlpoint

)

Notify the control point that any IP of the host has been changed.

Parameters

ctrlpoint

The control point in use

Returns

success of changing used interfaces

mupnp_controlpoint_isrunning()

bool mupnp_controlpoint_isrunning

(

mUpnpControlPoint *

ctrlPoint

)

Check if the control point is currently active.

Queries whether the control point's network services are active and ready to send/receive UPnP messages.

Parameters

ctrlPoint

The control point to query. Must not be NULL.

Return values

true	The control point is active (started)
false	The control point is inactive, or ctrlPoint is NULL

Note

Thread-safe: This function can be called from any thread at any time.

See also

mupnp_controlpoint_start()

mupnp_controlpoint_stop()

Check if the control point is activated.

Parameters

ctrlPoint

The control point to stop

Returns

true if running; otherwise false

mupnp_controlpoint_lock()

bool mupnp_controlpoint_lock

(

mUpnpControlPoint *

ctrlPoint

)

Lock the control point's mutex. The control point should be ALWAYS locked, when a mUpnpDevice*, mUpnpService*, mUpnpAction* or other pointer has been taken into use from the stack. This effectively prevents devices/services from being updated/ removed or added while the control point is locked. You should release the lock as soon as possible with mupnp_controlpoint_unlock

Note

Do NOT save any mUpnp* pointers to user-space variables. Use them only as local variables (inside one function) after gaining a mutex lock. Release the lock as soon as you are done accessing the pointer, and then discard the pointer immediately.

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_new()

mUpnpControlPoint * mupnp_controlpoint_new

(

void

)

Create a new control point instance.

Allocates and initializes a new UPnP control point object. The control point is initially inactive and does not start any network threads or listeners. You must call mupnp_controlpoint_start() to activate it and begin discovering devices on the network.

The function initializes:

• Device list (empty)
• SSDP servers for multicast listening
• HTTP servers for event reception
• Internal mutexes for thread safety
• Cached network interface list

Returns

A newly-created mUpnpControlPoint on success, or NULL if memory allocation fails

Note

The returned control point must be freed with mupnp_controlpoint_delete() when no longer needed to avoid memory leaks.

Thread-safe: This function can be called concurrently from multiple threads.

See also

mupnp_controlpoint_delete()

mupnp_controlpoint_start()

// Example: Create and start a control point
mUpnpControlPoint* ctrlPoint = mupnp_controlpoint_new();
if (ctrlPoint == NULL) {
    fprintf(stderr, "Failed to create control point\n");
    return -1;
}
 
// Set device listener before starting
mupnp_controlpoint_setdevicelistener(ctrlPoint, device_listener_callback);
 
if (!mupnp_controlpoint_start(ctrlPoint)) {
    fprintf(stderr, "Failed to start control point\n");
    mupnp_controlpoint_delete(ctrlPoint);
    return -1;
}
 
// Perform M-SEARCH to discover devices
mupnp_controlpoint_search(ctrlPoint, "ssdp:all");

Create a new control point. Does not start any threads.

Returns

A newly-created mUpnpControlPoint

mupnp_controlpoint_parsescservicescpd()

bool mupnp_controlpoint_parsescservicescpd

(

mUpnpService *

service

)

Parse the service description from the service's SCPD URL. Do not call this from user applications.

Parameters

service

The service in question

Returns

true if successful; otherwise false

mupnp_controlpoint_parseservicesfordevice()

bool mupnp_controlpoint_parseservicesfordevice	(	mUpnpDevice *	dev,
		mUpnpSSDPPacket *	ssdpPkt )

Parse the device's services using the received SSDP packet. Do not call this from user applications.

Parameters

dev	The device in question
ssdpPkt	An SSDP packet

mupnp_controlpoint_removedevicebyssdppacket()

void mupnp_controlpoint_removedevicebyssdppacket	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpSSDPPacket *	ssdpPkt )

Remove a device on the basis of an SSDP packet. Do not call this from user applications.

Parameters

ctrlPoint	The control point, whose device list to handle
ssdpPkt	The received SSDP packet

mupnp_controlpoint_resubscribe()

bool mupnp_controlpoint_resubscribe	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpService *	service,
		long	timeout )

Re-subscribe to a service's events (i.e. renew subscription)

Parameters

ctrlPoint	The control point in use
service	The service to subscribe to
timeout	Timeout for subscription expiration/renewal

Returns

true if successful; otherwise false

mupnp_controlpoint_resubscribeall()

bool mupnp_controlpoint_resubscribeall	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpDevice *	dev,
		long	timeout )

Re-subscribe to all of the device's services' events (i.e. renew subscription)

Parameters

ctrlPoint	The control point in use
dev	The device to subscribe to
timeout	Timeout for subscription expiration/renewal

Returns

true if successful; otherwise false

mupnp_controlpoint_search()

bool mupnp_controlpoint_search	(	mUpnpControlPoint *	ctrlPoint,
		const char *	target )

Send an M-SEARCH multicast message to discover UPnP devices.

Broadcasts an SSDP M-SEARCH request on all network interfaces to discover UPnP devices matching the specified search target. Devices that match will respond with unicast M-SEARCH responses, which are processed asynchronously.

The control point must be started (mupnp_controlpoint_start()) before calling this function. Discovered devices trigger the device listener callback if set.

Common search targets:

• "ssdp:all" - All devices and services
• "upnp:rootdevice" - Root devices only
• "urn:schemas-upnp-org:device:<deviceType>:<version>" - Specific device type
• "urn:schemas-upnp-org:service:<serviceType>:<version>" - Specific service type
• "uuid:<device-UUID>" - Specific device by UUID

The MX (Maximum Wait) header determines how long devices should wait before responding (default: 3 seconds). Set with mupnp_controlpoint_setssdpsearchmx().

Parameters

ctrlPoint	The control point to use. Must not be NULL and must be running.
target	The Search Target (ST) string. Must not be NULL or empty. See UPnP Device Architecture specification for valid values.

Return values

true	M-SEARCH successfully sent on at least one interface
false	Failed to send (ctrlPoint is NULL, not running, or network error)

Note

Thread-safe: Can be called from any thread.

Devices may take up to MX seconds to respond. Responses are handled asynchronously via the device listener callback.

Multiple M-SEARCH requests can be sent without waiting for responses.

Not all devices respond to M-SEARCH; some only advertise via periodic ssdp:alive messages.

See also

mupnp_controlpoint_setdevicelistener()

mupnp_controlpoint_setssdpsearchmx()

mupnp_controlpoint_start()

// Example: Discover all devices
mUpnpControlPoint* cp = mupnp_controlpoint_new();
mupnp_controlpoint_setdevicelistener(cp, my_device_listener);
mupnp_controlpoint_start(cp);
 
// Search for all devices
if (mupnp_controlpoint_search(cp, "ssdp:all")) {
    printf("M-SEARCH sent, waiting for responses...\n");
    sleep(5); // Wait for devices to respond
}
 
// Search for specific device type
mupnp_controlpoint_search(cp, "urn:schemas-upnp-org:device:MediaRenderer:1");

Do an M-SEARCH to look for devices in the network.

Parameters

ctrlPoint	The control point in question
target	The Search Target parameter (ex. "ssdp:all")

mupnp_controlpoint_seteventlistener()

bool mupnp_controlpoint_seteventlistener	(	mUpnpControlPoint *	ctrlPoint,
		MUPNP_EVENT_LISTENER	evlistener )

Set a single event listener for the control point. Use this function to get event notifications to user-space applications if you need only one listener.

Parameters

ctrlPoint	The control point in question
evlistener	The callback function to set, that is of type MUPNP_EVENT_LISTENER, or NULL

mupnp_controlpoint_start()

bool mupnp_controlpoint_start

(

mUpnpControlPoint *

ctrlPoint

)

Activate the control point and start network listeners.

Starts all network services required for UPnP operation:

• SSDP multicast listeners on all network interfaces
• SSDP unicast response servers (default port: 39400)
• HTTP event notification servers (default port: 39500)
• Device expiration monitoring thread

After successful activation, the control point will:

• Receive and process SSDP advertisements (ssdp:alive, ssdp:byebye)
• Respond to M-SEARCH requests if configured
• Accept event subscriptions and notifications
• Automatically remove expired devices

The control point must be started before performing any network operations such as device discovery or action invocations.

Parameters

ctrlPoint

The control point to activate. Must not be NULL.

Return values

true	Successfully started all services
false	Failed to start (e.g., port already in use, network error, insufficient permissions, or ctrlPoint is NULL)

Note

This function may fail if the required ports are already in use. Use mupnp_controlpoint_setssdpresponseport() and mupnp_controlpoint_seteventport() to configure alternative ports before calling start if needed.

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

Calling this function on an already-running control point has no effect and returns true.

Warning

On some platforms, binding to multicast addresses may require elevated privileges (e.g., root/administrator).

See also

mupnp_controlpoint_stop()

mupnp_controlpoint_isrunning()

mupnp_controlpoint_search()

Activate the control point. Starts listening for SSDP messages etc. You must call this function before you can actually use a control point.

Parameters

ctrlPoint

The control point to start

Returns

true if successful; otherwise false

mupnp_controlpoint_stop()

bool mupnp_controlpoint_stop

(

mUpnpControlPoint *

ctrlPoint

)

Stop the control point and shut down network listeners.

Gracefully shuts down all network services:

• Closes all SSDP multicast listeners
• Closes SSDP unicast response servers
• Closes HTTP event notification servers
• Terminates the device expiration monitoring thread

After stopping, the control point will no longer:

• Receive SSDP advertisements or M-SEARCH requests
• Accept event notifications
• Monitor device expirations

However, the device list is retained and can be accessed after stopping. The control point can be restarted with mupnp_controlpoint_start().

Parameters

ctrlPoint

The control point to stop. Must not be NULL.

Return values

true	Successfully stopped all services
false	Failed to stop (unlikely), or ctrlPoint is NULL

Note

This function blocks until all listener threads have terminated. This may take up to a few seconds.

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

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

Active event subscriptions are not automatically cancelled. The application should explicitly unsubscribe before stopping if cleanup is required.

See also

mupnp_controlpoint_start()

mupnp_controlpoint_isrunning()

mupnp_controlpoint_delete()

Stop the control point. Stops sending/receiveing/responding to any messages.

Parameters

ctrlPoint

The control point to stop

Returns

true if successful; otherwise false

mupnp_controlpoint_subscribe()

bool mupnp_controlpoint_subscribe	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpService *	service,
		long	timeout )

Subscribe to a UPnP service's event notifications.

Sends a SUBSCRIBE request to the service's event subscription URL to receive notifications when the service's state variables change. The service will send an initial event message with current values, followed by updates whenever evented state variables change.

The subscription is identified by a Subscription ID (SID) returned by the service and stored in the service object. Event notifications are received on the control point's HTTP event server and dispatched to registered event listeners.

Subscriptions must be renewed before they expire using mupnp_controlpoint_resubscribe() or they will be automatically cancelled by the service.

Parameters

ctrlPoint	The control point to use. Must not be NULL and must be running.
service	The service to subscribe to. Must not be NULL and must have a valid event subscription URL.
timeout	The requested subscription duration in seconds. Use 0 or negative value for infinite duration (if supported by the service). Typical values: 300-1800 seconds. The service may grant a different duration than requested.

Return values

true	Subscription successful. Check service's SID for subscription ID.
false	Subscription failed due to: NULL parameters Control point not running Network error Service doesn't support eventing Service rejected subscription (e.g., too many subscribers)

Note

Thread-safe: Can be called from any thread, but the control point should be locked if accessing device/service pointers.

Side effect: Updates the service's subscriptionSid and subscriptionTimeout fields on success.

Event notifications are delivered asynchronously via event listener callbacks. Set listeners with mupnp_controlpoint_addeventlistener().

The initial event notification (containing all evented state variables) should arrive shortly after subscription.

Warning

Always unsubscribe before destroying the control point to avoid orphaned subscriptions on the service side.

See also

mupnp_controlpoint_resubscribe()

mupnp_controlpoint_unsubscribe()

mupnp_controlpoint_addeventlistener()

mupnp_service_getsubscriptionsid()

// Example: Subscribe to a service's events
mupnp_controlpoint_lock(ctrlPoint);
mUpnpDevice* dev = mupnp_controlpoint_getdevicebytype(ctrlPoint, "...:MediaServer");
if (dev) {
    mUpnpService* service = mupnp_device_getservicebytype(dev, "ContentDirectory");
    if (service) {
        // Subscribe for 30 minutes
        if (mupnp_controlpoint_subscribe(ctrlPoint, service, 1800)) {
            printf("Subscribed with SID: %s\n", 
                   mupnp_service_getsubscriptionsid(service));
        }
    }
}
mupnp_controlpoint_unlock(ctrlPoint);

mupnp_controlpoint_subscribeall()

bool mupnp_controlpoint_subscribeall	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpDevice *	dev,
		long	timeout )

Subscribe to all of the device's services' events

Parameters

ctrlPoint	The control point in use
dev	The device to subscribe to
timeout	Timeout for subscription expiration/renewal

Returns

true if successful; otherwise false

mupnp_controlpoint_unlock()

bool mupnp_controlpoint_unlock

(

mUpnpControlPoint *

ctrlPoint

)

Release a previously locked control point mutex. See mupnp_controlpoint_lock for a more detailed description on the control point locking mechanism.

Parameters

ctrlPoint

The control point in question

mupnp_controlpoint_unsubscribe()

bool mupnp_controlpoint_unsubscribe	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpService *	service )

Unsubscribe to a service's events (i.e. cancel subscription)

Parameters

ctrlPoint	The control point in use
service	The service to unsubscribe to

Returns

true if successful; otherwise false

mupnp_controlpoint_unsubscribeall()

bool mupnp_controlpoint_unsubscribeall	(	mUpnpControlPoint *	ctrlPoint,
		mUpnpDevice *	dev )

Unsubscribe to all of the device's services' events (i.e. cancel subscription)

Parameters

ctrlPoint	The control point in use
dev	The device to unsubscribe to

Returns

true if successful; otherwise false

mupnp_controlpoint_updatestatetablefromproperty()

void mupnp_controlpoint_updatestatetablefromproperty	(	mUpnpService *	service,
		mUpnpProperty *	prop )

When an event is received, update also the associated service's state table to include the evented state variable.

Parameters

service	The service, whose state table to update
prop	The evented property from which to update