libnpupnp: /home/dockes/projets/mpdupnp/npupnp/inc/upnp.h File Reference

libnpupnp 4.1.0 An almost compatible successor for the Portable UPnP reference library

Classes | Macros
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. More...
EXPORT_SPEC int | UpnpInit2 (const char *IfName, unsigned short DestPort)
| Initializes the library, passing the interface spec as a single string. More...
EXPORT_SPEC int | UpnpInit2 (const std::vector< std::string > &ifnames, unsigned short DestPort)
| Initializes the library, passing the interface spec as a vector. More...
EXPORT_SPEC int | UpnpInitWithOptions (const char *IfNames, unsigned short DestPort, unsigned int flags,...)
| Initializes the library, passing the interface spec as a string. More...
EXPORT_SPEC int | UpnpFinish (void)
| Terminate and clean up the library. More...
EXPORT_SPEC unsigned short | UpnpGetServerPort (void)
| Returns the internal server IPv4 UPnP listening port. More...
EXPORT_SPEC const char * | UpnpGetServerIpAddress (void)
| Returns a local IPv4 listening ip address. More...
EXPORT_SPEC int | UpnpSetMaxContentLength (size_t contentLength)
| Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses. More...
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. More...
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. More...
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. More...
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. More...
EXPORT_SPEC int | UpnpUnRegisterRootDevice (UpnpDevice_Handle Hnd)
| Unregisters a root device. More...
EXPORT_SPEC int | UpnpUnRegisterRootDeviceLowPower (UpnpDevice_Handle Hnd, int PowerState, int SleepPeriod, int RegistrationState)
| Unregisters a root device. More...
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. More...
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. More...
EXPORT_SPEC int | UpnpUnRegisterClient (UpnpClient_Handle Hnd)
| Unregisters a control point application, unsubscribing all active subscriptions. More...
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. More...
EXPORT_SPEC int | UpnpSearchAsyncUnicast (UpnpClient_Handle Hnd, const std::string &url, const char *Target, void *cookie)
| Unicast search. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
EXPORT_SPEC int | UpnpRenewSubscription (UpnpClient_Handle Hnd, int *TimeOut, const Upnp_SID &SubsId)
| Renews a subscription that is about to expire. More...
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. More...
EXPORT_SPEC int | UpnpSetMaxSubscriptionTimeOut (UpnpDevice_Handle Hnd, int MaxSubscriptionTimeOut)
| Sets the maximum time-out accepted for a subscription request or renewal. More...
EXPORT_SPEC int | UpnpSubsOpsTimeoutMs (UpnpClient_Handle Hnd, int TimeOutMS)
| Sets the HTTP timeout for subscription operations. More...
Client interface: HTTP helper functions
EXPORT_SPEC int | UpnpDownloadUrlItem (const char *url, char **outBuf, char *contentType)
| Downloads a text file specified in a URL. More...
EXPORT_SPEC int | UpnpDownloadUrlItem (const std::string &url, std::string &data, std::string &ct)
| Downloads a file specified in a URL. More...

## 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. More...
#define | UPNP_E_ALREADY_REGISTERED -120
| A client or a device is already registered. More...
#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. More...
#define | UPNP_E_SOCKET_WRITE -201
| An error happened while writing to a socket. More...
#define | UPNP_E_SOCKET_READ -202
| An error happened while reading from a socket. More...
#define | UPNP_E_SOCKET_BIND -203
| The SDK had a problem binding a socket to a network interface. More...
#define | UPNP_E_SOCKET_CONNECT -204
| The SDK had a problem connecting to a remote host. More...
#define | UPNP_E_OUTOF_SOCKET -205
| The SDK cannot create any more sockets. More...
#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. More...
#define | UPNP_E_SOCKET_ERROR -208
| Generic socket error code for conditions not covered by other error codes. More...
#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. More...
typedef UpnpWebFileHandle(* | VDCallback_Open) (const char *filename, enum UpnpOpenFileMode Mode, const void *cookie, const void *request_cookie)
| Virtual Directory Open callback function prototype. More...
typedef int(* | VDCallback_Read) (UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)
| Virtual Directory Read callback function prototype. More...
typedef int(* | VDCallback_Write) (UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)
| Virtual Directory Write callback function prototype. More...
typedef int(* | VDCallback_Seek) (UpnpWebFileHandle fileHnd, int64_t offset, int origin, const void *cookie, const void *request_cookie)
| Virtual Directory Seek callback function prototype. More...
typedef int(* | VDCallback_Close) (UpnpWebFileHandle fileHnd, const void *cookie, const void *request_cookie)
| Virtual directory close callback function prototype. More...
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. More...
EXPORT_SPEC int | UpnpIsWebserverEnabled (void)
| Returns `TRUE` if the webserver is enabled, or `FALSE` if it is not. More...
EXPORT_SPEC int | UpnpSetWebServerRootDir (const char *rootDir)
| Sets the document root directory for the internal WEB server. More...
EXPORT_SPEC std::string | UpnpGetUrlHostPortForClient (const struct sockaddr_storage *)
| return an URL host:port string suitable for the passed-in client address. More...
EXPORT_SPEC int | UpnpSetWebRequestHostValidateCallback (WebCallback_HostValidate callback, void *cookie)
EXPORT_SPEC int | UpnpSetHostValidateCallback (WebCallback_HostValidate callback, void *cookie)
EXPORT_SPEC int | UpnpVirtualDir_set_GetInfoCallback (VDCallback_GetInfo callback)
| Sets the get_info callback function to be used to access a virtual directory. More...
EXPORT_SPEC int | UpnpVirtualDir_set_OpenCallback (VDCallback_Open callback)
| Sets the open callback function to be used to access a virtual directory. More...
EXPORT_SPEC int | UpnpVirtualDir_set_ReadCallback (VDCallback_Read callback)
| Sets the read callback function to be used to access a virtual directory. More...
EXPORT_SPEC int | UpnpVirtualDir_set_WriteCallback (VDCallback_Write callback)
| Sets the write callback function to be used to access a virtual directory. More...
EXPORT_SPEC int | UpnpVirtualDir_set_SeekCallback (VDCallback_Seek callback)
| Sets the seek callback function to be used to access a virtual directory. More...
EXPORT_SPEC int | UpnpVirtualDir_set_CloseCallback (VDCallback_Close callback)
| Sets the close callback function to be used to access a virtual directory. More...
EXPORT_SPEC int | UpnpSetVirtualDirCallbacks (struct UpnpVirtualDirCallbacks *callbacks)
| Sets the callback functions to be used to access a virtual directory. More...
EXPORT_SPEC int | UpnpAddVirtualDir (const char *dirName, const void *cookie, const void **oldcookie)
| Adds a virtual directory mapping. More...
EXPORT_SPEC int | UpnpRemoveVirtualDir (const char *dirName)
| Removes a virtual directory mapping made with UpnpAddVirtualDir. More...
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.

## ◆ 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.