upnp.h File Reference

main libnpupnp API definitions More...

#include <cstdint>
#include <ctime>
#include <map>
#include <string>
#include <unordered_map>
#include <utility>
#include <vector>
#include "upnpconfig.h"
#include <sys/socket.h>
#include "UpnpGlobal.h"

Go to the source code of this file.

Classes
struct	Upnp_Action_Request
struct	Upnp_Event
struct	Upnp_Discovery
struct	Upnp_Event_Subscribe
struct	Upnp_Subscription_Request
struct	File_Info
struct	UpnpVirtualDirCallbacks

Macros
#define	LINE_SIZE   size_t(180)
#define	NAME_SIZE   size_t(256)
#define	UPNP_INFINITE   -1
#define	UPNP_USING_CHUNKED   -3
#define	UPNP_UNTIL_CLOSE   -4
#define	UPNP_MAX_SEARCH_TIME   80
#define	UPNP_MIN_SEARCH_TIME   2

Functions
Initialization, common to client and device interfaces.
EXPORT_SPEC int	UpnpInit (const char *HostIP, unsigned short DestPort)
	Initializes the UPnP SDK for exclusive IP V4 operation on a single interface.
EXPORT_SPEC int	UpnpInit2 (const char *IfName, unsigned short DestPort)
	Initializes the library, passing the interface spec as a single string.
EXPORT_SPEC int	UpnpInit2 (const std::vector< std::string > &ifnames, unsigned short DestPort)
	Initializes the library, passing the interface spec as a vector.
EXPORT_SPEC int	UpnpInitWithOptions (const char *IfNames, unsigned short DestPort, unsigned int flags,...)
	Initializes the library, passing the interface spec as a string.
EXPORT_SPEC int	UpnpFinish (void)
	Terminate and clean up the library.
EXPORT_SPEC unsigned short	UpnpGetServerPort (void)
	Returns the internal server IPv4 UPnP listening port.
EXPORT_SPEC const char *	UpnpGetServerIpAddress (void)
	Returns a local IPv4 listening ip address.
EXPORT_SPEC int	UpnpSetMaxContentLength (size_t contentLength)
	Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses.
Initialization and termination, device interface.
EXPORT_SPEC int	UpnpRegisterRootDevice (const char *DescUrl, Upnp_FunPtr Fun, const void *Cookie, UpnpDevice_Handle *Hnd)
	Registers a device application with the UPnP Library.
EXPORT_SPEC int	UpnpRegisterRootDevice2 (Upnp_DescType descriptionType, const char *description, size_t bufferLen, int ignored, Upnp_FunPtr Fun, const void *Cookie, UpnpDevice_Handle *Hnd)
	Registers a device application with the UPnP Library. Similar to UpnpRegisterRootDevice, except that it also allows the description document to be specified as a file or a memory buffer, in which case, the data will be served by the internal WEB server.
EXPORT_SPEC int	UpnpRegisterRootDevice4 (const char *DescUrl, Upnp_FunPtr Fun, const void *Cookie, UpnpDevice_Handle *Hnd, int, const char *LowerDescUrl)
	Registers a device application with the UPnP library. This function can also be used to specify a dedicated description URL to be returned for legacy CPs.
EXPORT_SPEC int	UpnpDeviceSetProduct (UpnpDevice_Handle Hnd, const char *product, const char *version)
	Set the product information part of the SERVER header sent with some network requests.
EXPORT_SPEC int	UpnpUnRegisterRootDevice (UpnpDevice_Handle Hnd)
	Unregisters a root device.
EXPORT_SPEC int	UpnpUnRegisterRootDeviceLowPower (UpnpDevice_Handle Hnd, int PowerState, int SleepPeriod, int RegistrationState)
	Unregisters a root device.
Initialization and termination, client interface.
EXPORT_SPEC int	UpnpRegisterClient (Upnp_FunPtr Fun, const void *Cookie, UpnpClient_Handle *Hnd)
	Registers a control point application with the UPnP Library.
EXPORT_SPEC void	UpnpClientSetProduct (UpnpClient_Handle Hnd, const char *product, const char *version)
	Set the product information part of the User-Agent header sent with some network requests.
EXPORT_SPEC int	UpnpUnRegisterClient (UpnpClient_Handle Hnd)
	Unregisters a control point application, unsubscribing all active subscriptions.
Client interface: Discovery
EXPORT_SPEC int	UpnpSearchAsync (UpnpClient_Handle Hnd, int Mx, const char *Target, const void *cookie)
	Searches for devices matching the given search target.
EXPORT_SPEC int	UpnpSearchAsyncUnicast (UpnpClient_Handle Hnd, const std::string &url, const char *Target, void *cookie)
	Unicast search.
Device interface: Discovery
EXPORT_SPEC int	UpnpSendAdvertisement (UpnpDevice_Handle Hnd, int Exp)
	Sends out the discovery announcements for all devices and services for a device.
EXPORT_SPEC int	UpnpSendAdvertisementLowPower (UpnpDevice_Handle Hnd, int Exp, int PowerState, int SleepPeriod, int RegistrationState)
	Sends out the discovery announcements for all devices and services for a device.
Client interface: Control
EXPORT_SPEC int	UpnpSendAction (UpnpClient_Handle Hnd, const std::string &headerString, const std::string &actionURL, const std::string &serviceType, const std::string &actionName, const std::vector< std::pair< std::string, std::string > > &actionParams, std::vector< std::pair< std::string, std::string > > &responseData, int *errcodep, std::string &errdesc)
	Sends a message to change a state variable in a service.
Device interface: Eventing
EXPORT_SPEC int	UpnpAcceptSubscription (UpnpDevice_Handle Hnd, const char *DevID, const char *ServName, const char **VarName, const char **NewVal, int cVariables, const Upnp_SID &SubsId)
	Accepts a subscription request and sends out the current state of the eventable variables for a service.
EXPORT_SPEC int	UpnpAcceptSubscriptionXML (UpnpDevice_Handle Hnd, const char *DevID, const char *ServName, const std::string &propertyset, const Upnp_SID &SubsId)
EXPORT_SPEC int	UpnpNotify (UpnpDevice_Handle, const char *DevID, const char *ServName, const char **VarName, const char **NewVal, int cVariables)
	Sends out an event change notification to all control points subscribed to a particular service.
EXPORT_SPEC int	UpnpNotifyXML (UpnpDevice_Handle, const char *DevID, const char *ServName, const std::string &propset)
EXPORT_SPEC int	UpnpSetMaxSubscriptions (UpnpDevice_Handle Hnd, int MaxSubscriptions)
	Sets the maximum number of subscriptions accepted per service.
Client interface: Eventing
EXPORT_SPEC int	UpnpSubscribe (UpnpClient_Handle Hnd, const char *EvtUrl, int *TimeOut, Upnp_SID &SubsId)
	Registers a control point to receive event notifications from another device.
EXPORT_SPEC int	UpnpRenewSubscription (UpnpClient_Handle Hnd, int *TimeOut, const Upnp_SID &SubsId)
	Renews a subscription that is about to expire.
EXPORT_SPEC int	UpnpUnSubscribe (UpnpClient_Handle Hnd, const Upnp_SID &SubsId)
	Removes the subscription of a control point from a service previously subscribed to using UpnpSubscribe.
EXPORT_SPEC int	UpnpSetMaxSubscriptionTimeOut (UpnpDevice_Handle Hnd, int MaxSubscriptionTimeOut)
	Sets the maximum time-out accepted for a subscription request or renewal.
EXPORT_SPEC int	UpnpSubsOpsTimeoutMs (UpnpClient_Handle Hnd, int TimeOutMS)
	Sets the HTTP timeout for subscription operations.
