libnpupnp  4.1.0
An almost compatible successor for the Portable UPnP reference library
Classes | Macros
upnp.h File Reference

main libnpupnp API definitions More...

#include <string>
#include <vector>
#include <unordered_map>
#include <map>
#include "upnpconfig.h"
#include "UpnpInet.h"
#include "UpnpGlobal.h"

Go to the source code of this file.

Classes

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

Macros

#define LINE_SIZE   size_t(180)
 
#define NAME_SIZE   size_t(256)
 
#define UPNP_INFINITE   -1
 
#define UPNP_USING_CHUNKED   -3
 
#define UPNP_UNTIL_CLOSE   -4
 

Functions

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

Error codes

The functions in the SDK API can return a variety of error codes to describe problems encountered during execution. This section lists the error codes and provides a brief description of what each error code means. Refer to the documentation for each function for a description of what an error code means in that context.

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

Device interface: Web Server API

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

Detailed Description

main libnpupnp API definitions

Macro Definition Documentation

◆ LINE_SIZE

#define LINE_SIZE   size_t(180)

Array size for some fixed sized character arrays in API structures

◆ NAME_SIZE

#define NAME_SIZE   size_t(256)

Array size for some fixed sized character arrays in API structures

◆ UPNP_E_ALREADY_REGISTERED

#define UPNP_E_ALREADY_REGISTERED   -120

A client or a device is already registered.

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

◆ UPNP_E_BAD_HTTPMSG

#define UPNP_E_BAD_HTTPMSG   -119

The HTTP message contains invalid message headers.

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

◆ UPNP_E_NETWORK_ERROR

#define UPNP_E_NETWORK_ERROR   -200

A network error occurred.

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

◆ UPNP_E_OUTOF_SOCKET

#define UPNP_E_OUTOF_SOCKET   -205

The SDK cannot create any more sockets.

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

◆ UPNP_E_SOCKET_BIND

#define UPNP_E_SOCKET_BIND   -203

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

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

◆ UPNP_E_SOCKET_CONNECT

#define UPNP_E_SOCKET_CONNECT   -204

The SDK had a problem connecting to a remote host.

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

◆ UPNP_E_SOCKET_ERROR

#define UPNP_E_SOCKET_ERROR   -208

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

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

◆ UPNP_E_SOCKET_READ

#define UPNP_E_SOCKET_READ   -202

An error happened while reading from a socket.

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

◆ UPNP_E_SOCKET_WRITE

#define UPNP_E_SOCKET_WRITE   -201

An error happened while writing to a socket.

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

◆ UPNP_E_TIMEDOUT

#define UPNP_E_TIMEDOUT   -207

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

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

◆ UPNP_INFINITE

#define UPNP_INFINITE   -1

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

◆ UPNP_UNTIL_CLOSE

#define UPNP_UNTIL_CLOSE   -4

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

◆ UPNP_USING_CHUNKED

#define UPNP_USING_CHUNKED   -3

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

Typedef Documentation

◆ Upnp_EventType

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

◆ Upnp_FunPtr

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

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

Parameters
EventTypetype of the event that triggered the callback.
Eventpointer to an event type-dependant structure storing the relevant event information.
Cookiethe user data set when the callback was registered.

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

◆ UpnpClient_Handle

typedef int UpnpClient_Handle

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

◆ UpnpDevice_Handle

typedef int UpnpDevice_Handle

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

◆ UpnpWebFileHandle

typedef void* UpnpWebFileHandle

Handle returned by the VDCallback_Open virtual directory function.

Enumeration Type Documentation

◆ Upnp_DescType_e

Specifies the type of description passed to UpnpRegisterRootDevice2.

Enumerator
UPNPREG_URL_DESC 

The description is the URL to the description document.

UPNPREG_FILENAME_DESC 

The description is a file name on the local file system containing the description of the device.

UPNPREG_BUF_DESC 

The description is a pointer to a character array containing the XML description document.

◆ Upnp_EventType_e

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

Enumerator
UPNP_CONTROL_ACTION_REQUEST 

Received by a device when a control point issues a control request. The Event parameter contains a pointer to an Upnp_Action_Request structure

UPNP_CONTROL_ACTION_COMPLETE 

Not used.

UPNP_CONTROL_GET_VAR_REQUEST 

Not used.

UPNP_CONTROL_GET_VAR_COMPLETE 

Not used.

