UPnPClient::UPnPDeviceDirectory Class Reference

Manage UPnP discovery and maintain a directory of active devices. More...

#include <discovery.hxx>

Public Types
typedef std::function< bool(const UPnPDeviceDesc &, const UPnPServiceDesc &)>	Visitor
	Type of user callback functions used for reporting devices and services.

Public Member Functions
bool	traverse (Visitor)
	Possibly wait for the end of the initial delay, then traverse the directory and call Visitor for each device/service pair.
time_t	getRemainingDelayMs ()
	Remaining milliseconds until current search complete. More...
time_t	getRemainingDelay ()
	Remaining seconds until current search complete. More...
bool	getDevByFName (const std::string &fname, UPnPDeviceDesc &ddesc)
	Find device by 'friendly name'. More...
bool	getDevByUDN (const std::string &udn, UPnPDeviceDesc &ddesc)
	Find device by UDN. More...
bool	getDescriptionDocuments (const std::string &uidOrFriendly, std::string &deviceXML, std::unordered_map< std::string, std::string > &srvsXML)
	Helper function: retrieve all description data for a named device. More...
bool	ok ()
	My health.
const std::string	getReason ()
	My diagnostic if health is bad.

Static Public Member Functions
static UPnPDeviceDirectory *	getTheDir (time_t search_window=2)
	Retrieve the singleton object for the discovery service, and possibly start it up if this is the first call. More...
static void	terminate ()
	Clean up before exit. More...
static unsigned int	addCallback (Visitor v)
	Set a callback to be called when devices report their existence The function will be called once per device, with an empty service, Note that calls to v may be performed from a separate thread and some may occur before addCallback() returns.
static void	delCallback (unsigned int idx)

Detailed Description

Manage UPnP discovery and maintain a directory of active devices.

Singleton.

The service is initialized on the first call, starting the message-handling thread, registering our message handlers, and initiating an asynchronous UPnP device search.

The search implies a timeout period (the specified interval over which the servers will send replies at random points). Any subsequent traverse() call will block until the timeout is expired. Use getRemainingDelayMs() to know the current remaining delay, and use it to do something else.

We need a separate thread to process the messages coming up from libupnp, because some of them will in turn trigger other calls to libupnp, and this must not be done from the libupnp thread context which reported the initial message. So there are three threads in action:

• The reporting thread from libupnp.
• The discovery service processing thread, which also runs the callbacks.
• The user thread (typically the main thread), which calls traverse.

Member Function Documentation

getDescriptionDocuments()

bool UPnPClient::UPnPDeviceDirectory::getDescriptionDocuments	(	const std::string &	uidOrFriendly,
		std::string &	deviceXML,
		std::unordered_map< std::string, std::string > &	srvsXML
	)

Helper function: retrieve all description data for a named device.

Parameters

uidOrFriendly	device identification. First tried as UUID then friendly name.

getDevByFName()

bool UPnPClient::UPnPDeviceDirectory::getDevByFName	(	const std::string &	fname,
		UPnPDeviceDesc &	ddesc
	)

Find device by 'friendly name'.

This will wait for the remaining duration of the search window if the device is not found at once. Note that "friendly names" are not necessarily unique. The method will return a random instance (the first found) if there are several.

Parameters

	fname	the device UPnP "friendly name" to be looked for
[out]	ddesc	the description data if the device was found.

Returns

true if the name was found, else false.

getDevByUDN()

bool UPnPClient::UPnPDeviceDirectory::getDevByUDN	(	const std::string &	udn,
		UPnPDeviceDesc &	ddesc
	)

Find device by UDN.

This will wait for the remaining duration of the search window if the device is not found at once.

Parameters

	udn	the device Unique Device Name, a UUID.
[out]	ddesc	the description data if the device was found.

Returns

true if the device was found, else false.

getRemainingDelay()

time_t UPnPClient::UPnPDeviceDirectory::getRemainingDelay

(

)

Remaining seconds until current search complete.

Better use getRemainingDelayMs(), this is kept only for compatibility.

getRemainingDelayMs()

time_t UPnPClient::UPnPDeviceDirectory::getRemainingDelayMs

(

)

Remaining milliseconds until current search complete.

getTheDir()

UPnPDeviceDirectory * UPnPClient::UPnPDeviceDirectory::getTheDir ( time_t  search_window = 2 )

static

Retrieve the singleton object for the discovery service, and possibly start it up if this is the first call.

This does not wait significantly: a subsequent traverse() will wait until the initial delay is consumed. 2 S is libupnp MIN_SEARCH_WAIT, I don't see much reason to use more

terminate()

void UPnPClient::UPnPDeviceDirectory::terminate ( )

static

Clean up before exit.

Do call this.

---

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

• /home/dockes/projets/mpdupnp/libupnpp/libupnpp/control/discovery.hxx
• /home/dockes/projets/mpdupnp/libupnpp/libupnpp/control/discovery.cxx