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

#include <upnpapi.hpp>
#include <uuid.hpp>
#include <miniserver.hpp>
#include <httpreadwrite.hpp>
#include <ssdp_ctrlpt.hpp>
#include <ssdp_device.hpp>
#include <soap_device.hpp>
#include <soap_ctrlpt.hpp>
#include <UPnPsdk/addrinfo.hpp>
#include <UPnPsdk/netadapter.hpp>
#include <umock/iphlpapi.hpp>
#include <umock/stdio.hpp>
#include <gena.hpp>
#include <urlconfig.hpp>
#include <webserver.hpp>
#include <sys/stat.h>
#include <cassert>
#include <csignal>
#include <cstdlib>
#include <cstring>

Include dependency graph for upnpapi.cpp:

Go to the source code of this file.

Classes
struct	job_arg
	job_arg More...

struct	job_arg.advertise
	advertise More...

Namespaces
namespace	compa
	Refactored pupnp program code that is compatible to the original pupnp code.

Macros
#define	ifr_netmask ifr_addr
	ifr_netmask is not defined on e.g. OmniOS/Solaris, but since ifru_netmask/ifru_addr are all just union members, this should work.

#define	IN6_IS_ADDR_ULA(a)
	If IN6_IS_ADDR_ULA is not defined then this is set.

Functions
int	compa::anonymous_namespace{upnpapi.cpp}::UpnpGetIfInfo (std::string_view a_iface="")
	Retrieve local network adapter information and keep it in global variables.

static void	free_advertise_arg (job_arg *arg)
	Free memory associated with advertise job's argument.

static void	free_action_arg (job_arg *arg)
	Free memory associated with an action job's argument.

static int	UpnpInitMutexes ()
	Initializes the global mutexes used by the UPnP SDK.

static int	UpnpInitThreadPools ()
	Initializes the global threadm pools used by the UPnP SDK.

static int	UpnpInitPreamble ()
	Performs the initial steps in initializing the UPnP SDK.

static int	UpnpInitStartServers (in_port_t DestPort)
	Finishes initializing the UPnP SDK.

int	UpnpInit2 (const char *IfName, unsigned short DestPort)
	Initializes the Linux SDK for UPnP Devices.

void	PrintThreadPoolStats (ThreadPool tp, const char DbgFileName, int DbgLineNo, const char *msg)
	Prints thread pool statistics if DEBUG is enabled. See also #define PrintThreadPoolStats()

int	UpnpFinish ()
	Terminates the Linux SDK for UPnP Devices.

unsigned short	UpnpGetServerPort ()
	Returns the internal server IPv4 UPnP listening port.

unsigned short	UpnpGetServerPort6 ()
	Returns the internal server IPv6 link-local (LLA) UPnP listening port.

unsigned short	UpnpGetServerUlaGuaPort6 ()
	Returns the internal server IPv6 ULA or GUA UPnP listening port.

char *	UpnpGetServerIpAddress ()
	Returns the local IPv4 listening ip address.

char *	UpnpGetServerIp6Address ()
	Returns the IPv6 link-local listening ip address.

char *	UpnpGetServerUlaGuaIp6Address ()
	Returns the IPv6 unique-local or globally-unique listening ip address.

static int	GetFreeHandle ()
	Get a free UPnP Unit handle.

static int	FreeHandle (int Upnp_Handle)
	Free handle.

int	UpnpRegisterRootDevice (const char const DescUrl, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle *const Hnd)
	Registers one root- or logical-device object with the UPnP Library to get a handle for it.

static int	GetDescDocumentAndURL (Upnp_DescType descriptionType, char description, int config_baseURL, int AddressFamily, IXML_Document *xmlDoc, char descURL[LINE_SIZE])
	Fills the sockadr_in with miniserver information.

int	UpnpRegisterRootDevice2 (const Upnp_DescType descriptionType, const char const description_const, const size_t bufferLen, const int config_baseURL, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle *const Hnd)
	Registers one root- or logical-device object with the UPnP Library with additional description and get a handle for it.

int	compa::anonymous_namespace{upnpapi.cpp}::UpnpRegisterRootDevice3 (const char const DescUrl, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle const Hnd, const int AddressFamily, const char const LowerDescUrl)

int	UpnpRegisterRootDevice3 (const char const DescUrl, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle *const Hnd, const int AddressFamily)
	Registers one UPnP device object for a specific address family with the UPnP library and get a handle for it.

int	UpnpRegisterRootDevice4 (const char const DescUrl, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle const Hnd, const int AddressFamily, const char const LowerDescUrl)
	Same as UpnpRegisterRootDevice3() with additional argument to specify a description URL.

int	UpnpUnRegisterRootDevice (UpnpDevice_Handle Hnd)
	Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4.

int	UpnpUnRegisterRootDeviceLowPower (UpnpDevice_Handle Hnd, int PowerState, int SleepPeriod, int RegistrationState)
	Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4 for Low Power.

int	UpnpRegisterClient (Upnp_FunPtr Fun, const void Cookie, UpnpClient_Handle Hnd)
	Registers a control point application with the UPnP Library.

int	UpnpUnRegisterClient (UpnpClient_Handle Hnd)
	Unregisters a control point application, unsubscribing all active subscriptions.

static int	GetNameForAlias (char name, char *alias)
	Determines alias for given name which is a file name or URL.

static void	get_server_addr (struct sockaddr *serverAddr)
	Fill the sockadr with IPv4 miniserver information.

static void	get_server_addr6 (struct sockaddr *serverAddr)
	Fill the sockadr with IPv6 miniserver information.

int	UpnpSendAdvertisement (UpnpDevice_Handle Hnd, int Exp)
	Sends out the discovery announcements for all devices and services contained within one root device.

int	UpnpSendAdvertisementLowPower (UpnpDevice_Handle Hnd, int Exp, int PowerState, int SleepPeriod, int RegistrationState)
	Sends out the discovery announcements for all devices and services contained within one root device.

int	UpnpSearchAsync (UpnpClient_Handle Hnd, int Mx, const char Target_const, const void Cookie_const)
	Searches for devices matching the given search target.

int	UpnpSetMaxSubscriptions (UpnpDevice_Handle Hnd, int MaxSubscriptions)
	Sets the maximum number of subscriptions accepted per service.

int	UpnpSetMaxSubscriptionTimeOut (UpnpDevice_Handle Hnd, int MaxSubscriptionTimeOut)
	Sets the maximum time-out accepted for a subscription request or renewal.

int	UpnpSubscribeAsync (UpnpClient_Handle Hnd, const char EvtUrl_const, int TimeOut, Upnp_FunPtr Fun, const void Cookie_const)
	Performs the same operation as UpnpSubscribe(), but returns immediately and calls the registered callback function when the operation is complete.

int	UpnpSubscribe (UpnpClient_Handle Hnd, const char EvtUrl_const, int TimeOut, Upnp_SID SubsId)
	Registers a control point to receive event notifications from a UPnP device.

int	UpnpUnSubscribe (UpnpClient_Handle Hnd, const Upnp_SID SubsId)
	Removes the subscription of a control point from a service previously subscribed to using UpnpSubscribe() or UpnpSubscribeAsync().

int	UpnpUnSubscribeAsync (UpnpClient_Handle Hnd, Upnp_SID SubsId, Upnp_FunPtr Fun, const void *Cookie_const)
	Removes a subscription of a control point from a service previously subscribed to using UpnpSubscribe() or UpnpSubscribeAsync(), generating a callback when the operation is complete.

int	UpnpRenewSubscription (UpnpClient_Handle Hnd, int *TimeOut, const Upnp_SID SubsId)
	Renews a subscription that is about to expire.

int	UpnpRenewSubscriptionAsync (UpnpClient_Handle Hnd, int TimeOut, Upnp_SID SubsId, Upnp_FunPtr Fun, const void *Cookie_const)
	Renews a subscription that is about to expire, generating a callback when the operation is complete.

int	UpnpNotify (UpnpDevice_Handle Hnd, const char DevID_const, const char ServName_const, const char VarName_const, const char NewVal_const, int cVariables)
	Sends out an event change notification to all control points subscribed to a particular service.

int	UpnpNotifyExt (UpnpDevice_Handle Hnd, const char DevID_const, const char ServName_const, IXML_Document *PropSet)
	Similar to UpnpNotify() except that it takes a DOM document for the event rather than an array of strings.

int	UpnpAcceptSubscription (UpnpDevice_Handle Hnd, const char DevID_const, const char ServName_const, const char VarName_const, const char NewVal_const, int cVariables, const Upnp_SID SubsId)
	Accepts a subscription request and sends out the current state of the eventable variables for a service.

int	UpnpAcceptSubscriptionExt (UpnpDevice_Handle Hnd, const char DevID_const, const char ServName_const, IXML_Document *PropSet, const Upnp_SID SubsId)
	Similar to UpnpAcceptSubscription() except that it takes a DOM document for the variables to event rather than an array of strings.

int	UpnpSendAction (UpnpClient_Handle Hnd, const char ActionURL_const, const char ServiceType_const, const char DevUDN_const, IXML_Document Action, IXML_Document **RespNodePtr)
	Sends a message to change a state variable in a service.

int	UpnpSendActionEx (UpnpClient_Handle Hnd, const char ActionURL_const, const char ServiceType_const, const char DevUDN_const, IXML_Document Header, IXML_Document Action, IXML_Document *RespNodePtr)
	Sends a message to change a state variable in a service.

int	UpnpSendActionAsync (UpnpClient_Handle Hnd, const char ActionURL_const, const char ServiceType_const, const char DevUDN_const, IXML_Document Act, Upnp_FunPtr Fun, const void *Cookie_const)
	Sends a message to change a state variable in a service, generating a callback when the operation is complete.

int	UpnpSendActionExAsync (UpnpClient_Handle Hnd, const char ActionURL_const, const char ServiceType_const, const char DevUDN_const, IXML_Document Header, IXML_Document Act, Upnp_FunPtr Fun, const void Cookie_const)
	Sends a message to change a state variable in a service, generating a callback when the operation is complete.

