UPnP API

## Files

file | upnp.h
file | upnpapi.c

## Data Structures

struct | job_arg

## Macros

#define | LINE_SIZE (size_t)180
#define | NAME_SIZE (size_t)256
#define | MNFT_NAME_SIZE 64
#define | MODL_NAME_SIZE 32
#define | SERL_NUMR_SIZE 64
#define | MODL_DESC_SIZE 64
#define | UPNP_INFINITE -1
#define | UPNP_USING_CHUNKED -3
#define | UPNP_UNTIL_CLOSE -4
#define | ifr_netmask ifr_addr
#define | IN6_IS_ADDR_GLOBAL(a)
#define | IN6_IS_ADDR_ULA(a)

## Functions

static void | free_advertise_arg (job_arg *arg)
| Free memory associated with advertise job's argument.
static void | free_action_arg (job_arg *arg)
| Free memory associated with an action job's argument.
static int | WinsockInit (void)
| (Windows Only) Initializes the Windows Winsock library.
static int | UpnpInitMutexes (void)
| Initializes the global mutexes used by the UPnP SDK.
static int | UpnpInitThreadPools (void)
| Initializes the global threadm pools used by the UPnP SDK.
static int | UpnpInitPreamble (void)
| Performs the initial steps in initializing the UPnP SDK.
static int | UpnpInitStartServers (unsigned short DestPort)
| Finishes initializing the UPnP SDK.
void | PrintThreadPoolStats (ThreadPool *tp, const char *DbgFileName, int DbgLineNo, const char *msg)
| Prints thread pool statistics.
static int | GetFreeHandle ()
| Get a free handle.
static int | FreeHandle (int Upnp_Handle)
| Free handle.
static int | GetDescDocumentAndURL (Upnp_DescType descriptionType, char *description, int config_baseURL, int AddressFamily, IXML_Document **xmlDoc, char descURL[LINE_SIZE])
| Fills the sockadr_in with miniserver information.
static unsigned | UpnpComputeIpv6PrefixLength (struct sockaddr_in6 *Netmask)
| Computes prefix length from IPv6 netmask.
int | UpnpGetIfInfo (const char *IfName)
| Retrieve interface information and keep it in global variables. If NULL, we'll find the first suitable interface for operation.
void | UpnpThreadDistribution (struct UpnpNonblockParam *Param)
| Schedule async functions in threadpool.
Upnp_FunPtr | GetCallBackFn (UpnpClient_Handle Hnd)
| Get callback function ptr from a handle.
Upnp_Handle_Type | GetClientHandleInfo (UpnpClient_Handle *client_handle_out, struct Handle_Info **HndInfo)
| Get client handle info.
Upnp_Handle_Type | GetDeviceHandleInfo (UpnpDevice_Handle start, int AddressFamily, UpnpDevice_Handle *device_handle_out, struct Handle_Info **HndInfo)
| Retrieves the device handle and information of the first device of the address family specified. The search begins at the 'start' index, which should be 0 for the first call, then the last successful value returned. This allows listing all entries for the address family.
Upnp_Handle_Type | GetDeviceHandleInfoForPath (const char *path, int AddressFamily, UpnpDevice_Handle *device_handle_out, struct Handle_Info **HndInfo, service_info **serv_info)
| Retrieves the device handle and information of the first device of the address family specified, with a service having a controlURL or eventSubURL matching the path.
Upnp_Handle_Type | GetHandleInfo (UpnpClient_Handle Hnd, struct Handle_Info **HndInfo)
int | PrintHandleInfo (UpnpClient_Handle Hnd)
| Print handle info.
void | AutoAdvertise (void *input)
| This function is a timer thread scheduled by UpnpSendAdvertisement to the send advetisement again.
int | UpnpSetEventQueueLimits (int maxLen, int maxAge)

## Variables

struct VirtualDirCallbacks | virtualDirCallback
virtualDirList * | pVirtualDirList
ithread_mutex_t | GlobalClientSubscribeMutex
ithread_rwlock_t | GlobalHndRWLock
ithread_mutex_t | gUUIDMutex
ithread_mutex_t | gSDKInitMutex = PTHREAD_MUTEX_INITIALIZER
TimerThread | gTimerThread
ThreadPool | gSendThreadPool
ThreadPool | gRecvThreadPool
ThreadPool | gMiniServerThreadPool
WebServerState | bWebServerState = WEB_SERVER_DISABLED
WebCallback_HostValidate | gWebCallback_HostValidate = 0
void * | gWebCallback_HostValidateCookie = 0
int | gAllowLiteralHostRedirection = 0
char | gIF_NAME [LINE_SIZE] = {'\0'}
char | gIF_IPV4 [INET_ADDRSTRLEN] = {'\0'}
char | gIF_IPV4_NETMASK [INET_ADDRSTRLEN] = {'\0'}
char | gIF_IPV6 [INET6_ADDRSTRLEN] = {'\0'}
unsigned | gIF_IPV6_PREFIX_LENGTH = 0
char | gIF_IPV6_ULA_GUA [INET6_ADDRSTRLEN] = {'\0'}
unsigned | gIF_IPV6_ULA_GUA_PREFIX_LENGTH = 0
unsigned | gIF_INDEX = (unsigned)-1
unsigned short | LOCAL_PORT_V4
unsigned short | LOCAL_PORT_V6
unsigned short | LOCAL_PORT_V6_ULA_GUA
static void * | HandleTable [NUM_HANDLE]
membuffer | gDocumentRootDir
membuffer | gWebserverCorsString
size_t | g_maxContentLength = DEFAULT_SOAP_CONTENT_LENGTH
int | g_UpnpSdkEQMaxLen = MAX_SUBSCRIPTION_QUEUED_EVENTS
int | g_UpnpSdkEQMaxAge = MAX_SUBSCRIPTION_EVENT_AGE
int | UpnpSdkInit = 0
int | UpnpSdkClientRegistered = 0
int | UpnpSdkDeviceRegisteredV4 = 0
int | UpnpSdkDeviceregisteredV6 = 0
int job_arg::handle |
int job_arg::eventId |
void * job_arg::Event |
struct { |
int handle |
int eventId |
void * Event |
} | job_arg::advertise |
struct UpnpNonblockParam | job_arg::action

## Constants and Types

enum | UpnpOpenFileMode { UPNP_READ , UPNP_WRITE }
enum | Upnp_SType_e { UPNP_S_ALL , UPNP_S_ROOT , UPNP_S_DEVICE , UPNP_S_SERVICE }
| Represents the different types of searches that can be performed using the SDK for UPnP Devices API. More...
enum | Upnp_DescType_e { UPNPREG_URL_DESC , UPNPREG_FILENAME_DESC , UPNPREG_BUF_DESC }
| Specifies the type of description in UpnpRegisterRootDevice2. More...
typedef int | UpnpClient_Handle
| Returned when a control point application registers with UpnpRegisterClient.
typedef int | UpnpDevice_Handle
| Returned when a device application registers with UpnpRegisterRootDevice, UpnpRegisterRootDevice2, UpnpRegisterRootDevice3 or UpnpRegisterRootDevice4.
typedef char | Upnp_SID[44]
| Holds the subscription identifier for a subscription between a client and a device.
typedef enum Upnp_SType_e | Upnp_SType
typedef enum Upnp_DescType_e | Upnp_DescType

## Control Point HTTP API

enum | Upnp_HttpMethod_e { UPNP_HTTPMETHOD_PUT = 0 , UPNP_HTTPMETHOD_DELETE = 1 , UPNP_HTTPMETHOD_GET = 2 , UPNP_HTTPMETHOD_HEAD = 3 , UPNP_HTTPMETHOD_POST = 4 }
| Different HTTP methods. More...
typedef enum Upnp_HttpMethod_e | Upnp_HttpMethod
int | UpnpDownloadUrlItem (const char *url, char **outBuf, char *contentType)
| Downloads a file specified in a URL.
int | UpnpOpenHttpGet (const char *url, void **handle, char **contentType, int *contentLength, int *httpStatus, int timeout)
| Gets a file specified in a URL.
int | UpnpOpenHttpGetProxy (const char *url, const char *proxy_str, void **handle, char **contentType, int *contentLength, int *httpStatus, int timeout)
| Gets a file specified in a URL through the specified proxy.
int | UpnpOpenHttpGetEx (const char *url, void **handle, char **contentType, int *contentLength, int *httpStatus, int lowRange, int highRange, int timeout)
| Gets specified number of bytes from a file specified in the URL.
int | UpnpReadHttpGet (void *handle, char *buf, size_t *size, int timeout)
| Gets specified number of bytes from a file specified in a URL.
int | UpnpHttpGetProgress (void *handle, size_t *length, size_t *total)
| Retrieve progress information of a http-get transfer.
int | UpnpCancelHttpGet (void *handle)
| Set the cancel flag of the handle parameter.
int | UpnpCloseHttpGet (void *handle)
| Closes the connection and frees memory that was allocated for the handle parameter.
int | UpnpOpenHttpPost (const char *url, void **handle, const char *contentType, int contentLength, int timeout)
| Makes an HTTP POST request message, opens a connection to the server and sends the POST request to the server if the connection to the server succeeds.
int | UpnpWriteHttpPost (void *handle, char *buf, size_t *size, int timeout)
| Sends a request to a server to copy the contents of a buffer to the URI specified in the UpnpOpenHttpPost call.
int | UpnpCloseHttpPost (void *handle, int *httpStatus, int timeout)
| Sends and receives any pending data, closes the connection with the server, and frees memory allocated during the UpnpOpenHttpPost call.
int | UpnpOpenHttpConnection (const char *url, void **handle, int timeout)
| Opens a connection to the server.
int | UpnpMakeHttpRequest (Upnp_HttpMethod method, const char *url, void *handle, UpnpString *headers, const char *contentType, int contentLength, int timeout)
| Makes a HTTP request using a connection previously created by UpnpOpenHttpConnection.
int | UpnpWriteHttpRequest (void *handle, char *buf, size_t *size, int timeout)
| Writes the content of a HTTP request initiated by a UpnpMakeHttpRequest call. The end of the content should be indicated by a call to UpnpEndHttpRequest.
int | UpnpEndHttpRequest (void *handle, int timeout)
| Indicates the end of a HTTP request previously made by UpnpMakeHttpRequest.
int | UpnpGetHttpResponse (void *handle, UpnpString *headers, char **contentType, int *contentLength, int *httpStatus, int timeout)
| Gets the response from the server using a connection previously created by UpnpOpenHttpConnection.
int | UpnpReadHttpResponse (void *handle, char *buf, size_t *size, int timeout)
| Reads the content of a response using a connection previously created by UpnpOpenHttpConnection.
int | UpnpCloseHttpConnection (void *handle)
| Closes the connection created with UpnpOpenHttpConnection and frees any memory associated with the connection.
int | UpnpDownloadXmlDoc (const char *url, IXML_Document **xmlDoc)
| Downloads an XML document specified in a URL.

## Web Server API

