upnpapi.hpp File Reference

Inititalize the compatible library before it can be used. More...

#include <GenlibClientSubscription.hpp>
#include <TimerThread.hpp>
#include <VirtualDir.hpp>
#include <service_table.hpp>

Include dependency graph for upnpapi.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	Handle_Info
	Data to be stored in handle table for Handle Info. More...
struct	UpnpNonblockParam
	UpnpNonblockParam. More...

Macros
#define	MAX_INTERFACES   256
	MAX_INTERFACES.
#define	DEV_LIMIT   200
	DEV_LIMIT.
#define	DEFAULT_MX   5
	DEFAULT_MX.
#define	DEFAULT_MAXAGE   1800
	DEFAULT_MAXAGE.
#define	DEFAULT_SOAP_CONTENT_LENGTH   16000
	DEFAULT_SOAP_CONTENT_LENGTH.
#define	MAX_SOAP_CONTENT_LENGTH   (size_t)32000
	MAX_SOAP_CONTENT_LENGTH.
#define	UPNP_TIMEOUT   30
	UPNP_TIMEOUT.
#define	HandleLock()   HandleWriteLock()
	HandleLock.
#define	HandleWriteLock()   pthread_rwlock_wrlock(&GlobalHndRWLock);
	HandleWriteLock.
#define	HandleReadLock()   pthread_rwlock_rdlock(&GlobalHndRWLock);
	HandleReadLock.
#define	HandleUnlock()   pthread_rwlock_unlock(&GlobalHndRWLock);
	HandleUnlock.
#define	E_HTTP_SYNTAX   -6
	E_HTTP_SYNTAX.

Enumerations
enum	Upnp_Handle_Type { HND_TABLE_INVALID = -2 , HND_INVALID , HND_CLIENT , HND_DEVICE }
enum	UpnpFunName {   SUBSCRIBE , UNSUBSCRIBE , DK_NOTIFY , QUERY ,   ACTION , STATUS , DEVDESCRIPTION , SERVDESCRIPTION ,   MINI , RENEW }
	UpnpFunName. More...
enum	WebServerState { WEB_SERVER_DISABLED , WEB_SERVER_ENABLED }
	Possible status of the internal webserver. More...

Functions
Upnp_Handle_Type	GetHandleInfo (int Hnd, struct Handle_Info **HndInfo)
	Get handle information.
Upnp_Handle_Type	GetClientHandleInfo (int *client_handle_out, struct Handle_Info **HndInfo)
	Get client handle info.
Upnp_Handle_Type	GetDeviceHandleInfo (UpnpDevice_Handle start, int AddressFamily, int *device_handle_out, struct Handle_Info **HndInfo)
	Retrieves the device handle and information of the first device of the address family specified. The search begins at the 'start' index, which should be 0 for the first call, then the last successful value returned. This allows listing all entries for the address family.
Upnp_Handle_Type	GetDeviceHandleInfoForPath (const char *path, int AddressFamily, int *device_handle_out, struct Handle_Info **HndInfo, service_info **serv_info)
	Retrieves the device handle and information of the first device of the address family specified, with a service having a controlURL or eventSubURL matching the path.
void	UpnpThreadDistribution (struct UpnpNonblockParam *Param)
	UpnpThreadDistribution.
void	AutoAdvertise (void *input)
	This function is a timer thread scheduled by UpnpSendAdvertisement to the send advetisement again.
int	PrintHandleInfo (UpnpClient_Handle Hnd)
	Print handle info.

Variables
constexpr int	NUM_HANDLE {200}
	Maximal number of available UPnP Unit handles.
size_t	g_maxContentLength
	Maximum content-length (in bytes) that the SDK will process on an incoming packet.
int	g_UpnpSdkEQMaxLen
	Global variable to determines the maximum number of events.
int	g_UpnpSdkEQMaxAge
	Global variable to determine the maximum number of seconds which an event can spend on a subscription queue.
pthread_rwlock_t	GlobalHndRWLock
	rwlock to synchronize handles (root device or control point handle).
