upnpapi.hpp File Reference

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

#include <VirtualDir.hpp>
#include <client_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).
UPnPsdk_VIS char	gIF_NAME [LINE_SIZE]
	Static buffer to contain interface name. (extern'ed in upnp.h)
UPnPsdk_VIS char	gIF_IPV4 [INET_ADDRSTRLEN]
	Static buffer to contain interface IPv4 address. (extern'ed in upnp.h)
UPnPsdk_VIS char	gIF_IPV4_NETMASK [INET_ADDRSTRLEN]
	Static buffer to contain interface IPv4 netmask. (extern'ed in upnp.h)
UPnPsdk_VIS char	gIF_IPV6 [INET6_ADDRSTRLEN]
	Static buffer to contain interface IPv6 link-local address (LLA). (extern'ed in upnp.h)
UPnPsdk_VIS unsigned	gIF_IPV6_PREFIX_LENGTH
	IPv6 LLA prefix length. (extern'ed in upnp.h)
UPnPsdk_VIS char	gIF_IPV6_ULA_GUA [INET6_ADDRSTRLEN]
	Static buffer to contain interface IPv6 unique-local or globally-unique address (ULA or GUA). (extern'ed in upnp.h)
UPnPsdk_VIS unsigned	gIF_IPV6_ULA_GUA_PREFIX_LENGTH
	IPv6 ULA or GUA prefix length. (extern'ed in upnp.h)
UPnPsdk_VIS unsigned	gIF_INDEX
	Contains network interface index of the link local address gIF_IPV6 that is used as its scope_id.
UPnPsdk_VIS unsigned short	LOCAL_PORT_V4
	local IPv4 port for the mini-server
UPnPsdk_VIS unsigned short	LOCAL_PORT_V6
	IPv6 LLA port for the mini-server.
UPnPsdk_VIS unsigned short	LOCAL_PORT_V6_ULA_GUA
	IPv6 ULA or 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.
UPnPsdk_VIS WebCallback_HostValidate	gWebCallback_HostValidate
	webCallback for HOST validation.
UPnPsdk_VIS void *	gWebCallback_HostValidateCookie
	Cookie to the webCallback for HOST validation.
UPnPsdk_VIS 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 84 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 256 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 47 of file upnpapi.hpp.

DEV_LIMIT

#define DEV_LIMIT   200

DEV_LIMIT.

Definition at line 50 of file upnpapi.hpp.

DEFAULT_MX

#define DEFAULT_MX   5

DEFAULT_MX.

Definition at line 53 of file upnpapi.hpp.

DEFAULT_MAXAGE

#define DEFAULT_MAXAGE   1800

DEFAULT_MAXAGE.

Definition at line 56 of file upnpapi.hpp.

DEFAULT_SOAP_CONTENT_LENGTH

#define DEFAULT_SOAP_CONTENT_LENGTH   16000

DEFAULT_SOAP_CONTENT_LENGTH.

Definition at line 59 of file upnpapi.hpp.

MAX_SOAP_CONTENT_LENGTH

#define MAX_SOAP_CONTENT_LENGTH   (size_t)32000

MAX_SOAP_CONTENT_LENGTH.

Definition at line 61 of file upnpapi.hpp.

UPNP_TIMEOUT

#define UPNP_TIMEOUT   30

UPNP_TIMEOUT.

Definition at line 71 of file upnpapi.hpp.

HandleLock

#define HandleLock

(

)

HandleWriteLock()

HandleLock.

Definition at line 138 of file upnpapi.hpp.

HandleWriteLock

#define HandleWriteLock

(

)

pthread_rwlock_wrlock(&GlobalHndRWLock);

HandleWriteLock.

Definition at line 141 of file upnpapi.hpp.

HandleReadLock

#define HandleReadLock

(

)

pthread_rwlock_rdlock(&GlobalHndRWLock);

HandleReadLock.

Definition at line 144 of file upnpapi.hpp.

HandleUnlock

#define HandleUnlock

(

)

pthread_rwlock_unlock(&GlobalHndRWLock);

HandleUnlock.

Definition at line 147 of file upnpapi.hpp.

E_HTTP_SYNTAX

#define E_HTTP_SYNTAX   -6

E_HTTP_SYNTAX.

Definition at line 285 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 75 of file upnpapi.hpp.

UpnpFunName

enum UpnpFunName

UpnpFunName.

Definition at line 242 of file upnpapi.hpp.

WebServerState

enum WebServerState

Possible status of the internal webserver.

Definition at line 282 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 3342 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 3248 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 3268 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 3305 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 3142 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 3389 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 3364 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 64 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 327 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 335 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 346 of file upnpapi.cpp.

GlobalHndRWLock

pthread_rwlock_t GlobalHndRWLock

extern

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

Definition at line 253 of file upnpapi.cpp.

gIF_NAME

UPnPsdk_VIS char gIF_NAME[LINE_SIZE]

extern

Static buffer to contain interface name. (extern'ed in upnp.h)

Definition at line 280 of file upnpapi.cpp.

gIF_IPV4

UPnPsdk_VIS char gIF_IPV4[INET_ADDRSTRLEN]

extern

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

Definition at line 284 of file upnpapi.cpp.

gIF_IPV4_NETMASK

UPnPsdk_VIS char gIF_IPV4_NETMASK[INET_ADDRSTRLEN]

extern

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

Definition at line 288 of file upnpapi.cpp.

gIF_IPV6

UPnPsdk_VIS char gIF_IPV6[INET6_ADDRSTRLEN]

extern

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

Definition at line 292 of file upnpapi.cpp.

gIF_IPV6_PREFIX_LENGTH

UPnPsdk_VIS unsigned gIF_IPV6_PREFIX_LENGTH

extern

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

Definition at line 295 of file upnpapi.cpp.

gIF_IPV6_ULA_GUA

UPnPsdk_VIS char gIF_IPV6_ULA_GUA[INET6_ADDRSTRLEN]

extern

Static buffer to contain interface IPv6 unique-local or globally-unique address (ULA or GUA). (extern'ed in upnp.h)

Definition at line 305 of file upnpapi.cpp.

gIF_IPV6_ULA_GUA_PREFIX_LENGTH

UPnPsdk_VIS unsigned gIF_IPV6_ULA_GUA_PREFIX_LENGTH

extern

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

Definition at line 308 of file upnpapi.cpp.

gIF_INDEX

UPnPsdk_VIS unsigned gIF_INDEX

extern

Contains network interface index of the link local address gIF_IPV6 that is used as its scope_id.

Definition at line 299 of file upnpapi.cpp.

LOCAL_PORT_V4

UPnPsdk_VIS unsigned short LOCAL_PORT_V4

extern

local IPv4 port for the mini-server

Definition at line 311 of file upnpapi.cpp.

LOCAL_PORT_V6

UPnPsdk_VIS unsigned short LOCAL_PORT_V6

extern

IPv6 LLA port for the mini-server.

Definition at line 314 of file upnpapi.cpp.

LOCAL_PORT_V6_ULA_GUA

UPnPsdk_VIS unsigned short LOCAL_PORT_V6_ULA_GUA

extern

IPv6 ULA or GUA port for the mini-server.

Definition at line 317 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 373 of file upnpapi.cpp.

gTimerThread

TimerThread gTimerThread

extern

Global timer thread.

Definition at line 256 of file upnpapi.cpp.

gRecvThreadPool

ThreadPool gRecvThreadPool

extern

Receive thread pool.

Definition at line 262 of file upnpapi.cpp.

gSendThreadPool

ThreadPool gSendThreadPool

extern

Send thread pool.

Definition at line 259 of file upnpapi.cpp.

gMiniServerThreadPool

ThreadPool gMiniServerThreadPool

extern

Mini server thread pool.

Definition at line 265 of file upnpapi.cpp.

pVirtualDirList

virtualDirList* pVirtualDirList

extern

Pointer to the virtual directory list.

Definition at line 250 of file upnpapi.cpp.

virtualDirCallback

struct VirtualDirCallbacks virtualDirCallback

extern

This structure is for virtual directory callbacks.

Definition at line 247 of file upnpapi.cpp.

bWebServerState

WebServerState bWebServerState

extern

Flag to indicate the state of web server.

Definition at line 268 of file upnpapi.cpp.

gWebCallback_HostValidate

UPnPsdk_VIS WebCallback_HostValidate gWebCallback_HostValidate

extern

webCallback for HOST validation.

Definition at line 271 of file upnpapi.cpp.

gWebCallback_HostValidateCookie

UPnPsdk_VIS void* gWebCallback_HostValidateCookie

extern

Cookie to the webCallback for HOST validation.

Definition at line 274 of file upnpapi.cpp.

gAllowLiteralHostRedirection

UPnPsdk_VIS int gAllowLiteralHostRedirection

extern

Allow literal host names redirection to numeric host names.

Definition at line 277 of file upnpapi.cpp.