typedef void * | UpnpWebFileHandle
| The type of handle returned by the web server for open requests.
typedef int(* | VDCallback_GetInfo) (const char *filename, UpnpFileInfo *info, const void *cookie, const void **request_cookie)
| Get-info callback function prototype.
typedef UpnpWebFileHandle(* | VDCallback_Open) (const char *filename, enum UpnpOpenFileMode Mode, const void *cookie, const void *request_cookie)
| Open callback function prototype.
typedef int(* | VDCallback_Read) (UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)
| Read callback function prototype.
typedef int(* | VDCallback_Write) (UpnpWebFileHandle fileHnd, char *buf, size_t buflen, const void *cookie, const void *request_cookie)
| Write callback function prototype.
typedef int(* | VDCallback_Seek) (UpnpWebFileHandle fileHnd, off_t offset, int origin, const void *cookie, const void *request_cookie)
| Seek callback function prototype.
typedef int(* | VDCallback_Close) (UpnpWebFileHandle fileHnd, const void *cookie, const void *request_cookie)
| Close callback function prototype.
typedef int(* | WebCallback_HostValidate) (const char *hostname, void *cookie)
int | UpnpSetWebServerRootDir (const char *rootDir)
| Sets the document root directory for the internal web server.
int | UpnpVirtualDir_set_GetInfoCallback (VDCallback_GetInfo callback)
| Sets the get_info callback function to be used to access a virtual directory.
int | UpnpVirtualDir_set_OpenCallback (VDCallback_Open callback)
| Sets the open callback function to be used to access a virtual directory.
int | UpnpVirtualDir_set_ReadCallback (VDCallback_Read callback)
| Sets the read callback function to be used to access a virtual directory.
int | UpnpVirtualDir_set_WriteCallback (VDCallback_Write callback)
| Sets the write callback function to be used to access a virtual directory.
int | UpnpVirtualDir_set_SeekCallback (VDCallback_Seek callback)
| Sets the seek callback function to be used to access a virtual directory.
int | UpnpVirtualDir_set_CloseCallback (VDCallback_Close callback)
| Sets the close callback function to be used to access a virtual directory.
int | UpnpEnableWebserver (int enable)
| Enables or disables the webserver.
int | UpnpIsWebserverEnabled (void)
| Returns `1` if the webserver is enabled, or `0` if it is not.
void | UpnpSetHostValidateCallback (WebCallback_HostValidate callback, void *cookie)
void | UpnpSetAllowLiteralHostRedirection (int enable)
int | UpnpSetWebServerCorsString (const char *corsString)
| Assign the Access-Control-Allow-Origin specfied by the input const char* cors_string parameterto the global CORS string.
int | UpnpAddVirtualDir (const char *dirName, const void *cookie, const void **oldcookie)
| Adds a virtual directory mapping.
int | UpnpRemoveVirtualDir (const char *dirName)
| Removes a virtual directory mapping made with UpnpAddVirtualDir.
void | UpnpRemoveAllVirtualDirs (void)
| Removes all virtual directory mappings.

## Initialization and Registration