Client interface: HTTP helper functions
EXPORT_SPEC int	UpnpDownloadUrlItem (const char *url, char **outBuf, char *contentType)
	Downloads a text file specified in a URL.
EXPORT_SPEC int	UpnpDownloadUrlItem (const std::string &url, std::string &data, std::string &ct)
	Downloads a file specified in a URL.

Error codes
The functions in the SDK API can return a variety of error codes to describe problems encountered during execution. This section lists the error codes and provides a brief description of what each error code means. Refer to the documentation for each function for a description of what an error code means in that context.
#define	UPNP_E_SUCCESS   0
	The operation completed successfully.
#define	UPNP_E_INVALID_HANDLE   -100
	Not a valid handle.
#define	UPNP_E_INVALID_PARAM   -101
	One or more of the parameters passed to the function is not valid.
#define	UPNP_E_OUTOF_HANDLE   -102
	The SDK does not have any more space for additional handles.
#define	UPNP_E_OUTOF_CONTEXT   -103
	Not used.
#define	UPNP_E_OUTOF_MEMORY   -104
	Insufficient resources available to complete the operation.
#define	UPNP_E_INIT   -105
	The SDK has already been initialized.
#define	UPNP_E_BUFFER_TOO_SMALL   -106
	Not used.
#define	UPNP_E_INVALID_DESC   -107
	The description document passed to UpnpRegisterRootDevice, UpnpRegisterRootDevice2 or UpnpRegisterRootDevice4 is invalid.
#define	UPNP_E_INVALID_URL   -108
	An URL passed into the function is invalid.
#define	UPNP_E_INVALID_SID   -109
	Invalid subscription identifier.
#define	UPNP_E_INVALID_DEVICE   -110
	Not used currently.
#define	UPNP_E_INVALID_SERVICE   -111
	The device ID/service ID pair does not refer to a valid service.
#define	UPNP_E_BAD_RESPONSE   -113
	The response received from the remote side of a connection is not correct for the protocol (GENA, SOAP, and HTTP).
#define	UPNP_E_BAD_REQUEST   -114
	Not used.
#define	UPNP_E_INVALID_ACTION   -115
	The SOAP action message is invalid. This can be because the DOM document passed to the function was malformed or the action message is not correct for the given action.
#define	UPNP_E_FINISH   -116
	UpnpInit has not been called, or UpnpFinish has already been called. None of the API functions operate until UpnpInit successfully completes.
#define	UPNP_E_INIT_FAILED   -117
	UpnpInit cannot complete. The typical reason is failure to allocate sufficient resources.
#define	UPNP_E_URL_TOO_BIG   -118
	The URL passed into a function is too long. The SDK limits URLs to LINE_SIZE characters in length.
#define	UPNP_E_BAD_HTTPMSG   -119
	The HTTP message contains invalid message headers.
#define	UPNP_E_ALREADY_REGISTERED   -120
	A client or a device is already registered.
#define	UPNP_E_INVALID_INTERFACE   -121
	The interface provided to UpnpInit2 is unknown or does not have a valid IPv4 or IPv6 address configured.
#define	UPNP_E_NETWORK_ERROR   -200
	A network error occurred.
#define	UPNP_E_SOCKET_WRITE   -201
	An error happened while writing to a socket.
#define	UPNP_E_SOCKET_READ   -202
	An error happened while reading from a socket.
#define	UPNP_E_SOCKET_BIND   -203
	The SDK had a problem binding a socket to a network interface.
#define	UPNP_E_SOCKET_CONNECT   -204
	The SDK had a problem connecting to a remote host.
#define	UPNP_E_OUTOF_SOCKET   -205
	The SDK cannot create any more sockets.
#define	UPNP_E_LISTEN   -206
	While initializing, the SDK could not create or set up the listening socket.
#define	UPNP_E_TIMEDOUT   -207
	Too much time elapsed before the required number of bytes were sent or received over a socket.
#define	UPNP_E_SOCKET_ERROR   -208
	Generic socket error code for conditions not covered by other error codes.
#define	UPNP_E_FILE_WRITE_ERROR   -209
	Not used.
#define	UPNP_E_CANCELED   -210
	Not used.
#define	UPNP_E_EVENT_PROTOCOL   -300
	Not used.
#define	UPNP_E_SUBSCRIBE_UNACCEPTED   -301
	A subscription request was rejected from the remote side.
#define	UPNP_E_UNSUBSCRIBE_UNACCEPTED   -302
	An unsubscribe request was rejected from the remote side.
#define	UPNP_E_NOTIFY_UNACCEPTED   -303
	The remote host did not accept the notify sent from the local device.
#define	UPNP_E_INVALID_ARGUMENT   -501
	One or more of the parameters passed to a function is invalid.
#define	UPNP_E_FILE_NOT_FOUND   -502
	The filename passed to one of the device registration functions was not found or was not accessible.
#define	UPNP_E_FILE_READ_ERROR   -503
	An error happened while reading a file.
#define	UPNP_E_EXT_NOT_XML   -504
	The file name of the description document passed to UpnpRegisterRootDevice2 does not end in ".xml".
#define	UPNP_E_NO_WEB_SERVER   -505
	A function needs the internal Web server but it is not running.
#define	UPNP_E_OUTOF_BOUNDS   -506
	Not used.
#define	UPNP_E_NOT_FOUND   -507
	Not used.
#define	UPNP_E_INTERNAL_ERROR   -911
	Generic error code for internal conditions not covered by other error codes.