int	UpnpGetServiceVarStatusAsync (UpnpClient_Handle Hnd, const char ActionURL_const, const char VarName_const, Upnp_FunPtr Fun, const void *Cookie_const)
	Queries the state of a variable of a service, generating a callback when the operation is complete.

int	UpnpGetServiceVarStatus (UpnpClient_Handle Hnd, const char ActionURL_const, const char VarName_const, DOMString *StVar)
	Queries the state of a state variable of a service on another device.

int	UpnpOpenHttpPost (const char url, void handle, const char contentType, int contentLength, int timeout)
	Makes an HTTP POST request message, opens a connection to the server and sends the POST request to the server if the connection to the server succeeds.

int	UpnpWriteHttpPost (void handle, char buf, size_t *size, int timeout)
	Sends a request to a server to copy the contents of a buffer to the URI specified in the UpnpOpenHttpPost() call.

int	UpnpCloseHttpPost (void handle, int httpStatus, int timeout)
	Sends and receives any pending data, closes the connection with the server, and frees memory allocated during the UpnpOpenHttpPost() call.

int	UpnpOpenHttpGet (const char url, void handle, char contentType, int contentLength, int *httpStatus, int timeout)
	Gets a file specified in a URL.

int	UpnpOpenHttpGetProxy (const char url, const char proxy_str, void handle, char contentType, int contentLength, int httpStatus, int timeout)
	Gets a file specified in a URL through the specified proxy.

int	UpnpOpenHttpGetEx (const char url_str, void Handle, char contentType, int contentLength, int *httpStatus, int lowRange, int highRange, int timeout)
	Gets specified number of bytes from a file specified in the URL.

int	UpnpCancelHttpGet (void *Handle)
	Set the cancel flag of the handle parameter.

int	UpnpCloseHttpGet (void *Handle)
	Closes the connection and frees memory that was allocated for the handle parameter.

int	UpnpReadHttpGet (void Handle, char buf, size_t *size, int timeout)
	Gets specified number of bytes from a file specified in a URL.

int	UpnpHttpGetProgress (void Handle, size_t length, size_t *total)
	Retrieve progress information of a http-get transfer.

int	UpnpOpenHttpConnection (const char url, void *handle, int timeout)
	Opens a connection to the server.

int	UpnpMakeHttpRequest (Upnp_HttpMethod method, const char url, void handle, UpnpString headers, const char contentType, int contentLength, int timeout)
	Makes a HTTP request using a connection previously created by UpnpOpenHttpConnection().

int	UpnpWriteHttpRequest (void handle, char buf, size_t *size, int timeout)
	Writes the content of a HTTP request initiated by a UpnpMakeHttpRequest() call. The end of the content should be indicated by a call to UpnpEndHttpRequest().

int	UpnpEndHttpRequest (void *handle, int timeout)
	Indicates the end of a HTTP request previously made by UpnpMakeHttpRequest().

int	UpnpGetHttpResponse (void handle, UpnpString headers, char *contentType, int contentLength, int *httpStatus, int timeout)
	Gets the response from the server using a connection previously created by UpnpOpenHttpConnection().

int	UpnpReadHttpResponse (void handle, char buf, size_t *size, int timeout)
	Reads the content of a response using a connection previously created by UpnpOpenHttpConnection().

int	UpnpCloseHttpConnection (void *handle)
	Closes the connection created with UpnpOpenHttpConnection() and frees any memory associated with the connection.

int	UpnpDownloadUrlItem (const char url, char outBuf, char contentType)
	Downloads a file specified in a URL.

int	UpnpDownloadXmlDoc (const char url, IXML_Document *xmlDoc)
	Downloads an XML document specified in a URL.

void	UpnpThreadDistribution (struct UpnpNonblockParam *Param)
	Schedule async functions in threadpool.

Upnp_FunPtr	GetCallBackFn (UpnpClient_Handle Hnd)
	Get callback function ptr from a handle.

Upnp_Handle_Type	GetClientHandleInfo (UpnpClient_Handle client_handle_out, struct Handle_Info *HndInfo)
	Get client handle info.

