libUPnP 1.14.19
Macros
upnp.h File Reference
#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, 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.
 

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