#define	UPNP_SOAP_E_INVALID_ACTION   401
#define	UPNP_SOAP_E_INVALID_ARGS   402
#define	UPNP_SOAP_E_OUT_OF_SYNC   403
#define	UPNP_SOAP_E_INVALID_VAR   404
#define	UPNP_SOAP_E_ACTION_FAILED   501
#define	UpnpActionRequest_get_ErrCode(x)   ((x)->ErrCode)
#define	UpnpActionRequest_set_ErrCode(x, v)   ((x)->ErrCode = (v))
#define	UpnpActionRequest_get_Socket(x)   ((x)->Socket)
#define	UpnpActionRequest_get_ErrStr_cstr(x)   ((x)->ErrStr)
#define	UpnpActionRequest_set_ErrStr(x, v)   (strncpy((x)->ErrStr, v, LINE_SIZE))
#define	UpnpActionRequest_strcpy_ErrStr(x, v)   (strncpy((x)->ErrStr, v, LINE_SIZE))
#define	UpnpActionRequest_get_ActionName_cstr(x)   ((x)->ActionName)
#define	UpnpActionRequest_get_DevUDN_cstr(x)   ((x)->DevUDN)
#define	UpnpActionRequest_get_ServiceID_cstr(x)   ((x)->ServiceID)
#define	UpnpActionRequest_get_xmlAction(x)   ((x)->xmlAction)
#define	UpnpActionRequest_get_xmlResponse(x)   ((x)->xmlResponse)
#define	UpnpActionRequest_set_xmlResponse(x, v)   ((x)->xmlResponse = (v))
#define	UpnpActionRequest_get_CtrlPtIPAddr(x)   (&((x)->CtrlPtIPAddr))
#define	UpnpActionRequest_get_Os_cstr(x)   ((x)->Os.c_str())
#define	UpnpEvent_get_SID_cstr(x)   ((x)->Sid.c_str())
#define	UpnpEvent_get_EventKey(x)   ((x)->EventKey)
#define	UpnpEvent_get_ChangedVariables(x)   ((x)->ChangedVariables)
#define	UpnpDiscovery_get_ErrCode(x)   ((x)->ErrCode)
#define	UpnpDiscovery_get_Expires(x)   ((x)->Expires)
#define	UpnpDiscovery_get_DeviceID_cstr(x)   ((x)->DeviceId)
#define	UpnpDiscovery_get_DeviceType_cstr(x)   ((x)->DeviceType)
#define	UpnpDiscovery_get_ServiceType_cstr(x)   ((x)->ServiceType)
#define	UpnpDiscovery_get_ServiceVer_cstr(x)   ((x)->ServiceVer)
#define	UpnpDiscovery_get_Location_cstr(x)   ((x)->Location)
#define	UpnpDiscovery_get_Os_cstr(x)   ((x)->Os)
#define	UpnpDiscovery_get_Date_cstr(x)   ((x)->Date)
#define	UpnpDiscovery_get_Ext_cstr(x)   ((x)->Ext)
#define	UpnpDiscovery_get_Os_cstr(x)   ((x)->Os)
#define	UpnpDiscovery_get_DestAddr(x)   (&((x)->DestAddr))
#define	UpnpEventSubscribe_get_SID_cstr(x)   ((x)->Sid.c_str())
#define	UpnpEventSubscribe_get_ErrCode(x)   ((x)->ErrCode)
#define	UpnpEventSubscribe_get_PublisherUrl_cstr(x)   ((x)->PublisherUrl)
#define	UpnpEventSubscribe_get_TimeOut(x)   ((x)->TimeOut)
#define	UpnpSubscriptionRequest_get_ServiceId_cstr(x)   ((x)->ServiceId)
#define	UpnpSubscriptionRequest_get_UDN_cstr(x)   ((x)->UDN)
#define	UpnpSubscriptionRequest_get_SID_cstr(x)   ((x)->Sid.c_str())
#define	UpnpFileInfo_get_FileLength(x)   ((x)->file_length)
#define	UpnpFileInfo_set_FileLength(x, v)   ((x)->file_length = (v))
#define	UpnpFileInfo_get_LastModified(x)   ((x)->last_modified)
#define	UpnpFileInfo_set_LastModified(x, v)   ((x)->last_modified = (v))
#define	UpnpFileInfo_get_IsDirectory(x)   ((x)->is_directory)
#define	UpnpFileInfo_set_IsDirectory(x, v)   ((x)->is_directory = (v))
#define	UpnpFileInfo_get_IsReadable(x)   ((x)->is_readable)
#define	UpnpFileInfo_set_IsReadable(x, v)   ((x)->is_readable = (v))
#define	UpnpFileInfo_get_ContentType(x)   ((x)->content_type)
#define	UpnpFileInfo_set_ContentType(x, v)   ((x)->content_type = (v))
#define	UpnpFileInfo_get_CtrlPtIPAddr(x)   (&((x)->CtrlPtIPAddr))
#define	UpnpFileInfo_get_Os_cstr(x)   ((x)->Os.c_str())
enum	UpnpOpenFileMode { UPNP_READ , UPNP_WRITE }
enum	Upnp_EventType_e {   UPNP_CONTROL_ACTION_REQUEST , UPNP_CONTROL_ACTION_COMPLETE , UPNP_CONTROL_GET_VAR_REQUEST , UPNP_CONTROL_GET_VAR_COMPLETE ,   UPNP_DISCOVERY_ADVERTISEMENT_ALIVE , UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE , UPNP_DISCOVERY_SEARCH_RESULT , UPNP_DISCOVERY_SEARCH_TIMEOUT ,   UPNP_EVENT_SUBSCRIPTION_REQUEST , UPNP_EVENT_RECEIVED , UPNP_EVENT_RENEWAL_COMPLETE , UPNP_EVENT_SUBSCRIBE_COMPLETE ,   UPNP_EVENT_UNSUBSCRIBE_COMPLETE , UPNP_EVENT_AUTORENEWAL_FAILED , UPNP_EVENT_SUBSCRIPTION_EXPIRED }
enum	Upnp_DescType_e { UPNPREG_URL_DESC , UPNPREG_FILENAME_DESC , UPNPREG_BUF_DESC }
	Specifies the type of description passed to UpnpRegisterRootDevice2. More...
enum	Upnp_InitFlag {   UPNP_FLAG_NONE = 0 , UPNP_FLAG_IPV6 = 0x1 , UPNP_FLAG_IPV6_REQUIRED = 0x2 , UPNP_FLAG_NO_HOST_VALIDATE = 0x4 ,   UPNP_FLAG_REJECT_HOSTNAMES = 0x8 }
enum	Upnp_InitOption {   UPNP_OPTION_END = 0 , UPNP_OPTION_NETWORK_WAIT , UPNP_OPTION_BOOTID , UPNP_OPTION_CONFIGID ,   UPNP_OPTION_NEXTBOOTID , UPNP_OPTION_SEARCHPORT }
typedef int	UpnpClient_Handle
typedef int	UpnpDevice_Handle
typedef enum Upnp_EventType_e	Upnp_EventType
typedef std::string	Upnp_SID
	Holds a service subscription unique identifier.
typedef enum Upnp_DescType_e	Upnp_DescType
	Specifies the type of description passed to UpnpRegisterRootDevice2.
typedef struct Upnp_Action_Request	UpnpActionRequest
typedef struct Upnp_Event	UpnpEvent
typedef struct Upnp_Discovery	UpnpDiscovery
typedef struct Upnp_Event_Subscribe	UpnpEventSubscribe
typedef struct Upnp_Subscription_Request	UpnpSubscriptionRequest
typedef struct File_Info	UpnpFileInfo
typedef int(*	Upnp_FunPtr) (Upnp_EventType EventType, const void *Event, void *Cookie)

Device interface: Web Server API
typedef int(*	WebCallback_HostValidate) (const char *hostname, void *cookie)
typedef void *	UpnpWebFileHandle
typedef int(*	VDCallback_GetInfo) (const char *filename, struct File_Info *info, const void *cookie, const void **request_cookiep)
	Virtual Directory function prototype for the "get file information" callback. This is guaranteed to always be the first call in a sequence to access a virtual file, so the cookie will be accessible to other calls.
typedef UpnpWebFileHandle(*	VDCallback_Open) (const char *filename, enum UpnpOpenFileMode Mode, const void *cookie, const void *request_cookie)
	Virtual Directory Open callback function prototype.
typedef int(*	VDCallback_Read) (UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)
	Virtual Directory Read callback function prototype.
typedef int(*	VDCallback_Write) (UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)
	Virtual Directory Write callback function prototype.
typedef int(*	VDCallback_Seek) (UpnpWebFileHandle fileHnd, int64_t offset, int origin, const void *cookie, const void *request_cookie)
	Virtual Directory Seek callback function prototype.
typedef int(*	VDCallback_Close) (UpnpWebFileHandle fileHnd, const void *cookie, const void *request_cookie)
	Virtual directory close callback function prototype.
EXPORT_SPEC int	UpnpEnableWebserver (int enable)
	Enables or disables the WEB server file service. The WEB server is automatically enabled by UpnpInit2(), this call should only be used to stop it.
EXPORT_SPEC int	UpnpIsWebserverEnabled (void)
	Returns TRUE if the webserver is enabled, or FALSE if it is not.
EXPORT_SPEC int	UpnpSetWebServerRootDir (const char *rootDir)
	Sets the document root directory for the internal WEB server.
EXPORT_SPEC std::string	UpnpGetUrlHostPortForClient (const struct sockaddr_storage *)
	return an URL host:port string suitable for the passed-in client address.