Upnp_Handle_Type	GetDeviceHandleInfo (UpnpDevice_Handle start, int AddressFamily, UpnpDevice_Handle 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, UpnpDevice_Handle 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.

Upnp_Handle_Type	GetHandleInfo (UpnpClient_Handle Hnd, Handle_Info **HndInfo)
	Get handle information.

int	PrintHandleInfo (UpnpClient_Handle Hnd)
	Print handle info.

void	AutoAdvertise (void *input)
	This function is a timer thread scheduled by UpnpSendAdvertisement to the send advetisement again.

int	UpnpSetWebServerRootDir (const char *rootDir)
	Sets the document root directory for the internal web server.

int	UpnpSetWebServerCorsString (const char *corsString)
	Assign the Access-Control-Allow-Origin specfied by the input const char* cors_string parameter to the global CORS string.

int	UpnpAddVirtualDir (const char newDirName, const void cookie, const void **oldcookie)
	Adds a web directory mapping.

int	UpnpRemoveVirtualDir (const char *dirName)
	Removes a web directory mapping made with UpnpAddVirtualDir().

void	UpnpRemoveAllVirtualDirs ()
	Removes all web directory mappings.

int	UpnpEnableWebserver (int enable)
	Enables or disables the webserver.

int	UpnpIsWebserverEnabled ()
	Returns the status of the webserver.

void	UpnpSetHostValidateCallback (WebCallback_HostValidate callback, void *cookie)
	Set callback for validating HTTP requests HOST header values.

void	UpnpSetAllowLiteralHostRedirection (int enable)
	Enable or disable literal IP redirection.

int	UpnpVirtualDir_set_GetInfoCallback (VDCallback_GetInfo callback)
	Sets the get_info callback function to be used to access a web directory.

int	UpnpVirtualDir_set_OpenCallback (VDCallback_Open callback)
	Sets the open callback function to be used to access a web directory.

int	UpnpVirtualDir_set_ReadCallback (VDCallback_Read callback)
	Sets the read callback function to be used to access a web directory.

int	UpnpVirtualDir_set_WriteCallback (VDCallback_Write callback)
	Sets the write callback function to be used to access a web directory.

int	UpnpVirtualDir_set_SeekCallback (VDCallback_Seek callback)
	Sets the seek callback function to be used to access a web directory.

int	UpnpVirtualDir_set_CloseCallback (VDCallback_Close callback)
	Sets the close callback function to be used to access a web directory.

int	UpnpSetContentLength (UpnpClient_Handle Hnd, size_t contentLength)
	Sets the content-length that the SDK will process on an incoming SOAP requests or responses.

int	UpnpSetMaxContentLength (size_t contentLength)
	Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses.

Variables
pthread_mutex_t	compa::anonymous_namespace{upnpapi.cpp}::sdkInit_mutex = PTHREAD_MUTEX_INITIALIZER
	Initialization mutex.

Handle_Info *	compa::anonymous_namespace{upnpapi.cpp}::HandleTable [NUM_HANDLE]
	UPnP Device and Control Point handle table

struct VirtualDirCallbacks	virtualDirCallback
	This structure is for virtual directory callbacks.

virtualDirList *	pVirtualDirList
	Pointer to the virtual directory list.

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

TimerThread	gTimerThread
	Global timer thread.

ThreadPool	gSendThreadPool
	Send thread pool.

ThreadPool	gRecvThreadPool
	Receive thread pool.

ThreadPool	gMiniServerThreadPool
	Mini server thread pool.

WebServerState	bWebServerState = WEB_SERVER_DISABLED
	Flag to indicate the state of web server.

WebCallback_HostValidate	gWebCallback_HostValidate = 0
	webCallback for HOST validation.

void *	gWebCallback_HostValidateCookie = 0
	Cookie to the webCallback for HOST validation.

int	gAllowLiteralHostRedirection = 0
	Allow literal host names redirection to numeric host names.

char	gIF_NAME [LINE_SIZE] = {'\0'}
	Static buffer to contain interface name. (extern'ed in upnp.h)

char	gIF_IPV4 [INET_ADDRSTRLEN] = {'\0'}
	Static buffer to contain interface IPv4 address. (extern'ed in upnp.h)

char	gIF_IPV4_NETMASK [INET_ADDRSTRLEN] = {'\0'}
	Static buffer to contain interface IPv4 netmask. (extern'ed in upnp.h)

char	gIF_IPV6 [INET6_ADDRSTRLEN] = {'\0'}
	Static buffer to contain interface IPv6 link-local address (LLA). (extern'ed in upnp.h)

unsigned	gIF_IPV6_PREFIX_LENGTH = 0
	IPv6 LLA prefix length. (extern'ed in upnp.h)

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

char	gIF_IPV6_ULA_GUA [INET6_ADDRSTRLEN] = {'\0'}
	Static buffer to contain interface IPv6 unique-local or globally-unique address (ULA or GUA). (extern'ed in upnp.h)

unsigned	gIF_IPV6_ULA_GUA_PREFIX_LENGTH = 0
	IPv6 ULA or GUA prefix length. (extern'ed in upnp.h)

in_port_t	LOCAL_PORT_V4
	local IPv4 port for the mini-server

in_port_t	LOCAL_PORT_V6
	IPv6 LLA port for the mini-server.

in_port_t	LOCAL_PORT_V6_ULA_GUA
	IPv6 ULA or GUA port for the mini-server.

membuffer	gWebserverCorsString

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

int	g_UpnpSdkEQMaxLen = MAX_SUBSCRIPTION_QUEUED_EVENTS
	Global variable to determines the maximum number of events.

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

int	UpnpSdkInit = 0
	Global variable to denote the state of Upnp SDK == 0 if uninitialized, == 1 if initialized.

int	UpnpSdkClientRegistered = 0
	Global variable to denote the state of Upnp SDK client registration.

int	UpnpSdkDeviceRegisteredV4 = 0
	Global variable to denote the state of Upnp SDK IPv4 device registration.

int	UpnpSdkDeviceregisteredV6 = 0
	Global variable to denote the state of Upnp SDK IPv6 device registration.

Upnp_SID	gUpnpSdkNLSuuid
	Global variable used in discovery notifications.

Detailed Description

Inititalize the compatible library before it can be used.

Definition in file upnpapi.cpp.

Class Documentation

◆ job_arg

struct job_arg

job_arg

Definition at line 377 of file upnpapi.cpp.

Collaboration diagram for job_arg:

Class Members
struct job_arg.advertise	advertise	advertise
struct UpnpNonblockParam	action	UpnpNonblockParam.
int	handle
int	eventId
void *	Event

◆ job_arg.advertise

struct job_arg.advertise

advertise

Definition at line 379 of file upnpapi.cpp.

Class Members
int	handle
int	eventId
void *	Event

Macro Definition Documentation

◆ ifr_netmask

#define ifr_netmask ifr_addr

ifr_netmask is not defined on e.g. OmniOS/Solaris, but since ifru_netmask/ifru_addr are all just union members, this should work.

Definition at line 236 of file upnpapi.cpp.

◆ IN6_IS_ADDR_ULA

#define IN6_IS_ADDR_ULA ( a )

Value:

((((__const uint32_t*)(a))[0] & htonl((uint32_t)0xfe000000)) == \

htonl((uint32_t)0xfc000000))

If IN6_IS_ADDR_ULA is not defined then this is set.

Definition at line 241 of file upnpapi.cpp.

Function Documentation

◆ free_advertise_arg()

static void free_advertise_arg ( job_arg * arg )

static

Free memory associated with advertise job's argument.

Definition at line 392 of file upnpapi.cpp.

Here is the caller graph for this function:

◆ free_action_arg()

static void free_action_arg ( job_arg * arg )

static

Free memory associated with an action job's argument.

Definition at line 404 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpInitMutexes()

static int UpnpInitMutexes ( )

static

Initializes the global mutexes used by the UPnP SDK.

Returns: UPNP_E_SUCCESS on success or UPNP_E_INIT_FAILED if a mutex could not be initialized.

Definition at line 422 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpInitThreadPools()

static int UpnpInitThreadPools ( )

static

Initializes the global threadm pools used by the UPnP SDK.

Returns: UPNP_E_SUCCESS on success or UPNP_E_INIT_FAILED if a mutex could not be initialized.

Definition at line 450 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpInitPreamble()

static int UpnpInitPreamble ( )

static

Performs the initial steps in initializing the UPnP SDK.

Winsock library is initialized for the process (Windows specific).
The logging (for debug messages) is initialized.
Mutexes, Handle table and thread pools are allocated and initialized.
Callback functions for SOAP and GENA are set, if they're enabled.
The SDK timer thread is initialized.

Returns: UPNP_E_SUCCESS on success.

Definition at line 497 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpInitStartServers()

static int UpnpInitStartServers ( in_port_t DestPort )

static

Finishes initializing the UPnP SDK.

The MiniServer is started, if enabled.
The WebServer is started, if enabled.

Returns: UPNP_E_SUCCESS on success or UPNP_E_INIT_FAILED if a mutex could not be initialized.

Parameters

[in] DestPort Local Port to listen for incoming connections.

Definition at line 564 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ PrintThreadPoolStats()

void PrintThreadPoolStats	(	ThreadPool *	tp,
		const char *	DbgFileName,
		int	DbgLineNo,
		const char *	msg
	)

Prints thread pool statistics if DEBUG is enabled. See also #define PrintThreadPoolStats()

Parameters

[in]	tp	The thread pool.
[in]	DbgFileName	The file name that called this function, use the macro __FILE__.
[in]	DbgLineNo	The line number that the function was called, use the macro __LINE__.
[in]	msg	The message.

Definition at line 646 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpFinish()

int UpnpFinish ( void )

Terminates the Linux SDK for UPnP Devices.

Checks for pending jobs and threads
Unregisters either the client or device
Shuts down the Timer Thread
Stops the Mini Server
Uninitializes the Thread Pool
For Win32 cleans up Winsock Interface
Cleans up mutex objects

This function must be the last API function called. It should be called only once. Subsequent calls to this API return a UPNP_E_FINISH error code.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or it is not initialized.

Definition at line 684 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpGetServerPort()

unsigned short UpnpGetServerPort ( void )

Returns the internal server IPv4 UPnP listening port.

If '0' is used as the port number in UpnpInit2(), then this function can be used to retrieve the actual port allocated to the SDK.

Returns

On success: The port on which an internal server is listening for IPv4 UPnP related requests.
On error: 0 is returned if UpnpInit2() has not succeeded.

Definition at line 756 of file upnpapi.cpp.

◆ UpnpGetServerPort6()

unsigned short UpnpGetServerPort6 ( void )

Returns the internal server IPv6 link-local (LLA) UPnP listening port.

If '0' is used as the port number in UpnpInit2(), then this function can be used to retrieve the actual port allocated to the SDK.

Returns

On success: The port on which an internal server is listening for IPv6 link-local (LLA) UPnP related requests.
On error: 0 is returned if UpnpInit2() has not succeeded.

Definition at line 763 of file upnpapi.cpp.

◆ UpnpGetServerUlaGuaPort6()

unsigned short UpnpGetServerUlaGuaPort6 ( void )

Returns the internal server IPv6 ULA or GUA UPnP listening port.

If '0' is used as the port number in UpnpInit2(), then this function can be used to retrieve the actual port allocated to the SDK.

Returns

On success: The port on which an internal server is listening for IPv6 ULA or GUA UPnP related requests.
On error: 0 is returned if UpnpInit2() has not succeeded.

Definition at line 774 of file upnpapi.cpp.

◆ UpnpGetServerIpAddress()

char * UpnpGetServerIpAddress ( void )

Returns the local IPv4 listening ip address.

If nullptr is used as the interface in UpnpInit2(), then this function can be used to retrieve the actual interface address on which device is running.

Returns

On success: The IPv4 address on which an internal server is listening for UPnP related requests.
On error: nullptr is returned if UpnpInit2() has not succeeded.

Definition at line 785 of file upnpapi.cpp.

◆ UpnpGetServerIp6Address()

char * UpnpGetServerIp6Address ( void )

Returns the IPv6 link-local listening ip address.

If nullptr is used as the interface in UpnpInit2(), then this function can be used to retrieve the actual interface address on which device is running.

Returns

On success: The IPv6 link-local address (LLA) on which an internal server is listening for UPnP related requests.
On error: nullptr is returned if UpnpInit2() has not succeeded.

Definition at line 792 of file upnpapi.cpp.

◆ UpnpGetServerUlaGuaIp6Address()

char * UpnpGetServerUlaGuaIp6Address ( void )

Returns the IPv6 unique-local or globally-unique listening ip address.

If nullptr is used as the interface in UpnpInit2(), then this function can be used to retrieve the actual interface address on which device is running.

Returns

On success: The IPv6 unique-local or globally-unique address (ULA or GUA) on which an internal server is listening for UPnP related requests.
On error: nullptr is returned if UpnpInit2() has not succeeded.

Definition at line 803 of file upnpapi.cpp.

◆ GetFreeHandle()

static int GetFreeHandle ( )

static

Get a free UPnP Unit handle.

Returns: On success: an integer greater than zero
On error: UPNP_E_OUTOF_HANDLE

Definition at line 822 of file upnpapi.cpp.

Here is the caller graph for this function:

◆ FreeHandle()

static int FreeHandle ( int Upnp_Handle )

static

Free handle.

Returns: UPNP_E_SUCCESS if successful or UPNP_E_INVALID_HANDLE if not

Parameters

[in] Upnp_Handle Handle index.

Definition at line 839 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpRegisterRootDevice()

int UpnpRegisterRootDevice	(	const char *const	DescUrl,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd
	)

Registers one root- or logical-device object with the UPnP Library to get a handle for it.

A root- or logical-device object cannot make any other API calls until it registers using this function. To register a control point see UpnpRegisterClient() to get a control point handle to perform control point functionality.

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns. A registered root device needs to be unregistered with UpnpUnRegisterRootDevice() after using.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_DESC: The description document was not a valid device description.
UPNP_E_INVALID_URL: The URL for the description document is not valid.
UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is a nullptr.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.

Parameters

[in]	DescUrl	Pointer to a string containing the description URL for this root device instance.
[in]	Fun	Pointer to the callback function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new device handle.

Definition at line 866 of file upnpapi.cpp.

Here is the call graph for this function:

◆ GetDescDocumentAndURL()

static int GetDescDocumentAndURL	(	Upnp_DescType	descriptionType,
		char *	description,
		int	config_baseURL,
		int	AddressFamily,
		IXML_Document **	xmlDoc,
		char	descURL[LINE_SIZE]
	)

static

Fills the sockadr_in with miniserver information.

Definition at line 1569 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpRegisterRootDevice2()

int UpnpRegisterRootDevice2	(	const Upnp_DescType	descriptionType,
		const char *const	description_const,
		const size_t	bufferLen,
		const int	config_baseURL,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd
	)

Registers one root- or logical-device object with the UPnP Library with additional description and get a handle for it.

Similar to UpnpRegisterRootDevice(), except that it also allows the description document to be specified as a file or a memory buffer. The description can also be configured to have the correct IP and port address.

For the configuration to be functional, the internal web server MUST be present. In addition, the web server MUST be activated (using UpnpSetWebServerRootDir()) before calling this function. The only condition where the web server can be absent is if the description document is specified as a URL and no configuration is required (i.e. config_baseURL = 0.)

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns. A registered root device needs to be unregistered with UpnpUnRegisterRootDevice() after using.

Examples of using the valid three different types of description documents:

1) Description specified as a URL:
      descriptionType == UPNPREG_URL_DESC
      description is the URL
      bufferLen = 0 (ignored)
2) Description specified as a file:
      descriptionType == UPNPREG_FILENAME_DESC
      description is a filename
      bufferLen = 0 (ignored)
3) Description specified as a memory buffer:
      descriptionType == UPNPREG_BUF_DESC
      description is pointer to a memory buffer
      bufferLen == length of memory buffer

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_DESC: The description document is not a valid device description.
UPNP_E_INVALID_PARAM: Either callback Fun or Hnd is not a valid pointer or description_const is a nullptr.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the internal buffer.
UPNP_E_FILE_NOT_FOUND: The description file could not be found.
UPNP_E_FILE_READ_ERROR: An error occurred reading the description file.
UPNP_E_INVALID_URL: The URL to the description document is invalid.
UPNP_E_EXT_NOT_XML: The URL to the description document or file should have a .xml extension.
UPNP_E_NO_WEB_SERVER: The internal web server has been compiled out; the SDK cannot configure itself from the description document.

Parameters

[in]	descriptionType	The type of the description document.
[in]	description_const	Treated as a URL, file name or memory buffer depending on description type.
[in]	bufferLen	The length of memory buffer if passing a description in a buffer, otherwise it is ignored.
[in]	config_baseURL	If nonzero, `URLBase` of description document is configured and the description is served using the internal web server.
[in]	Fun	Pointer to the callback function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new device handle.

Definition at line 1020 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpRegisterRootDevice3()

int UpnpRegisterRootDevice3	(	const char *const	DescUrl,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd,
		const int	AddressFamily
	)

Registers one UPnP device object for a specific address family with the UPnP library and get a handle for it.

A UPnP device object cannot make any other API calls until it registers using this function. To register a control point see UpnpRegisterClient() to get a control point handle to perform control point functionality.

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns. A registered root device needs to be unregistered with UpnpUnRegisterRootDevice() after using.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_DESC: The description document was not a valid device description.
UPNP_E_INVALID_URL: The URL for the description document is not valid.
UPNP_E_INVALID_PARAM: Either callback Fun or Hnd is not a valid pointer or DescURL is a nullptr.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.

Parameters

[in]	DescUrl	Pointer to a string containing the description URL fo this root device instance.
[in]	Fun	Pointer to the callback function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new device handle.
[in]	AddressFamily	Address family of this device. Can be AF_INET for an IPv4 device, or AF_INET6 for an IPv6 device. Defaults to AF_INET.

Definition at line 1311 of file upnpapi.cpp.

◆ UpnpRegisterRootDevice4()

int UpnpRegisterRootDevice4	(	const char *const	DescUrl,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd,
		const int	AddressFamily,
		const char *const	LowerDescUrl
	)

Same as UpnpRegisterRootDevice3() with additional argument to specify a description URL.

This function can be used to specify a dedicated description URL LowerDescUrl to be returned for legacy control points.

Parameters

[in]	DescUrl	.
[in]	Fun	.
[in]	Cookie	.
[out]	Hnd	.
[in]	AddressFamily	.
[in]	LowerDescUrl	This is a pointer to a string containing the description URL to be returned for legacy control points for this root device instance.

Definition at line 1320 of file upnpapi.cpp.

◆ UpnpUnRegisterRootDevice()

int UpnpUnRegisterRootDevice ( UpnpDevice_Handle Hnd )

Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4.

After this call, the UpnpDevice_Handle is no longer valid. For all advertisements that have not yet expired, the SDK sends a device unavailable message automatically.

This is a synchronous call and generates no callbacks. Once this call returns, the SDK will no longer generate callbacks to the application.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.

Parameters

[in] Hnd The handle of the root device instance to unregister.

Definition at line 1331 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpUnRegisterRootDeviceLowPower()

int UpnpUnRegisterRootDeviceLowPower	(	UpnpDevice_Handle	Hnd,
		int	PowerState,
		int	SleepPeriod,
		int	RegistrationState
	)

Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4 for Low Power.

After this call, the UpnpDevice_Handle is no longer valid. For all advertisements that have not yet expired, the SDK sends a device unavailable message automatically.

This is a synchronous call and generates no callbacks. Once this call returns, the SDK will no longer generate callbacks to the application.

This function allow a device to specify the SSDP extensions defined by UPnP Low Power.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.

Parameters

[in]	Hnd	The handle of the root device instance to unregister.
	PowerState	PowerState as defined by UPnP Low Power.
	SleepPeriod	SleepPeriod as defined by UPnP Low Power.
	RegistrationState	RegistrationState as defined by UPnP Low Power.

Definition at line 1337 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpRegisterClient()

int UpnpRegisterClient	(	Upnp_FunPtr	Fun,
		const void *	Cookie,
		UpnpClient_Handle *	Hnd
	)

Registers a control point application with the UPnP Library.

A control point application cannot make any other API calls until it registers using this function.

UpnpRegisterClient() is a synchronous call and generates no callbacks. Callbacks can occur as soon as this function returns.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_PARAM: Either callback Fun or Hnd is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to register this control point.

Parameters

[in]	Fun	Pointer to a function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new control point handle.

Definition at line 1409 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpUnRegisterClient()

int UpnpUnRegisterClient ( UpnpClient_Handle Hnd )

Unregisters a control point application, unsubscribing all active subscriptions.

This function unregisters a client registered with UpnpRegisterClient(). After this call, the UpnpClient_Handle is no longer valid. The UPnP Library generates no more callbacks after this function returns.

UpnpUnRegisterClient() is a synchronous call and generates no callbacks.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.

Parameters

[in] Hnd The handle of the control point instance to unregister.

Definition at line 1458 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetNameForAlias()

static int GetNameForAlias	(	char *	name,
		char **	alias
	)

static

Determines alias for given name which is a file name or URL.

Returns: UPNP_E_SUCCESS on success, nonzero on failure.

Parameters

[in]	name	Name of the file.
[out]	alias	Pointer to alias string.

Definition at line 1516 of file upnpapi.cpp.

Here is the caller graph for this function:

◆ get_server_addr()

static void get_server_addr ( struct sockaddr * serverAddr )

static

Fill the sockadr with IPv4 miniserver information.

Parameters

[out] serverAddr pointer to server address structure.

Definition at line 1542 of file upnpapi.cpp.

Here is the caller graph for this function:

◆ get_server_addr6()

static void get_server_addr6 ( struct sockaddr * serverAddr )

static

Fill the sockadr with IPv6 miniserver information.

Parameters

[out] serverAddr pointer to server address structure.

Definition at line 1557 of file upnpapi.cpp.

Here is the caller graph for this function:

◆ UpnpSendAdvertisement()

int UpnpSendAdvertisement	(	UpnpDevice_Handle	Hnd,
		int	Exp
	)

Sends out the discovery announcements for all devices and services contained within one root device.

Each announcement is made with the same expiration time.

This is a synchronous call.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.

Parameters

[in]	Hnd	The device handle for which to send out the announcements.
[in]	Exp	The expiration age, in seconds, of the announcements. If the expiration age is less than 1 then the expiration age is set to `DEFAULT_MAXAGE`. If the expiration age is less than or equal to `AUTO_ADVERTISEMENT_TIME` * 2 then the expiration age is set to ( `AUTO_ADVERTISEMENT_TIME` + 1 ) * 2.

Definition at line 1718 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpSendAdvertisementLowPower()

int UpnpSendAdvertisementLowPower	(	UpnpDevice_Handle	Hnd,
		int	Exp,
		int	PowerState,
		int	SleepPeriod,
		int	RegistrationState
	)

Sends out the discovery announcements for all devices and services contained within one root device.

Each announcement is made with the same expiration time.

This is a synchronous call.

This function allow a device to specify the SSDP extensions defined by UPnP Low Power.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.

Parameters

[in]	Hnd	The device handle for which to send out the announcements.
[in]	Exp	The expiration age, in seconds, of the announcements. If the expiration age is less than 1 then the expiration age is set to `DEFAULT_MAXAGE`. If the expiration age is less than or equal to `AUTO_ADVERTISEMENT_TIME` * 2 then the expiration age is set to ( `AUTO_ADVERTISEMENT_TIME` + 1 ) * 2.
[in]	PowerState	PowerState as defined by UPnP Low Power.
[in]	SleepPeriod	SleepPeriod as defined by UPnP Low Power.
[in]	RegistrationState	RegistrationState as defined by UPnP Low Power.

Definition at line 1724 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpSetMaxSubscriptions()

int UpnpSetMaxSubscriptions	(	UpnpDevice_Handle	Hnd,
		int	MaxSubscriptions
	)

Sets the maximum number of subscriptions accepted per service.

The default value accepts as many as system resources allow. If the number of current subscriptions for a service is greater than the requested value, the SDK accepts no new subscriptions or renewals, however, the SDK does not remove any current subscriptions.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.

Parameters

Hnd	The handle of the device for which the maximum number of subscriptions is being set.
MaxSubscriptions	The maximum number of subscriptions to be allowed per service.

Definition at line 1869 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSetMaxSubscriptionTimeOut()

int UpnpSetMaxSubscriptionTimeOut	(	UpnpDevice_Handle	Hnd,
		int	MaxSubscriptionTimeOut
	)

Sets the maximum time-out accepted for a subscription request or renewal.

The default value accepts the time-out set by the control point. If a control point requests a subscription time-out less than or equal to the maximum, the SDK grants the value requested by the control point. If the time-out is greater, the SDK returns the maximum value.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.

Parameters

Hnd	The handle of the device for which the maximum subscription time-out is being set.
MaxSubscriptionTimeOut	The maximum subscription time-out to be accepted.

Definition at line 1902 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSubscribeAsync()

int UpnpSubscribeAsync	(	UpnpClient_Handle	Hnd,
		const char *	EvtUrl_const,
		int	TimeOut,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Performs the same operation as UpnpSubscribe(), but returns immediately and calls the registered callback function when the operation is complete.

Note that many of the error codes for this function are returned in the s_UpnpEventSubscribe structure. In those cases, the function returns UPNP_E_SUCCESS and the appropriate error code will be in the UpnpEventSubscribe.ErrCode field in the Event structure passed to the callback.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_URL: The PublisherUrl is not a valid URL.
UPNP_E_INVALID_PARAM: Either TimeOut or Fun or PublisherUrl is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
UPNP_E_NETWORK_ERROR: A network error occured (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_BIND: An error occurred binding the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_OUTOF_SOCKET: An error occurred creating the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription request (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).

Parameters

Hnd	The handle of the control point that is subscribing.
EvtUrl_const	The URL of the service to subscribe to.
TimeOut	The requested subscription time. Upon return, it contains the actual subscription time returned from the service.
Fun	Pointer to the callback function for this subscribe request.
Cookie_const	A user data value passed to the callback function when invoked.

Definition at line 1939 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSubscribe()

int UpnpSubscribe	(	UpnpClient_Handle	Hnd,
		const char *	EvtUrl_const,
		int *	TimeOut,
		Upnp_SID	SubsId
	)

Registers a control point to receive event notifications from a UPnP device.

This operation is synchronous.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_URL: PublisherUrl is not a valid URL.
UPNP_E_INVALID_PARAM: Timeout is not a valid pointer or SubsId or PublisherUrl is a nullptr.
UPNP_E_NETWORK_ERROR: A network error occured.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl.
UPNP_E_OUTOF_SOCKET: An error occurred creating a socket.
UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher.
UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription request.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point.
[in]	EvtUrl_const	The URL of the service to subscribe to.
[in,out]	TimeOut	Pointer to a variable containing the requested subscription time. Upon return, it contains the actual subscription time returned from the service.
[out]	SubsId	Pointer to a variable to receive the subscription ID (SID).

Definition at line 2005 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpUnSubscribe()

int UpnpUnSubscribe	(	UpnpClient_Handle	Hnd,
		const Upnp_SID	SubsId
	)

Removes the subscription of a control point from a service previously subscribed to using UpnpSubscribe() or UpnpSubscribeAsync().

This is a synchronous call.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_SID: The SubsId is not a valid subscription ID.
UPNP_E_NETWORK_ERROR: A network error occured.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl.
UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher.
UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused the unsubscribe request (the client is still unsubscribed and no longer receives events).
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the subscribed control point.
[in]	SubsId	The ID returned when the control point subscribed to the service.

Definition at line 2071 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpUnSubscribeAsync()

int UpnpUnSubscribeAsync	(	UpnpClient_Handle	Hnd,
		Upnp_SID	SubsId,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Removes a subscription of a control point from a service previously subscribed to using UpnpSubscribe() or UpnpSubscribeAsync(), generating a callback when the operation is complete.

Note that many of the error codes for this function are returned in the s_UpnpEventSubscribe structure. In those cases, the function returns UPNP_E_SUCCESS and the appropriate error code will be in the UpnpEventSubscribe.ErrCode field in the Event structure passed to the callback.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_SID: The SubsId is not a valid SID.
UPNP_E_INVALID_PARAM: Fun is not a valid callback function pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
UPNP_E_NETWORK_ERROR: A network error occured (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_BIND: An error occurred binding the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_OUTOF_SOCKET: An error occurred creating a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused the subscription request (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).

Parameters

[in]	Hnd	The handle of the subscribed control point.
[in]	SubsId	The ID returned when the control point subscribed to the service.
[in]	Fun	Pointer to a callback function to be called when the operation is complete.
[in]	Cookie_const	Pointer to user data to pass to the callback function when invoked.

Definition at line 2117 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpRenewSubscription()

int UpnpRenewSubscription	(	UpnpClient_Handle	Hnd,
		int *	TimeOut,
		const Upnp_SID	SubsId
	)

Renews a subscription that is about to expire.

This function is synchronous.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_PARAM: Timeout is not a valid pointer.
UPNP_E_INVALID_SID: The SID being passed to this function is not a valid subscription ID.
UPNP_E_NETWORK_ERROR: A network error occured.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl.
UPNP_E_OUTOF_SOCKET: An error occurred creating a socket.
UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher.
UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription renew.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point that is renewing the subscription.
[in,out]	TimeOut	Pointer to a variable containing the requested subscription time. Upon return, it contains the actual renewal time.
[in]	SubsId	The ID for the subscription to renew.

Definition at line 2182 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpRenewSubscriptionAsync()

int UpnpRenewSubscriptionAsync	(	UpnpClient_Handle	Hnd,
		int	TimeOut,
		Upnp_SID	SubsId,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Renews a subscription that is about to expire, generating a callback when the operation is complete.

Note that many of the error codes for this function are returned in the UpnpEventSubscribe structure. In those cases, the function returns UPNP_E_SUCCESS and the appropriate error code will be in the UpnpEventSubscribe.ErrCode field in the Event structure passed to the callback.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_SID: The SubsId is not a valid subscription ID.
UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function pointer or Timeout is less than zero but is not UPNP_INFINITE.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
UPNP_E_NETWORK_ERROR: A network error occured (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_BIND: An error occurred binding the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_OUTOF_SOCKET: An error occurred creating socket ( returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription request (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).

Parameters

[in]	Hnd	The handle of the control point that is renewing the subscription.
[in]	TimeOut	The requested subscription time. The actual timeout value is returned when the callback function is called.
[in]	SubsId	The ID for the subscription to renew.
[in]	Fun	Pointer to a callback function to be invoked when the renewal is complete.
[in]	Cookie_const	Pointer to user data passed to the callback function when invoked.

Definition at line 2235 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpNotify()

int UpnpNotify	(	UpnpDevice_Handle	Hnd,
		const char *	DevID_const,
		const char *	ServName_const,
		const char **	VarName_const,
		const char **	NewVal_const,
		int	cVariables
	)

Sends out an event change notification to all control points subscribed to a particular service.

This function is synchronous and generates no callbacks.

This function may be called during a callback function to send out a notification.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
UPNP_E_INVALID_SERVICE: The DevId/ServName pair refers to an invalid service.
UPNP_E_INVALID_PARAM: Either VarName, NewVal, DevID, or ServName is not a valid pointer or cVariables is less than zero.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle to the device sending the event.
[in]	DevID_const	The device ID of the subdevice of the service generating the event.
[in]	ServName_const	The unique identifier of the service generating the event.
[in]	VarName_const	Pointer to an array of variables that have changed.
[in]	NewVal_const	Pointer to an array of new values for those variables.
[in]	cVariables	The count of variables included in this notification.

Definition at line 2300 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpNotifyExt()

int UpnpNotifyExt	(	UpnpDevice_Handle	Hnd,
		const char *	DevID_const,
		const char *	ServName_const,
		IXML_Document *	PropSet
	)

Similar to UpnpNotify() except that it takes a DOM document for the event rather than an array of strings.

This function is synchronous and generates no callbacks.

This function may be called during a callback function to send out a notification.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
UPNP_E_INVALID_SERVICE: The DevId/ServName pair refers to an invalid service.
UPNP_E_INVALID_PARAM: Either DevID, ServName, or PropSet is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle to the device sending the event.
[in]	DevID_const	The device ID of the subdevice of the service generating the event.
[in]	ServName_const	The unique identifier of the service generating the event.
[in]	PropSet	The DOM document for the property set. Property set documents must conform to the XML schema defined in section 4.3 of the Universal Plug and Play Device Architecture specification.

Definition at line 2345 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpAcceptSubscriptionExt()

int UpnpAcceptSubscriptionExt	(	UpnpDevice_Handle	Hnd,
		const char *	DevID_const,
		const char *	ServName_const,
		IXML_Document *	PropSet,
		const Upnp_SID	SubsId
	)

Similar to UpnpAcceptSubscription() except that it takes a DOM document for the variables to event rather than an array of strings.

This function is sychronous and generates no callbacks.

This function can be called during the execution of a callback function.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
UPNP_E_INVALID_SERVICE: The DevId/ServId pair refers to an invalid service.
UPNP_E_INVALID_SID: The specified subscription ID is not valid.
UPNP_E_INVALID_PARAM: Either VarName, NewVal, DevID, ServID, or PropSet is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the device.
[in]	DevID_const	The device ID of the subdevice of the service generating the event.
[in]	ServName_const	The unique service identifier of the service generating the event.
[in]	PropSet	The DOM document for the property set. Property set documents must conform to the XML schema defined in section 4.3 of the Universal Plug and Play Device Architecture specification.
[in]	SubsId	The subscription ID of the newly registered control point.

Definition at line 2460 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSendAction()

int UpnpSendAction	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Action,
		IXML_Document **	RespNodePtr
	)

Sends a message to change a state variable in a service.

This is a synchronous call that does not return until the action is complete.

Note that a positive return value indicates a SOAP-protocol error code. In this case, the error description can be retrieved from RespNode. A negative return value indicates an SDK error.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
UPNP_E_INVALID_ACTION: This action is not valid.
UPNP_E_INVALID_DEVICE: DevUDN is not a valid device.
UPNP_E_INVALID_PARAM: ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a `nullptr`.
[in]	Action	The DOM document for the action.
[out]	RespNodePtr	The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

Definition at line 2538 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpSendActionEx()

int UpnpSendActionEx	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Header,
		IXML_Document *	Action,
		IXML_Document **	RespNodePtr
	)

Sends a message to change a state variable in a service.

This is a synchronous call that does not return until the action is complete.

Note that a positive return value indicates a SOAP-protocol error code. In this case, the error description can be retrieved from RespNode. A negative return value indicates an SDK error.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
UPNP_E_INVALID_ACTION: This action is not valid.
UPNP_E_INVALID_DEVICE: DevUDN is not a valid device.
UPNP_E_INVALID_PARAM: ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a `nullptr`.
[in]	Header	The DOM document for the SOAP header. This may be a `nullptr` if the header is not required.
[in]	Action	The DOM document for the action.
[out]	RespNodePtr	The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

Definition at line 2586 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSendActionAsync()

int UpnpSendActionAsync	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Act,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Sends a message to change a state variable in a service, generating a callback when the operation is complete.

See UpnpSendAction() for comments on positive return values. These positive return values are sent in the event struct associated with the UPNP_CONTROL_ACTION_COMPLETE event.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_URL: ActionUrl is an invalid URL.
UPNP_E_INVALID_DEVICE: DevUDN is an invalid device.
UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is a nullptr.
UPNP_E_INVALID_ACTION: This action is not valid.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a `nullptr`.
[in]	Act	The DOM document for the action to perform on this device.
[in]	Fun	Pointer to a callback function to be invoked when the operation completes.
[in]	Cookie_const	Pointer to user data that to be passed to the callback when invoked.

Definition at line 2634 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpSendActionExAsync()

int UpnpSendActionExAsync	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Header,
		IXML_Document *	Act,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Sends a message to change a state variable in a service, generating a callback when the operation is complete.

See UpnpSendAction() for comments on positive return values. These positive return values are sent in the event struct associated with the UPNP_CONTROL_ACTION_COMPLETE event.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_URL: ActionUrl is an invalid URL.
UPNP_E_INVALID_DEVICE: DevUDN is an invalid device.
UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is a nullptr.
UPNP_E_INVALID_ACTION: This action is not valid.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a `nullptr`.
[in]	Header	The DOM document for the SOAP header. This may be a `nullptr` if the header is not required.
[in]	Act	The DOM document for the action to perform on this device.
[in]	Fun	Pointer to a callback function to be invoked when the operation completes.
[in]	Cookie_const	Pointer to user data that to be passed to the callback when invoked.

Definition at line 2720 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpGetServiceVarStatusAsync()

int UpnpGetServiceVarStatusAsync	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	VarName_const,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Queries the state of a variable of a service, generating a callback when the operation is complete.

Deprecated:: The use of this function is deprecated by the UPnP Forum.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
UPNP_E_INVALID_URL: The ActionUrl is not a valid URL.
UPNP_E_INVALID_PARAM: VarName, Fun or ActionUrl is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point.
[in]	ActionURL_const	The URL of the service.
[in]	VarName_const	The name of the variable to query.
[in]	Fun	Pointer to a callback function to be invoked when the operation is complete.
[in]	Cookie_const	Pointer to user data to pass to the callback function when invoked.

Definition at line 2832 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpOpenHttpPost()

int UpnpOpenHttpPost	(	const char *	url,
		void **	handle,
		const char *	contentType,
		int	contentLength,
		int	timeout
	)

Makes an HTTP POST request message, opens a connection to the server and sends the POST request to the server if the connection to the server succeeds.

The SDK allocates the memory for handle, the application is responsible for freeing this memory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url, handle or contentType is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_SOCKET_ERROR: Error occured allocating a socket and resources or an error occurred binding a socket.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	url	The URL in which to send the POST request.
[in,out]	handle	A pointer in which to store the handle for this connection. This handle is required for futher operations over this connection.
[in]	contentType	A buffer to store the media type of content being sent. Can be NULL.
[in]	contentLength	The length of the content, in bytes, being posted.
[in]	timeout	The time out value sent with the request during which a response is expected from the receiver, failing which, an error is reported. If value is negative, timeout is infinite.

Definition at line 2945 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpWriteHttpPost()

int UpnpWriteHttpPost	(	void *	handle,
		char *	buf,
		size_t *	size,
		int	timeout
	)

Sends a request to a server to copy the contents of a buffer to the URI specified in the UpnpOpenHttpPost() call.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either handle, buf or size is not a valid pointer.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	handle	The handle of the connection created by the call to UpnpOpenHttpPost().
[in]	buf	The buffer to be posted.
[in]	size	The size, in bytes of buf.
[in]	timeout	A timeout value sent with the request during which a response is expected from the server, failing which, an error is reported. If value is negative, timeout is infinite.

Definition at line 2955 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpCloseHttpPost()

int UpnpCloseHttpPost	(	void *	handle,
		int *	httpStatus,
		int	timeout
	)

Sends and receives any pending data, closes the connection with the server, and frees memory allocated during the UpnpOpenHttpPost() call.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either handle, or httpStatus is not a valid pointer.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	handle	The handle of the connection to close, created by the call to UpnpOpenHttpPost().
[in,out]	httpStatus	A pointer to a buffer to store the final status of the connection.
[in]	timeout	A time out value sent with the request during which a response is expected from the server, failing which, an error is reported. If value is negative, timeout is infinite.

Definition at line 2959 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpOpenHttpGet()

int UpnpOpenHttpGet	(	const char *	url,
		void **	handle,
		char **	contentType,
		int *	contentLength,
		int *	httpStatus,
		int	timeout
	)

Gets a file specified in a URL.

The SDK allocates the memory for handle and contentType, the application is responsible for freeing this memory.

Note: Memory for contentType is freed when freeing the memory for handle.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url, handle, is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.

Parameters

[in]	url	The URL of an item to get.
[in,out]	handle	A pointer to store the handle for this connection.
[in,out]	contentType	A buffer to store the media type of the item.
[in,out]	contentLength	A pointer to store the length of the item.
[in,out]	httpStatus	The status returned on receiving a response message.
[in]	timeout	The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user. If value is negative, timeout is infinite.

Definition at line 2969 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpOpenHttpGetProxy()

int UpnpOpenHttpGetProxy	(	const char *	url,
		const char *	proxy_str,
		void **	handle,
		char **	contentType,
		int *	contentLength,
		int *	httpStatus,
		int	timeout
	)

Gets a file specified in a URL through the specified proxy.

The SDK allocates the memory for handle and contentType, the application is responsible for freeing this memory.

Note: Memory for contentType is freed when freeing the memory for handle.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url, handle, is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.

Parameters

[in]	url	The URL of an item to get.
[in]	proxy_str	The URL of the proxy.
[in,out]	handle	A pointer to store the handle for this connection.
[in,out]	contentType	A buffer to store the media type of the item.
[in,out]	contentLength	A pointer to store the length of the item.
[in,out]	httpStatus	The status returned on receiving a response message.
[in]	timeout	The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user. If value is negative, timeout is infinite.

Definition at line 2986 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpOpenHttpGetEx()

int UpnpOpenHttpGetEx	(	const char *	url_str,
		void **	Handle,
		char **	contentType,
		int *	contentLength,
		int *	httpStatus,
		int	lowRange,
		int	highRange,
		int	timeout
	)

Gets specified number of bytes from a file specified in the URL.

The number of bytes is specified through a low count and a high count which are passed as a range of bytes for the request. The SDK allocates the memory for handle and contentType, the application is responsible for freeing this memory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url, handle, contentType, contentLength or httpStatus is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.

Parameters

[in]	url_str	The URL of the item to get.
[in,out]	Handle	A pointer to store the handle for this connection.
[in,out]	contentType	A buffer to store the media type of the item.
[in,out]	contentLength	A buffer to store the length of the item.
[in,out]	httpStatus	The status returned on receiving a response message from the remote server.
[in]	lowRange	An integer value representing the low end of a range to retrieve.
[in]	highRange	An integer value representing the high end of a range to retrieve.
[in]	timeout	A time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user. If value is negative, timeout is infinite.

Definition at line 3004 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpCancelHttpGet()

int UpnpCancelHttpGet ( void * Handle )

Set the cancel flag of the handle parameter.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: handle is not a valid pointer.

Parameters

[in] Handle The handle of the connection created by the call to UpnpOpenHttpGet.

Definition at line 3011 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpCloseHttpGet()

int UpnpCloseHttpGet ( void * Handle )

Closes the connection and frees memory that was allocated for the handle parameter.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: handle is not a valid pointer.

Parameters

[in] Handle The handle of the connection created by the call to UpnpOpenHttpGet.

Definition at line 3013 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpReadHttpGet()

int UpnpReadHttpGet	(	void *	Handle,
		char *	buf,
		size_t *	size,
		int	timeout
	)

Gets specified number of bytes from a file specified in a URL.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either handle, buf or size is not a valid pointer.
UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.
UPNP_E_BAD_HTTPMSG: Either the request or response was in the incorrect format.
UPNP_E_CANCELED: another thread called UpnpCancelHttpGet.

Note: In case of return values, the status code parameter of the passed in handle value may provide additional information on the return value.

Parameters

[in]	Handle	The token created by the call to UpnpOpenHttpGet.
[in,out]	buf	The buffer to store the read item.
[in,out]	size	The size of the buffer to be read.
[in]	timeout	The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user. If value is negative, timeout is infinite.

Definition at line 3015 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpHttpGetProgress()

int UpnpHttpGetProgress	(	void *	Handle,
		size_t *	length,
		size_t *	total
	)

Retrieve progress information of a http-get transfer.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either handle, length or total is not a valid pointer.

Parameters

[in]	Handle	The token created by the call to UpnpOpenHttpGet.
[out]	length	The number of bytes received.
[out]	total	The content length.

Definition at line 3019 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpOpenHttpConnection()

int UpnpOpenHttpConnection	(	const char *	url,
		void **	handle,
		int	timeout
	)

Opens a connection to the server.

The SDK allocates the memory for handle, the application is responsible for freeing this memory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url, or handle is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_SOCKET_ERROR: Error occured allocating a socket and resources or an error occurred binding a socket.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	url	The URL which contains the host, and the scheme to make the connection.
[in,out]	handle	A pointer in which to store the handle for this connection. This handle is required for futher operations over this connection.
[in]	timeout	The time out value sent with the request during which a response is expected from the receiver, failing which, an error is reported. If value is negative, timeout is infinite.

Definition at line 3023 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpMakeHttpRequest()

int UpnpMakeHttpRequest	(	Upnp_HttpMethod	method,
		const char *	url,
		void *	handle,
		UpnpString *	headers,
		const char *	contentType,
		int	contentLength,
		int	timeout
	)

Makes a HTTP request using a connection previously created by UpnpOpenHttpConnection().

Note: Trying to make another request while a request is already being processed results in undefined behavior. It's up to the user to end a previous request by calling UpnpEndHttpRequest().

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url, handle or contentType is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_SOCKET_ERROR: Error occured allocating a socket and resources or an error occurred binding a socket.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	method	The method to use to make the request.
[in]	url	The URL to use to make the request. The URL should use the same scheme used to create the connection, but the host can be different if the request is being proxied.
[in]	handle	The handle to the connection.
[in]	headers	Headers to be used for the request. Each header should be terminated by a CRLF as specified in the HTTP specification. If NULL then the default headers will be used.
[in]	contentType	The media type of content being sent. Can be NULL.
[in]	contentLength	The length of the content being sent, in bytes. Set to UPNP_USING_CHUNKED to use chunked encoding, or UPNP_UNTIL_CLOSE to avoid specifying the content length to the server. In this case the request is considered unfinished until the connection is closed.
[in]	timeout	The time out value sent with the request during which a response is expected from the receiver, failing which, an error is reported. If value is negative, timeout is infinite.

Definition at line 3027 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpWriteHttpRequest()

int UpnpWriteHttpRequest	(	void *	handle,
		char *	buf,
		size_t *	size,
		int	timeout
	)

Writes the content of a HTTP request initiated by a UpnpMakeHttpRequest() call. The end of the content should be indicated by a call to UpnpEndHttpRequest().

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either handle, buf or size is not a valid pointer.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	handle	The handle of the connection created by the call to UpnpOpenHttpConnection().
[in]	buf	The buffer containing date to be written.
[in]	size	The size, in bytes of buf.
[in]	timeout	A timeout value sent with the request during which a response is expected from the server, failing which, an error is reported. If value is negative, timeout is infinite.

Definition at line 3034 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpEndHttpRequest()

int UpnpEndHttpRequest	(	void *	handle,
		int	timeout
	)

Indicates the end of a HTTP request previously made by UpnpMakeHttpRequest().

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: handle is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_SOCKET_ERROR: Error occured allocating a socket and resources or an error occurred binding a socket.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	handle	The handle to the connection.
[in]	timeout	The time out value sent with the request during which a response is expected from the receiver, failing which, an error is reported. If value is negative, timeout is infinite.

Definition at line 3038 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpGetHttpResponse()

int UpnpGetHttpResponse	(	void *	handle,
		UpnpString *	headers,
		char **	contentType,
		int *	contentLength,
		int *	httpStatus,
		int	timeout
	)

Gets the response from the server using a connection previously created by UpnpOpenHttpConnection().

Note: Memory for contentType is only valid until the next call to the HTTP API for the same connection.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either handle, is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.

Parameters

[in]	handle	The handle of the connection created by the call to UpnpOpenHttpConnection().
[in]	headers	Headers sent by the server for the response. If NULL then the headers are not copied.
[out]	contentType	A buffer to store the media type of the item.
[out]	contentLength	A pointer to store the length of the item.
[out]	httpStatus	The status returned on receiving a response message.
[in]	timeout	The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user. If value is negative, timeout is infinite.

Definition at line 3042 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpReadHttpResponse()

int UpnpReadHttpResponse	(	void *	handle,
		char *	buf,
		size_t *	size,
		int	timeout
	)

Reads the content of a response using a connection previously created by UpnpOpenHttpConnection().

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either handle, buf or size is not a valid pointer.
UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.
UPNP_E_BAD_HTTPMSG: Either the request or response was in the incorrect format.
UPNP_E_CANCELED: another thread called UpnpCancelHttpGet.

Note: In case of return values, the status code parameter of the passed in handle value may provide additional information on the return value.

Parameters

[in]	handle	The handle of the connection created by the call to UpnpOpenHttpConnection().
[in,out]	buf	The buffer to store the read item.
[in,out]	size	The size of the buffer to be read.
[in]	timeout	The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user. If value is negative, timeout is infinite.

Definition at line 3048 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpCloseHttpConnection()

int UpnpCloseHttpConnection ( void * handle )

Closes the connection created with UpnpOpenHttpConnection() and frees any memory associated with the connection.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: handle, or is not a valid pointer.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in] handle The handle of the connection to close, created by the call to UpnpOpenHttpPost().

Definition at line 3052 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpDownloadUrlItem()

int UpnpDownloadUrlItem	(	const char *	url,
		char **	outBuf,
		char *	contentType
	)

Downloads a file specified in a URL.

The SDK allocates the memory for outBuf and the application is responsible for freeing this memory. Note that the item is passed as a single buffer. Large items should not be transferred using this function.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url, outBuf or contentType is not a valid pointer.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	url	URL of an item to download.
[out]	outBuf	Buffer to store the downloaded item.
[out]	contentType	HTTP header value content type if present. It should be at least `LINE_SIZE` bytes in size.

Definition at line 3058 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpDownloadXmlDoc()

int UpnpDownloadXmlDoc	(	const char *	url,
		IXML_Document **	xmlDoc
	)

Downloads an XML document specified in a URL.

The SDK parses the document and returns it in the form of a DOM document. The application is responsible for freeing the DOM document.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: Either url or xmlDoc is not a valid pointer.
UPNP_E_INVALID_DESC: The XML document was not found or it does not contain a valid XML description.
UPNP_E_INVALID_URL: The url is not a valid URL.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to download the XML document.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.

Parameters

[in]	url	URL of the XML document.
[out]	xmlDoc	A pointer to a variable in which to store the pointer to the XML document.

Definition at line 3080 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 )

Schedule async functions in threadpool.

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:

◆ GetCallBackFn()

Upnp_FunPtr GetCallBackFn ( UpnpClient_Handle Hnd )

Get callback function ptr from a handle.

Returns: Upnp_FunPtr

Definition at line 3243 of file upnpapi.cpp.

◆ 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:

◆ 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:

◆ 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:

◆ 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:

◆ UpnpSetWebServerRootDir()

int UpnpSetWebServerRootDir ( const char * rootDir )

Sets the document root directory for the internal web server.

This directory is considered the root directory (i.e. "/") of the web server.

The function is independent of whether the web server is enabled or disabled. To select the root directory '/' of the filesystem on the local storage to be also the websites virtual root directory then use UpnpSetWebServerRootDir("//").

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The library has not been initialized.
UPNP_E_INVALID_PARAM: rootDir argument is not valid.
UPNP_E_OUTOF_MEMORY: Resource for storing string not available.

Parameters

[in] rootDir Path on the filesystem of the local storage to be the root directory of the web server.

Definition at line 3398 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSetWebServerCorsString()

int UpnpSetWebServerCorsString ( const char * corsString )

Assign the Access-Control-Allow-Origin specfied by the input const char* cors_string parameter to the global CORS string.

Note: This function is not available when the web server is not compiled into the UPnP Library.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_ARGUMENT: rootDir is an invalid directory.

Parameters

[in] corsString String having the Access-Control-Allow-Origin string.

Definition at line 3411 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpAddVirtualDir()

int UpnpAddVirtualDir	(	const char *	newDirName,
		const void *	cookie,
		const void **	oldcookie
	)

Adds a web directory mapping.

All webserver requests containing the given directory are read using functions contained in a VirtualDirCallbacks structure registered via UpnpSetVirtualDirCallbacks().

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The library has not been initialized.
UPNP_E_INVALID_ARGUMENT: dirName is not valid.

Parameters

[in]	newDirName	The name of the new directory mapping to add.
[in]	cookie	The cookie to associated with this web directory
[out]	oldcookie	The cookie previously associated, if mapping is already present

Definition at line 3424 of file upnpapi.cpp.

◆ UpnpRemoveVirtualDir()

int UpnpRemoveVirtualDir ( const char * dirName )

Removes a web directory mapping made with UpnpAddVirtualDir().

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The library has not been initialized.
UPNP_E_INVALID_ARGUMENT: dirName is not valid.

Parameters

[in] dirName The name of the web directory mapping to remove.

Definition at line 3499 of file upnpapi.cpp.

◆ UpnpRemoveAllVirtualDirs()

void UpnpRemoveAllVirtualDirs ( void )

Removes all web directory mappings.

Definition at line 3545 of file upnpapi.cpp.

Here is the caller graph for this function:

◆ UpnpEnableWebserver()

int UpnpEnableWebserver ( int enable )

Enables or disables the webserver.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The library has not been initialized.
UPNP_E_OUTOF_MEMORY: The web server could not be started due to an out-of-memory condition.
UPNP_E_NO_WEB_SERVER: The internal web server has been compiled out so it can't be enabled or disabled.

Parameters

[in] enable 1 to enable, 0 to disable.

Definition at line 3565 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpIsWebserverEnabled()

int UpnpIsWebserverEnabled ( void )

Returns the status of the webserver.

Returns

An integer representing one of the following:

1: The webserver is enabled.
0: The webserver is not enabled.

Definition at line 3581 of file upnpapi.cpp.

◆ UpnpSetHostValidateCallback()

void UpnpSetHostValidateCallback	(	WebCallback_HostValidate	callback,
		void *	cookie
	)

Set callback for validating HTTP requests HOST header values.

Parameters

callback	the host validating callback function or NULL.
cookie	the chocolate you like.

Definition at line 3589 of file upnpapi.cpp.

◆ UpnpSetAllowLiteralHostRedirection()

void UpnpSetAllowLiteralHostRedirection ( int enable )

Enable or disable literal IP redirection.

Parameters

enable Zero to disable (default) non-zero to enable.

Definition at line 3595 of file upnpapi.cpp.

◆ UpnpVirtualDir_set_GetInfoCallback()

int UpnpVirtualDir_set_GetInfoCallback ( VDCallback_GetInfo callback )

Sets the get_info callback function to be used to access a web directory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: callback is not a valid pointer.
UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

Definition at line 3599 of file upnpapi.cpp.

◆ UpnpVirtualDir_set_OpenCallback()

int UpnpVirtualDir_set_OpenCallback ( VDCallback_Open callback )

Sets the open callback function to be used to access a web directory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: callback is not a valid pointer.
UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

Definition at line 3610 of file upnpapi.cpp.

◆ UpnpVirtualDir_set_ReadCallback()

int UpnpVirtualDir_set_ReadCallback ( VDCallback_Read callback )

Sets the read callback function to be used to access a web directory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: callback is not a valid pointer.
UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

Definition at line 3621 of file upnpapi.cpp.

◆ UpnpVirtualDir_set_WriteCallback()

int UpnpVirtualDir_set_WriteCallback ( VDCallback_Write callback )

Sets the write callback function to be used to access a web directory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: callback is not a valid pointer.
UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

Definition at line 3632 of file upnpapi.cpp.

◆ UpnpVirtualDir_set_SeekCallback()

int UpnpVirtualDir_set_SeekCallback ( VDCallback_Seek callback )

Sets the seek callback function to be used to access a web directory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: callback is not a valid pointer.
UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

Definition at line 3643 of file upnpapi.cpp.

◆ UpnpVirtualDir_set_CloseCallback()

int UpnpVirtualDir_set_CloseCallback ( VDCallback_Close callback )

Sets the close callback function to be used to access a web directory.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_INVALID_PARAM: callback is not a valid pointer.
UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

Definition at line 3654 of file upnpapi.cpp.

◆ UpnpSetContentLength()

int UpnpSetContentLength	(	UpnpClient_Handle	Hnd,
		size_t	contentLength
	)

Sets the content-length that the SDK will process on an incoming SOAP requests or responses.

Deprecated:: Warning: The Handle argument provided here is not used, so the effect of this function is global to the SDK (= same as UpnpSetMaxContentLength()). Use UpnpSetMaxContentLength() instead.

Parameters

[in]	Hnd	The handle of the device instance for which the coincoming content length needs to be set.
[in]	contentLength	Permissible content length

Definition at line 3666 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSetMaxContentLength()

int UpnpSetMaxContentLength ( size_t contentLength )

Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses.

This API allows devices that have memory constraints to exhibit consistent behaviour if the size of the incoming SOAP message exceeds the memory that device can allocate.

If set to 0 then checking will be disabled.

The default maximum content-length is DEFAULT_SOAP_CONTENT_LENGTH = 16K bytes.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.

Parameters

[in] contentLength The maximum permissible content length for incoming SOAP actions, in bytes.

Definition at line 3696 of file upnpapi.cpp.

Variable Documentation

◆ virtualDirCallback

struct VirtualDirCallbacks virtualDirCallback

This structure is for virtual directory callbacks.

Definition at line 247 of file upnpapi.cpp.

◆ pVirtualDirList

virtualDirList* pVirtualDirList

Pointer to the virtual directory list.

Definition at line 250 of file upnpapi.cpp.

◆ GlobalHndRWLock

pthread_rwlock_t GlobalHndRWLock

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

Definition at line 253 of file upnpapi.cpp.

◆ gTimerThread

TimerThread gTimerThread

Global timer thread.

Definition at line 256 of file upnpapi.cpp.

◆ gSendThreadPool

ThreadPool gSendThreadPool

Send thread pool.

Definition at line 259 of file upnpapi.cpp.

◆ gRecvThreadPool

ThreadPool gRecvThreadPool

Receive thread pool.

Definition at line 262 of file upnpapi.cpp.

◆ gMiniServerThreadPool

ThreadPool gMiniServerThreadPool

Mini server thread pool.

Definition at line 265 of file upnpapi.cpp.

◆ bWebServerState

WebServerState bWebServerState = WEB_SERVER_DISABLED

Flag to indicate the state of web server.

Definition at line 268 of file upnpapi.cpp.

◆ gWebCallback_HostValidate

WebCallback_HostValidate gWebCallback_HostValidate = 0

webCallback for HOST validation.

Definition at line 271 of file upnpapi.cpp.

◆ gWebCallback_HostValidateCookie

void* gWebCallback_HostValidateCookie = 0

Cookie to the webCallback for HOST validation.

Definition at line 274 of file upnpapi.cpp.

◆ gAllowLiteralHostRedirection

int gAllowLiteralHostRedirection = 0

Allow literal host names redirection to numeric host names.

Definition at line 277 of file upnpapi.cpp.

◆ gIF_NAME

char gIF_NAME[LINE_SIZE] = {'\0'}

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

Definition at line 280 of file upnpapi.cpp.

◆ gIF_IPV4

char gIF_IPV4[INET_ADDRSTRLEN] = {'\0'}

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

Definition at line 284 of file upnpapi.cpp.

◆ gIF_IPV4_NETMASK

char gIF_IPV4_NETMASK[INET_ADDRSTRLEN] = {'\0'}

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

Definition at line 288 of file upnpapi.cpp.

◆ gIF_IPV6

char gIF_IPV6[INET6_ADDRSTRLEN] = {'\0'}

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

unsigned gIF_IPV6_PREFIX_LENGTH = 0

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

Definition at line 295 of file upnpapi.cpp.

◆ gIF_INDEX

unsigned gIF_INDEX

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.

◆ gIF_IPV6_ULA_GUA

char gIF_IPV6_ULA_GUA[INET6_ADDRSTRLEN] = {'\0'}

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

unsigned gIF_IPV6_ULA_GUA_PREFIX_LENGTH = 0

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

Definition at line 308 of file upnpapi.cpp.

◆ LOCAL_PORT_V4

in_port_t LOCAL_PORT_V4

local IPv4 port for the mini-server

Definition at line 311 of file upnpapi.cpp.

◆ LOCAL_PORT_V6

in_port_t LOCAL_PORT_V6

IPv6 LLA port for the mini-server.

Definition at line 314 of file upnpapi.cpp.

◆ LOCAL_PORT_V6_ULA_GUA

in_port_t LOCAL_PORT_V6_ULA_GUA

IPv6 ULA or GUA port for the mini-server.

Definition at line 317 of file upnpapi.cpp.

◆ gWebserverCorsString

membuffer gWebserverCorsString

externinline

a string which is set in the header field

Global variable. A string which is set in the header field.

Definition at line 47 of file webserver.hpp.

◆ g_maxContentLength

size_t g_maxContentLength = DEFAULT_SOAP_CONTENT_LENGTH

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 = MAX_SUBSCRIPTION_QUEUED_EVENTS

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 = MAX_SUBSCRIPTION_EVENT_AGE

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.

◆ UpnpSdkInit

int UpnpSdkInit = 0

Global variable to denote the state of Upnp SDK == 0 if uninitialized, == 1 if initialized.

Definition at line 350 of file upnpapi.cpp.

◆ UpnpSdkClientRegistered

int UpnpSdkClientRegistered = 0

Global variable to denote the state of Upnp SDK client registration.

== 0 if unregistered, >= 1 if registered - registered clients count.

Definition at line 355 of file upnpapi.cpp.

◆ UpnpSdkDeviceRegisteredV4

int UpnpSdkDeviceRegisteredV4 = 0

Global variable to denote the state of Upnp SDK IPv4 device registration.

== 0 if unregistered, == 1 if registered.

Definition at line 361 of file upnpapi.cpp.

◆ UpnpSdkDeviceregisteredV6

int UpnpSdkDeviceregisteredV6 = 0

Global variable to denote the state of Upnp SDK IPv6 device registration.

== 0 if unregistered, == 1 if registered.

Definition at line 367 of file upnpapi.cpp.

◆ gUpnpSdkNLSuuid

Upnp_SID gUpnpSdkNLSuuid

Global variable used in discovery notifications.

Only available when options SSDP are compiled in.

Definition at line 373 of file upnpapi.cpp.

UPnPsdk 0.1 Universal Plug and Play +, Software Development Kit

Classes

Namespaces

Macros

Functions

Variables

Detailed Description

Class Documentation

◆ job_arg

◆ job_arg.advertise

Macro Definition Documentation

◆ ifr_netmask

◆ IN6_IS_ADDR_ULA

Function Documentation

◆ free_advertise_arg()

◆ free_action_arg()

◆ UpnpInitMutexes()

◆ UpnpInitThreadPools()

◆ UpnpInitPreamble()

◆ UpnpInitStartServers()

◆ PrintThreadPoolStats()

◆ UpnpFinish()

◆ UpnpGetServerPort()

◆ UpnpGetServerPort6()

◆ UpnpGetServerUlaGuaPort6()

◆ UpnpGetServerIpAddress()

◆ UpnpGetServerIp6Address()

◆ UpnpGetServerUlaGuaIp6Address()

◆ GetFreeHandle()

◆ FreeHandle()

◆ UpnpRegisterRootDevice()

◆ GetDescDocumentAndURL()

◆ UpnpRegisterRootDevice2()

◆ UpnpRegisterRootDevice3()

◆ UpnpRegisterRootDevice4()

◆ UpnpUnRegisterRootDevice()

◆ UpnpUnRegisterRootDeviceLowPower()

◆ UpnpRegisterClient()

◆ UpnpUnRegisterClient()

◆ GetNameForAlias()

◆ get_server_addr()

◆ get_server_addr6()

◆ UpnpSendAdvertisement()

◆ UpnpSendAdvertisementLowPower()

◆ UpnpSetMaxSubscriptions()

◆ UpnpSetMaxSubscriptionTimeOut()

◆ UpnpSubscribeAsync()

◆ UpnpSubscribe()

◆ UpnpUnSubscribe()

◆ UpnpUnSubscribeAsync()

◆ UpnpRenewSubscription()

◆ UpnpRenewSubscriptionAsync()

◆ UpnpNotify()

◆ UpnpNotifyExt()

◆ UpnpAcceptSubscriptionExt()

◆ UpnpSendAction()

◆ UpnpSendActionEx()

◆ UpnpSendActionAsync()

◆ UpnpSendActionExAsync()

◆ UpnpGetServiceVarStatusAsync()

◆ UpnpOpenHttpPost()

◆ UpnpWriteHttpPost()

◆ UpnpCloseHttpPost()

◆ UpnpOpenHttpGet()

◆ UpnpOpenHttpGetProxy()

◆ UpnpOpenHttpGetEx()

◆ UpnpCancelHttpGet()

◆ UpnpCloseHttpGet()

◆ UpnpReadHttpGet()

◆ UpnpHttpGetProgress()

◆ UpnpOpenHttpConnection()

◆ UpnpMakeHttpRequest()

◆ UpnpWriteHttpRequest()

◆ UpnpEndHttpRequest()

◆ UpnpGetHttpResponse()

◆ UpnpReadHttpResponse()

◆ UpnpCloseHttpConnection()

◆ UpnpDownloadUrlItem()

◆ UpnpDownloadXmlDoc()

◆ UpnpThreadDistribution()

◆ GetCallBackFn()