upnp.h File Reference
UPnP API
`#include "UpnpGlobal.h"`
`#include "UpnpInet.h"`
`#include "ixml.h"`
`#include "upnpconfig.h"`
`#include "UpnpActionComplete.h"`
`#include "UpnpActionRequest.h"`
`#include "UpnpDiscovery.h"`
`#include "UpnpEvent.h"`
`#include "UpnpEventSubscribe.h"`
`#include "UpnpFileInfo.h"`
`#include "UpnpStateVarComplete.h"`
`#include "UpnpStateVarRequest.h"`
`#include "UpnpSubscriptionRequest.h"`
`#include "Callback.h"`
Include dependency graph for upnp.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

## Functions

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, char **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.

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