UPNP_DISCOVERY_ADVERTISEMENT_ALIVE 

Received by a control point when a new device or service is available.
The Event parameter contains a pointer to an Upnp_Discovery structure with the information about the device or service.

UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE 

Received by a control point when a device or service shuts down. The Event parameter contains a pointer to an Upnp_Discovery structure containing the information about the device or service.

UPNP_DISCOVERY_SEARCH_RESULT 

Received by a control point when a matching device or service responds. The Event parameter contains a pointer to an Upnp_Discovery structure containing the information about the reply to the search request.

UPNP_DISCOVERY_SEARCH_TIMEOUT 

Received by a control point when the search timeout expires. The SDK generates no more callbacks for this search after this event. The Event parameter is NULL.

UPNP_EVENT_SUBSCRIPTION_REQUEST 

Received by a device when a subscription request arrives. The Event parameter contains a pointer to an Upnp_Subscription_Request structure. The device code needs to call UpnpAcceptSubscription to confirm the subscription and transmit the initial state table. This can be done during this callback.

UPNP_EVENT_RECEIVED 

Received by a control point when an event arrives. The Event parameter contains an Upnp_Event structure with the information about the event.

UPNP_EVENT_RENEWAL_COMPLETE 

Not used.

UPNP_EVENT_SUBSCRIBE_COMPLETE 

Not used.

UPNP_EVENT_UNSUBSCRIBE_COMPLETE 

Not used.

UPNP_EVENT_AUTORENEWAL_FAILED 

The auto-renewal of a client subscription failed.
The Event parameter is an Upnp_Event_Subscribe structure with the error code set appropriately. The subscription is no longer valid.

UPNP_EVENT_SUBSCRIPTION_EXPIRED 

A client subscription has expired. This will only occur if auto-renewal of subscriptions is disabled. The Event parameter is an Upnp_Event_Subscribe structure. The subscription is no longer valid.

◆ Upnp_InitFlag

Option values for the UpnpInitWithOptions flags argument

Enumerator
UPNP_FLAG_IPV6 

Accept IPV4+IPV6 operation, run with IPV4 only if IPV6 not available

UPNP_FLAG_IPV6_REQUIRED 

Same but fail if IPV6 is not available.

UPNP_FLAG_NO_HOST_VALIDATE 

Do not validate HOST headers (preserve compatibility with old versions)

UPNP_FLAG_REJECT_HOSTNAMES 

Reject Web requests with a host name (non-numeric) value in the HOST header, instead of redirecting them.

◆ Upnp_InitOption

Values for the UpnpInitWithOptions vararg options list

Enumerator
UPNP_OPTION_END 

Terminate the VARARGs list.

UPNP_OPTION_NETWORK_WAIT 

Max wait seconds for an IP address to be found, int arg follows.

Function Documentation

◆ UpnpAcceptSubscription()

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

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

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

This function is synchronous and generates no callbacks.

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
  • UPNP_E_INVALID_SERVICE: The DevId/ServId pair refers to an invalid service.
  • UPNP_E_INVALID_SID: The specified subscription ID is not valid.
  • UPNP_E_INVALID_PARAM: Either VarName, NewVal, DevID, or ServID is not a valid pointer or cVariables is less than zero.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters
[in]Hnd[in] The handle of the device.
[in]DevID[in] The device ID of the service device .
[in]ServName[in] The unique service identifier of the service generating the event.
[in]VarName[in] Pointer to an array of event variables.
[in]NewVal[in] Pointer to an array of values for the event variables.
[in]cVariables[in] The number of event variables in VarName.
[in]SubsId[in] The subscription ID of the newly registered control point.

◆ UpnpAcceptSubscriptionXML()

EXPORT_SPEC int UpnpAcceptSubscriptionXML ( UpnpDevice_Handle  Hnd,
const char *  DevID,
const char *  ServName,
const std::string &  propertyset,
const Upnp_SID SubsId 
)
Parameters
[in]Hnd[in] The handle of the device.
[in]DevID[in] The device ID of the service device .
[in]ServName[in] The unique service identifier of the service generating the event.
[in]propertyset[in] Initial property set (all state variables) as XML string.
[in]SubsId[in] The subscription ID of the newly registered control point.

◆ UpnpAddVirtualDir()

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

Adds a virtual directory mapping.

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