EXPORT_SPEC int	UpnpSetWebRequestHostValidateCallback (WebCallback_HostValidate callback, void *cookie)
EXPORT_SPEC int	UpnpSetHostValidateCallback (WebCallback_HostValidate callback, void *cookie)
EXPORT_SPEC int	UpnpSetWebServerCorsString (const char *corsString)
	Assign the Access-Control-Allow-Origin specfied by the input const char* cors_string parameterto the global CORS string.
EXPORT_SPEC int	UpnpVirtualDir_set_GetInfoCallback (VDCallback_GetInfo callback)
	Sets the get_info callback function to be used to access a virtual directory.
EXPORT_SPEC int	UpnpVirtualDir_set_OpenCallback (VDCallback_Open callback)
	Sets the open callback function to be used to access a virtual directory.
EXPORT_SPEC int	UpnpVirtualDir_set_ReadCallback (VDCallback_Read callback)
	Sets the read callback function to be used to access a virtual directory.
EXPORT_SPEC int	UpnpVirtualDir_set_WriteCallback (VDCallback_Write callback)
	Sets the write callback function to be used to access a virtual directory.
EXPORT_SPEC int	UpnpVirtualDir_set_SeekCallback (VDCallback_Seek callback)
	Sets the seek callback function to be used to access a virtual directory.
EXPORT_SPEC int	UpnpVirtualDir_set_CloseCallback (VDCallback_Close callback)
	Sets the close callback function to be used to access a virtual directory.
EXPORT_SPEC int	UpnpSetVirtualDirCallbacks (struct UpnpVirtualDirCallbacks *callbacks)
	Sets the callback functions to be used to access a virtual directory.
EXPORT_SPEC int	UpnpAddVirtualDir (const char *dirName, const void *cookie, const void **oldcookie)
	Adds a virtual directory mapping.
EXPORT_SPEC int	UpnpRemoveVirtualDir (const char *dirName)
	Removes a virtual directory mapping made with UpnpAddVirtualDir.
EXPORT_SPEC void	UpnpRemoveAllVirtualDirs (void)
	Removes all virtual directory mappings.

Detailed Description

main libnpupnp API definitions

Macro Definition Documentation

LINE_SIZE

#define LINE_SIZE   size_t(180)

Array size for some fixed sized character arrays in API structures

NAME_SIZE

#define NAME_SIZE   size_t(256)

Array size for some fixed sized character arrays in API structures

UPNP_E_ALREADY_REGISTERED

#define UPNP_E_ALREADY_REGISTERED   -120

A client or a device is already registered.

The SDK currently has a limit of one registered client and one registered device per process.

UPNP_E_BAD_HTTPMSG

#define UPNP_E_BAD_HTTPMSG   -119

The HTTP message contains invalid message headers.

The error always refers to the HTTP message header received from the remote host. The main areas where this occurs are in SOAP control messages (e.g. UpnpSendAction), GENA subscription message (e.g. UpnpSubscribe), GENA event notifications (e.g. UpnpNotify), and HTTP transfers (e.g. UpnpDownloadUrlItem).

UPNP_E_NETWORK_ERROR

#define UPNP_E_NETWORK_ERROR   -200

A network error occurred.

It is the generic error code for network problems that are not covered under one of the more specific error codes. The typical meaning is the SDK failed to read the local IP address or had problems configuring one of the sockets.

UPNP_E_OUTOF_SOCKET

#define UPNP_E_OUTOF_SOCKET   -205

The SDK cannot create any more sockets.

This occurs in any function that makes network connections, such as discovery (e.g. UpnpSearchAsync or UpnpSendAdvertisement), control (e.g. UpnpSendAction), eventing (e.g. UpnpNotify), and HTTP functions (e.g. UpnpDownloadUrlItem).

UPNP_E_SOCKET_BIND

#define UPNP_E_SOCKET_BIND   -203

The SDK had a problem binding a socket to a network interface.

This occurs in any function that makes network connections, such as discovery (e.g. UpnpSearchAsync or UpnpSendAdvertisement), control (e.g. UpnpSendAction), eventing (e.g. UpnpNotify), and HTTP functions (e.g. UpnpDownloadUrlItem).

UPNP_E_SOCKET_CONNECT

#define UPNP_E_SOCKET_CONNECT   -204

The SDK had a problem connecting to a remote host.

This occurs in any function that makes network connections, such as discovery (e.g. UpnpSearchAsync or UpnpSendAdvertisement), control (e.g. UpnpSendAction), eventing (e.g. UpnpNotify), and HTTP functions (e.g. UpnpDownloadUrlItem).

UPNP_E_SOCKET_ERROR

#define UPNP_E_SOCKET_ERROR   -208

Generic socket error code for conditions not covered by other error codes.

This error can be returned by any function that performs network operations.

UPNP_E_SOCKET_READ

#define UPNP_E_SOCKET_READ   -202

An error happened while reading from a socket.

This occurs in any function that makes network connections, such as discovery (e.g. UpnpSearchAsync or UpnpSendAdvertisement), control (e.g. UpnpSendAction), eventing (e.g. UpnpNotify), and HTTP functions (e.g. UpnpDownloadUrlItem).

UPNP_E_SOCKET_WRITE

#define UPNP_E_SOCKET_WRITE   -201

An error happened while writing to a socket.

This occurs in any function that makes network connections, such as discovery (e.g. UpnpSearchAsync or UpnpSendAdvertisement), control (e.g.UpnpSendAction), eventing (e.g. UpnpNotify), and HTTP functions (e.g. UpnpDownloadUrlItem).

UPNP_E_TIMEDOUT

#define UPNP_E_TIMEDOUT   -207

Too much time elapsed before the required number of bytes were sent or received over a socket.

This error can be returned by any function that performs network operations.

UPNP_INFINITE

#define UPNP_INFINITE   -1

Value indicating a non-limited specification in some calls (e.g. timeout)

UPNP_MAX_SEARCH_TIME

#define UPNP_MAX_SEARCH_TIME   80

Maximum search window settable by a control point in seconds. The window defines the period over which devices may answer at a random point. Setting the mx parameter to UpnpSearchAsync() higher than this value will result in the value being used instead.

UPNP_MIN_SEARCH_TIME

#define UPNP_MIN_SEARCH_TIME   2

Minimum search window settable by a control point in seconds. The window defines the period over which devices may answer at a random point. Setting the mx parameter to UpnpSearchAsync() below this value will result in this value to be used instead.

UPNP_UNTIL_CLOSE

#define UPNP_UNTIL_CLOSE   -4

I don't think that this is actually used in the API, but define it for compatibility

UPNP_USING_CHUNKED

#define UPNP_USING_CHUNKED   -3

This can be set in the file_length field of a File_Info structure to indicate that the web server should use chunked encoding. In npupnp practise, we set the length to -1 and let microhttpd do its thing.

Typedef Documentation

Upnp_EventType

typedef enum Upnp_EventType_e Upnp_EventType

This value defines the reason for an event callback, and the kind of data structure which the Event parameter points to.

Upnp_FunPtr

typedef int(* Upnp_FunPtr) (Upnp_EventType EventType, const void *Event, void *Cookie)

Function prototype for all event callback functions. This is set when registering a device (UpnpRegisterRootDevice) or client (UpnpRegisterClient). Any memory referenced by the call is valid only for its duration and should be copied if it needs to persist.
This callback function needs to be thread safe.
The context of the callback is always on a valid thread context and standard synchronization methods can be used. Note, however, because of this the callback cannot call SDK functions unless explicitly noted.

Parameters

EventType	type of the event that triggered the callback.
Event	pointer to an event type-dependant structure storing the relevant event information.
Cookie	the user data set when the callback was registered.

See Upnp_EventType for more information on the callback values and the associated Event parameter.

UpnpClient_Handle

typedef int UpnpClient_Handle

