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
	UPnPDeviceDirectory (const UPnPDeviceDirectory &)=delete
UPnPDeviceDirectory &	operator= (const UPnPDeviceDirectory &)=delete
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 the initial search window complete.
time_t	getRemainingDelay ()
	Remaining seconds until current search complete.
bool	getDevByFName (const std::string &fname, UPnPDeviceDesc &ddesc)
	Find device by 'friendly name'.
bool	getDevByUDN (const std::string &udn, UPnPDeviceDesc &ddesc)
	Find device by UDN.
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.
bool	uniSearch (const std::string &url)
	Directed (unicast) search.
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.
static void	terminate ()
	Clean up before exit.
static unsigned int	addCallback (Visitor v)
	Set a callback to be called when devices report their existence.
static void	delCallback (unsigned int idx)
	Unregister device existence callback.
static unsigned int	addLostCallback (Visitor v)
	Set a callback to be called when a device signals that it is stopping service, or when it is lost because it did not signal before its discovery timeout.
static void	delLostCallback (unsigned int idx)
	Unset "Lost" callback.

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.

Once initialisation is complete, we supposedly maintain a complete directory of the upnp devices on the network, using their advertisement messages. However a new search operation will be triggered by the user calling any of the lookup functions, if the last search is older than 5 s.

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

addCallback()

unsigned int UPnPClient::UPnPDeviceDirectory::addCallback ( UPnPDeviceDirectory::Visitor  v )

static

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.

delCallback()

void UPnPClient::UPnPDeviceDirectory::delCallback ( unsigned int  idx )

static

Unregister device existence callback.

The arg. is the value returned by addCallback()

delLostCallback()

void UPnPClient::UPnPDeviceDirectory::delLostCallback ( unsigned int  idx )

static

Unset "Lost" callback.

The argument is the value returned by addLostCallback()

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.
[output]	deviceXML device description document.
[output]	srvsXML service name - service description map.

Returns

true for success.

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 initial search window if the device is not found at once. Later calls will trigger a search but will not wait. 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 initial search window if the device is not found at once. Later calls will trigger a search but will not wait.

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 the initial search window complete.

Further searchs do not reinitialise the window and the function will always return 0.

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.

uniSearch()

bool UPnPClient::UPnPDeviceDirectory::uniSearch

(

const std::string &

url

)

Directed (unicast) search.

This will trigger a unicast search to the device which sent the

Parameters

url

in an earlier discovery message (this would be typically obtained by the library user as an UPnPDeviceDesc URLBase field). This may enable more reliable discovery in networking environments when multicast communication is very unreliable. Note that this is still an asynchronous method, and you should either wait for approximately 1 s or use a callback (above) to check for results.

---

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