Note
This function is not available when the web server is not compiled into the UPnP Library.
Parameters
dirNameThe name of the new directory mapping to add.
cookiea value which will be set in callbacks related to this directory.
[out]oldcookieIf not null and the virtual directory previously existed, returns the old cookie value.
Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: dirName is not valid.

◆ UpnpClientSetProduct()

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

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

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

◆ UpnpDeviceSetProduct()

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

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
  • UPNP_E_INVALID_PARAM: null or empty product or version.
Parameters
[in]Hnd[in] The handle of the control point instance to unregister.
[in]product[in] The product name, e.g. "MyAwsomeProduct"
[in]version[in] The product version, e.g: "1.1"

◆ UpnpDownloadUrlItem() [1/2]

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

Downloads a text file specified in a URL.

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either url, outBuf or contentType is not a valid pointer.
  • UPNP_E_INVALID_URL: The url is not a valid URL.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
Parameters
[in]url[in] URL of an item to download.
[out]outBuf[out] Buffer to store the downloaded item. Caller must free. Guaranteed zero-terminated on success
[out]contentType[out] HTTP header value content type if present. It should be at least LINE_SIZE bytes in size.

◆ UpnpDownloadUrlItem() [2/2]

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

Downloads a file specified in a URL.

Simplified interface using std::string

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

◆ UpnpEnableWebserver()

EXPORT_SPEC int UpnpEnableWebserver ( int  enable)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: enable is not valid.
Parameters
[in]enable[in] TRUE to enable, FALSE to disable.

◆ UpnpFinish()

EXPORT_SPEC int UpnpFinish ( void  )

Terminate and clean up the library.

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

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

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

◆ UpnpGetServerIpAddress()

const EXPORT_SPEC char* UpnpGetServerIpAddress ( void  )

Returns a local IPv4 listening ip address.

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

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

◆ UpnpGetServerPort()

EXPORT_SPEC unsigned short UpnpGetServerPort ( void  )

Returns the internal server IPv4 UPnP listening port.

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

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

◆ UpnpGetUrlHostPortForClient()

EXPORT_SPEC std::string UpnpGetUrlHostPortForClient ( const struct sockaddr_storage *  )

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

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

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

◆ UpnpInit()

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

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

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

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

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

This call is synchronous.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
  • UPNP_E_INIT: The SDK is already initialized.
  • UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_LISTEN: An error occurred listening to a socket.
  • UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
  • UPNP_E_INTERNAL_ERROR: An internal error ocurred.
Parameters
HostIPThe host local IPv4 address to use, in dotted string format, or empty or NULL to use the first IPv4 adapter's IP address.
DestPortLocal Port to listen for incoming connections 0 will pick the first free port at or above the configured default (49152).

◆ UpnpInit2() [1/2]

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

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

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

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

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

This call is synchronous.

Parameters
ifNameThe interface name(s) to use by the UPnP SDK operations, as a space-separated list. Use double quotes or backslashes escapes if there are space characters inside the interface name. Use a single "*" character to use all available interfaces. NULL or empty to use the first suitable interface.
DestPortlocal port to listen on for incoming connections. 0 will pick the first free port at or above the configured default.
Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
  • UPNP_E_INIT: The SDK is already initialized.
  • UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_LISTEN: An error occurred listening to a socket.
  • UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
  • UPNP_E_INTERNAL_ERROR: An internal error ocurred.
  • UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.

◆ UpnpInit2() [2/2]

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

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

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

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

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

This call is synchronous.

Parameters
ifnamesThe interface name(s) as a as a vector of strings, to avoid any quoting headaches. Leave empty for using the first found interface. Set a single "*" element for using all interfaces.
DestPortlocal port to listen on for incoming connections. 0 will pick the first free port at or above the configured default.
Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
  • UPNP_E_INIT: The SDK is already initialized.
  • UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_LISTEN: An error occurred listening to a socket.
  • UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
  • UPNP_E_INTERNAL_ERROR: An internal error ocurred.
  • UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.

◆ UpnpInitWithOptions()

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

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

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

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

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

This call is synchronous.

Parameters
ifnamesThe interface name(s) to use by the UPnP SDK operations, as a quoted space-separated list. Use double quotes or backslashes escapes if there are space characters inside the interface name. Use a single "*" character to use all available interfaces. NULL or empty to use the first suitable interface.
DestPortlocal port to listen on for incoming connections. 0 will pick the first free port at or above the configured default.
flagsA bitfield of Upnp_InitFlag values.
...Variable list of Upnp_InitOption options and arguments, terminated by UPNP_OPTION_END.
Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
  • UPNP_E_INIT: The SDK is already initialized.
  • UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_LISTEN: An error occurred listening to a socket.
  • UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
  • UPNP_E_INTERNAL_ERROR: An internal error ocurred.
  • UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.