int | UpnpInit2 (const char *IfName, unsigned short DestPort)
| Initializes the Linux SDK for UPnP Devices (IPv4 or IPv6).
int | UpnpFinish (void)
| Initializes the OpenSSL library, and the OpenSSL context for use with pupnp.
unsigned short | UpnpGetServerPort (void)
| Returns the internal server IPv4 UPnP listening port.
unsigned short | UpnpGetServerPort6 (void)
| Returns the internal server IPv6 link-local (LLA) UPnP listening port.
unsigned short | UpnpGetServerUlaGuaPort6 (void)
| Returns the internal server IPv6 ULA or GUA UPnP listening port.
char * | UpnpGetServerIpAddress (void)
| Returns the local IPv4 listening ip address.
char * | UpnpGetServerIp6Address (void)
| Returns the IPv6 link-local listening ip address.
char * | UpnpGetServerUlaGuaIp6Address (void)
| Returns the IPv6 unique-local or globally-unique listening ip address.
int | UpnpRegisterRootDevice (const char *DescUrl, Upnp_FunPtr Callback, const void *Cookie, UpnpDevice_Handle *Hnd)
| Registers a device application with the UPnP Library.
int | UpnpRegisterRootDevice2 (Upnp_DescType descriptionType, const char *description, size_t bufferLen, int config_baseURL, 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.
int | UpnpRegisterRootDevice3 (const char *DescUrl, Upnp_FunPtr Callback, const void *Cookie, UpnpDevice_Handle *Hnd, int AddressFamily)
| Registers a device application for a specific address family with the UPnP library.
int | UpnpRegisterRootDevice4 (const char *DescUrl, Upnp_FunPtr Callback, const void *Cookie, UpnpDevice_Handle *Hnd, int AddressFamily, const char *LowerDescUrl)
| Registers a device application for a specific address family with the UPnP library. This function can also be used to specify a dedicated description URL to be returned for legacy CPs.
int | UpnpUnRegisterRootDevice (UpnpDevice_Handle Hnd)
| Unregisters a root device registered with UpnpRegisterRootDevice, UpnpRegisterRootDevice2, UpnpRegisterRootDevice3 or UpnpRegisterRootDevice4.
int | UpnpUnRegisterRootDeviceLowPower (UpnpDevice_Handle Hnd, int PowerState, int SleepPeriod, int RegistrationState)
| Unregisters a root device registered with UpnpRegisterRootDevice, UpnpRegisterRootDevice2, UpnpRegisterRootDevice3 or UpnpRegisterRootDevice4.
int | UpnpRegisterClient (Upnp_FunPtr Callback, const void *Cookie, UpnpClient_Handle *Hnd)
| Registers a control point application with the UPnP Library.
int | UpnpUnRegisterClient (UpnpClient_Handle Hnd)
| Unregisters a control point application, unsubscribing all active subscriptions.
int | UpnpSetContentLength (UpnpClient_Handle Hnd, size_t contentLength)
int | UpnpSetMaxContentLength (size_t contentLength)
| Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses.

## Discovery

int | UpnpSearchAsync (UpnpClient_Handle Hnd, int Mx, const char *TTarget_constarget_const, const void *Cookie_const)
| Searches for devices matching the given search target.
int | UpnpSendAdvertisement (UpnpDevice_Handle Hnd, int Exp)
| Sends out the discovery announcements for all devices and services for a device.
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.

## Control

int | UpnpGetServiceVarStatus (UpnpClient_Handle Hnd, const char *ActionURL, const char *VarName, DOMString *StVarVal)
| Queries the state of a state variable of a service on another device.
int | UpnpGetServiceVarStatusAsync (UpnpClient_Handle Hnd, const char *ActionURL, const char *VarName, Upnp_FunPtr Fun, const void *Cookie)
| Queries the state of a variable of a service, generating a callback when the operation is complete.
int | UpnpSendAction (UpnpClient_Handle Hnd, const char *ActionURL, const char *ServiceType, const char *DevUDN, IXML_Document *Action, IXML_Document **RespNode)
| Sends a message to change a state variable in a service.
int | UpnpSendActionEx (UpnpClient_Handle Hnd, const char *ActionURL, const char *ServiceType, const char *DevUDN, IXML_Document *Header, IXML_Document *Action, IXML_Document **RespNode)
| Sends a message to change a state variable in a service.
int | UpnpSendActionAsync (UpnpClient_Handle Hnd, const char *ActionURL, const char *ServiceType, const char *DevUDN, IXML_Document *Action, Upnp_FunPtr Fun, const void *Cookie)
| Sends a message to change a state variable in a service, generating a callback when the operation is complete.
int | UpnpSendActionExAsync (UpnpClient_Handle Hnd, const char *ActionURL, const char *ServiceType, const char *DevUDN, IXML_Document *Header, IXML_Document *Action, Upnp_FunPtr Fun, const void *Cookie)
| Sends a message to change a state variable in a service, generating a callback when the operation is complete.

## Eventing

int | UpnpAcceptSubscription (UpnpDevice_Handle Hnd, const char *DevID, const char *ServID, 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.
int | UpnpAcceptSubscriptionExt (UpnpDevice_Handle Hnd, const char *DevID, const char *ServID, IXML_Document *PropSet, const Upnp_SID SubsId)
| Similar to UpnpAcceptSubscription() except that it takes a DOM document for the variables to event rather than an array of strings.
int | UpnpNotify (UpnpDevice_Handle, const char *DevID, const char *ServID, const char **VarName, const char **NewVal, int cVariables)
| Sends out an event change notification to all control points subscribed to a particular service.
int | UpnpNotifyExt (UpnpDevice_Handle, const char *DevID, const char *ServID, IXML_Document *PropSet)
| Similar to UpnpNotify except that it takes a DOM document for the event rather than an array of strings.
int | UpnpRenewSubscription (UpnpClient_Handle Hnd, int *TimeOut, const Upnp_SID SubsId)
| Renews a subscription that is about to expire.
int | UpnpRenewSubscriptionAsync (UpnpClient_Handle Hnd, int TimeOut, Upnp_SID SubsId, Upnp_FunPtr Fun, const void *Cookie)
| Renews a subscription that is about to expire, generating a callback when the operation is complete.
int | UpnpSetMaxSubscriptions (UpnpDevice_Handle Hnd, int MaxSubscriptions)
| Sets the maximum number of subscriptions accepted per service.
int | UpnpSetMaxSubscriptionTimeOut (UpnpDevice_Handle Hnd, int MaxSubscriptionTimeOut)
| Sets the maximum time-out accepted for a subscription request or renewal.
int | UpnpSubscribe (UpnpClient_Handle Hnd, const char *PublisherUrl, int *TimeOut, Upnp_SID SubsId)
| Registers a control point to receive event notifications from another device.
int | UpnpSubscribeAsync (UpnpClient_Handle Hnd, const char *PublisherUrl, int TimeOut, Upnp_FunPtr Fun, const void *Cookie)
| Performs the same operation as UpnpSubscribe, but returns immediately and calls the registered callback function when the operation is complete.
int | UpnpUnSubscribe (UpnpClient_Handle Hnd, const Upnp_SID SubsId)
| Removes the subscription of a control point from a service previously subscribed to using UpnpSubscribe or UpnpSubscribeAsync.
int | UpnpUnSubscribeAsync (UpnpClient_Handle Hnd, Upnp_SID SubsId, Upnp_FunPtr Fun, const void *Cookie)
| Removes a subscription of a control point from a service previously subscribed to using UpnpSubscribe or UpnpSubscribeAsync, generating a callback when the operation is complete.

## 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
| The handle passed to a function is not a recognized as 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
#define | UPNP_E_OUTOF_MEMORY -104
| Not enough resources are currently available to complete the operation.
#define | UPNP_E_INIT -105
| The SDK has already been initialized.
#define | UPNP_E_BUFFER_TOO_SMALL -106
#define | UPNP_E_INVALID_DESC -107
| The description document passed to UpnpRegisterRootDevice, UpnpRegisterRootDevice2 UpnpRegisterRootDevice3 or UpnpRegisterRootDevice4 is invalid.
#define | UPNP_E_INVALID_URL -108
| An URL passed into the function is invalid.
#define | UPNP_E_INVALID_SID -109
#define | UPNP_E_INVALID_DEVICE -110
#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.
#define | UPNP_E_BAD_REQUEST -114
#define | UPNP_E_INVALID_ACTION -115
| The SOAP action message is invalid.
#define | UPNP_E_FINISH -116
| UpnpInit2 has not been called, or UpnpFinish has already been called.
#define | UPNP_E_INIT_FAILED -117
| UpnpInit2 cannot complete.
#define | UPNP_E_URL_TOO_BIG -118
| The URL passed into a function is too long.
#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
| The SDK had a problem setting the socket to listen for incoming connections.
#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
#define | UPNP_E_CANCELED -210
| The operation was canceled.
#define | UPNP_E_EVENT_PROTOCOL -300
#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
#define | UPNP_E_OUTOF_BOUNDS -506
#define | UPNP_E_NOT_FOUND -507
| The response to a SOAP request did not contain the required XML constructs.
#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

## Detailed Description

## Macro Definition Documentation

## IN6_IS_ADDR_GLOBAL

#define IN6_IS_ADDR_GLOBAL | ( |  | a | ) |

Value:
((((__const uint32_t *)(a))[0] & \
htonl((uint32_t)0x70000000)) == \
htonl((uint32_t)0x20000000))

## IN6_IS_ADDR_ULA

#define IN6_IS_ADDR_ULA | ( |  | a | ) |

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

## 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. UpnpDownloadXmlDoc).

## UPNP_E_BAD_RESPONSE

#define UPNP_E_BAD_RESPONSE -113

The response received from the remote side of a connection is not correct for the protocol.

This applies to the GENA, SOAP, and HTTP protocols.

## UPNP_E_CANCELED

#define UPNP_E_CANCELED -210

The operation was canceled.

This error can be returned by any function that allows for external cancelation.

## UPNP_E_EXT_NOT_XML

#define UPNP_E_EXT_NOT_XML -504

The file name of the description document passed to UpnpRegisterRootDevice2 does not end in ".xml".

## UPNP_E_FILE_NOT_FOUND

#define UPNP_E_FILE_NOT_FOUND -502

The filename passed to one of the device registration functions was not found or was not accessible.

## UPNP_E_FILE_READ_ERROR

#define UPNP_E_FILE_READ_ERROR -503

An error happened while reading a file.

## UPNP_E_FINISH

#define UPNP_E_FINISH -116

UpnpInit2 has not been called, or UpnpFinish has already been called.

None of the API functions operate until UpnpInit2 successfully completes.

## UPNP_E_INIT

#define UPNP_E_INIT -105

The SDK has already been initialized.

The SDK needs to be initialied only once per process. Any additional initialization attempts simply return this error with no other ill effects.

## UPNP_E_INIT_FAILED

#define UPNP_E_INIT_FAILED -117

UpnpInit2 cannot complete.

The typical reason is failure to allocate sufficient resources.

## UPNP_E_INTERNAL_ERROR

#define UPNP_E_INTERNAL_ERROR -911

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

## UPNP_E_INVALID_ACTION

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

## UPNP_E_INVALID_ARGUMENT

#define UPNP_E_INVALID_ARGUMENT -501

One or more of the parameters passed to a function is invalid.

Refer to the individual function descriptions for the acceptable ranges for parameters.

## UPNP_E_INVALID_DESC

#define UPNP_E_INVALID_DESC -107

The description document passed to UpnpRegisterRootDevice, UpnpRegisterRootDevice2 UpnpRegisterRootDevice3 or UpnpRegisterRootDevice4 is invalid.

## UPNP_E_INVALID_HANDLE

#define UPNP_E_INVALID_HANDLE -100

The handle passed to a function is not a recognized as a valid handle.

## UPNP_E_INVALID_INTERFACE

#define UPNP_E_INVALID_INTERFACE -121

The interface provided to UpnpInit2 is unknown or does not have a valid IPv4 or IPv6 address configured.

## UPNP_E_INVALID_PARAM

#define UPNP_E_INVALID_PARAM -101

One or more of the parameters passed to the function is not valid.

Refer to the documentation for each function for more information on the valid ranges of the parameters.

## UPNP_E_INVALID_SERVICE

#define UPNP_E_INVALID_SERVICE -111

The device ID/service ID pair does not refer to a valid service.

Returned only by UpnpNotify, UpnpNotifyExt, UpnpAcceptSubscription, and UpnpAcceptSubscriptionExt.

## UPNP_E_INVALID_URL

#define UPNP_E_INVALID_URL -108

An URL passed into the function is invalid.

The actual cause is function specific, but in general, the URL itself might be malformed (e.g. have invalid characters in it) or the host might be unreachable.

## UPNP_E_LISTEN

#define UPNP_E_LISTEN -206

The SDK had a problem setting the socket to listen for incoming connections.

This error only happens during initialization (i.e. UpnpInit2).

## 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_NOT_FOUND

#define UPNP_E_NOT_FOUND -507

The response to a SOAP request did not contain the required XML constructs.

## UPNP_E_NOTIFY_UNACCEPTED

#define UPNP_E_NOTIFY_UNACCEPTED -303

The remote host did not accept the notify sent from the local device.

## UPNP_E_OUTOF_HANDLE

#define UPNP_E_OUTOF_HANDLE -102

The SDK does not have any more space for additional handles.

The SDK allocates space for only a few handles in order to conserve memory.

## UPNP_E_OUTOF_MEMORY

#define UPNP_E_OUTOF_MEMORY -104

Not enough resources are currently available to complete the operation.

Most operations require some free memory in order to complete their work.

## 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. UpnpDownloadXmlDoc).

## 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. UpnpDownloadXmlDoc).

## 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. UpnpDownloadXmlDoc).

## 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. UpnpDownloadXmlDoc).

## 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. UpnpDownloadXmlDoc).

## UPNP_E_SUBSCRIBE_UNACCEPTED

#define UPNP_E_SUBSCRIBE_UNACCEPTED -301

A subscription request was rejected from the remote side.

## UPNP_E_SUCCESS

#define UPNP_E_SUCCESS 0

The operation completed successfully.

For asynchronous functions, this only means that the packet generated by the operation was successfully transmitted on the network. The result of the entire operation comes as part of the callback for that operation.

## 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_E_UNSUBSCRIBE_UNACCEPTED

#define UPNP_E_UNSUBSCRIBE_UNACCEPTED -302

An unsubscribe request was rejected from the remote side.

## UPNP_E_URL_TOO_BIG

#define UPNP_E_URL_TOO_BIG -118

The URL passed into a function is too long.

The SDK limits URLs to 180 characters in length.

## Typedef Documentation

## Upnp_SID

typedef char Upnp_SID[44]

Holds the subscription identifier for a subscription between a client and a device.

The SID is a string representation of a globally unique id (GUID) and should not be modified.

## UpnpClient_Handle

typedef int UpnpClient_Handle

Returned when a control point application registers with UpnpRegisterClient.

Client handles can only be used with functions that operate with a client handle.

## UpnpDevice_Handle

typedef int UpnpDevice_Handle

Returned when a device application registers with UpnpRegisterRootDevice, UpnpRegisterRootDevice2, UpnpRegisterRootDevice3 or UpnpRegisterRootDevice4.

Device handles can only be used with functions that operate with a device handle.

## UpnpWebFileHandle

typedef void* UpnpWebFileHandle

The type of handle returned by the web server for open requests.

## VDCallback_Close

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

Close callback function prototype.

Parameters

  [in] | fileHnd | The handle of the file to close.
  [in] | cookie | The cookie associated with this VirtualDir
  [in] | request_cookie | The cookie associated with this request

## VDCallback_GetInfo

typedef int(* VDCallback_GetInfo) ( const char *filename, UpnpFileInfo *info, const void *cookie, const void **request_cookie)

Get-info callback function prototype.

Parameters

  [in] | filename | The name of the file to query.
  [out] | info | Pointer to a structure to store the information on the file.
  [in] | cookie | The cookie associated with this VirtualDir
  [out] | request_cookie | The cookie associated with this request

## VDCallback_Open

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

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`.
  [in] | cookie | The cookie associated with this VirtualDir
  [in] | request_cookie | The cookie associated with this request

## VDCallback_Read

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

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).
  [in] | cookie | The cookie associated with this VirtualDir
  [in] | request_cookie | The cookie associated with this request

## VDCallback_Seek

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

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.
  [in] | cookie | The cookie associated with this VirtualDir
  [in] | request_cookie | The cookie associated with this request

## VDCallback_Write

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

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.
  [in] | cookie | The cookie associated with this VirtualDir
  [in] | request_cookie | The cookie associated with this request

## Enumeration Type Documentation

## Upnp_DescType_e

enum Upnp_DescType_e

Specifies the type of description in UpnpRegisterRootDevice2.

These values control how UpnpRegisterRootDevice2 interprets the description parameter.

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_HttpMethod_e

enum Upnp_HttpMethod_e

Different HTTP methods.

## Upnp_SType_e

enum Upnp_SType_e

Represents the different types of searches that can be performed using the SDK for UPnP Devices API.

By specifying these different values to UpnpSearchAsync, the control point application can control the scope of the search from all devices to specific devices or services.

Enumerator
UPNP_S_ALL | Search for all devices and services on the network.
UPNP_S_ROOT | Search for all root devices on the network.
UPNP_S_DEVICE | Search for a particular device type or a particular device instance.
UPNP_S_SERVICE | Search for a particular service type, possibly on a particular device type or device instance.

## Function Documentation

## AutoAdvertise()

void AutoAdvertise | ( | void * | input | ) |

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

Parameters

  [in] | input | Information provided to the thread.

References free_advertise_arg(), and UpnpSendAdvertisement().

Referenced by UpnpSendAdvertisementLowPower().

## free_action_arg()

static void free_action_arg | ( | job_arg * | arg | ) |

static

Free memory associated with an action job's argument.

References ixmlDocument_free().

Referenced by UpnpSendActionAsync(), UpnpSendActionExAsync(), and UpnpThreadDistribution().

## free_advertise_arg()

static void free_advertise_arg | ( | job_arg * | arg | ) |

static

Free memory associated with advertise job's argument.

Referenced by AutoAdvertise(), and UpnpSendAdvertisementLowPower().

## FreeHandle()

static int FreeHandle | ( | int | Upnp_Handle | ) |

static

Free handle.

Returns
  UPNP_E_SUCCESS if successful or UPNP_E_INVALID_HANDLE if not

Parameters

  [in] | Upnp_Handle | Handle index.

References HandleTable, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, and UpnpPrintf().

Referenced by UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice4(), UpnpUnRegisterClient(), and UpnpUnRegisterRootDeviceLowPower().

## GetCallBackFn()

Upnp_FunPtr GetCallBackFn | ( | UpnpClient_Handle | Hnd | ) |

Get callback function ptr from a handle.

Returns
  Upnp_FunPtr

References HandleTable.

## GetClientHandleInfo()

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

Get client handle info.

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

Returns
  HND_CLIENT, HND_INVALID

Parameters

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

References GetHandleInfo().

Referenced by gena_process_notification_event(), ssdp_handle_ctrlpt_msg(), and UpnpFinish().

## GetDescDocumentAndURL()

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

static

Fills the sockadr_in with miniserver information.

References UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, UPNP_E_URL_TOO_BIG, UpnpDownloadXmlDoc(), and UPNPREG_URL_DESC.

Referenced by UpnpRegisterRootDevice2().

## GetDeviceHandleInfo()

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

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

Returns
  HND_DEVICE or HND_INVALID

Parameters

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

References GetHandleInfo(), UpnpSdkDeviceRegisteredV4, and UpnpSdkDeviceregisteredV6.

Referenced by ssdp_handle_device_request(), and UpnpFinish().

## GetDeviceHandleInfoForPath()

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

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

Returns
  HND_DEVICE or HND_INVALID

Parameters

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

References GetHandleInfo(), UpnpSdkDeviceRegisteredV4, and UpnpSdkDeviceregisteredV6.

Referenced by gena_process_subscription_renewal_request(), gena_process_subscription_request(), gena_process_unsubscribe_request(), and get_dev_service().

## GetFreeHandle()

static int GetFreeHandle | ( |  | ) |

static

Get a free handle.

Returns
  On success, an integer greater than zero or UPNP_E_OUTOF_HANDLE on failure.

References HandleTable, and UPNP_E_OUTOF_HANDLE.

Referenced by UpnpRegisterClient(), UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), and UpnpRegisterRootDevice4().

## GetHandleInfo()

Upnp_Handle_Type GetHandleInfo | ( | UpnpClient_Handle | Hnd,
|  | struct Handle_Info ** | HndInfo
| ) |  |

Parameters

  Hnd | handle pointer (key for the client handle structure).
  HndInfo | handle structure passed by this function.

References HandleTable, Handle_Info::HType, and UpnpPrintf().

Referenced by AdvertiseAndReply(), gena_process_notification_event(), GenaAutoRenewSubscription(), genaNotifyThread(), genaRenewSubscription(), genaSubscribe(), genaUnregisterClient(), genaUnregisterDevice(), genaUnSubscribe(), GetClientHandleInfo(), GetDeviceHandleInfo(), GetDeviceHandleInfoForPath(), SearchByTarget(), ssdp_handle_ctrlpt_msg(), UpnpAcceptSubscription(), UpnpAcceptSubscriptionExt(), UpnpGetServiceVarStatus(), UpnpGetServiceVarStatusAsync(), UpnpNotify(), UpnpNotifyExt(), UpnpRenewSubscription(), UpnpRenewSubscriptionAsync(), UpnpSearchAsync(), UpnpSendAction(), UpnpSendActionAsync(), UpnpSendActionEx(), UpnpSendActionExAsync(), UpnpSendAdvertisementLowPower(), UpnpSetContentLength(), UpnpSetMaxSubscriptions(), UpnpSetMaxSubscriptionTimeOut(), UpnpSubscribe(), UpnpSubscribeAsync(), UpnpUnRegisterClient(), UpnpUnRegisterRootDeviceLowPower(), UpnpUnSubscribe(), and UpnpUnSubscribeAsync().

## PrintHandleInfo()

int PrintHandleInfo | ( | UpnpClient_Handle | Hnd | ) |

Print handle info.

Returns
  UPNP_E_SUCCESS if successful, otherwise returns appropriate error.

Parameters

  [in] | Hnd | Handle index.

References Handle_Info::DescURL, HandleTable, Handle_Info::HType, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, and UpnpPrintf().

## PrintThreadPoolStats()

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

Prints thread pool statistics.

Parameters

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

References ThreadPoolGetStats(), and UpnpPrintf().

Referenced by UpnpFinish().

## UpnpAcceptSubscription()

int UpnpAcceptSubscription | ( | UpnpDevice_Handle | Hnd,
|  | const char * | DevID,
|  | const char * | ServID,
|  | 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 subdevice of the service generating the event.
  [in] | ServID | 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.

References genaInitNotify(), GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UpnpPrintf(), and UpnpSdkInit.

Referenced by TvDeviceHandleSubscriptionRequest().

## UpnpAcceptSubscriptionExt()

int UpnpAcceptSubscriptionExt | ( | UpnpDevice_Handle | Hnd,
|  | const char * | DevID,
|  | const char * | ServID,
|  | IXML_Document * | PropSet,
|  | const Upnp_SID | SubsId
| ) |  |

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

This function is sychronous and generates no callbacks.

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid device handle.
  - `UPNP_E_INVALID_SERVICE:` The DevId/ServId pair refers to an invalid service.
  - `UPNP_E_INVALID_SID:` The specified subscription ID is not valid.
  - `UPNP_E_INVALID_PARAM:` Either VarName, NewVal, DevID, ServID, or PropSet is not a valid pointer.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.

Parameters

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

References genaInitNotifyExt(), GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UpnpPrintf(), and UpnpSdkInit.

Referenced by TvDeviceHandleSubscriptionRequest().

## UpnpAddVirtualDir()

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.

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 new directory mapping to add.
  [in] | cookie | The cookie to associated with this virtual directory
  [out] | oldcookie | The cookie previously associated, if mapping is already present

References pVirtualDirList, UPNP_E_FINISH, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, and UpnpSdkInit.

## UpnpCancelHttpGet()

int UpnpCancelHttpGet | ( | void * | handle | ) |

Set the cancel flag of the handle parameter.

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` handle is not a valid pointer.

Parameters

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

## UpnpCloseHttpConnection()

int UpnpCloseHttpConnection | ( | void * | handle | ) |

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` handle, or is not a valid pointer.
  - `UPNP_E_SOCKET_READ:` An error or timeout occurred reading from a socket.
  - `UPNP_E_OUTOF_SOCKET:` Too many sockets are currently allocated.

Parameters

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

References http_CloseHttpConnection().

Referenced by UpnpCloseHttpGet().

## UpnpCloseHttpGet()

int UpnpCloseHttpGet | ( | void * | handle | ) |

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` handle is not a valid pointer.

Parameters

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

References UpnpCloseHttpConnection().

## UpnpCloseHttpPost()

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` Either handle, or httpStatus is not a valid pointer.
  - `UPNP_E_SOCKET_READ:` An error or timeout occurred reading from a socket.
  - `UPNP_E_OUTOF_SOCKET:` Too many sockets are currently allocated.

Parameters

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

References http_CloseHttpConnection(), http_EndHttpRequest(), http_GetHttpResponse(), and UPNP_E_SUCCESS.

## UpnpComputeIpv6PrefixLength()

static unsigned UpnpComputeIpv6PrefixLength | ( | struct sockaddr_in6 * | Netmask | ) |

static

Computes prefix length from IPv6 netmask.

Returns
  The IPv6 prefix length.

Referenced by UpnpGetIfInfo().

## UpnpDownloadUrlItem()

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

Downloads a file specified in a URL.

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

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

Parameters

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

References UPNP_E_INVALID_PARAM, and UPNP_E_INVALID_URL.

Referenced by UpnpDownloadXmlDoc().

## UpnpDownloadXmlDoc()

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

Downloads an XML document specified in a URL.

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

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

Parameters

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

References ixmlFreeDOMString(), ixmlParseBufferEx(), ixmlPrintNode(), UPNP_E_INVALID_DESC, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpDownloadUrlItem(), and UpnpPrintf().

Referenced by GetDescDocumentAndURL(), TvDeviceStateTableInit(), UpnpRegisterRootDevice(), and UpnpRegisterRootDevice4().

## UpnpEnableWebserver()

int UpnpEnableWebserver | ( | int | enable | ) |

Enables or disables the webserver.

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_OUTOF_MEMORY:` The web server could not be started due to an out-of-memory condition.
  - `UPNP_E_NO_WEB_SERVER:` The internal web server has been compiled out so it can't be enabled or disabled.

Parameters

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

References bWebServerState, SetHTTPGetCallback(), UPNP_E_FINISH, UPNP_E_SUCCESS, UpnpSdkInit, web_server_callback(), web_server_destroy(), and web_server_init().

Referenced by UpnpInitStartServers().

## UpnpEndHttpRequest()

int UpnpEndHttpRequest | ( | void * | handle,
|  | int | timeout
| ) |  |

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

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

Parameters

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

References http_EndHttpRequest().

Referenced by UpnpOpenHttpGet(), and UpnpOpenHttpGetProxy().

## UpnpFinish()

int UpnpFinish | ( | void |  | ) |

Initializes the OpenSSL library, and the OpenSSL context for use with pupnp.

Note
  This method is only enabled if pupnp is compiled with open-ssl support.

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INIT:` The SDK is already initialized.
  - `UPNP_E_INIT_FAILED:` The SDK initialization failed for an unknown reason.
  Terminates the Linux SDK for UPnP Devices.

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_FINISH:` The SDK is already terminated or it is not initialized.

References device_handle, GetClientHandleInfo(), GetDeviceHandleInfo(), GlobalClientSubscribeMutex, GlobalHndRWLock, gMiniServerThreadPool, gRecvThreadPool, gSendThreadPool, gTimerThread, gUUIDMutex, PrintThreadPoolStats(), StopMiniServer(), ThreadPoolShutdown(), TimerThreadShutdown(), UPNP_E_FINISH, UPNP_E_SUCCESS, UpnpCloseLog(), UpnpPrintf(), UpnpRemoveAllVirtualDirs(), UpnpSdkInit, UpnpUnRegisterClient(), UpnpUnRegisterRootDevice(), and web_server_destroy().

Referenced by TvCtrlPointStart(), TvDeviceStart(), TvDeviceStop(), UpnpInit2(), UpnpInitPreamble(), UpnpInitStartServers(), and UpnpInitThreadPools().

## UpnpGetHttpResponse()

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

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

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

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

Parameters

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

References http_GetHttpResponse().

Referenced by UpnpOpenHttpGet(), and UpnpOpenHttpGetProxy().

## UpnpGetIfInfo()

int UpnpGetIfInfo | ( | const char * | IfName | ) |

Retrieve interface information and keep it in global variables. If NULL, we'll find the first suitable interface for operation.

The interface must fulfill these requirements:

- Be UP.
- Not be LOOPBACK.
- Support MULTICAST.
- Have a valid IPv4 or IPv6 address.

We'll retrieve the following information from the interface:

- gIF_NAME -> Interface name (by input or found).
- gIF_IPV4 -> IPv4 address (if any).
- gIF_IPV6 -> IPv6 address (if any).
- gIF_IPV6_ULA_GUA -> ULA or GUA IPv6 address (if any)
- gIF_INDEX -> Interface index number.

Returns
  UPNP_E_SUCCESS on success.

Parameters

  [in] | IfName | Interface name (can be NULL).

References gIF_INDEX, gIF_IPV4, gIF_IPV4_NETMASK, gIF_IPV6, gIF_IPV6_PREFIX_LENGTH, gIF_IPV6_ULA_GUA, gIF_IPV6_ULA_GUA_PREFIX_LENGTH, gIF_NAME, UPNP_E_INIT, UPNP_E_INVALID_INTERFACE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpComputeIpv6PrefixLength(), and UpnpPrintf().

Referenced by UpnpInit2().

## UpnpGetServerIp6Address()

char * UpnpGetServerIp6Address | ( | void |  | ) |

Returns the IPv6 link-local listening ip address.

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

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

References gIF_IPV6, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

## UpnpGetServerIpAddress()

char * UpnpGetServerIpAddress | ( | void |  | ) |

Returns the local IPv4 listening ip address.

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

Returns
  - On success: The IPv4 address on which an internal server is listening for UPnP related requests.
  - On error: `NULL` is returned if UpnpInit2 has not succeeded.

References gIF_IPV4, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

## UpnpGetServerPort()

unsigned short UpnpGetServerPort | ( | void |  | ) |

Returns the internal server IPv4 UPnP listening port.

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

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

References LOCAL_PORT_V4, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

## UpnpGetServerPort6()

unsigned short UpnpGetServerPort6 | ( | void |  | ) |

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

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

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

References LOCAL_PORT_V6, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

## UpnpGetServerUlaGuaIp6Address()

char * UpnpGetServerUlaGuaIp6Address | ( | void |  | ) |

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

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

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

References gIF_IPV6_ULA_GUA, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

## UpnpGetServerUlaGuaPort6()

unsigned short UpnpGetServerUlaGuaPort6 | ( | void |  | ) |

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

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

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

References LOCAL_PORT_V6_ULA_GUA, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

## UpnpGetServiceVarStatus()

int UpnpGetServiceVarStatus | ( | UpnpClient_Handle | Hnd,
|  | const char * | ActionURL,
|  | const char * | VarName,
|  | DOMString * | StVarVal
| ) |  |

Queries the state of a state variable of a service on another device.

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

This is a synchronous call.

A positive return value indicates a SOAP error code, whereas a negative return code indicates an SDK error code.

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:` ActionUrl is not a valid URL.
  - `UPNP_E_INVALID_DESC:` The XML document was not found or it does not contain a valid XML description.
  - `UPNP_E_INVALID_PARAM:` StVarVal is not a valid pointer or VarName or ActionUrl is `NULL`.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.
  - `UPNP_SOAP_E_INVALID_VAR:` The given variable is invalid according to the device.

Parameters

  [in] | Hnd | The handle of the control point.
  [in] | ActionURL | The URL of the service.
  [in] | VarName | The name of the variable to query.
  [out] | StVarVal | The pointer to store the value for VarName. The SDK allocates this string and the caller needs to free it using ixmlFreeDOMString.

References GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UpnpPrintf(), and UpnpSdkInit.

## UpnpGetServiceVarStatusAsync()

int UpnpGetServiceVarStatusAsync | ( | UpnpClient_Handle | Hnd,
|  | const char * | ActionURL,
|  | const char * | VarName,
|  | Upnp_FunPtr | Fun,
|  | const void * | Cookie
| ) |  |

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid control point handle.
  - `UPNP_E_INVALID_URL:` The ActionUrl is not a valid URL.
  - `UPNP_E_INVALID_PARAM:` VarName, Fun or ActionUrl is not a valid pointer.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.

Parameters

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

References GetHandleInfo(), gSendThreadPool, ThreadPoolAdd(), TPJobInit(), TPJobSetFreeFunction(), TPJobSetPriority(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkInit, and UpnpThreadDistribution().

## UpnpHttpGetProgress()

int UpnpHttpGetProgress | ( | void * | handle,
|  | size_t * | length,
|  | size_t * | total
| ) |  |

Retrieve progress information of a http-get transfer.

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` Either handle, length or total is not a valid pointer.

Parameters

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

## UpnpInit2()

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

Initializes the Linux SDK for UPnP Devices (IPv4 or IPv6).

This function must be called before any other API function can be called. It should be called only once. Subsequent calls to this API return a `UPNP_E_INIT` error code.

Optionally, the application can specify an interface name (in the case of a multi-homed configuration) and a port number to use for all UPnP operations. Since a port number can be used only by one process, multiple processes using the SDK must specify different port numbers.

If unspecified, the SDK will use the first suitable interface and an arbitrary port.

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.
  - `UPNP_E_INVALID_INTERFACE:` IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.

Parameters

  IfName | The interface name to use by the UPnP SDK operations. Examples: "eth0", "xl0", "Local Area Connection", `NULL` to use the first suitable interface.
  DestPort | Local Port to listen for incoming connections. `NULL` will pick an arbitrary free port.

References gSDKInitMutex, UPNP_E_INIT, UPNP_E_SUCCESS, UpnpFinish(), UpnpGetIfInfo(), UpnpInitPreamble(), UpnpInitStartServers(), UpnpPrintf(), and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

## UpnpInitMutexes()

static int UpnpInitMutexes | ( | void |  | ) |

static

Initializes the global mutexes used by the UPnP SDK.

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

References GlobalClientSubscribeMutex, GlobalHndRWLock, gUUIDMutex, UPNP_E_INIT_FAILED, and UPNP_E_SUCCESS.

Referenced by UpnpInitPreamble().

## UpnpInitPreamble()

static int UpnpInitPreamble | ( | void |  | ) |

static

Performs the initial steps in initializing the UPnP SDK.

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

Returns
  UPNP_E_SUCCESS on success.

References gSendThreadPool, gTimerThread, gUpnpSdkNLSuuid, HandleTable, SetGenaCallback(), SetSoapCallback(), soap_device_callback(), TimerThreadInit(), UPNP_E_INIT_FAILED, UPNP_E_SUCCESS, UpnpFinish(), UpnpInitLog(), UpnpInitMutexes(), UpnpInitThreadPools(), UpnpPrintf(), and WinsockInit().

Referenced by UpnpInit2().

## UpnpInitStartServers()

static int UpnpInitStartServers | ( | unsigned short | DestPort | ) |

static

Finishes initializing the UPnP SDK.

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

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

Parameters

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

References gDocumentRootDir, gWebserverCorsString, LOCAL_PORT_V4, LOCAL_PORT_V6, LOCAL_PORT_V6_ULA_GUA, StartMiniServer(), UPNP_E_SUCCESS, UpnpEnableWebserver(), UpnpFinish(), and UpnpPrintf().

Referenced by UpnpInit2().

## UpnpInitThreadPools()

static int UpnpInitThreadPools | ( | void |  | ) |

static

Initializes the global threadm pools used by the UPnP SDK.

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

References gMiniServerThreadPool, gRecvThreadPool, gSendThreadPool, ThreadPoolInit(), TPAttrInit(), TPAttrSetIdleTime(), TPAttrSetJobsPerThread(), TPAttrSetMaxJobsTotal(), TPAttrSetMaxThreads(), TPAttrSetMinThreads(), TPAttrSetStackSize(), UPNP_E_INIT_FAILED, UPNP_E_SUCCESS, UpnpFinish(), and UpnpSdkInit.

Referenced by UpnpInitPreamble().

## UpnpIsWebserverEnabled()

int UpnpIsWebserverEnabled | ( | void |  | ) |

Returns `1` if the webserver is enabled, or `0` if it is not.

Checks if the webserver is enabled or disabled.

Returns
  An integer representing one of the following:
  - `1`: The webserver is enabled.
  - `0`: The webserver is not enabled
  1, if webserver is enabled or 0, if webserver is disabled.

References bWebServerState, and UpnpSdkInit.

## UpnpMakeHttpRequest()

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

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

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

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

Parameters

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

References http_MakeHttpRequest().

Referenced by UpnpOpenHttpGet(), and UpnpOpenHttpGetProxy().

## UpnpNotify()

int UpnpNotify | ( | UpnpDevice_Handle | Hnd,
|  | const char * | DevID,
|  | const char * | ServID,
|  | 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] | Hnd | The handle to the device sending the event.
  [in] | DevID | The device ID of the subdevice of the service generating the event.
  [in] | ServID | 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.

References genaNotifyAll(), GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UpnpPrintf(), and UpnpSdkInit.

Referenced by TvDeviceSetServiceTableVar().

## UpnpNotifyExt()

int UpnpNotifyExt | ( | UpnpDevice_Handle | Hnd,
|  | const char * | DevID,
|  | const char * | ServID,
|  | IXML_Document * | PropSet
| ) |  |

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

This function is synchronous and generates no callbacks.

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_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, ServID, or PropSet is not a valid pointer or cVariables is less than zero.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.

Parameters

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

References genaNotifyAllExt(), GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UpnpPrintf(), and UpnpSdkInit.

Referenced by TvDeviceSetServiceTableVar().

## UpnpOpenHttpConnection()

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

Opens a connection to the server.

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

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

Parameters

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

References http_OpenHttpConnection().

Referenced by UpnpOpenHttpGet(), and UpnpOpenHttpGetProxy().

## UpnpOpenHttpGet()

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

Gets a file specified in a URL.

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

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

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

Parameters

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

References UPNP_E_SUCCESS, UpnpEndHttpRequest(), UpnpGetHttpResponse(), UpnpMakeHttpRequest(), and UpnpOpenHttpConnection().

## UpnpOpenHttpGetEx()

int UpnpOpenHttpGetEx | ( | const char * | url,
|  | void ** | handle,
|  | char ** | contentType,
|  | int * | contentLength,
|  | int * | httpStatus,
|  | int | lowRange,
|  | int | highRange,
|  | int | timeout
| ) |  |

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

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

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

Parameters

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

## UpnpOpenHttpGetProxy()

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

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

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

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

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

Parameters

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

References UPNP_E_SUCCESS, UpnpEndHttpRequest(), UpnpGetHttpResponse(), UpnpMakeHttpRequest(), and UpnpOpenHttpConnection().

## UpnpOpenHttpPost()

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

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

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

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

Parameters

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

References http_MakeHttpRequest(), http_OpenHttpConnection(), and UPNP_E_SUCCESS.

## UpnpReadHttpGet()

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` Either handle, buf or size is not a valid pointer.
  - `UPNP_E_BAD_RESPONSE:` A bad response was received from the remote server.
  - `UPNP_E_BAD_HTTPMSG:` Either the request or response was in the incorrect format.
  - `UPNP_E_CANCELED:` another thread called UpnpCancelHttpGet.
  Note: In case of return values, the status code parameter of the passed in handle value may provide additional information on the return value.

Parameters

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

References http_ReadHttpResponse().

## UpnpReadHttpResponse()

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` Either handle, buf or size is not a valid pointer.
  - `UPNP_E_BAD_RESPONSE:` A bad response was received from the remote server.
  - `UPNP_E_BAD_HTTPMSG:` Either the request or response was in the incorrect format.
  - `UPNP_E_CANCELED:` another thread called UpnpCancelHttpGet.
  Note: In case of return values, the status code parameter of the passed in handle value may provide additional information on the return value.

Parameters

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

References http_ReadHttpResponse().

## UpnpRegisterClient()

int UpnpRegisterClient | ( | Upnp_FunPtr | Callback,
|  | 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] | Callback | Pointer to a function for receiving asynchronous events.
  [in] | Cookie | Pointer to user data returned with the callback function when invoked.
  [out] | Hnd | Pointer to a variable to store the new control point handle.

References Handle_Info::Callback, Handle_Info::ClientSubList, Handle_Info::Cookie, GetFreeHandle(), HandleTable, Handle_Info::HType, Handle_Info::MaxSubscriptions, Handle_Info::MaxSubscriptionTimeOut, Handle_Info::SsdpSearchList, UPNP_E_ALREADY_REGISTERED, UPNP_E_FINISH, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_HANDLE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkClientRegistered, UpnpSdkDeviceRegisteredV4, UpnpSdkDeviceregisteredV6, and UpnpSdkInit.

Referenced by TvCtrlPointStart().

## UpnpRegisterRootDevice()

int UpnpRegisterRootDevice | ( | const char * | DescUrl,
|  | Upnp_FunPtr | Callback,
|  | 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.

Device applications can also register as control points (see UpnpRegisterClient to get a control point handle to perform control point functionality).

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns.

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] | Callback | Pointer to the callback function for receiving asynchronous events.
  [in] | Cookie | Pointer to user data returned with the callback function when invoked.
  [out] | Hnd | Pointer to a variable to store the new device handle.

References Handle_Info::aliasInstalled, Handle_Info::Callback, Handle_Info::ClientSubList, Handle_Info::Cookie, Handle_Info::DescDocument, Handle_Info::DescURL, Handle_Info::DeviceAf, Handle_Info::DeviceList, FreeHandle(), GetFreeHandle(), HandleTable, Handle_Info::HType, ixmlDocument_free(), ixmlDocument_getElementsByTagName(), Handle_Info::LowerDescURL, Handle_Info::MaxSubscriptions, Handle_Info::MaxSubscriptionTimeOut, Handle_Info::ServiceList, Handle_Info::ServiceTable, Handle_Info::SsdpSearchList, UPNP_E_FINISH, UPNP_E_INVALID_DESC, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_HANDLE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpDownloadXmlDoc(), UpnpPrintf(), UpnpSdkDeviceRegisteredV4, and UpnpSdkInit.

## UpnpRegisterRootDevice2()

int UpnpRegisterRootDevice2 | ( | Upnp_DescType | descriptionType,
|  | const char * | description,
|  | size_t | bufferLen,
|  | int | config_baseURL,
|  | 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.

The description can also be configured to have the correct IP and port address.

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

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns.

Examples of using different types of description documents:

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_FINISH:` The SDK is already terminated or is not initialized.
  - `UPNP_E_INVALID_DESC:` The description document is not a valid device description.
  - `UPNP_E_INVALID_PARAM:` Either Callback 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.
  [in] | config_baseURL | If nonzero, `URLBase` of description document is configured and the description is served using the internal web server.
  [in] | Fun | Pointer to the callback function for receiving asynchronous events.
  [in] | Cookie | Pointer to user data returned with the callback function when invoked.
  [out] | Hnd | Pointer to a variable to store the new device handle.

References Handle_Info::aliasInstalled, Handle_Info::Callback, Handle_Info::ClientSubList, Handle_Info::Cookie, Handle_Info::DescDocument, Handle_Info::DescURL, Handle_Info::DeviceAf, Handle_Info::DeviceList, FreeHandle(), GetDescDocumentAndURL(), GetFreeHandle(), HandleTable, Handle_Info::HType, ixmlDocument_free(), ixmlDocument_getElementsByTagName(), Handle_Info::LowerDescURL, Handle_Info::MaxSubscriptions, Handle_Info::MaxSubscriptionTimeOut, Handle_Info::ServiceList, Handle_Info::ServiceTable, Handle_Info::SsdpSearchList, UPNP_E_FINISH, UPNP_E_INVALID_DESC, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_HANDLE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkDeviceRegisteredV4, and UpnpSdkInit.

## UpnpRegisterRootDevice3()

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

Registers a device application for a specific address family with the UPnP library.

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] | Callback | Pointer to the callback function for receiving asynchronous events.
  [in] | Cookie | Pointer to user data returned with the callback function when invoked.
  [out] | Hnd | Pointer to a variable to store the new device handle.
  [in] | AddressFamily | Address family of this device. Can be AF_INET for an IPv4 device, or AF_INET6 for an IPv6 device. Defaults to AF_INET.

References Handle_Info::Cookie, UpnpPrintf(), and UpnpRegisterRootDevice4().

Referenced by TvDeviceStart().

## UpnpRegisterRootDevice4()

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

Registers a device application for a specific address family 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] | Callback | Pointer to the callback function for receiving asynchronous events.
  [in] | Cookie | Pointer to user data returned with the callback function when invoked.
  [out] | Hnd | Pointer to a variable to store the new device handle.
  [in] | AddressFamily | Address family of this device. Can be AF_INET for an IPv4 device, or AF_INET6 for an IPv6 device. Defaults to AF_INET.
  [in] | LowerDescUrl | Pointer to a string containing the description URL to be returned for legacy CPs for this root device instance.

References Handle_Info::aliasInstalled, Handle_Info::Callback, Handle_Info::ClientSubList, Handle_Info::Cookie, Handle_Info::DescDocument, Handle_Info::DescURL, Handle_Info::DeviceAf, Handle_Info::DeviceList, FreeHandle(), GetFreeHandle(), HandleTable, Handle_Info::HType, ixmlDocument_free(), ixmlDocument_getElementsByTagName(), Handle_Info::LowerDescURL, Handle_Info::MaxSubscriptions, Handle_Info::MaxSubscriptionTimeOut, Handle_Info::ServiceList, Handle_Info::ServiceTable, Handle_Info::SsdpSearchList, UPNP_E_FINISH, UPNP_E_INVALID_DESC, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_HANDLE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpDownloadXmlDoc(), UpnpPrintf(), UpnpSdkDeviceRegisteredV4, UpnpSdkDeviceregisteredV6, and UpnpSdkInit.

Referenced by UpnpRegisterRootDevice3().

## UpnpRemoveAllVirtualDirs()

void UpnpRemoveAllVirtualDirs | ( | void |  | ) |

Removes all virtual directory mappings.

References pVirtualDirList, and UpnpSdkInit.

Referenced by UpnpFinish().

## UpnpRemoveVirtualDir()

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.

References pVirtualDirList, UPNP_E_FINISH, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, and UpnpSdkInit.

## UpnpRenewSubscription()

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

Renews a subscription that is about to expire.

This function is synchronous.

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_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.

References genaRenewSubscription(), GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UpnpPrintf(), UpnpSdkInit, UpnpString_delete(), UpnpString_new(), and UpnpString_set_String().

## UpnpRenewSubscriptionAsync()

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

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

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

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

Parameters

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

References GetHandleInfo(), gSendThreadPool, ThreadPoolAdd(), TPJobInit(), TPJobSetFreeFunction(), TPJobSetPriority(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkInit, and UpnpThreadDistribution().

## UpnpSearchAsync()

int UpnpSearchAsync | ( | UpnpClient_Handle | Hnd,
|  | int | Mx,
|  | const char * | TTarget_constarget_const,
|  | const void * | Cookie_const
| ) |  |

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 root device, device, or service. The application specifies the search type by the Target parameter.

This function searches for the devices for the provided maximum time. It is an asynchronous function. It schedules a search job and returns. The client is notified about the search results after search timer.

Note that there is no way for the SDK to distinguish which client instance issued a particular search. Therefore, the client can get search callbacks that do not match the original criteria of the search. Also, the application will receive multiple callbacks for each 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`.
  TTarget_constarget_const | The search target as defined in the UPnP Device Architecture v1.0 specification.
  Cookie_const | The user data to pass when the callback function is invoked.

References GetHandleInfo(), SearchByTarget(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, UpnpPrintf(), and UpnpSdkInit.

Referenced by TvCtrlPointVerifyTimeouts().

## UpnpSendAction()

int UpnpSendAction | ( | UpnpClient_Handle | Hnd,
|  | const char * | ActionURL,
|  | const char * | ServiceType,
|  | const char * | DevUDN,
|  | IXML_Document * | Action,
|  | IXML_Document ** | RespNode
| ) |  |

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

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid control point handle.
  - `UPNP_E_INVALID_URL:` ActionUrl is not a valid URL.
  - `UPNP_E_INVALID_ACTION:` This action is not valid.
  - `UPNP_E_INVALID_DEVICE:` DevUDN is not a valid device.
  - `UPNP_E_INVALID_PARAM:` ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.

Parameters

  [in] | Hnd | The handle of the control point sending the action.
  [in] | ActionURL | The action URL of the service.
  [in] | ServiceType | The type of the service.
  [in] | DevUDN | This parameter is ignored and must be `NULL`.
  [in] | Action | The DOM document for the action.
  [out] | RespNode | The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

References GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UpnpPrintf(), and UpnpSdkInit.

Referenced by UpnpSendActionEx().

## UpnpSendActionAsync()

int UpnpSendActionAsync | ( | UpnpClient_Handle | Hnd,
|  | const char * | ActionURL,
|  | const char * | ServiceType,
|  | const char * | DevUDN,
|  | IXML_Document * | Action,
|  | Upnp_FunPtr | Fun,
|  | const void * | Cookie
| ) |  |

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid control point handle.
  - `UPNP_E_INVALID_URL:` ActionUrl is an invalid URL.
  - `UPNP_E_INVALID_DEVICE:` DevUDN is an invalid device.
  - `UPNP_E_INVALID_PARAM:` Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is `NULL`.
  - `UPNP_E_INVALID_ACTION:` This action is not valid.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.

Parameters

  [in] | Hnd | The handle of the control point sending the action.
  [in] | ActionURL | The action URL of the service.
  [in] | ServiceType | The type of the service.
  [in] | DevUDN | This parameter is ignored and must be `NULL`.
  [in] | Action | The DOM document for the action to perform on this device.
  [in] | Fun | Pointer to a callback function to be invoked when the operation completes.
  [in] | Cookie | Pointer to user data that to be passed to the callback when invoked.

References DOMString, free_action_arg(), GetHandleInfo(), gSendThreadPool, ixmlFreeDOMString(), ixmlParseBufferEx(), ixmlPrintNode(), ThreadPoolAdd(), TPJobInit(), TPJobSetFreeFunction(), TPJobSetPriority(), UPNP_E_FINISH, UPNP_E_INVALID_ACTION, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkInit, and UpnpThreadDistribution().

Referenced by UpnpSendActionExAsync().

## UpnpSendActionEx()

int UpnpSendActionEx | ( | UpnpClient_Handle | Hnd,
|  | const char * | ActionURL,
|  | const char * | ServiceType,
|  | const char * | DevUDN,
|  | IXML_Document * | Header,
|  | IXML_Document * | Action,
|  | IXML_Document ** | RespNode
| ) |  |

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

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid control point handle.
  - `UPNP_E_INVALID_URL:` ActionUrl is not a valid URL.
  - `UPNP_E_INVALID_ACTION:` This action is not valid.
  - `UPNP_E_INVALID_DEVICE:` DevUDN is not a valid device.
  - `UPNP_E_INVALID_PARAM:` ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.

Parameters

  [in] | Hnd | The handle of the control point sending the action.
  [in] | ActionURL | The action URL of the service.
  [in] | ServiceType | The type of the service.
  [in] | DevUDN | This parameter is ignored and must be `NULL`.
  [in] | Header | The DOM document for the SOAP header. This may be `NULL` if the header is not required.
  [in] | Action | The DOM document for the action.
  [out] | RespNode | The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

References GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UpnpPrintf(), UpnpSdkInit, and UpnpSendAction().

## UpnpSendActionExAsync()

int UpnpSendActionExAsync | ( | UpnpClient_Handle | Hnd,
|  | const char * | ActionURL,
|  | const char * | ServiceType,
|  | const char * | DevUDN,
|  | IXML_Document * | Header,
|  | IXML_Document * | Action,
|  | Upnp_FunPtr | Fun,
|  | const void * | Cookie
| ) |  |

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid control point handle.
  - `UPNP_E_INVALID_URL:` ActionUrl is an invalid URL.
  - `UPNP_E_INVALID_DEVICE:` DevUDN is an invalid device.
  - `UPNP_E_INVALID_PARAM:` Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is `NULL`.
  - `UPNP_E_INVALID_ACTION:` This action is not valid.
  - `UPNP_E_OUTOF_MEMORY:` Insufficient resources exist to complete this operation.

Parameters

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

References DOMString, free_action_arg(), GetHandleInfo(), gSendThreadPool, ixmlDocument_free(), ixmlFreeDOMString(), ixmlParseBufferEx(), ixmlPrintNode(), ThreadPoolAdd(), TPJobInit(), TPJobSetFreeFunction(), TPJobSetPriority(), UPNP_E_FINISH, UPNP_E_INVALID_ACTION, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkInit, UpnpSendActionAsync(), and UpnpThreadDistribution().

## UpnpSendAdvertisement()

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.

References UpnpPrintf(), and UpnpSendAdvertisementLowPower().

Referenced by AutoAdvertise(), and TvDeviceStart().

## UpnpSendAdvertisementLowPower()

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.

References AdvertiseAndReply(), AutoAdvertise(), free_advertise_arg(), GetHandleInfo(), gTimerThread, REL_SEC, TimerThreadSchedule(), TPJobInit(), TPJobSetFreeFunction(), TPJobSetPriority(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), and UpnpSdkInit.

Referenced by UpnpSendAdvertisement().

## UpnpSetContentLength()

int UpnpSetContentLength | ( | UpnpClient_Handle | Hnd,
|  | size_t | contentLength
| ) |  |

Deprecated:
  Use UpnpSetMaxContentLength instead.

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

Parameters

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

References g_maxContentLength, GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, and UpnpSdkInit.

## UpnpSetMaxContentLength()

int UpnpSetMaxContentLength | ( | size_t | contentLength | ) |

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

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

If set to 0 then checking will be disabled.

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.

Parameters

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

References g_maxContentLength, UPNP_E_FINISH, UPNP_E_SUCCESS, and UpnpSdkInit.

## UpnpSetMaxSubscriptions()

int UpnpSetMaxSubscriptions | ( | UpnpDevice_Handle | Hnd,
|  | int | MaxSubscriptions
| ) |  |

Sets the maximum number of subscriptions accepted per service.

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_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.

References GetHandleInfo(), Handle_Info::MaxSubscriptions, UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, UpnpPrintf(), and UpnpSdkInit.

## UpnpSetMaxSubscriptionTimeOut()

int UpnpSetMaxSubscriptionTimeOut | ( | UpnpDevice_Handle | Hnd,
|  | int | MaxSubscriptionTimeOut
| ) |  |

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_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.

References GetHandleInfo(), Handle_Info::MaxSubscriptionTimeOut, UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, UpnpPrintf(), and UpnpSdkInit.

## UpnpSetWebServerCorsString()

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:` rootDir is an invalid directory.

Parameters

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

## UpnpSetWebServerRootDir()

int UpnpSetWebServerRootDir | ( | const char * | rootDir | ) |

Sets the document root directory for the internal web server.

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

This function also activates or deactivates the web server. To disable the web server, pass `NULL` for rootDir; to activate, pass a valid directory string.

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_ARGUMENT:` rootDir is an invalid directory.

Parameters

  [in] | rootDir | Path of the root directory of the web server.

Referenced by TvDeviceStart().

## UpnpSubscribe()

int UpnpSubscribe | ( | UpnpClient_Handle | Hnd,
|  | const char * | PublisherUrl,
|  | 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] | PublisherUrl | 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).

References genaSubscribe(), GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UpnpPrintf(), UpnpSdkInit, UpnpString_delete(), UpnpString_get_String(), UpnpString_new(), and UpnpString_set_String().

## UpnpSubscribeAsync()

int UpnpSubscribeAsync | ( | UpnpClient_Handle | Hnd,
|  | const char * | PublisherUrl,
|  | int | TimeOut,
|  | Upnp_FunPtr | Fun,
|  | const void * | Cookie
| ) |  |

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

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

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

Parameters

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

References GetHandleInfo(), gSendThreadPool, ThreadPoolAdd(), TPJobInit(), TPJobSetFreeFunction(), TPJobSetPriority(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkInit, and UpnpThreadDistribution().

## UpnpThreadDistribution()

void UpnpThreadDistribution | ( | struct UpnpNonblockParam * | Param | ) |

Schedule async functions in threadpool.

References DOMString, free_action_arg(), genaRenewSubscription(), genaSubscribe(), genaUnSubscribe(), ixmlDocument_free(), UPNP_CONTROL_ACTION_COMPLETE, UPNP_CONTROL_GET_VAR_COMPLETE, UPNP_EVENT_RENEWAL_COMPLETE, UPNP_EVENT_SUBSCRIBE_COMPLETE, UPNP_EVENT_UNSUBSCRIBE_COMPLETE, UpnpActionComplete_delete(), UpnpActionComplete_new(), UpnpActionComplete_set_ActionRequest(), UpnpActionComplete_set_ActionResult(), UpnpActionComplete_set_ErrCode(), UpnpActionComplete_strcpy_CtrlUrl(), UpnpEventSubscribe_delete(), UpnpEventSubscribe_get_PublisherUrl(), UpnpEventSubscribe_get_SID(), UpnpEventSubscribe_new(), UpnpEventSubscribe_set_ErrCode(), UpnpEventSubscribe_set_SID(), UpnpEventSubscribe_set_TimeOut(), UpnpEventSubscribe_strcpy_PublisherUrl(), UpnpEventSubscribe_strcpy_SID(), UpnpPrintf(), UpnpStateVarComplete_delete(), UpnpStateVarComplete_new(), UpnpStateVarComplete_set_CurrentVal(), UpnpStateVarComplete_set_ErrCode(), UpnpStateVarComplete_strcpy_CtrlUrl(), UpnpStateVarComplete_strcpy_StateVarName(), UpnpString_delete(), and UpnpString_new().

Referenced by UpnpGetServiceVarStatusAsync(), UpnpRenewSubscriptionAsync(), UpnpSendActionAsync(), UpnpSendActionExAsync(), UpnpSubscribeAsync(), and UpnpUnSubscribeAsync().

## UpnpUnRegisterClient()

int UpnpUnRegisterClient | ( | UpnpClient_Handle | Hnd | ) |

Unregisters a control point application, unsubscribing all active subscriptions.

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

UpnpUnRegisterClient is a synchronous call and generates no callbacks.

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid control point handle.

Parameters

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

References FreeHandle(), genaUnregisterClient(), GetHandleInfo(), Handle_Info::SsdpSearchList, UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkClientRegistered, and UpnpSdkInit.

Referenced by UpnpFinish().

## UpnpUnRegisterRootDevice()

int UpnpUnRegisterRootDevice | ( | UpnpDevice_Handle | Hnd | ) |

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

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_HANDLE:` The handle is not a valid device handle.

Parameters

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

References UpnpPrintf(), and UpnpUnRegisterRootDeviceLowPower().

Referenced by TvDeviceStop(), and UpnpFinish().

## UpnpUnRegisterRootDeviceLowPower()

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

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

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

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

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.

References AdvertiseAndReply(), Handle_Info::aliasInstalled, Handle_Info::DescDocument, Handle_Info::DeviceAf, Handle_Info::DeviceList, FreeHandle(), genaUnregisterDevice(), GetHandleInfo(), ixmlDocument_free(), ixmlNodeList_free(), Handle_Info::ServiceList, Handle_Info::SsdpSearchList, UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkDeviceRegisteredV4, UpnpSdkDeviceregisteredV6, UpnpSdkInit, and web_server_set_alias().

Referenced by UpnpUnRegisterRootDevice().

## UpnpUnSubscribe()

int UpnpUnSubscribe | ( | UpnpClient_Handle | Hnd,
|  | const Upnp_SID | SubsId
| ) |  |

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

This is a synchronous call.

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_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.

References genaUnSubscribe(), GetHandleInfo(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UpnpPrintf(), UpnpSdkInit, UpnpString_delete(), UpnpString_new(), and UpnpString_set_String().

## UpnpUnSubscribeAsync()

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

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

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

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

Parameters

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

References GetHandleInfo(), gSendThreadPool, ThreadPoolAdd(), TPJobInit(), TPJobSetFreeFunction(), TPJobSetPriority(), UPNP_E_FINISH, UPNP_E_INVALID_HANDLE, UPNP_E_INVALID_PARAM, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpSdkInit, and UpnpThreadDistribution().

## UpnpVirtualDir_set_CloseCallback()

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.

References VirtualDirCallbacks::close, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, and virtualDirCallback.

## UpnpVirtualDir_set_GetInfoCallback()

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.

References VirtualDirCallbacks::get_info, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, and virtualDirCallback.

## UpnpVirtualDir_set_OpenCallback()

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.

References VirtualDirCallbacks::open, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, and virtualDirCallback.

## UpnpVirtualDir_set_ReadCallback()

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.

References VirtualDirCallbacks::read, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, and virtualDirCallback.

## UpnpVirtualDir_set_SeekCallback()

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.

References VirtualDirCallbacks::seek, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, and virtualDirCallback.

## UpnpVirtualDir_set_WriteCallback()

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.

References UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, virtualDirCallback, and VirtualDirCallbacks::write.

## UpnpWriteHttpPost()

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` Either handle, buf or size is not a valid pointer.
  - `UPNP_E_SOCKET_WRITE:` An error or timeout occurred writing to a socket.
  - `UPNP_E_OUTOF_SOCKET:` Too many sockets are currently allocated.

Parameters

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

References http_WriteHttpRequest().

## UpnpWriteHttpRequest()

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

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

Returns
  An integer representing one of the following:
  - `UPNP_E_SUCCESS:` The operation completed successfully.
  - `UPNP_E_INVALID_PARAM:` Either handle, buf or size is not a valid pointer.
  - `UPNP_E_SOCKET_WRITE:` An error or timeout occurred writing to a socket.
  - `UPNP_E_OUTOF_SOCKET:` Too many sockets are currently allocated.

Parameters

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

References http_WriteHttpRequest().

## WinsockInit()

static int WinsockInit | ( | void |  | ) |

static

(Windows Only) Initializes the Windows Winsock library.

Returns
  UPNP_E_SUCCESS on success, UPNP_E_INIT_FAILED on failure.

References UPNP_E_INIT_FAILED, and UPNP_E_SUCCESS.

Referenced by UpnpInitPreamble().

## Variable Documentation

## bWebServerState

WebServerState bWebServerState = WEB_SERVER_DISABLED

Flag to indicate the state of web server

Referenced by UpnpEnableWebserver(), UpnpIsWebserverEnabled(), web_server_destroy(), and web_server_init().

## g_maxContentLength

size_t g_maxContentLength = DEFAULT_SOAP_CONTENT_LENGTH

Maximum content-length (in bytes) that the SDK will process on an incoming packet. Content-Length exceeding this size will be not processed and error 413 (HTTP Error Code) will be returned to the remote end point.

Referenced by http_RecvMessage(), UpnpSetContentLength(), and UpnpSetMaxContentLength().

## g_UpnpSdkEQMaxAge

int g_UpnpSdkEQMaxAge = MAX_SUBSCRIPTION_EVENT_AGE

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

## g_UpnpSdkEQMaxLen

int g_UpnpSdkEQMaxLen = MAX_SUBSCRIPTION_QUEUED_EVENTS

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

## gAllowLiteralHostRedirection

int gAllowLiteralHostRedirection = 0

Allow literal host names redirection to numeric host names.

## gDocumentRootDir

membuffer gDocumentRootDir

extern

a local dir which serves as webserver root

Global variable. A local dir which serves as webserver root.

Referenced by process_request(), UpnpInitStartServers(), web_server_destroy(), web_server_init(), and web_server_set_root_dir().

## gIF_INDEX

unsigned gIF_INDEX = (unsigned)-1

Contains interface index. (extern'ed in upnp.h)

Referenced by DeviceAdvertisement(), DeviceShutdown(), parse_hostport(), SearchByTarget(), SendToCaller(), ServiceAdvertisement(), ServiceShutdown(), and UpnpGetIfInfo().

## gIF_IPV4

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

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

Referenced by create_ssdp_sock_v4(), gena_subscribe(), gena_validate_delivery_urls(), get_ssdp_sockets(), NewRequestHandler(), SearchByTarget(), UpnpGetIfInfo(), and UpnpGetServerIpAddress().

## gIF_IPV4_NETMASK

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

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

Referenced by gena_validate_delivery_urls(), and UpnpGetIfInfo().

## gIF_IPV6

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

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

Referenced by gena_subscribe(), gena_validate_delivery_urls(), get_ssdp_sockets(), UpnpGetIfInfo(), and UpnpGetServerIp6Address().

## gIF_IPV6_PREFIX_LENGTH

unsigned gIF_IPV6_PREFIX_LENGTH = 0

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

Referenced by gena_validate_delivery_urls(), and UpnpGetIfInfo().

## gIF_IPV6_ULA_GUA

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

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

Referenced by gena_subscribe(), gena_validate_delivery_urls(), get_ssdp_sockets(), UpnpGetIfInfo(), and UpnpGetServerUlaGuaIp6Address().

## gIF_IPV6_ULA_GUA_PREFIX_LENGTH

unsigned gIF_IPV6_ULA_GUA_PREFIX_LENGTH = 0

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

Referenced by gena_validate_delivery_urls(), and UpnpGetIfInfo().

## gIF_NAME

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

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

Referenced by UpnpGetIfInfo().

## GlobalClientSubscribeMutex

ithread_mutex_t GlobalClientSubscribeMutex

Mutex to synchronize the subscription handling at the client side.

Referenced by UpnpFinish(), and UpnpInitMutexes().

## GlobalHndRWLock

ithread_rwlock_t GlobalHndRWLock

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

Referenced by UpnpFinish(), and UpnpInitMutexes().

## gMiniServerThreadPool

ThreadPool gMiniServerThreadPool

Mini server thread pool.

Referenced by StartMiniServer(), UpnpFinish(), and UpnpInitThreadPools().

## gRecvThreadPool

ThreadPool gRecvThreadPool

Receive thread pool.

Referenced by readFromSSDPSocket(), ssdp_handle_ctrlpt_msg(), UpnpFinish(), and UpnpInitThreadPools().

## gSDKInitMutex

ithread_mutex_t gSDKInitMutex = PTHREAD_MUTEX_INITIALIZER

Initialization mutex.

Referenced by UpnpInit2().

## gSendThreadPool

ThreadPool gSendThreadPool

Send thread pool.

Referenced by genaNotifyThread(), UpnpFinish(), UpnpGetServiceVarStatusAsync(), UpnpInitPreamble(), UpnpInitThreadPools(), UpnpRenewSubscriptionAsync(), UpnpSendActionAsync(), UpnpSendActionExAsync(), UpnpSubscribeAsync(), and UpnpUnSubscribeAsync().

## gTimerThread

TimerThread gTimerThread

Global timer thread.

Referenced by free_client_subscription(), genaRenewSubscription(), ScheduleGenaAutoRenew(), SearchByTarget(), ssdp_handle_device_request(), UpnpFinish(), UpnpInitPreamble(), and UpnpSendAdvertisementLowPower().

## gUUIDMutex

ithread_mutex_t gUUIDMutex

Mutex to synchronize the uuid creation process.

Referenced by UpnpFinish(), and UpnpInitMutexes().

## gWebCallback_HostValidate

WebCallback_HostValidate gWebCallback_HostValidate = 0

webCallback for HOST validation.

## gWebCallback_HostValidateCookie

void* gWebCallback_HostValidateCookie = 0

Cookie to the webCallback for HOST validation.

## gWebserverCorsString

membuffer gWebserverCorsString

extern

a string which is set in the header field

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

Referenced by process_request(), UpnpInitStartServers(), web_server_destroy(), web_server_init(), and web_server_set_cors().

## HandleTable

void* HandleTable[NUM_HANDLE]

static

UPnP device and control point handle table

Referenced by FreeHandle(), GetCallBackFn(), GetFreeHandle(), GetHandleInfo(), PrintHandleInfo(), UpnpInitPreamble(), UpnpRegisterClient(), UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), and UpnpRegisterRootDevice4().

## LOCAL_PORT_V4

unsigned short LOCAL_PORT_V4

local IPv4 port for the mini-server

Referenced by gena_subscribe(), UpnpGetServerPort(), and UpnpInitStartServers().

## LOCAL_PORT_V6

unsigned short LOCAL_PORT_V6

IPv6 LLA port for the mini-server

Referenced by gena_subscribe(), UpnpGetServerPort6(), and UpnpInitStartServers().

## LOCAL_PORT_V6_ULA_GUA

unsigned short LOCAL_PORT_V6_ULA_GUA

IPv6 ULA or GUA port for the mini-server

Referenced by gena_subscribe(), UpnpGetServerUlaGuaPort6(), and UpnpInitStartServers().

## pVirtualDirList

virtualDirList* pVirtualDirList

Pointer to the virtual directory list.

Referenced by isFileInVirtualDir(), UpnpAddVirtualDir(), UpnpRemoveAllVirtualDirs(), UpnpRemoveVirtualDir(), and web_server_init().

## UpnpSdkClientRegistered

int UpnpSdkClientRegistered = 0

Global variable to denote the state of Upnp SDK client registration. == 0 if unregistered, >= 1 if registered - registered clients count.

Referenced by UpnpRegisterClient(), and UpnpUnRegisterClient().

## UpnpSdkDeviceRegisteredV4

int UpnpSdkDeviceRegisteredV4 = 0

Global variable to denote the state of Upnp SDK IPv4 device registration. == 0 if unregistered, == 1 if registered.

Referenced by GetDeviceHandleInfo(), GetDeviceHandleInfoForPath(), UpnpRegisterClient(), UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice4(), and UpnpUnRegisterRootDeviceLowPower().

## UpnpSdkDeviceregisteredV6

int UpnpSdkDeviceregisteredV6 = 0

Global variable to denote the state of Upnp SDK IPv6 device registration. == 0 if unregistered, == 1 if registered.

Referenced by GetDeviceHandleInfo(), GetDeviceHandleInfoForPath(), UpnpRegisterClient(), UpnpRegisterRootDevice4(), and UpnpUnRegisterRootDeviceLowPower().

## UpnpSdkInit

int UpnpSdkInit = 0

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

Referenced by UpnpAcceptSubscription(), UpnpAcceptSubscriptionExt(), UpnpAddVirtualDir(), UpnpEnableWebserver(), UpnpFinish(), UpnpGetServerIp6Address(), UpnpGetServerIpAddress(), UpnpGetServerPort(), UpnpGetServerPort6(), UpnpGetServerUlaGuaIp6Address(), UpnpGetServerUlaGuaPort6(), UpnpGetServiceVarStatus(), UpnpGetServiceVarStatusAsync(), UpnpInit2(), UpnpInitThreadPools(), UpnpIsWebserverEnabled(), UpnpNotify(), UpnpNotifyExt(), UpnpRegisterClient(), UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice4(), UpnpRemoveAllVirtualDirs(), UpnpRemoveVirtualDir(), UpnpRenewSubscription(), UpnpRenewSubscriptionAsync(), UpnpSearchAsync(), UpnpSendAction(), UpnpSendActionAsync(), UpnpSendActionEx(), UpnpSendActionExAsync(), UpnpSendAdvertisementLowPower(), UpnpSetContentLength(), UpnpSetMaxContentLength(), UpnpSetMaxSubscriptions(), UpnpSetMaxSubscriptionTimeOut(), UpnpSubscribe(), UpnpSubscribeAsync(), UpnpUnRegisterClient(), UpnpUnRegisterRootDeviceLowPower(), UpnpUnSubscribe(), and UpnpUnSubscribeAsync().

## virtualDirCallback

struct VirtualDirCallbacks virtualDirCallback

This structure is for virtual directory callbacks

Referenced by http_RecvPostMessage(), http_SendMessage(), process_request(), UpnpVirtualDir_set_CloseCallback(), UpnpVirtualDir_set_GetInfoCallback(), UpnpVirtualDir_set_OpenCallback(), UpnpVirtualDir_set_ReadCallback(), UpnpVirtualDir_set_SeekCallback(), UpnpVirtualDir_set_WriteCallback(), and web_server_init().