Client (Control Point) registration handle. Returned by UpnpRegisterClient, and first parameter to further API calls.

UpnpDevice_Handle

typedef int UpnpDevice_Handle

Device registration handle. Returned by UpnpRegisterRootDevice and its variants, and first paramter to further API calls

UpnpWebFileHandle

typedef void* UpnpWebFileHandle

Handle returned by the VDCallback_Open virtual directory function.

VDCallback_Close

typedef int(* VDCallback_Close) ( UpnpWebFileHandle fileHnd, const void *cookie, const void *request_cookie)

Virtual directory close callback function prototype.

Parameters

[in]

fileHnd

The handle of the file to close.

VDCallback_GetInfo

typedef int(* VDCallback_GetInfo) ( const char *filename, struct File_Info *info, const void *cookie, const void **request_cookiep)

Virtual Directory function prototype for the "get file information" callback. This is guaranteed to always be the first call in a sequence to access a virtual file, so the cookie will be accessible to other calls.

Parameters

[in]	filename	The name of the file to query.
[out]	info	Pointer to a structure to store the information on the file.

VDCallback_Open

typedef UpnpWebFileHandle(* VDCallback_Open) ( const char *filename, enum UpnpOpenFileMode Mode, const void *cookie, const void *request_cookie)

Virtual Directory Open callback function prototype.

Parameters

[in]	filename	The name of the file to open.
[in]	Mode	The mode in which to open the file. Valid values are UPNP_READ or UPNP_WRITE.

VDCallback_Read

typedef int(* VDCallback_Read) ( UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)

Virtual Directory Read callback function prototype.

Parameters

[in]	fileHnd	The handle of the file to read.
[out]	buf	The buffer in which to place the data.
[in]	buflen	The size of the buffer (i.e. the number of bytes to read).

VDCallback_Seek

typedef int(* VDCallback_Seek) ( UpnpWebFileHandle fileHnd, int64_t offset, int origin, const void *cookie, const void *request_cookie)

Virtual Directory Seek callback function prototype.

Parameters

[in]	fileHnd	The handle of the file to move the file pointer.
[in]	offset	The number of bytes to move in the file. Positive values move foward and negative values move backward. Note that this must be positive if the origin is SEEK_SET.
[in]	origin	The position to move relative to. It can be SEEK_CUR to move relative to the current position, SEEK_END to move relative to the end of the file, or SEEK_SET to specify an absolute offset.

VDCallback_Write

typedef int(* VDCallback_Write) ( UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)

Virtual Directory Write callback function prototype.

Parameters

[in]	fileHnd	The handle of the file to write.
[in]	buf	The buffer with the bytes to write.
[in]	buflen	The number of bytes to write.

Enumeration Type Documentation

Upnp_DescType_e

enum Upnp_DescType_e

Specifies the type of description passed to UpnpRegisterRootDevice2.

Enumerator
UPNPREG_URL_DESC	The description is the URL to the description document.
UPNPREG_FILENAME_DESC	The description is a file name on the local file system containing the description of the device.
UPNPREG_BUF_DESC	The description is a pointer to a character array containing the XML description document.

Upnp_EventType_e

enum Upnp_EventType_e

This value defines the reason for an event callback, and the kind of data structure which the Event parameter points to.

Enumerator
UPNP_CONTROL_ACTION_REQUEST	Received by a device when a control point issues a control request. The Event parameter contains a pointer to an Upnp_Action_Request structure
UPNP_CONTROL_ACTION_COMPLETE	Not used.
UPNP_CONTROL_GET_VAR_REQUEST	Not used.
UPNP_CONTROL_GET_VAR_COMPLETE	Not used.
UPNP_DISCOVERY_ADVERTISEMENT_ALIVE	Received by a control point when a new device or service is available. The Event parameter contains a pointer to an Upnp_Discovery structure with the information about the device or service.
UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE	Received by a control point when a device or service shuts down. The Event parameter contains a pointer to an Upnp_Discovery structure containing the information about the device or service.
UPNP_DISCOVERY_SEARCH_RESULT	Received by a control point when a matching device or service responds. The Event parameter contains a pointer to an Upnp_Discovery structure containing the information about the reply to the search request.
UPNP_DISCOVERY_SEARCH_TIMEOUT	Received by a control point when the search timeout expires. The SDK generates no more callbacks for this search after this event. The Event parameter is NULL.
UPNP_EVENT_SUBSCRIPTION_REQUEST	Received by a device when a subscription request arrives. The Event parameter contains a pointer to an Upnp_Subscription_Request structure. The device code needs to call UpnpAcceptSubscription to confirm the subscription and transmit the initial state table. This can be done during this callback.
UPNP_EVENT_RECEIVED	Received by a control point when an event arrives. The Event parameter contains an Upnp_Event structure with the information about the event.
UPNP_EVENT_RENEWAL_COMPLETE	Not used.
UPNP_EVENT_SUBSCRIBE_COMPLETE	Not used.
UPNP_EVENT_UNSUBSCRIBE_COMPLETE	Not used.
UPNP_EVENT_AUTORENEWAL_FAILED	The auto-renewal of a client subscription failed. The Event parameter is an Upnp_Event_Subscribe structure with the error code set appropriately. The subscription is no longer valid.
UPNP_EVENT_SUBSCRIPTION_EXPIRED	A client subscription has expired. This will only occur if auto-renewal of subscriptions is disabled. The Event parameter is an Upnp_Event_Subscribe structure. The subscription is no longer valid.

Upnp_InitFlag

enum Upnp_InitFlag

Option values for the UpnpInitWithOptions flags argument

Enumerator
UPNP_FLAG_IPV6	Accept IPV4+IPV6 operation, run with IPV4 only if IPV6 not available
UPNP_FLAG_IPV6_REQUIRED	Same but fail if IPV6 is not available.
UPNP_FLAG_NO_HOST_VALIDATE	Do not validate HOST headers (preserve compatibility with old versions)
UPNP_FLAG_REJECT_HOSTNAMES	Reject Web requests with a host name (non-numeric) value in the HOST header, instead of redirecting them.

Upnp_InitOption

enum Upnp_InitOption

Values for the UpnpInitWithOptions vararg options list. For all the current integer values, a value <= 0 will be ignored, leaving the default in place.

Enumerator
UPNP_OPTION_END	Terminate the VARARGs list.
UPNP_OPTION_NETWORK_WAIT	Max wait seconds for an IP address to be found, int arg follows.
UPNP_OPTION_BOOTID	BOOTID value to be sent in SSDP messages, int arg follows.
UPNP_OPTION_CONFIGID	CONFIGID value to be sent in SSDP messages, int arg follows.
UPNP_OPTION_NEXTBOOTID	NEXTBOOTID value to be sent in SSDP messages, int arg follows. Currently ignored.
UPNP_OPTION_SEARCHPORT	SEARCHPORT value to be sent in SSDP messages, int arg follows. Currently ignored.

Function Documentation

UpnpAcceptSubscription()

EXPORT_SPEC int UpnpAcceptSubscription	(	UpnpDevice_Handle	Hnd,
		const char *	DevID,
		const char *	ServName,
		const char **	VarName,
		const char **	NewVal,
		int	cVariables,
		const Upnp_SID &	SubsId
	)

Accepts a subscription request and sends out the current state of the eventable variables for a service.

The device application should call this function when it receives a UPNP_EVENT_SUBSCRIPTION_REQUEST callback.

This function is synchronous 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_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, or ServID 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 of the device.
[in]	DevID	The device ID of the service device .
[in]	ServName	The unique service identifier of the service generating the event.
[in]	VarName	Pointer to an array of event variables.
[in]	NewVal	Pointer to an array of values for the event variables.
[in]	cVariables	The number of event variables in VarName.
[in]	SubsId	The subscription ID of the newly registered control point.

