UPnPP::LibUPnP Class Reference

Our link to libupnp. More...

#include <upnpplib.hxx>

Classes
class	Internal

Public Types
enum	InitFlags { UPNPPINIT_FLAG_NONE = 0 , UPNPPINIT_FLAG_NOIPV6 = 0x1 , UPNPPINIT_FLAG_SERVERONLY = 0x2 , UPNPPINIT_FLAG_RESANITIZE_URLS = 0x4 }
	Configuration flags for the initialisation call. More...
enum	InitOption {   UPNPPINIT_OPTION_END = 0 , UPNPPINIT_OPTION_IFNAMES , UPNPPINIT_OPTION_IPV4 , UPNPPINIT_OPTION_PORT ,   UPNPPINIT_OPTION_SUBSCRIPTION_TIMEOUT , UPNPPINIT_OPTION_CLIENT_PRODUCT , UPNPPINIT_OPTION_CLIENT_VERSION , UPNPPINIT_OPTION_SUBSOPS_TIMEOUTMS ,   UPNPPINIT_OPTION_RESANITIZED_CHARS , UPNPPINIT_OPTION_BOOTID }
	Options for the initialisation call. More...
enum	LogLevel {   LogLevelNone , LogLevelError , LogLevelInfo , LogLevelDebug ,   LogLevelAll }
	libnpupnp (pupnp) logging: this is distinct from libupnpp logging More...

Public Member Functions
	LibUPnP (const LibUPnP &)=delete
LibUPnP &	operator= (const LibUPnP &)=delete
std::string	host ()
	Return the IP v4 address as dotted notation.
std::string	port ()
	Return the listening port.
std::string	hwaddr ()
	Return one ethernet address.
bool	setWebServerDocumentRoot (const std::string &rootpath)
	Set the root/base directory for the HTTP server.
void	setMaxContentLength (int bytes)
	Set max library buffer size for reading content from servers.
bool	ok () const
	Check state after initialization.

Static Public Member Functions
static bool	init (unsigned int flags,...)
	Initialize the library, with more complete control than a direct getLibUPnP() call.
static LibUPnP *	getLibUPnP (bool serveronly=false, std::string *hwaddr=0, const std::string ifname=std::string(), const std::string ip=std::string(), unsigned short port=0)
	Retrieve the singleton LibUPnP object.
static std::string	versionString ()
	Returns something like "libupnpp 0.14.0 libupnp x.y.z".
static bool	setLogFileName (const std::string &fn, LogLevel level=LogLevelError)
	Set libnpupnp log file name and activate/deactivate logging.
static bool	setLogLevel (LogLevel level)
	Set libnpupnp log level.
static int	getInitError ()
	Retrieve init error if state not ok.
static std::string	makeDevUUID (const std::string &name, const std::string &hw)
	Build a unique stable UUID.
static std::string	errAsString (const std::string &who, int code)
	Translate libupnp integer error code (UPNP_E_XXX) to string.

Public Attributes
class UPNPP_LOCAL	Internal
Internal *	m

Detailed Description

Our link to libupnp.

Initialize and keep the handle around.

Not all applications will need to use this. The initialization call will be performed internally as needed, you only need to call it if you need to set specific parameters.

Member Enumeration Documentation

InitFlags

enum UPnPP::LibUPnP::InitFlags

Configuration flags for the initialisation call.

Enumerator
UPNPPINIT_FLAG_NOIPV6	Disable IPV6 support.
UPNPPINIT_FLAG_SERVERONLY	Do not initialize the client side (we are a device)
UPNPPINIT_FLAG_RESANITIZE_URLS	Perform extra escaping on URLs read from a content directory. This will encode some characters which have a tendancy to cause problems even if they do not have to be escaped according to the standard. Unfortunately, this also causes issues with some UPnP/AV renderers (Yamaha) which emit change event containing the (maybe partially) decoded* URLs, which breaks string comparisons in the CP. This could be worked around in Upplay, but this also triggers issues inside other CPs, e.g. when Bubble server is proxying an UPnP/AV renderer.

InitOption

enum UPnPP::LibUPnP::InitOption

Options for the initialisation call.

Each option argument may be followed by specific parameters.