Parameters
flagsBitmask of Upnp_InitFlag values

◆ UpnpIsWebserverEnabled()

EXPORT_SPEC int UpnpIsWebserverEnabled ( void  )

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

Returns
An integer representing one of the following:
  • TRUE: The webserver is enabled.
  • FALSE: The webserver is not enabled

◆ UpnpNotify()

EXPORT_SPEC int UpnpNotify ( UpnpDevice_Handle  ,
const char *  DevID,
const char *  ServName,
const char **  VarName,
const char **  NewVal,
int  cVariables 
)

Sends out an event change notification to all control points subscribed to a particular service.

This function is synchronous and generates no callbacks.

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
  • UPNP_E_INVALID_SERVICE: The DevId/ServId pair refers to an invalid service.
  • UPNP_E_INVALID_PARAM: Either VarName, NewVal, DevID, or ServID is not a valid pointer or cVariables is less than zero.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters
[in]DevID[in] The device ID of the subdevice of the service generating the event.
[in]ServName[in] The unique identifier of the service generating the event.
[in]VarName[in] Pointer to an array of variables that have changed.
[in]NewVal[in] Pointer to an array of new values for those variables.
[in]cVariables[in] The count of variables included in this notification.

◆ UpnpNotifyXML()

EXPORT_SPEC int UpnpNotifyXML ( UpnpDevice_Handle  ,
const char *  DevID,
const char *  ServName,
const std::string &  propset 
)
Parameters
[in]DevID[in] The device ID of the device generating the event.
[in]ServName[in] The unique identifier of the service generating the event.
[in]propset[in] Property set (changed variables) as XML string

◆ UpnpRegisterClient()

EXPORT_SPEC int UpnpRegisterClient ( Upnp_FunPtr  Fun,
const void *  Cookie,
UpnpClient_Handle Hnd 
)

Registers a control point application with the UPnP Library.

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

UpnpRegisterClient is a synchronous call and generates no callbacks. Callbacks can occur as soon as this function returns.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to register this control point.
Parameters
[in]Fun[in] Callback function.
[in]Cookie[in] Pointer to be passed as parameter to the callback invocations.
[out]Hnd[out] Pointer to a variable to store the new control point handle.

◆ UpnpRegisterRootDevice()

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

Registers a device application with the UPnP Library.

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

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

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_DESC: The description document was not a valid device description.
  • UPNP_E_INVALID_URL: The URL for the description document is not valid.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
Parameters
[in]DescUrl[in] Pointer to a string containing the description URL for this root device instance.
[in]Fun[in] Callback function.
[in]Cookie[in] Pointer to be passed as parameter to the callback invocations.
[out]Hnd[out] Pointer to a variable to store the new device handle.

◆ UpnpRegisterRootDevice2()

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

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

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

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_DESC: The description document is not a valid device description.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
  • UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the internal buffer.
  • UPNP_E_FILE_NOT_FOUND: The description file could not be found.
  • UPNP_E_FILE_READ_ERROR: An error occurred reading the description file.
  • UPNP_E_INVALID_URL: The URL to the description document is invalid.
  • UPNP_E_EXT_NOT_XML: The URL to the description document or file should have a .xml extension.
  • UPNP_E_NO_WEB_SERVER: The internal web server has been compiled out; the SDK cannot configure itself from the description document.
Parameters
[in]descriptionType[in] The type of the description document.
[in]description[in] Treated as a URL, file name or memory buffer depending on description type.
[in]bufferLen[in] The length of memory buffer if passing a description in a buffer, otherwise it is ignored.
ignoredIgnored
[in]Fun[in] Callback function
[in]Cookie[in] Pointer to be passed as parameter to the callback invocations.
[out]Hnd[out] Pointer to a variable to store the new device handle.

◆ UpnpRegisterRootDevice4()

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

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

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

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_DESC: The description document was not a valid device description.
  • UPNP_E_INVALID_URL: The URL for the description document is not valid.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