UpnpAcceptSubscriptionXML()

EXPORT_SPEC int UpnpAcceptSubscriptionXML	(	UpnpDevice_Handle	Hnd,
		const char *	DevID,
		const char *	ServName,
		const std::string &	propertyset,
		const Upnp_SID &	SubsId
	)

Parameters

[in]	Hnd	The handle of the device.
[in]	DevID	The device ID of the service device .
[in]	ServName	The unique service identifier of the service generating the event.
[in]	propertyset	Initial property set (all state variables) as XML string.
[in]	SubsId	The subscription ID of the newly registered control point.

UpnpAddVirtualDir()

EXPORT_SPEC int UpnpAddVirtualDir	(	const char *	dirName,
		const void *	cookie,
		const void **	oldcookie
	)

Adds a virtual directory mapping.

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

Note

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

Parameters

	dirName	The name of the new directory mapping to add.
	cookie	a value which will be set in callbacks related to this directory.
[out]	oldcookie	If not null and the virtual directory previously existed, returns the old cookie value.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_ARGUMENT: dirName is not valid.

UpnpClientSetProduct()

EXPORT_SPEC void UpnpClientSetProduct	(	UpnpClient_Handle	Hnd,
		const char *	product,
		const char *	version
	)

Set the product information part of the User-Agent header sent with some network requests.

Parameters

[in]	Hnd	The handle of the control point instance to unregister.
[in]	product	The product name, e.g. "MyAwsomeProduct"
[in]	version	The product version, e.g: "1.1"

UpnpDeviceSetProduct()

EXPORT_SPEC int UpnpDeviceSetProduct	(	UpnpDevice_Handle	Hnd,
		const char *	product,
		const char *	version
	)

Set the product information part of the SERVER header sent with some network requests.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
• UPNP_E_INVALID_PARAM: null or empty product or version.

Parameters

[in]	Hnd	The handle of the control point instance to unregister.
[in]	product	The product name, e.g. "MyAwsomeProduct"
[in]	version	The product version, e.g: "1.1"

UpnpDownloadUrlItem() [1/2]

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

Downloads a text 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. Caller must free. Guaranteed zero-terminated on success
[out]	contentType	HTTP header value content type if present. It should be at least LINE_SIZE bytes in size.

UpnpDownloadUrlItem() [2/2]

EXPORT_SPEC int UpnpDownloadUrlItem	(	const std::string &	url,
		std::string &	data,
		std::string &	ct
	)

Downloads a file specified in a URL.

Simplified interface using std::string

Parameters

[in]	url	URL of an item to download.
[out]	data	Buffer to store the downloaded item.
[out]	ct	HTTP header value content type if present.

UpnpEnableWebserver()

EXPORT_SPEC int UpnpEnableWebserver

(

int

enable

)

Enables or disables the WEB server file service. The WEB server is automatically enabled by UpnpInit2(), this call should only be used to stop it.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_ARGUMENT: enable is not valid.

Parameters

[in]

enable

TRUE to enable, FALSE to disable.

UpnpFinish()

EXPORT_SPEC int UpnpFinish

(

void

)

Terminate and clean up the library.

• 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.

UpnpGetServerIpAddress()

EXPORT_SPEC const char * UpnpGetServerIpAddress

(

void

)

Returns a local IPv4 listening ip address.

If NULL is used as the IPv4 address in UpnpInit, 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: NULL is returned if UpnpInit has not succeeded.

UpnpGetServerPort()

EXPORT_SPEC unsigned short UpnpGetServerPort

(

void

)

Returns the internal server IPv4 UPnP listening port.

If '0' is used as the port number in UpnpInit, 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 UpnpInit has not succeeded.

UpnpGetUrlHostPortForClient()

EXPORT_SPEC std::string UpnpGetUrlHostPortForClient

(

const struct sockaddr_storage *

)

return an URL host:port string suitable for the passed-in client address.