PUPNP_API char	gIF_NAME [LINE_SIZE]
	Buffer to contain used network interface name. (extern'ed in upnp.h)
PUPNP_API char	gIF_IPV4 [INET_ADDRSTRLEN]
	IPv4 buffer to contain interface address. (extern'ed in upnp.h)
PUPNP_API char	gIF_IPV4_NETMASK [INET_ADDRSTRLEN]
	IPv4 buffer to contain interface netmask. (extern'ed in upnp.h)
PUPNP_API char	gIF_IPV6 [INET6_ADDRSTRLEN]
	IPv6 LLA buffer to contain interface address. (extern'ed in upnp.h)
PUPNP_API unsigned	gIF_IPV6_PREFIX_LENGTH
	IPv6 LLA prefix length. (extern'ed in upnp.h)
PUPNP_API char	gIF_IPV6_ULA_GUA [INET6_ADDRSTRLEN]
	IPv6 GUA buffer to contain interface IPv6 global-unicast address.
PUPNP_API unsigned	gIF_IPV6_ULA_GUA_PREFIX_LENGTH
	IPv6 GUA prefix length. (extern'ed in upnp.h)
PUPNP_API unsigned	gIF_INDEX
	Index/scope-id from the used network interface.
PUPNP_API unsigned short	LOCAL_PORT_V4
	IPv4 local port for the mini-server.
PUPNP_API unsigned short	LOCAL_PORT_V6
	IPv6 LLA port for the mini-server.
PUPNP_API unsigned short	LOCAL_PORT_V6_ULA_GUA
	IPv6 GUA port for the mini-server.
Upnp_SID	gUpnpSdkNLSuuid
	Global variable used in discovery notifications.
TimerThread	gTimerThread
	Global timer thread.
ThreadPool	gRecvThreadPool
	Receive thread pool.
ThreadPool	gSendThreadPool
	Send thread pool.
ThreadPool	gMiniServerThreadPool
	Mini server thread pool.
virtualDirList *	pVirtualDirList
	Pointer to the virtual directory list.
struct VirtualDirCallbacks	virtualDirCallback
	This structure is for virtual directory callbacks.
WebServerState	bWebServerState
	Flag to indicate the state of web server.
WebCallback_HostValidate	gWebCallback_HostValidate
	webCallback for HOST validation.
void *	gWebCallback_HostValidateCookie
	Cookie to the webCallback for HOST validation.
int	gAllowLiteralHostRedirection
	Allow literal host names redirection to numeric host names.

Detailed Description

Inititalize the compatible library before it can be used.

Definition in file upnpapi.hpp.

---

Class Documentation

Handle_Info

struct Handle_Info

Data to be stored in handle table for Handle Info.

Definition at line 86 of file upnpapi.hpp.

Collaboration diagram for Handle_Info:

Class Members
Upnp_Handle_Type	HType	Handle Type.
Upnp_FunPtr	Callback	Callback function pointer.
char *	Cookie	???
int	aliasInstalled	0 = not installed; otherwise installed.
char	DescURL[LINE_SIZE]	URL for the use of SSDP.
char	LowerDescURL[LINE_SIZE]	URL for the use of SSDP when answering to legacy CPs (CP searching for a v1 when the device is v2).
char	DescXML[LINE_SIZE]	XML file path for device description.
int	MaxAge	Advertisement timeout.
int	PowerState	Power State as defined by UPnP Low Power.
int	SleepPeriod	Sleep Period as defined by UPnP Low Power.
int	RegistrationState	Registration State as defined by UPnP Low Power.
IXML_Document *	DescDocument	Description parsed in terms of DOM document.
IXML_NodeList *	DeviceList	List of devices in the description document.
IXML_NodeList *	ServiceList	List of services in the description document.
service_table	ServiceTable	Table holding subscriptions and URL information.
int	MaxSubscriptions	???
int	MaxSubscriptionTimeOut	???
int	DeviceAf	Address family: AF_INET6 or AF_INET.
GenlibClientSubscription *	ClientSubList	Client subscription list.
LinkedList	SsdpSearchList	Active SSDP searches.

UpnpNonblockParam

struct UpnpNonblockParam

UpnpNonblockParam.

Definition at line 258 of file upnpapi.hpp.

Collaboration diagram for UpnpNonblockParam:

Class Members
UpnpFunName	FunName	UpnpNonblockParam
int	Handle	UpnpNonblockParam
int	TimeOut	UpnpNonblockParam
char	VarName[NAME_SIZE]	UpnpNonblockParam
char	NewVal[NAME_SIZE]	UpnpNonblockParam
char	DevType[NAME_SIZE]	UpnpNonblockParam
char	DevId[NAME_SIZE]	UpnpNonblockParam
char	ServiceType[NAME_SIZE]	UpnpNonblockParam
char	ServiceVer[NAME_SIZE]	UpnpNonblockParam
char	Url[NAME_SIZE]	UpnpNonblockParam
Upnp_SID	SubsId	UpnpNonblockParam
char *	Cookie	UpnpNonblockParam
Upnp_FunPtr	Fun	UpnpNonblockParam
IXML_Document *	Header	UpnpNonblockParam
IXML_Document *	Act	UpnpNonblockParam
struct DevDesc *	Devdesc	UpnpNonblockParam

Macro Definition Documentation

MAX_INTERFACES

#define MAX_INTERFACES   256

MAX_INTERFACES.

Definition at line 49 of file upnpapi.hpp.

DEV_LIMIT

#define DEV_LIMIT   200

DEV_LIMIT.

Definition at line 52 of file upnpapi.hpp.

DEFAULT_MX

#define DEFAULT_MX   5

DEFAULT_MX.

Definition at line 55 of file upnpapi.hpp.

DEFAULT_MAXAGE

#define DEFAULT_MAXAGE   1800

DEFAULT_MAXAGE.

Definition at line 58 of file upnpapi.hpp.

DEFAULT_SOAP_CONTENT_LENGTH

#define DEFAULT_SOAP_CONTENT_LENGTH   16000

DEFAULT_SOAP_CONTENT_LENGTH.

Definition at line 61 of file upnpapi.hpp.

MAX_SOAP_CONTENT_LENGTH

#define MAX_SOAP_CONTENT_LENGTH   (size_t)32000

MAX_SOAP_CONTENT_LENGTH.

Definition at line 63 of file upnpapi.hpp.

UPNP_TIMEOUT

#define UPNP_TIMEOUT   30

UPNP_TIMEOUT.

Definition at line 73 of file upnpapi.hpp.

HandleLock

#define HandleLock

(

)

HandleWriteLock()

HandleLock.

Definition at line 140 of file upnpapi.hpp.

HandleWriteLock

#define HandleWriteLock

(

)

pthread_rwlock_wrlock(&GlobalHndRWLock);

HandleWriteLock.

Definition at line 143 of file upnpapi.hpp.

HandleReadLock

#define HandleReadLock

(

)

pthread_rwlock_rdlock(&GlobalHndRWLock);

HandleReadLock.

Definition at line 146 of file upnpapi.hpp.

HandleUnlock

#define HandleUnlock

(

)

pthread_rwlock_unlock(&GlobalHndRWLock);

HandleUnlock.

Definition at line 149 of file upnpapi.hpp.

E_HTTP_SYNTAX

#define E_HTTP_SYNTAX   -6

E_HTTP_SYNTAX.

Definition at line 287 of file upnpapi.hpp.

Enumeration Type Documentation

Upnp_Handle_Type

enum Upnp_Handle_Type

Specifies if a UPnP Device, or a control point has to be handled for a connection.

Definition at line 77 of file upnpapi.hpp.

UpnpFunName

enum UpnpFunName

UpnpFunName.

Definition at line 244 of file upnpapi.hpp.

WebServerState

enum WebServerState

Possible status of the internal webserver.

Definition at line 284 of file upnpapi.hpp.

Function Documentation

GetHandleInfo()

Upnp_Handle_Type GetHandleInfo	(	int	Hnd,
		struct Handle_Info **	HndInfo
	)

Get handle information.

Returns

HND_DEVICE, HND_CLIENT, HND_INVALID, HND_TABLE_INVALID

Parameters

[in]	Hnd	handle number (table index for the handle structure table).
[out]	HndInfo	handle structure passed by this function.

Definition at line 3339 of file upnpapi.cpp.

Here is the caller graph for this function:

GetClientHandleInfo()

Upnp_Handle_Type GetClientHandleInfo	(	int *	client_handle_out,
		struct Handle_Info **	HndInfo
	)

Get client handle info.

Note

The logic around the use of this function should be revised.

Returns

HND_CLIENT, HND_INVALID

Parameters

[in]	client_handle_out	client handle pointer (key for the client handle structure).
[out]	HndInfo	Client handle structure passed by this function.

Definition at line 3245 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

GetDeviceHandleInfo()

Upnp_Handle_Type GetDeviceHandleInfo	(	UpnpDevice_Handle	start,
		int	AddressFamily,
		int *	device_handle_out,
		struct Handle_Info **	HndInfo
	)

Retrieves the device handle and information of the first device of the address family specified. The search begins at the 'start' index, which should be 0 for the first call, then the last successful value returned. This allows listing all entries for the address family.

Returns

HND_DEVICE or HND_INVALID

Parameters

[in]	start	place to start the search (i.e. last value returned).
[in]	AddressFamily	Address family.
[out]	device_handle_out	Device handle pointer.
[out]	HndInfo	Device handle structure passed by this function.

Definition at line 3265 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

GetDeviceHandleInfoForPath()

Upnp_Handle_Type GetDeviceHandleInfoForPath	(	const char *	path,
		int	AddressFamily,
		int *	device_handle_out,
		struct Handle_Info **	HndInfo,
		service_info **	serv_info
	)

Retrieves the device handle and information of the first device of the address family specified, with a service having a controlURL or eventSubURL matching the path.

Returns

HND_DEVICE or HND_INVALID

Parameters

	path	The Uri path.
[in]	AddressFamily	Address family.
[out]	device_handle_out	Device handle pointer.
[out]	HndInfo	Device handle structure passed by this function.
[out]	serv_info	Service info for found path.

Definition at line 3302 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

UpnpThreadDistribution()

void UpnpThreadDistribution

(

struct UpnpNonblockParam *

Param

)

UpnpThreadDistribution.

UpnpThreadDistribution.

Definition at line 3139 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

AutoAdvertise()

void AutoAdvertise

(

void *

input

)

This function is a timer thread scheduled by UpnpSendAdvertisement to the send advetisement again.

Parameters

[in]

input

Information provided to the thread.

Definition at line 3386 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

PrintHandleInfo()

int PrintHandleInfo

(

UpnpClient_Handle

Hnd

)

Print handle info.

Returns

UPNP_E_SUCCESS if successful, otherwise returns appropriate error.

Parameters

[in]

Hnd

Handle index.

Definition at line 3361 of file upnpapi.cpp.

Here is the call graph for this function:

Variable Documentation

NUM_HANDLE

constexpr int NUM_HANDLE {200}

constexpr

Maximal number of available UPnP Unit handles.

Definition at line 66 of file upnpapi.hpp.

g_maxContentLength

size_t g_maxContentLength

extern

Maximum content-length (in bytes) that the SDK will process on an incoming packet.

Content-Length exceeding this size will be not processed and error 413 (HTTP Error Code) will be returned to the remote end point.

Definition at line 166 of file upnpapi.cpp.

g_UpnpSdkEQMaxLen

int g_UpnpSdkEQMaxLen

extern

Global variable to determines the maximum number of events.

Number of events which can be queued for a given subscription before events begin to be discarded. This limits the amount of memory used for a non-responding subscribed entity.

Definition at line 174 of file upnpapi.cpp.

g_UpnpSdkEQMaxAge

int g_UpnpSdkEQMaxAge

extern

Global variable to determine the maximum number of seconds which an event can spend on a subscription queue.

Spend on a subscription queue (waiting for the event at the head of the queue to be communicated). This parameter will have no effect in most situations with the default (low) value of MAX_SUBSCRIPTION_QUEUED_EVENTS. However, if MAX_SUBSCRIPTION_QUEUED_EVENTS is set to a high value, the AGE parameter will allow pruning the queue in good conformance with the UPnP Device Architecture standard, at the price of higher potential memory use.

Definition at line 185 of file upnpapi.cpp.

GlobalHndRWLock

pthread_rwlock_t GlobalHndRWLock

extern

rwlock to synchronize handles (root device or control point handle).

Definition at line 105 of file upnpapi.cpp.

gIF_NAME

PUPNP_API char gIF_NAME[LINE_SIZE]

extern

Buffer to contain used network interface name. (extern'ed in upnp.h)

Only one network interface is supported.

Definition at line 133 of file upnpapi.cpp.

gIF_IPV4

PUPNP_API char gIF_IPV4[INET_ADDRSTRLEN]

extern

IPv4 buffer to contain interface address. (extern'ed in upnp.h)

Definition at line 152 of file upnpapi.cpp.

gIF_IPV4_NETMASK

PUPNP_API char gIF_IPV4_NETMASK[INET_ADDRSTRLEN]

extern

IPv4 buffer to contain interface netmask. (extern'ed in upnp.h)

Definition at line 154 of file upnpapi.cpp.

gIF_IPV6

PUPNP_API char gIF_IPV6[INET6_ADDRSTRLEN]

extern

IPv6 LLA buffer to contain interface address. (extern'ed in upnp.h)

Definition at line 138 of file upnpapi.cpp.

gIF_IPV6_PREFIX_LENGTH

PUPNP_API unsigned gIF_IPV6_PREFIX_LENGTH

extern

IPv6 LLA prefix length. (extern'ed in upnp.h)

Definition at line 140 of file upnpapi.cpp.

gIF_IPV6_ULA_GUA

PUPNP_API char gIF_IPV6_ULA_GUA[INET6_ADDRSTRLEN]

extern

IPv6 GUA buffer to contain interface IPv6 global-unicast address.

Definition at line 145 of file upnpapi.cpp.

gIF_IPV6_ULA_GUA_PREFIX_LENGTH

PUPNP_API unsigned gIF_IPV6_ULA_GUA_PREFIX_LENGTH

extern

IPv6 GUA prefix length. (extern'ed in upnp.h)

Definition at line 147 of file upnpapi.cpp.

gIF_INDEX

PUPNP_API unsigned gIF_INDEX

extern

Index/scope-id from the used network interface.

Definition at line 135 of file upnpapi.cpp.

LOCAL_PORT_V4

PUPNP_API unsigned short LOCAL_PORT_V4

extern

IPv4 local port for the mini-server.

Definition at line 156 of file upnpapi.cpp.

LOCAL_PORT_V6

PUPNP_API unsigned short LOCAL_PORT_V6

extern

IPv6 LLA port for the mini-server.

Definition at line 142 of file upnpapi.cpp.

LOCAL_PORT_V6_ULA_GUA

PUPNP_API unsigned short LOCAL_PORT_V6_ULA_GUA

extern

IPv6 GUA port for the mini-server.

Definition at line 149 of file upnpapi.cpp.

gUpnpSdkNLSuuid

Upnp_SID gUpnpSdkNLSuuid

extern

Global variable used in discovery notifications.

NLS uuid.

Only available when options SSDP are compiled in.

Definition at line 212 of file upnpapi.cpp.

gTimerThread

TimerThread gTimerThread

extern

Global timer thread.

Definition at line 108 of file upnpapi.cpp.

gRecvThreadPool

ThreadPool gRecvThreadPool

extern

Receive thread pool.

Definition at line 114 of file upnpapi.cpp.

gSendThreadPool

ThreadPool gSendThreadPool

extern

Send thread pool.

Definition at line 111 of file upnpapi.cpp.

gMiniServerThreadPool

ThreadPool gMiniServerThreadPool

extern

Mini server thread pool.

Definition at line 117 of file upnpapi.cpp.

pVirtualDirList

virtualDirList* pVirtualDirList

extern

Pointer to the virtual directory list.

Definition at line 102 of file upnpapi.cpp.

virtualDirCallback

struct VirtualDirCallbacks virtualDirCallback

extern

This structure is for virtual directory callbacks.

Definition at line 99 of file upnpapi.cpp.

bWebServerState

WebServerState bWebServerState

extern

Flag to indicate the state of web server.

Definition at line 120 of file upnpapi.cpp.

gWebCallback_HostValidate

WebCallback_HostValidate gWebCallback_HostValidate

extern

webCallback for HOST validation.

Definition at line 123 of file upnpapi.cpp.

gWebCallback_HostValidateCookie

void* gWebCallback_HostValidateCookie

extern

Cookie to the webCallback for HOST validation.

Definition at line 126 of file upnpapi.cpp.

gAllowLiteralHostRedirection

int gAllowLiteralHostRedirection

extern

Allow literal host names redirection to numeric host names.

Definition at line 129 of file upnpapi.cpp.