Enumerator
UPNPPINIT_OPTION_END	Terminate the VARARGs list.
UPNPPINIT_OPTION_IFNAMES	Names of the interfaces to use. A const std::string* follows. This is a space-separated list. If not set, we will use the first interface. If set to '*', we will use all possible interfaces. Use an empty string to keep the default setting.
UPNPPINIT_OPTION_IPV4	Use single IPV4 address. A const std::string* address in dot notation follows. This is incompatible with OPTION_IFNAMES. Use an empty string to keep the default value.
UPNPPINIT_OPTION_PORT	IP Port to use. An int parameter follows. The lower lib default is 49152.
UPNPPINIT_OPTION_SUBSCRIPTION_TIMEOUT	Control: subscription timeout in seconds. An int parameter follows. Default: 1800.
UPNPPINIT_OPTION_CLIENT_PRODUCT	Control: product name to set in user-agent strings. A const std::string* follows. Use an empty string to keep the default.
UPNPPINIT_OPTION_CLIENT_VERSION	Control: product version to set in user-agent strings. A const std::string* follows. Use an empty string to keep the default.
UPNPPINIT_OPTION_SUBSOPS_TIMEOUTMS	Control: HTTP timeout for subscription/unsubscriptions connections to the device. The libupnp default of 30000 ms is very high. An int parameter follows. Use -1 to keep the default.
UPNPPINIT_OPTION_RESANITIZED_CHARS	Control: characters that we should further url-escape when found in URLs out of a content directory. The default is <!$'()+,> (delimited by excluded <>) A const std::string* follows. Use an empty string to keep the default.
UPNPPINIT_OPTION_BOOTID	Device: UPnP 1.1 BOOTINIT.UPNP.ORG value. int value. Use -1 to keep the constant default of 1

LogLevel

enum UPnPP::LibUPnP::LogLevel

libnpupnp (pupnp) logging: this is distinct from libupnpp logging

libnpupnp log levels

Member Function Documentation

getLibUPnP()

LibUPnP * UPnPP::LibUPnP::getLibUPnP ( bool  serveronly = false, std::string *  hwaddr = 0, const std::string  ifname = std::string(), const std::string  ip = std::string(), unsigned short  port = 0  )

static

Retrieve the singleton LibUPnP object.

Using this call with arguments is deprecated. Call init() instead, (creates the lib) then getLibUPnP() without arguments.

This initializes libupnp, possibly setting an address and port, possibly registering a client if serveronly is false.

Parameters

serveronly	no client init
[output]	hwaddr returns the hardware address for the specified network interface, or the first one is ifname is empty. If the IP address is specified instead of the interface name, the hardware address returned is not necessarily the one matching the IP.
ifname	if not empty, network interface to use. Passed to libnpupnp. Null or empty to use the first interface, "*" for all interfaces, or space-separated list of interface names.
ip	if not empty, IP address to use. Only used if ifname is empty.
port	port parameter to UpnpInit() (0 for default).

Returns

0 for failure.

init()

bool UPnPP::LibUPnP::init ( unsigned int  flags,   ...  )

static

Initialize the library, with more complete control than a direct getLibUPnP() call.

On success you will then call getLibUPnP() to access the object instance.

Parameters

flags	A bitfield of InitFlags values.
...	A list of InitOption and values, ended by UPNPPINIT_OPTION_END.

Returns

false for failure, true for success.

makeDevUUID()

string UPnPP::LibUPnP::makeDevUUID ( const std::string &  name, const std::string &  hw  )

static

Build a unique stable UUID.

This uses a hash of the input name (e.g.: friendlyName), and the Ethernet address.

Parameters

name	device "friendly name"
hw	device ethernet address (as 12 ascii hexadecimal bytes)

setLogFileName()

bool UPnPP::LibUPnP::setLogFileName ( const std::string &  fn, LogLevel  level = LogLevelError  )

static

Set libnpupnp log file name and activate/deactivate logging.

Do not use the same file as the one used for libupnpp logging.

Parameters

fn	file name to use. Use an empty string log to stderr.
level	verbosity. Set to LogLevelNone to turn off.

setLogLevel()

bool UPnPP::LibUPnP::setLogLevel ( LogLevel  level )

static

Set libnpupnp log level.

Returns

true if logging is enabled, else false.

setMaxContentLength()

void UPnPP::LibUPnP::setMaxContentLength

(

int

bytes

)

Set max library buffer size for reading content from servers.

Just calls libupnp UpnpSetMaxContentLength(). This defines the maximum amount of data that Soap calls will accept from the remote. The libupnp default is very low (16KB), but libupnpp sets the value to 2MB during initialization. You can reset the value to your own choice by using this method.

setWebServerDocumentRoot()

bool UPnPP::LibUPnP::setWebServerDocumentRoot

(

const std::string &

rootpath

)

Set the root/base directory for the HTTP server.

This is for serving files directly from the file system. If this is not called, no local files will be directly served, all data will have to go through the VDir interface.

Parameters

rootpath

the absolute path to a file system directory. The paths for all requests which do not match a virtual directory will be interpreted as subdirectories of rootpath.

---

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

• /home/dockes/projets/mpdupnp/libupnpp/libupnpp/upnpplib.hxx
• /home/dockes/projets/mpdupnp/libupnpp/libupnpp/upnpplib.cxx