We chose a host address on the same subnet or the same link (for an IPV6 link-local client address), and the appropriate server port (as would be returned by UpnpGetServerPort[6](). Example of returned values: "192.168.0.4:49152", "[e80::4da9:6cfc:df0c:6700]:59152". The client address would typically be obtained from the CtrlPtIPAddr field of an Upnp_Action_Request structure.

Returns

the appropriate host:port string or an empty string if no appropriate value can be found.

UpnpInit()

EXPORT_SPEC int UpnpInit	(	const char *	HostIP,
		unsigned short	DestPort
	)

Initializes the UPnP SDK for exclusive IP V4 operation on a single interface.

Deprecated:

Kept for backwards compatibility. Use UpnpInit2 for new implementations or where IPv6 is required.

This function must be called before any other API function can be called, except for a possible initialisation of the log output file and level. It should be called only once. Subsequent calls to this API return a UPNP_E_INIT error code.

Optionally, the application can specify a host IPv4 address. By default, the SDK will use the first IPv4-capable adapter's IP first address. Optionally the application can specify a port number for the UPnP HTTP interface (used for control, eventing and serving files). The first available port number above the one specified will be used. The default base port value is 49152.

This call is synchronous.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
• UPNP_E_INIT: The SDK is already initialized.
• UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
• UPNP_E_SOCKET_BIND: An error occurred binding a socket.
• UPNP_E_LISTEN: An error occurred listening to a socket.
• UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
• UPNP_E_INTERNAL_ERROR: An internal error ocurred.

Parameters

HostIP	The host local IPv4 address to use, in dotted string format, or empty or NULL to use the first IPv4 adapter's IP address.
DestPort	Local Port to listen for incoming connections 0 will pick the first free port at or above the configured default (49152).

UpnpInit2() [1/2]

EXPORT_SPEC int UpnpInit2	(	const char *	IfName,
		unsigned short	DestPort
	)

Initializes the library, passing the interface spec as a single string.

This function must be called before any other API function can be called, except for a possible initialisation of the log output file and level. It should be called only once. Subsequent calls to this API return a UPNP_E_INIT error code.

Optionally, the application can specify an one or several interface names. If the interface is unspecified, the SDK will use the first suitable one.

The application can also specify a port number. The default is 49152. the SDK will pick the first available port at or above the default or specified value.

This call is synchronous.

Parameters

ifName	The interface name(s) to use by the UPnP SDK operations, as a space-separated list (utf-8). Use double quotes or backslashes escapes if there are space characters inside the interface name. Use a single "*" character to use all available interfaces. NULL or empty to use the first suitable interface.
DestPort	local port to listen on for incoming connections. 0 will pick the first free port at or above the configured default.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
• UPNP_E_INIT: The SDK is already initialized.
• UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
• UPNP_E_SOCKET_BIND: An error occurred binding a socket.
• UPNP_E_LISTEN: An error occurred listening to a socket.
• UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
• UPNP_E_INTERNAL_ERROR: An internal error ocurred.
• UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.

UpnpInit2() [2/2]

EXPORT_SPEC int UpnpInit2	(	const std::vector< std::string > &	ifnames,
		unsigned short	DestPort
	)

Initializes the library, passing the interface spec as a vector.

This function must be called before any other API function can be called, except for a possible initialisation of the log output file and level. It should be called only once. Subsequent calls to this API return a UPNP_E_INIT error code.

Optionally, the application can specify an one or several interface names. If the interface is unspecified, the SDK will use the first suitable one.

The application can also specify a port number. The default is 49152. the SDK will pick the first available port at or above the default or specified value.

This call is synchronous.

Parameters

ifnames	The interface name(s) as a as a vector of UTF-8 strings, to avoid any quoting headaches. Leave empty for using the first found interface. Set a single "*" element for using all interfaces.
DestPort	local port to listen on for incoming connections. 0 will pick the first free port at or above the configured default.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
• UPNP_E_INIT: The SDK is already initialized.
• UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
• UPNP_E_SOCKET_BIND: An error occurred binding a socket.
• UPNP_E_LISTEN: An error occurred listening to a socket.
• UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
• UPNP_E_INTERNAL_ERROR: An internal error ocurred.
• UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.

UpnpInitWithOptions()

EXPORT_SPEC int UpnpInitWithOptions	(	const char *	IfNames,
		unsigned short	DestPort,
		unsigned int	flags,
			...
	)

Initializes the library, passing the interface spec as a string.

This function must be called before any other API function can be called, except for a possible initialisation of the log output file and level. It should be called only once. Subsequent calls to this API return a UPNP_E_INIT error code.

Optionally, the application can specify an one or several interface names. If the interface is unspecified, the SDK will use the first suitable one.

The application can also specify a port number. The default is 49152. the SDK will pick the first available port at or above the default or specified value.

This call is synchronous.

Parameters

ifnames	The interface name(s) to use for the UPnP SDK operations, as a quoted space-separated list (utf-8 string). Use double quotes or backslashes escapes if there are space characters inside the interface name(s). Use a single "*" character to use all available interfaces. Use NULL or empty to use the first suitable interface.
DestPort	local port to listen on for incoming connections. 0 will pick the first free port at or above the configured default.
flags	A bitfield of Upnp_InitFlag values.
...	Variable list of Upnp_InitOption options and arguments, terminated by UPNP_OPTION_END.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
• UPNP_E_INIT: The SDK is already initialized.
• UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
• UPNP_E_SOCKET_BIND: An error occurred binding a socket.
• UPNP_E_LISTEN: An error occurred listening to a socket.
• UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
• UPNP_E_INTERNAL_ERROR: An internal error ocurred.
• UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 address configured.

Parameters

flags

Bitmask of Upnp_InitFlag values

UpnpIsWebserverEnabled()

EXPORT_SPEC int UpnpIsWebserverEnabled

(

void

)

Returns TRUE if the webserver is enabled, or FALSE if it is not.

Returns

An integer representing one of the following:

• TRUE: The webserver is enabled.
• FALSE: The webserver is not enabled

UpnpNotify()

EXPORT_SPEC int UpnpNotify	(	UpnpDevice_Handle	,
		const char *	DevID,
		const char *	ServName,
		const char **	VarName,
		const char **	NewVal,
		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_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_PARAM: Either VarName, NewVal, DevID, or ServID is not a valid pointer or cVariables is less than zero.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	DevID	The device ID of the subdevice of the service generating the event.
[in]	ServName	The unique identifier of the service generating the event.
[in]	VarName	Pointer to an array of variables that have changed.
[in]	NewVal	Pointer to an array of new values for those variables.
[in]	cVariables	The count of variables included in this notification.

UpnpNotifyXML()

EXPORT_SPEC int UpnpNotifyXML	(	UpnpDevice_Handle	,
		const char *	DevID,
		const char *	ServName,
		const std::string &	propset
	)

Parameters

[in]	DevID	The device ID of the device generating the event.
[in]	ServName	The unique identifier of the service generating the event.
[in]	propset	Property set (changed variables) as XML string

UpnpRegisterClient()

EXPORT_SPEC 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 or Hnd is not a valid pointer.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to register this control point.

Parameters

[in]	Fun	Callback function.
[in]	Cookie	Pointer to be passed as parameter to the callback invocations.
[out]	Hnd	Pointer to a variable to store the new control point handle.

UpnpRegisterRootDevice()

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

Registers a device application with the UPnP Library.

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

The description document is passed as an URL, which must be accessible. If it is served by the internal Web server, this must have been set up before this call (by initializing the corresponding virtual directory or using UpnpSetWebServerRootDir)

This is a synchronous call and does not generate any 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_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 NULL.
• 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	Callback function.
[in]	Cookie	Pointer to be passed as parameter to the callback invocations.
[out]	Hnd	Pointer to a variable to store the new device handle.

UpnpRegisterRootDevice2()

EXPORT_SPEC int UpnpRegisterRootDevice2	(	Upnp_DescType	descriptionType,
		const char *	description,
		size_t	bufferLen,
		int	ignored,
		Upnp_FunPtr	Fun,
		const void *	Cookie,
		UpnpDevice_Handle *	Hnd
	)

Registers a device application with the UPnP Library. Similar to UpnpRegisterRootDevice, except that it also allows the description document to be specified as a file or a memory buffer, in which case, the data will be served by the internal WEB server.

If the description document is passed as an URL, it must be accessible. If it is served by the internal Web server, this must have been set up before this call (by initializing the corresponding virtual directory or using UpnpSetWebServerRootDir)

This is a synchronous call and does not generate any 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_DESC: The description document is not a valid device description.
• UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
• 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	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.
	ignored	Ignored
[in]	Fun	Callback function
[in]	Cookie	Pointer to be passed as parameter to the callback invocations.
[out]	Hnd	Pointer to a variable to store the new device handle.

UpnpRegisterRootDevice4()

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

Registers a device application with the UPnP library. This function can also be used to specify a dedicated description URL to be returned for legacy CPs.

A device application cannot make any other API calls until it registers using this function. Device applications can also register as control points (see UpnpRegisterClient to get a control point handle to perform control point functionality).

This is synchronous and does not generate any 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_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 NULL.
• 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	Callback function.
[in]	Cookie	Pointer to be passed as parameter to the callback invocations.
[out]	Hnd	Pointer to a variable to store the new device handle.
[in]	LowerDescUrl	Pointer to a string containing the description URL to be returned for legacy CPs for this root device instance.

UpnpRemoveVirtualDir()

EXPORT_SPEC int UpnpRemoveVirtualDir

(

const char *

dirName

)

Removes a virtual directory mapping made with UpnpAddVirtualDir.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_ARGUMENT: dirName is not valid.

Parameters

[in]

dirName

The name of the virtual directory mapping to remove.

UpnpRenewSubscription()

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

Renews a subscription that is about to expire.

This function is synchronous, and the client does not really need to call it as subscription renewals are automatically performed internally by the library.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• 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.

UpnpSearchAsync()

EXPORT_SPEC int UpnpSearchAsync	(	UpnpClient_Handle	Hnd,
		int	Mx,
		const char *	Target,
		const void *	cookie
	)

Searches for devices matching the given search target.

The function returns immediately and the SDK calls the default callback function, registered during the UpnpRegisterClient call, for each matching response from a root device, device, or service. The application specifies the search type by the Target parameter.

The application will receive multiple callbacks for each search, and some of the responses may not match the initial search.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_PARAM: Target is NULL.

Parameters

Hnd	The handle of the client performing the search.
Mx	The time, in seconds, to wait for responses. If the time is greater than MAX_SEARCH_TIME then the time is set to MAX_SEARCH_TIME. If the time is less than MIN_SEARCH_TIME then the time is set to MIN_SEARCH_TIME.
Target	The search target as defined in the UPnP Device Architecture v1.0 specification.
cookie	The user data to pass when the callback function is invoked.

UpnpSearchAsyncUnicast()

EXPORT_SPEC int UpnpSearchAsyncUnicast	(	UpnpClient_Handle	Hnd,
		const std::string &	url,
		const char *	Target,
		void *	cookie
	)

Unicast search.

Interrogate specific address for device matching the given search target. This may allow faster and more reliable verification of the presence of a previously discovered device.

The function returns immediately and the SDK calls the default callback function, registered during the UpnpRegisterClient call, for each matching response from a root device, device, or service. The application specifies the search type by the Target parameter.

The application will receive multiple callbacks for each search, and some of the responses may not match the initial search.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_PARAM: Target is NULL.

Parameters

Hnd	The handle of the client performing the search.
url	An URL providing the host and port to use for the search. This would typically be the description URL from an earlier discovery.
Target	The search target as defined in the UPnP Device Architecture v1.0 specification.
cookie	The user data to pass when the callback function is invoked.

UpnpSendAction()

EXPORT_SPEC int UpnpSendAction	(	UpnpClient_Handle	Hnd,
		const std::string &	headerString,
		const std::string &	actionURL,
		const std::string &	serviceType,
		const std::string &	actionName,
		const std::vector< std::pair< std::string, std::string > > &	actionParams,
		std::vector< std::pair< std::string, std::string > > &	responseData,
		int *	errcodep,
		std::string &	errdesc
	)

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.
• Negative values are UPNP_E_... UPnP library errors (system error)

• Positive values are UPnP action error codes (the dialog completed successfully, but we received an error response from the device).

Parameters

	Hnd	client handle
	headerString	SOAP header. This may be empty if no header header is not required. e.g. <soapns:Header>xxx</soapns:Header>
	actionURL	the service action url from the device description document.
	serviceType	the service type from the device description document
	actionName	the action to perform (from the service description)
	actionParams	the action name/value argument pairs, in order.
[in,out]	responseData	the return values. On input some additional parameters can be specified. Currently accepted parameters: ("timeoutms", milliseconds-string) responseData is cleared after using the values, and before further processing.
[out]	errorCodep	pointer to an integer to store the UPNP error code if we got an error response document. Same as the return value if set.
[out]	errorDescr	A place to store an error description (if we got an error response document).

UpnpSendAdvertisement()

EXPORT_SPEC int UpnpSendAdvertisement	(	UpnpDevice_Handle	Hnd,
		int	Exp
	)

Sends out the discovery announcements for all devices and services for a 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_INVALID_HANDLE: The handle is not a valid device handle.
• UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.

Parameters

Hnd	The device handle for which to send out the announcements.
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.

UpnpSendAdvertisementLowPower()

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

Sends out the discovery announcements for all devices and services for a 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_INVALID_HANDLE: The handle is not a valid device handle.
• UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.

Parameters

Hnd	The device handle for which to send out the announcements.
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.
PowerState	PowerState as defined by UPnP Low Power.
SleepPeriod	SleepPeriod as defined by UPnP Low Power.
RegistrationState	RegistrationState as defined by UPnP Low Power.

UpnpSetHostValidateCallback()

EXPORT_SPEC int UpnpSetHostValidateCallback	(	WebCallback_HostValidate	callback,
		void *	cookie
	)

UpnpSetHostValidateCallback alias for compatibility with libupnp

UpnpSetMaxContentLength()

EXPORT_SPEC 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

UPNP_E_SUCCESS.

Parameters

[in]

contentLength

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

UpnpSetMaxSubscriptions()

EXPORT_SPEC 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_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.

UpnpSetMaxSubscriptionTimeOut()

EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut	(	UpnpDevice_Handle	Hnd,
		int	MaxSubscriptionTimeOut
	)

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

This affects the UPnP Subscription timeout value (the time after which a subscription will expire). The default value accepts the time-out set by the control point (no maximum). If a maximum is set through this call and 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_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.

UpnpSetVirtualDirCallbacks()

EXPORT_SPEC int UpnpSetVirtualDirCallbacks

(

struct UpnpVirtualDirCallbacks *

callbacks

)

Sets the callback functions to be used to access a virtual directory.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_PARAM: one of the callbacks is not valid.

Parameters

[in]

callbacks

A structure that contains the callback functions.

UpnpSetWebServerCorsString()

EXPORT_SPEC int UpnpSetWebServerCorsString

(

const char *

corsString

)

Assign the Access-Control-Allow-Origin specfied by the input const char* cors_string parameterto 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: corsString is an invalid directory.

Parameters

[in]

corsString

String having the Access-Control-Allow-Origin string.

UpnpSetWebServerRootDir()

EXPORT_SPEC int UpnpSetWebServerRootDir

(

const char *

rootDir

)

Sets the document root directory for the internal WEB server.

If this is not called, the internal WEB server will not serve any document from the local file system. Only the protocol functions (SOAP), and, if configured, the virtual directories, will be active.

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]

rootDir

Path of the root directory of the web server.

UpnpSubscribe()

EXPORT_SPEC int UpnpSubscribe	(	UpnpClient_Handle	Hnd,
		const char *	EvtUrl,
		int *	TimeOut,
		Upnp_SID &	SubsId
	)

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

This operation is synchronous.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• 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 NULL.
• 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	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).