Parameters
[in]DescUrl[in] Pointer to a string containing the description URL for this root device instance.
[in]Fun[in] Callback function.
[in]Cookie[in] Pointer to be passed as parameter to the callback invocations.
[out]Hnd[out] Pointer to a variable to store the new device handle.
[in]LowerDescUrl[in] Pointer to a string containing the description URL to be returned for legacy CPs for this root device instance.

◆ UpnpRemoveVirtualDir()

EXPORT_SPEC int UpnpRemoveVirtualDir ( const char *  dirName)

Removes a virtual directory mapping made with UpnpAddVirtualDir.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: dirName is not valid.
Parameters
[in]dirName[in] The name of the virtual directory mapping to remove.

◆ UpnpRenewSubscription()

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

Renews a subscription that is about to expire.

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_PARAM: Timeout is not a valid pointer.
  • UPNP_E_INVALID_SID: The SID being passed to this function is not a valid subscription ID.
  • UPNP_E_NETWORK_ERROR: A network error occured.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl.
  • UPNP_E_OUTOF_SOCKET: An error occurred creating a socket.
  • UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher.
  • UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription renew.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters
[in]Hnd[in] The handle of the control point that is renewing the subscription.
[in,out]TimeOut[in,out] Pointer to a variable containing the requested subscription time. Upon return, it contains the actual renewal time.
[in]SubsId[in] The ID for the subscription to renew.

◆ UpnpSearchAsync()

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

Searches for devices matching the given search target.

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

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_PARAM: Target is NULL.
Parameters
HndThe handle of the client performing the search.
MxThe 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.
TargetThe search target as defined in the UPnP Device Architecture v1.0 specification.
cookieThe user data to pass when the callback function is invoked.

◆ UpnpSendAction()

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

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

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

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • Negative values are UPNP_E_... UPnP library errors (system error)
  • Positive values are UPnP action error codes (the dialog completed successfully, but we received an error response from the device).
Parameters
Hndclient handle
headerStringSOAP header. This may be empty if no header header is not required. e.g. <soapns:Header>xxx</soapns:Header>
actionURLthe service action url from the device description document.
serviceTypethe service type from the device description document
actionNamethe action to perform (from the service description)
actionParamsthe action name/value argument pairs, in order.
[out]responseDatathe return values
[out]errorCodeppointer to an integer to store the UPNP error code if we got an error response document. Same as the return value if set.
[out]errorDescrA place to store an error description (if we got an error response document).

◆ UpnpSendAdvertisement()

EXPORT_SPEC int UpnpSendAdvertisement ( UpnpDevice_Handle  Hnd,
int  Exp 
)

Sends out the discovery announcements for all devices and services for a device.

Each announcement is made with the same expiration time.

This is a synchronous call.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.
Parameters
HndThe device handle for which to send out the announcements.
ExpThe expiration age, in seconds, of the announcements. If the expiration age is less than 1 then the expiration age is set to DEFAULT_MAXAGE. If the expiration age is less than or equal to AUTO_ADVERTISEMENT_TIME * 2 then the expiration age is set to ( AUTO_ADVERTISEMENT_TIME + 1 ) * 2.

◆ UpnpSendAdvertisementLowPower()

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

Sends out the discovery announcements for all devices and services for a device.

Each announcement is made with the same expiration time.

This is a synchronous call.

This function allow a device to specify the SSDP extensions defined by UPnP Low Power.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.
Parameters
HndThe device handle for which to send out the announcements.
ExpThe 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.
PowerStatePowerState as defined by UPnP Low Power.
SleepPeriodSleepPeriod as defined by UPnP Low Power.
RegistrationStateRegistrationState as defined by UPnP Low Power.

◆ UpnpSetHostValidateCallback()

EXPORT_SPEC int UpnpSetHostValidateCallback ( WebCallback_HostValidate  callback,
void *  cookie 
)

UpnpSetHostValidateCallback alias for compatibility with libupnp

◆ UpnpSetMaxContentLength()

EXPORT_SPEC int UpnpSetMaxContentLength ( size_t  contentLength)

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

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

If set to 0 then checking will be disabled.

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

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

◆ UpnpSetMaxSubscriptions()

EXPORT_SPEC int UpnpSetMaxSubscriptions ( UpnpDevice_Handle  Hnd,
int  MaxSubscriptions 
)

Sets the maximum number of subscriptions accepted per service.

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
Parameters
HndThe handle of the device for which the maximum number of subscriptions is being set.
MaxSubscriptionsThe maximum number of subscriptions to be allowed per service.

◆ UpnpSetMaxSubscriptionTimeOut()

EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut ( UpnpDevice_Handle  Hnd,
int  MaxSubscriptionTimeOut 
)

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

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
HndThe handle of the device for which the maximum subscription time-out is being set.
MaxSubscriptionTimeOutThe maximum subscription time-out to be accepted.

◆ UpnpSetVirtualDirCallbacks()

EXPORT_SPEC int UpnpSetVirtualDirCallbacks ( struct UpnpVirtualDirCallbacks callbacks)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: one of the callbacks is not valid.
Parameters
[in]callbacks[in] A structure that contains the callback functions.

◆ UpnpSetWebServerRootDir()

EXPORT_SPEC int UpnpSetWebServerRootDir ( const char *  rootDir)

Sets the document root directory for the internal WEB server.

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: rootDir is an invalid directory.
Parameters
[in]rootDir[in] Path of the root directory of the web server.

◆ UpnpSubscribe()

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

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

This operation is synchronous.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: PublisherUrl is not a valid URL.
  • UPNP_E_INVALID_PARAM: Timeout is not a valid pointer or SubsId or PublisherUrl is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occured.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl.
  • UPNP_E_OUTOF_SOCKET: An error occurred creating a socket.
  • UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher.
  • UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription request.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters
[in]Hnd[in] The handle of the control point.
[in]EvtUrl[in] The URL of the service to subscribe to.
[in,out]TimeOut[in,out]Pointer to a variable containing the requested subscription time. Upon return, it contains the actual subscription time returned from the service.
[out]SubsId[out] Pointer to a variable to receive the subscription ID (SID).

◆ UpnpUnRegisterClient()

EXPORT_SPEC int UpnpUnRegisterClient ( UpnpClient_Handle  Hnd)

Unregisters a control point application, unsubscribing all active subscriptions.

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

UpnpUnRegisterClient is a synchronous call and generates no callbacks.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
Parameters
[in]Hnd[in] The handle of the control point instance to unregister.

◆ UpnpUnRegisterRootDevice()

EXPORT_SPEC int UpnpUnRegisterRootDevice ( UpnpDevice_Handle  Hnd)

Unregisters a root device.

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

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
Parameters
[in]Hnd[in] The handle of the root device instance to unregister.

◆ UpnpUnRegisterRootDeviceLowPower()

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

Unregisters a root device.

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

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

This function allow a device to specify the SSDP extensions defined by UPnP Low Power.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
Parameters
[in]Hnd[in] The handle of the root device instance to unregister.
PowerStatePowerState as defined by UPnP Low Power.
SleepPeriodSleepPeriod as defined by UPnP Low Power.
RegistrationStateRegistrationState as defined by UPnP Low Power.

◆ UpnpUnSubscribe()

EXPORT_SPEC int UpnpUnSubscribe ( UpnpClient_Handle  Hnd,
const Upnp_SID SubsId 
)

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

This is a synchronous call.

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_SID: The SubsId is not a valid subscription ID.
  • UPNP_E_NETWORK_ERROR: A network error occured.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl.
  • UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
  • UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher.
  • UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused the unsubscribe request (the client is still unsubscribed and no longer receives events).
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters
[in]Hnd[in] The handle of the subscribed control point.
[in]SubsId[in] The ID returned when the control point subscribed to the service.

◆ UpnpVirtualDir_set_CloseCallback()

EXPORT_SPEC int UpnpVirtualDir_set_CloseCallback ( VDCallback_Close  callback)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

◆ UpnpVirtualDir_set_GetInfoCallback()

EXPORT_SPEC int UpnpVirtualDir_set_GetInfoCallback ( VDCallback_GetInfo  callback)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

◆ UpnpVirtualDir_set_OpenCallback()

EXPORT_SPEC int UpnpVirtualDir_set_OpenCallback ( VDCallback_Open  callback)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

◆ UpnpVirtualDir_set_ReadCallback()

EXPORT_SPEC int UpnpVirtualDir_set_ReadCallback ( VDCallback_Read  callback)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

◆ UpnpVirtualDir_set_SeekCallback()

EXPORT_SPEC int UpnpVirtualDir_set_SeekCallback ( VDCallback_Seek  callback)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.

◆ UpnpVirtualDir_set_WriteCallback()

EXPORT_SPEC int UpnpVirtualDir_set_WriteCallback ( VDCallback_Write  callback)

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

Returns
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: callback is not a valid pointer.