UpnpSubsOpsTimeoutMs()

EXPORT_SPEC int UpnpSubsOpsTimeoutMs	(	UpnpClient_Handle	Hnd,
		int	TimeOutMS
	)

Sets the HTTP timeout for subscription operations.

This defines how much time we wait for an answer from a device which might be reachable but unresponsive. This has nothing to do with the UPnP subscription/renewal durations.

The library default is 30S (30000), which much too long in common cases.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
• UPNP_E_INVALID_PARAM: TimeOut is <= 0.

Parameters

[in]	Hnd	The handle of the control point.
[in]	TimeOutMS	Timeout value in milliseconds.

UpnpUnRegisterClient()

EXPORT_SPEC 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_INVALID_HANDLE: The handle is not a valid control point handle.

Parameters

[in]

Hnd

The handle of the control point instance to unregister.

UpnpUnRegisterRootDevice()

EXPORT_SPEC int UpnpUnRegisterRootDevice

(

UpnpDevice_Handle

Hnd

)

Unregisters a root device.

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_INVALID_HANDLE: The handle is not a valid device handle.

Parameters

[in]

Hnd

The handle of the root device instance to unregister.

UpnpUnRegisterRootDeviceLowPower()

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

Unregisters a root device.

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_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.

UpnpUnSubscribe()

EXPORT_SPEC int UpnpUnSubscribe	(	UpnpClient_Handle	Hnd,
		const Upnp_SID &	SubsId
	)

Removes the subscription of a control point from a service previously subscribed to using UpnpSubscribe.

This is a synchronous call.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• 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.

UpnpVirtualDir_set_CloseCallback()

EXPORT_SPEC int UpnpVirtualDir_set_CloseCallback

(

VDCallback_Close

callback

)

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

Returns

An integer representing one of the following:

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

UpnpVirtualDir_set_GetInfoCallback()

EXPORT_SPEC int UpnpVirtualDir_set_GetInfoCallback

(

VDCallback_GetInfo

callback

)

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

Returns

An integer representing one of the following:

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

UpnpVirtualDir_set_OpenCallback()

EXPORT_SPEC int UpnpVirtualDir_set_OpenCallback

(

VDCallback_Open

callback

)

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

Returns

An integer representing one of the following:

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

UpnpVirtualDir_set_ReadCallback()

EXPORT_SPEC int UpnpVirtualDir_set_ReadCallback

(

VDCallback_Read

callback

)

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

Returns

An integer representing one of the following:

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

UpnpVirtualDir_set_SeekCallback()

EXPORT_SPEC int UpnpVirtualDir_set_SeekCallback

(

VDCallback_Seek

callback

)

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

Returns

An integer representing one of the following:

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

UpnpVirtualDir_set_WriteCallback()

EXPORT_SPEC int UpnpVirtualDir_set_WriteCallback

(

VDCallback_Write

callback

)

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

Returns

An integer representing one of the following:

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