libUPnP  1.6.17
Data Structures | Files | Defines | Functions | Variables
UPnP API

Data Structures

struct  Upnp_Action_Request
struct  Upnp_Action_Complete
struct  Upnp_State_Var_Request
struct  Upnp_State_Var_Complete
struct  Upnp_Event
struct  Upnp_Discovery
struct  Upnp_Event_Subscribe
struct  Upnp_Subscription_Request
struct  File_Info
struct  UpnpVirtualDirCallbacks
 The { UpnpVirtualDirCallbacks} structure contains the pointers to file-related callback functions a device application can register to virtualize URLs. More...

Files

file  upnp.h
file  upnpapi.c

Defines

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

Functions

static int WinsockInit (void)
 (Windows Only) Initializes the Windows Winsock library.
static int UpnpInitMutexes (void)
 Initializes the global mutexes used by the UPnP SDK.
static int UpnpInitThreadPools (void)
 Initializes the global threadm pools used by the UPnP SDK.
static int UpnpInitPreamble (void)
 Performs the initial steps in initializing the UPnP SDK.
static int UpnpInitStartServers (unsigned short DestPort)
 Finishes initializing the UPnP SDK.
void PrintThreadPoolStats (ThreadPool *tp, const char *DbgFileName, int DbgLineNo, const char *msg)
 Prints thread pool statistics.
char * UpnpGetServerIp6Address (void)
char * UpnpGetServerUlaGuaIp6Address (void)
static int GetFreeHandle ()
 Get a free handle.
static int FreeHandle (int Upnp_Handle)
 Free handle.
static int GetDescDocumentAndURL (Upnp_DescType descriptionType, char *description, int config_baseURL, int AddressFamily, IXML_Document **xmlDoc, char descURL[LINE_SIZE])
 Fills the sockadr_in with miniserver information.
static void Param_delete (struct UpnpNonblockParam *Param)
 De-allocate a UpnpNonblockParam and its fields.
int UpnpGetIfInfo (const char *IfName)
 Retrieve interface information and keep it in global variables. If NULL, we'll find the first suitable interface for operation.
void UpnpThreadDistribution (struct UpnpNonblockParam *Param)
 Schedule async functions in threadpool.
Upnp_FunPtr GetCallBackFn (UpnpClient_Handle Hnd)
 Get callback function ptr from a handle.
Upnp_Handle_Type GetClientHandleInfo (UpnpClient_Handle *client_handle_out, struct Handle_Info **HndInfo)
 Get client handle info.
Upnp_Handle_Type GetDeviceHandleInfo (int AddressFamily, UpnpDevice_Handle *device_handle_out, struct Handle_Info **HndInfo)
 Retrieves the device handle and information of the first device of the address family spcified.
Upnp_Handle_Type GetHandleInfo (UpnpClient_Handle Hnd, struct Handle_Info **HndInfo)
 Get handle information.
int PrintHandleInfo (UpnpClient_Handle Hnd)
 Print handle info.
int getlocalhostname (char *out, size_t out_len)
 Get local IP address.
void AutoAdvertise (void *input)
 This function is a timer thread scheduled by UpnpSendAdvertisement to the send advetisement again.

Variables

struct VirtualDirCallbacks virtualDirCallback
virtualDirListpVirtualDirList
ithread_mutex_t GlobalClientSubscribeMutex
ithread_rwlock_t GlobalHndRWLock
ithread_mutex_t gUUIDMutex
ithread_mutex_t gSDKInitMutex = PTHREAD_MUTEX_INITIALIZER
TimerThread gTimerThread
ThreadPool gSendThreadPool
ThreadPool gRecvThreadPool
ThreadPool gMiniServerThreadPool
WebServerState bWebServerState = WEB_SERVER_DISABLED
char gIF_NAME [LINE_SIZE] = { '\0' }
char gIF_IPV4 [INET_ADDRSTRLEN] = { '\0' }
char gIF_IPV6 [INET6_ADDRSTRLEN] = { '\0' }
char gIF_IPV6_ULA_GUA [INET6_ADDRSTRLEN] = { '\0' }
unsigned gIF_INDEX = (unsigned)-1
unsigned short LOCAL_PORT_V4
unsigned short LOCAL_PORT_V6
static void * HandleTable [200]
membuffer gDocumentRootDir
size_t g_maxContentLength = DEFAULT_SOAP_CONTENT_LENGTH
int UpnpSdkInit = 0
int UpnpSdkClientRegistered = 0
int UpnpSdkDeviceRegisteredV4 = 0
int UpnpSdkDeviceregisteredV6 = 0

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
 UpnpInit has not been called, or UpnpFinish has already been called.
#define UPNP_E_INIT_FAILED   -117
 UpnpInit 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

Constants and Types

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
}
 The reason code for an event callback. More...
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 enum Upnp_EventType_e Upnp_EventType
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
typedef int(* Upnp_FunPtr )(Upnp_EventType EventType, void *Event, void *Cookie)

Initialization and Registration

int UpnpInit (const char *HostIP, unsigned short DestPort)
 Initializes the Linux SDK for UPnP Devices (IPv4 only).
int UpnpFinish (void)
 Initializes the Linux SDK for UPnP Devices (IPv4 or IPv6).
unsigned short UpnpGetServerPort (void)
 Returns the internal server IPv4 UPnP listening port.
char * UpnpGetServerIpAddress (void)
 Returns the internal server IPv6 UPnP listening port.
int UpnpRegisterRootDevice (const char *DescUrl, Upnp_FunPtr Callback, const void *Cookie, UpnpDevice_Handle *Hnd)
 Returns the local IPv6 listening ip address.
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, 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.

Control Point HTTP API

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 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, struct File_Info *info)
 Get-info callback function prototype.
typedef UpnpWebFileHandle(* VDCallback_Open )(const char *filename, enum UpnpOpenFileMode Mode)
 Open callback function prototype.
typedef int(* VDCallback_Read )(UpnpWebFileHandle fileHnd, char *buf, size_t buflen)
 Read callback function prototype.
typedef int(* VDCallback_Write )(UpnpWebFileHandle fileHnd, char *buf, size_t buflen)
 Write callback function prototype.
typedef int(* VDCallback_Seek )(UpnpWebFileHandle fileHnd, off_t offset, int origin)
 Seek callback function prototype.
typedef int(* VDCallback_Close )(UpnpWebFileHandle fileHnd)
 Close callback function prototype.
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 TRUE if the webserver is enabled, or FALSE if it is not.
int UpnpSetVirtualDirCallbacks (struct UpnpVirtualDirCallbacks *callbacks)
 Sets the callback functions to be used to access a virtual directory.
int UpnpAddVirtualDir (const char *dirName)
 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.

Define Documentation

#define IN6_IS_ADDR_GLOBAL (   a)
Value:
((((__const uint32_t *) (a))[0] & htonl((uint32_t)0x70000000)) \
                == htonl ((uint32_t)0x20000000))
#define IN6_IS_ADDR_ULA (   a)
Value:
((((__const uint32_t *) (a))[0] & htonl((uint32_t)0xfe000000)) \
                == htonl ((uint32_t)0xfc000000))
#define NUM_HANDLE   200

UPnP device and control point handle table

Referenced by FreeHandle(), GetDeviceHandleInfo(), GetFreeHandle(), GetHandleInfo(), UpnpInitPreamble(), and UpnpRegisterRootDevice4().

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

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

#define UPNP_E_BAD_HTTPMSG   -119

The HTTP message contains invalid message headers.

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

Referenced by http_RecvMessage(), and ReadResponseLineAndHeaders().

#define UPNP_E_BAD_RESPONSE   -113

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

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

Referenced by gena_subscribe(), and http_OpenHttpGetProxy().

#define UPNP_E_CANCELED   -210

The operation was canceled.

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

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

Referenced by http_SendMessage().

#define UPNP_E_FINISH   -116
#define UPNP_E_INIT   -105

The SDK has already been initialized.

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

Referenced by getlocalhostname(), UpnpGetIfInfo(), and UpnpInit().

#define UPNP_E_INIT_FAILED   -117

UpnpInit cannot complete.

The typical reason is failure to allocate sufficient resources.

Referenced by UpnpInit(), UpnpInitMutexes(), UpnpInitPreamble(), UpnpInitThreadPools(), and WinsockInit().

#define UPNP_E_INTERNAL_ERROR   -911
#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.

Referenced by check_soap_action_header(), check_soap_body(), get_device_info(), UpnpSendActionAsync(), and UpnpSendActionExAsync().

#define UPNP_E_INVALID_ARGUMENT   -501

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

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

Referenced by CreateClientRequestPacket().

#define UPNP_E_INVALID_DESC   -107

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

Referenced by addToAction(), TvDeviceStateTableInit(), UpnpDownloadXmlDoc(), UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), and UpnpRegisterRootDevice4().

#define UPNP_E_INVALID_HANDLE   -100
#define UPNP_E_INVALID_INTERFACE   -121

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

Referenced by UpnpGetIfInfo().

#define UPNP_E_INVALID_PARAM   -101
#define UPNP_E_INVALID_SERVICE   -111

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

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

Referenced by get_device_info().

#define UPNP_E_INVALID_URL   -108

An URL passed into the function is invalid.

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

Referenced by Check_Connect_And_Wait_Connection(), http_MakeMessage(), parse_hostport(), remove_dots(), UpnpDownloadUrlItem(), UpnpResolveURL(), and UpnpResolveURL2().

#define UPNP_E_LISTEN   -206

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

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

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

Referenced by create_ssdp_sock_v4(), and NewRequestHandler().

#define UPNP_E_NOT_FOUND   -507

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

#define UPNP_E_NOTIFY_UNACCEPTED   -303

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

#define UPNP_E_OUTOF_HANDLE   -102

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

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

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

#define UPNP_E_OUTOF_MEMORY   -104
#define UPNP_E_OUTOF_SOCKET   -205

The SDK cannot create any more sockets.

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

Referenced by Check_Connect_And_Wait_Connection(), create_ssdp_sock_reqv4(), create_ssdp_sock_v4(), get_miniserver_stopsock(), and NewRequestHandler().

#define UPNP_E_SOCKET_BIND   -203

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

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

Referenced by create_ssdp_sock_v4(), and get_miniserver_stopsock().

#define UPNP_E_SOCKET_CONNECT   -204

The SDK had a problem connecting to a remote host.

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

Referenced by Check_Connect_And_Wait_Connection(), http_OpenHttpGetProxy(), and notify_send_and_recv().

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

Referenced by create_ssdp_sock_v4(), http_OpenHttpGetProxy(), sock_destroy(), and sock_read_write().

#define UPNP_E_SOCKET_READ   -202

An error happened while reading from a socket.

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

#define UPNP_E_SOCKET_WRITE   -201

An error happened while writing to a socket.

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

Referenced by NewRequestHandler().

#define UPNP_E_SUBSCRIBE_UNACCEPTED   -301

A subscription request was rejected from the remote side.

Referenced by gena_subscribe().

#define UPNP_E_SUCCESS   0

The operation completed successfully.

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

Referenced by addToAction(), AdvertiseAndReply(), Check_Connect_And_Wait_Connection(), check_soap_action_header(), check_soap_body(), create_ssdp_sock_reqv4(), create_ssdp_sock_v4(), CreateClientRequestPacket(), FreeHandle(), gena_process_subscription_renewal_request(), gena_process_subscription_request(), gena_subscribe(), GenaAutoRenewSubscription(), genaNotify(), genaRenewSubscription(), genaSubscribe(), genaUnregisterClient(), genaUnregisterDevice(), get_device_info(), get_miniserver_stopsock(), get_ssdp_sockets(), GetDescDocumentAndURL(), getlocalhostname(), handle_invoke_action(), handle_query_variable(), http_OpenHttpGetProxy(), http_RecvMessage(), IncrementBrightness(), IncrementColor(), IncrementContrast(), IncrementVolume(), NewRequestHandler(), notify_send_and_recv(), PrintHandleInfo(), process_request(), remove_dots(), resolve_rel_url(), SampleUtil_FindAndParseService(), SampleUtil_Finish(), SampleUtil_Initialize(), SampleUtil_RegisterUpdateFunction(), ScheduleGenaAutoRenew(), SearchByTarget(), sock_destroy(), sock_init(), sock_init_with_ip(), ssdp_handle_ctrlpt_msg(), StartMiniServer(), TvCtrlPointStart(), TvCtrlPointVerifyTimeouts(), TvDeviceHandleActionRequest(), TvDeviceHandleGetVarRequest(), TvDevicePowerOff(), TvDevicePowerOn(), TvDeviceSetBrightness(), TvDeviceSetChannel(), TvDeviceSetColor(), TvDeviceSetTint(), TvDeviceSetVolume(), TvDeviceStart(), TvDeviceStateTableInit(), TvDeviceStop(), UpnpAddToPropertySet(), UpnpAddVirtualDir(), UpnpDownloadXmlDoc(), UpnpEnableWebserver(), UpnpFinish(), UpnpGetIfInfo(), UpnpGetServiceVarStatusAsync(), UpnpInit(), UpnpInitLog(), UpnpInitMutexes(), UpnpInitPreamble(), UpnpInitStartServers(), UpnpInitThreadPools(), UpnpRegisterClient(), UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice4(), UpnpRemoveVirtualDir(), UpnpRenewSubscriptionAsync(), UpnpResolveURL(), UpnpResolveURL2(), UpnpSearchAsync(), UpnpSendActionAsync(), UpnpSendActionExAsync(), UpnpSendAdvertisementLowPower(), UpnpSetContentLength(), UpnpSetMaxContentLength(), UpnpSetMaxSubscriptions(), UpnpSetMaxSubscriptionTimeOut(), UpnpSetVirtualDirCallbacks(), UpnpSubscribeAsync(), UpnpUnRegisterClient(), UpnpUnRegisterRootDeviceLowPower(), UpnpUnSubscribeAsync(), UpnpVirtualDir_set_CloseCallback(), UpnpVirtualDir_set_GetInfoCallback(), UpnpVirtualDir_set_OpenCallback(), UpnpVirtualDir_set_ReadCallback(), UpnpVirtualDir_set_SeekCallback(), UpnpVirtualDir_set_WriteCallback(), and WinsockInit().

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

Referenced by sock_read_write().

#define UPNP_E_UNSUBSCRIBE_UNACCEPTED   -302

An unsubscribe request was rejected from the remote side.

Referenced by gena_unsubscribe().

#define UPNP_E_URL_TOO_BIG   -118

The URL passed into a function is too long.

The SDK limits URLs to 180 characters in length.

Referenced by GetDescDocumentAndURL().


Typedef Documentation

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

All callback functions share the same prototype, documented below. Note that any memory passed to the callback function is valid only during the callback 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.

      int CallbackFxn(Upnp_EventType EventType, void *Event, void *Cookie);
    

where EventType is the event that triggered the callback, Event is a structure that denotes event-specific information for that event, and Cookie is the user data passed when the callback was registered.

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

The return value of the callback is currently ignored. It may be used in the future to communicate results back to the SDK.

typedef char Upnp_SID[44]

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

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

typedef int UpnpClient_Handle

Returned when a control point application registers with UpnpRegisterClient.

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

typedef int UpnpDevice_Handle

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

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

typedef void* UpnpWebFileHandle

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

typedef int(* VDCallback_Close)(UpnpWebFileHandle fileHnd)

Close callback function prototype.

typedef int(* VDCallback_GetInfo)(const char *filename,struct File_Info *info)

Get-info callback function prototype.

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

Open callback function prototype.

typedef int(* VDCallback_Read)(UpnpWebFileHandle fileHnd,char *buf,size_t buflen)

Read callback function prototype.

typedef int(* VDCallback_Seek)(UpnpWebFileHandle fileHnd,off_t offset,int origin)

Seek callback function prototype.

typedef int(* VDCallback_Write)(UpnpWebFileHandle fileHnd,char *buf,size_t buflen)

Write callback function prototype.


Enumeration Type Documentation

Specifies the type of description in UpnpRegisterRootDevice2.

These values control how UpnpRegisterRootDevice2 interprets the description parameter.

Enumerator:
UPNPREG_URL_DESC 

The description is the URL to the description document.

UPNPREG_FILENAME_DESC 

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

UPNPREG_BUF_DESC 

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

The reason code for an event callback.

The Event parameter will be different depending on the reason for the callback. The descriptions for each event type describe the contents of the Event parameter.

Enumerator:
UPNP_CONTROL_ACTION_REQUEST 

Received by a device when a control point issues a control request. The Event parameter contains a pointer to a UpnpActionRequest structure containing the action. The application stores the results of the action in this structure.

UPNP_CONTROL_ACTION_COMPLETE 

A UpnpSendActionAsync call completed. The Event parameter contains a pointer to a UpnpActionComplete structure with the results of the action.

UPNP_CONTROL_GET_VAR_REQUEST 

Received by a device when a query for a single service variable arrives. The Event parameter contains a pointer to a UpnpStateVarRequest structure containing the name of the variable and value.

UPNP_CONTROL_GET_VAR_COMPLETE 

A UpnpGetServiceVarStatus call completed. The Event parameter contains a pointer to a UpnpStateVarComplete structure containing the value for the variable.

UPNP_DISCOVERY_ADVERTISEMENT_ALIVE 

Received by a control point when a new device or service is available. The Event parameter contains a pointer to a UpnpDiscovery 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 a UpnpDiscovery 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 a UpnpDiscovery 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 arrives. The Event parameter contains a pointer to a UpnpSubscriptionRequest structure. At this point, the subscription has already been accepted. UpnpAcceptSubscription needs to be called to confirm the subscription and transmit the initial state table. This can be done during this callback. The SDK generates no events for a subscription unless the device application calls UpnpAcceptSubscription.

UPNP_EVENT_RECEIVED 

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

UPNP_EVENT_RENEWAL_COMPLETE 

A UpnpRenewSubscriptionAsync call completed. The status of the renewal is in the Event parameter as a Upnp_Event_Subscription structure.

UPNP_EVENT_SUBSCRIBE_COMPLETE 

A UpnpSubscribeAsync call completed. The status of the subscription is in the Event parameter as a Upnp_Event_Subscription structure.

UPNP_EVENT_UNSUBSCRIBE_COMPLETE 

A UpnpUnSubscribeAsync call completed. The status of the subscription is in the Event parameter as a UpnpEventSubscribe structure.

UPNP_EVENT_AUTORENEWAL_FAILED 

The auto-renewal of a client subscription failed. The Event parameter is a UpnpEventSubscribe 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 a UpnpEventSubscribe structure. The subscription is no longer valid.

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

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

Enumerator:
UPNP_S_ALL 

Search for all devices and services on the network.

UPNP_S_ROOT 

Search for all root devices on the network.

UPNP_S_DEVICE 

Search for a particular device type or a particular device instance.

UPNP_S_SERVICE 

Search for a particular service type, possibly on a particular device type or device instance.


Function Documentation

void AutoAdvertise ( void *  input)

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

Parameters:
[in]inputInformation provided to the thread.

References free_upnp_timeout(), and UpnpSendAdvertisement().

Referenced by UpnpSendAdvertisementLowPower().

static int FreeHandle ( int  Upnp_Handle) [static]

Free handle.

Returns:
UPNP_E_SUCCESS if successful or UPNP_E_INVALID_HANDLE if not
Parameters:
[in]Upnp_HandleHandle index.

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

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

Get callback function ptr from a handle.

Returns:
Upnp_FunPtr
Upnp_Handle_Type GetClientHandleInfo ( int *  client_handle_out,
struct Handle_Info **  HndInfo 
)

Get client handle info.

Note:
The logic around the use of this function should be revised.
Returns:
HND_CLIENT, HND_INVALID
Parameters:
[in]client_handle_outclient handle pointer (key for the client handle structure).
[out]HndInfoClient handle structure passed by this function.

References GetHandleInfo().

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

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

Fills the sockadr_in with miniserver information.

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

Referenced by UpnpRegisterRootDevice2().

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

Retrieves the device handle and information of the first device of the address family spcified.

Returns:
HND_DEVICE or HND_INVALID
Parameters:
[in]AddressFamilyAddress family.
[out]device_handle_outDevice handle pointer.
[out]HndInfoDevice handle structure passed by this function.

References GetHandleInfo(), NUM_HANDLE, UpnpSdkDeviceRegisteredV4, and UpnpSdkDeviceregisteredV6.

Referenced by gena_process_subscription_renewal_request(), gena_process_subscription_request(), gena_process_unsubscribe_request(), get_device_info(), ssdp_handle_device_request(), and UpnpFinish().

static int GetFreeHandle ( ) [static]

Get a free handle.

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

References NUM_HANDLE, and UPNP_E_OUTOF_HANDLE.

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

Upnp_Handle_Type GetHandleInfo ( int  Hnd,
struct Handle_Info **  HndInfo 
)
int getlocalhostname ( char *  out,
size_t  out_len 
)

Get local IP address.

Gets the ip address for the DEFAULT_INTERFACE interface which is up and not a loopback. Assumes at most MAX_INTERFACES interfaces

Returns:
UPNP_E_SUCCESS if successful or UPNP_E_INIT.
Parameters:
[out]outIP address of the interface.
[in]out_lenLength of the output buffer.

References INVALID_SOCKET, UPNP_E_INIT, UPNP_E_SUCCESS, and UpnpPrintf().

Referenced by UpnpInit().

static void Param_delete ( struct UpnpNonblockParam Param) [static]

Print handle info.

Returns:
UPNP_E_SUCCESS if successful, otherwise returns appropriate error.
Parameters:
[in]HndHandle index.

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

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

Prints thread pool statistics.

Parameters:
[in]tpThe thread pool.
[in]DbgFileNameThe file name that called this function, use the macro __FILE__.
[in]DbgLineNoThe line number that the function was called, use the macro __LINE__.
[in]msgThe message.

References ThreadPoolGetStats(), and UpnpPrintf().

Referenced by UpnpFinish().

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

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

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

This function is synchronous and generates no callbacks.

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

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

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

Referenced by TvDeviceHandleSubscriptionRequest().

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

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

This function is sychronous and generates no callbacks.

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
  • UPNP_E_INVALID_SERVICE: The DevId/ServId pair refers to an invalid service.
  • UPNP_E_INVALID_SID: The specified subscription ID is not valid.
  • UPNP_E_INVALID_PARAM: Either VarName, NewVal, DevID, ServID, or PropSet is not a valid pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters:
[in]HndThe handle of the device.
[in]DevIDThe device ID of the subdevice of the service generating the event.
[in]ServIDThe unique service identifier of the service generating the event.
[in]PropSetThe DOM document for the property set. Property set documents must conform to the XML schema defined in section 4.3 of the Universal Plug and Play Device Architecture specification.
[in]SubsIdThe subscription ID of the newly registered control point.

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

Referenced by TvDeviceHandleSubscriptionRequest().

int UpnpAddVirtualDir ( const char *  dirName)

Adds a virtual directory mapping.

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

Note:
This function is not available when the web server is not compiled into the UPnP Library.
Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: dirName is not valid.
Parameters:
[in]dirNameThe name of the new directory mapping to add.

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

int UpnpCancelHttpGet ( void *  handle)

Set the cancel flag of the handle parameter.

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: handle is not a valid pointer.
Parameters:
[in]handleThe handle of the connection created by the call to UpnpOpenHttpGet.
int UpnpCloseHttpGet ( void *  handle)

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: handle is not a valid pointer.
Parameters:
[in]handleThe handle of the connection created by the call to UpnpOpenHttpGet.
int UpnpCloseHttpPost ( void *  handle,
int *  httpStatus,
int  timeout 
)

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either handle, or httpStatus is not a valid pointer.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
Parameters:
[in]handleThe handle of the connection to close, created by the call to UpnpOpenHttpPost.
[in,out]httpStatusA pointer to a buffer to store the final status of the connection.
[in]timeoutA time out value sent with the request during which a response is expected from the server, failing which, an error is reported.
int UpnpDownloadUrlItem ( const char *  url,
char **  outBuf,
char *  contentType 
)

Downloads a file specified in a URL.

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

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

References UPNP_E_INVALID_PARAM, and UPNP_E_INVALID_URL.

Referenced by UpnpDownloadXmlDoc().

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

Downloads an XML document specified in a URL.

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

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

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

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

int UpnpEnableWebserver ( int  enable)

Enables or disables the webserver.

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

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

Referenced by UpnpInitStartServers().

int UpnpFinish ( void  )

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

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

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

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

This call is synchronous.

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
  • UPNP_E_INIT: The SDK is already initialized.
  • UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_LISTEN: An error occurred listening to a socket.
  • UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
  • UPNP_E_INTERNAL_ERROR: An internal error ocurred.
  • UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.
Terminates the Linux SDK for UPnP Devices.
  • Checks for pending jobs and threads
  • Unregisters either the client or device
  • Shuts down the Timer Thread
  • Stops the Mini Server
  • Uninitializes the Thread Pool
  • For Win32 cleans up Winsock Interface
  • Cleans up mutex objects

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

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

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

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

int UpnpGetIfInfo ( const char *  IfName)

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

The interface must fulfill these requirements:

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

We'll retrieve the following information from the interface:

  • gIF_NAME -> Interface name (by input or found).
  • gIF_IPV4 -> IPv4 address (if any).
  • gIF_IPV6 -> IPv6 address (if any).
  • gIF_IPV6_ULA_GUA -> ULA or GUA IPv6 address (if any)
  • gIF_INDEX -> Interface index number.
Returns:
UPNP_E_SUCCESS on success.
Parameters:
[in]IfNameInterface name (can be NULL).

References gIF_INDEX, gIF_IPV4, gIF_IPV6, gIF_IPV6_ULA_GUA, gIF_NAME, INVALID_SOCKET, UPNP_E_INIT, UPNP_E_INVALID_INTERFACE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, and UpnpPrintf().

char * UpnpGetServerIpAddress ( void  )

Returns the internal server IPv6 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 IPv6 UPnP related requests.
  • On error: 0 is returned if UpnpInit has not succeeded.
Returns the 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.

References gIF_IPV4, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

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.

References LOCAL_PORT_V4, and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

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

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

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

This is a synchronous call.

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
  • UPNP_E_INVALID_DESC: The XML document was not found or it does not contain a valid XML description.
  • UPNP_E_INVALID_PARAM: StVarVal is not a valid pointer or VarName or ActionUrl is NULL.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
  • UPNP_SOAP_E_INVALID_VAR: The given variable is invalid according to the device.
Parameters:
[in]HndThe handle of the control point.
[in]ActionURLThe URL of the service.
[in]VarNameThe name of the variable to query.
[out]StVarValThe pointer to store the value for VarName. The SDK allocates this string and the caller needs to free it using ixmlFreeDOMString.

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

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

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

Deprecated:
The use of this function is deprecated by the UPnP Forum.
Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: The ActionUrl is not a valid URL.
  • UPNP_E_INVALID_PARAM: VarName, Fun or ActionUrl is not a valid pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters:
[in]HndThe handle of the control point.
[in]ActionURLThe URL of the service.
[in]VarNameThe name of the variable to query.
[in]FunPointer to a callback function to be invoked when the operation is complete.
[in]CookiePointer to user data to pass to the callback function when invoked.

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

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

Retrieve progress information of a http-get transfer.

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either handle, length or total is not a valid pointer.
Parameters:
[in]handleThe token created by the call to UpnpOpenHttpGet.
[out]lengthThe number of bytes received.
[out]totalThe content length.
int UpnpInit ( const char *  HostIP,
unsigned short  DestPort 
)

Initializes the Linux SDK for UPnP Devices (IPv4 only).

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. 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 (in the case of a multi-homed configuration) and a port number to use for all UPnP operations. Since a port number can be used only by one process, multiple processes using the SDK must specify different port numbers.

If unspecified, the SDK will use the first IPv4-capable adapter's IP address and an arbitrary port.

This call is synchronous.

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

References getlocalhostname(), gIF_IPV4, gSDKInitMutex, LOCAL_PORT_V4, UPNP_E_INIT, UPNP_E_INIT_FAILED, UPNP_E_SUCCESS, UpnpInitPreamble(), UpnpInitStartServers(), UpnpPrintf(), and UpnpSdkInit.

Referenced by TvCtrlPointStart(), and TvDeviceStart().

static int UpnpInitMutexes ( void  ) [static]

Initializes the global mutexes used by the UPnP SDK.

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

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

Referenced by UpnpInitPreamble().

static int UpnpInitPreamble ( void  ) [static]

Performs the initial steps in initializing the UPnP SDK.

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

References genaCallback(), gUpnpSdkNLSuuid, NUM_HANDLE, SetGenaCallback(), SetSoapCallback(), soap_device_callback(), TimerThreadInit(), UPNP_E_INIT_FAILED, UPNP_E_SUCCESS, UpnpFinish(), UpnpInitLog(), UpnpInitMutexes(), UpnpInitThreadPools(), UpnpPrintf(), uuid_create(), uuid_unpack(), and WinsockInit().

Referenced by UpnpInit().

static int UpnpInitStartServers ( unsigned short  DestPort) [static]

Finishes initializing the UPnP SDK.

  • The MiniServer is started, if enabled.
  • The WebServer is started, if enabled.
Returns:
UPNP_E_SUCCESS on success or UPNP_E_INIT_FAILED if a mutex could not be initialized.
Parameters:
[in]DestPortLocal Port to listen for incoming connections.

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

Referenced by UpnpInit().

static int UpnpInitThreadPools ( void  ) [static]

Initializes the global threadm pools used by the UPnP SDK.

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

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

Referenced by UpnpInitPreamble().

int UpnpIsWebserverEnabled ( void  )

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

Checks if the webserver is enabled or disabled.

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

References bWebServerState, and UpnpSdkInit.

int UpnpNotify ( UpnpDevice_Handle  Hnd,
const char *  DevID,
const char *  ServID,
const char **  VarName,
const char **  NewVal,
int  cVariables 
)

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

This function is synchronous and generates no callbacks.

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

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

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

Referenced by TvDeviceSetServiceTableVar().

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

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

This function is synchronous and generates no callbacks.

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
  • UPNP_E_INVALID_SERVICE: The DevId/ServId pair refers to an invalid service.
  • UPNP_E_INVALID_PARAM: Either VarName, NewVal, DevID, ServID, or PropSet is not a valid pointer or cVariables is less than zero.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters:
[in]HndThe handle to the device sending the event.
[in]DevIDThe device ID of the subdevice of the service generating the event.
[in]ServIDThe unique identifier of the service generating the event.
[in]PropSetThe DOM document for the property set. Property set documents must conform to the XML schema defined in section 4.3 of the Universal Plug and Play Device Architecture specification.

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

Referenced by TvDeviceSetServiceTableVar().

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

Gets a file specified in a URL.

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either url, handle, contentType, contentLength or httpStatus is not a valid pointer.
  • UPNP_E_INVALID_URL: The url is not a valid URL.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.
Parameters:
[in]urlThe URL of an item to get.
[in,out]handleA pointer to store the handle for this connection.
[in,out]contentTypeA buffer to store the media type of the item.
[in,out]contentLengthA pointer to store the length of the item.
[in,out]httpStatusThe status returned on receiving a response message.
[in]timeoutThe time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.
int UpnpOpenHttpGetEx ( const char *  url,
void **  handle,
char **  contentType,
int *  contentLength,
int *  httpStatus,
int  lowRange,
int  highRange,
int  timeout 
)

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either url, handle, contentType, contentLength or httpStatus is not a valid pointer.
  • UPNP_E_INVALID_URL: The url is not a valid URL.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.
Parameters:
[in]urlThe URL of the item to get.
[in,out]handleA pointer to store the handle for this connection.
[in,out]contentTypeA buffer to store the media type of the item.
[in,out]contentLengthA buffer to store the length of the item.
[in,out]httpStatusThe status returned on receiving a response message from the remote server.
[in]lowRangeAn integer value representing the low end of a range to retrieve.
[in]highRangeAn integer value representing the high end of a range to retrieve.
[in]timeoutA time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.
int UpnpOpenHttpGetProxy ( const char *  url,
const char *  proxy_str,
void **  handle,
char **  contentType,
int *  contentLength,
int *  httpStatus,
int  timeout 
)

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either url, handle, contentType, contentLength or httpStatus is not a valid pointer.
  • UPNP_E_INVALID_URL: The url is not a valid URL.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.
Parameters:
[in]urlThe URL of an item to get.
[in]proxy_strThe URL of the proxy.
[in,out]handleA pointer to store the handle for this connection.
[in,out]contentTypeA buffer to store the media type of the item.
[in,out]contentLengthA pointer to store the length of the item.
[in,out]httpStatusThe status returned on receiving a response message.
[in]timeoutThe time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.

References http_OpenHttpGetProxy().

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either url, handle or contentType is not a valid pointer.
  • UPNP_E_INVALID_URL: The url is not a valid URL.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to download this file.
  • UPNP_E_SOCKET_ERROR: Error occured allocating a socket and resources or an error occurred binding a socket.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting a socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
Parameters:
[in]urlThe URL in which to send the POST request.
[in,out]handleA pointer in which to store the handle for this connection. This handle is required for futher operations over this connection.
[in]contentTypeA buffer to store the media type of content being sent.
[in]contentLengthThe length of the content, in bytes, being posted.
[in]timeoutThe time out value sent with the request during which a response is expected from the receiver, failing which, an error is reported.
int UpnpReadHttpGet ( void *  handle,
char *  buf,
size_t *  size,
int  timeout 
)

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either handle, buf or size is not a valid pointer.
  • UPNP_E_BAD_RESPONSE: A bad response was received from the remote server.
  • UPNP_E_BAD_HTTPMSG: Either the request or response was in the incorrect format.
  • UPNP_E_CANCELED: another thread called UpnpCancelHttpGet.
Note: In case of return values, the status code parameter of the passed in handle value may provide additional information on the return value.
Parameters:
[in]handleThe token created by the call to UpnpOpenHttpGet.
[in,out]bufThe buffer to store the read item.
[in,out]sizeThe size of the buffer to be read.
[in]timeoutThe time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.
int UpnpRegisterClient ( Upnp_FunPtr  Callback,
const void *  Cookie,
UpnpClient_Handle Hnd 
)

Registers a control point application with the UPnP Library.

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to register this control point.
Parameters:
[in]CallbackPointer to a function for receiving asynchronous events.
[in]CookiePointer to user data returned with the callback function when invoked.
[out]HndPointer to a variable to store the new control point handle.

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

Referenced by TvCtrlPointStart().

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

Returns the local IPv6 listening ip address.

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

Returns:
  • On success: The IPv6 address on which an internal server is listening for UPnP related requests.
  • On error: NULL is returned if UpnpInit has not succeeded.
Registers a device application with the UPnP Library.

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_DESC: The description document was not a valid device description.
  • UPNP_E_INVALID_URL: The URL for the description document is not valid.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
Parameters:
[in]DescUrlPointer to a string containing the description URL for this root device instance.
[in]CallbackPointer to the callback function for receiving asynchronous events.
[in]CookiePointer to user data returned with the callback function when invoked.
[out]HndPointer to a variable to store the new device handle.

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

Referenced by TvDeviceStart().

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

Registers a device application with the UPnP Library. Similar to UpnpRegisterRootDevice, except that it also allows the description document to be specified as a file or a memory buffer.

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

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

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

Examples of using different types of description documents:

   1) Description specified as a URL:
         descriptionType == UPNPREG_URL_DESC
         description is the URL
         bufferLen = 0 (ignored)
   2) Description specified as a file:
         descriptionType == UPNPREG_FILENAME_DESC
         description is a filename
         bufferLen = 0 (ignored)
   3) Description specified as a memory buffer:
         descriptionType == UPNPREG_BUF_DESC
         description is pointer to a memory buffer
         bufferLen == length of memory buffer
   
Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_DESC: The description document is not a valid device description.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
  • UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the internal buffer.
  • UPNP_E_FILE_NOT_FOUND: The description file could not be found.
  • UPNP_E_FILE_READ_ERROR: An error occurred reading the description file.
  • UPNP_E_INVALID_URL: The URL to the description document is invalid.
  • UPNP_E_EXT_NOT_XML: The URL to the description document or file should have a .xml extension.
  • UPNP_E_NO_WEB_SERVER: The internal web server has been compiled out; the SDK cannot configure itself from the description document.
Parameters:
[in]descriptionTypeThe type of the description document.
[in]descriptionTreated as a URL, file name or memory buffer depending on description type.
[in]bufferLenThe length of memory buffer if passing a description in a buffer, otherwise it is ignored.
[in]config_baseURLIf nonzero, URLBase of description document is configured and the description is served using the internal web server.
[in]FunPointer to the callback function for receiving asynchronous events.
[in]CookiePointer to user data returned with the callback function when invoked.
[out]HndPointer to a variable to store the new device handle.

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

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_DESC: The description document was not a valid device description.
  • UPNP_E_INVALID_URL: The URL for the description document is not valid.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
Parameters:
[in]DescUrlPointer to a string containing the description URL for this root device instance.
[in]CallbackPointer to the callback function for receiving asynchronous events.
[in]CookiePointer to user data returned with the callback function when invoked.
[out]HndPointer to a variable to store the new device handle.
[in]AddressFamilyAddress family of this device. Can be AF_INET for an IPv4 device, or AF_INET6 for an IPv6 device. Defaults to AF_INET.

References UpnpPrintf(), and UpnpRegisterRootDevice4().

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_FINISH: The SDK is already terminated or is not initialized.
  • UPNP_E_INVALID_DESC: The description document was not a valid device description.
  • UPNP_E_INVALID_URL: The URL for the description document is not valid.
  • UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is NULL.
  • UPNP_E_NETWORK_ERROR: A network error occurred.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
  • UPNP_E_SOCKET_BIND: An error occurred binding a socket.
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
  • UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
Parameters:
[in]DescUrlPointer to a string containing the description URL for this root device instance.
[in]CallbackPointer to the callback function for receiving asynchronous events.
[in]CookiePointer to user data returned with the callback function when invoked.
[out]HndPointer to a variable to store the new device handle.
[in]AddressFamilyAddress family of this device. Can be AF_INET for an IPv4 device, or AF_INET6 for an IPv6 device. Defaults to AF_INET.
[in]LowerDescUrlPointer to a string containing the description URL to be returned for legacy CPs for this root device instance.

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

Referenced by UpnpRegisterRootDevice3().

void UpnpRemoveAllVirtualDirs ( void  )

Removes all virtual directory mappings.

References pVirtualDirList, and UpnpSdkInit.

Referenced by UpnpFinish().

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]dirNameThe name of the virtual directory mapping to remove.

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

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

Renews a subscription that is about to expire.

This function is synchronous.

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

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_SID: The SubsId is not a valid subscription ID.
  • UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function pointer or Timeout is less than zero but is not UPNP_INFINITE.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
  • UPNP_E_NETWORK_ERROR: A network error occured (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_BIND: An error occurred binding the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_OUTOF_SOCKET: An error occurred creating socket ( returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription request (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
Parameters:
[in]HndThe handle of the control point that is renewing the subscription.
[in]TimeOutThe requested subscription time. The actual timeout value is returned when the callback function is called.
[in]SubsIdThe ID for the subscription to renew.
[in]FunPointer to a callback function to be invoked when the renewal is complete.
[in]CookiePointer to user data passed to the callback function when invoked.

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

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

Searches for devices matching the given search target.

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

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

Note that there is no way for the SDK to distinguish which client instance issued a particular search. Therefore, the client can get search callbacks that do not match the original criteria of the search. Also, the application will receive multiple callbacks for each search.

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

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

Referenced by TvCtrlPointVerifyTimeouts().

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
  • UPNP_E_INVALID_ACTION: This action is not valid.
  • UPNP_E_INVALID_DEVICE: DevUDN is not a valid device.
  • UPNP_E_INVALID_PARAM: ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters:
[in]HndThe handle of the control point sending the action.
[in]ActionURLThe action URL of the service.
[in]ServiceTypeThe type of the service.
[in]DevUDNThis parameter is ignored and must be NULL.
[in]ActionThe DOM document for the action.
[out]RespNodeThe DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

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

Referenced by UpnpSendActionEx().

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: ActionUrl is an invalid URL.
  • UPNP_E_INVALID_DEVICE: DevUDN is an invalid device.
  • UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is NULL.
  • UPNP_E_INVALID_ACTION: This action is not valid.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters:
[in]HndThe handle of the control point sending the action.
[in]ActionURLThe action URL of the service.
[in]ServiceTypeThe type of the service.
[in]DevUDNThis parameter is ignored and must be NULL.
[in]ActionThe DOM document for the action to perform on this device.
[in]FunPointer to a callback function to be invoked when the operation completes.
[in]CookiePointer to user data that to be passed to the callback when invoked.

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

Referenced by UpnpSendActionExAsync().

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
  • UPNP_E_INVALID_ACTION: This action is not valid.
  • UPNP_E_INVALID_DEVICE: DevUDN is not a valid device.
  • UPNP_E_INVALID_PARAM: ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters:
[in]HndThe handle of the control point sending the action.
[in]ActionURLThe action URL of the service.
[in]ServiceTypeThe type of the service.
[in]DevUDNThis parameter is ignored and must be NULL.
[in]HeaderThe DOM document for the SOAP header. This may be NULL if the header is not required.
[in]ActionThe DOM document for the action.
[out]RespNodeThe DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: ActionUrl is an invalid URL.
  • UPNP_E_INVALID_DEVICE: DevUDN is an invalid device.
  • UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is NULL.
  • UPNP_E_INVALID_ACTION: This action is not valid.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
Parameters:
[in]HndThe handle of the control point sending the action.
[in]ActionURLThe action URL of the service.
[in]ServiceTypeThe type of the service.
[in]DevUDNThis parameter is ignored and must be NULL.
[in]HeaderThe DOM document for the SOAP header. This may be NULL if the header is not required.
[in]ActionThe DOM document for the action to perform on this device.
[in]FunPointer to a callback function to be invoked when the operation completes.
[in]CookiePointer to user data that to be passed to the callback when invoked.

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

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.

References UpnpPrintf(), and UpnpSendAdvertisementLowPower().

Referenced by AutoAdvertise(), and TvDeviceStart().

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.
PowerStatePowerState as defined by UPnP Low Power.
SleepPeriodSleepPeriod as defined by UPnP Low Power.
RegistrationStateRegistrationState as defined by UPnP Low Power.

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

Referenced by UpnpSendAdvertisement().

int UpnpSetContentLength ( UpnpClient_Handle  Hnd,
size_t  contentLength 
)
Deprecated:
Use UpnpSetMaxContentLength instead.

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

Parameters:
[in]HndThe handle of the device instance for which the coincoming content length needs to be set.
[in]contentLengthPermissible content length

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

int UpnpSetMaxContentLength ( size_t  contentLength)

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

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

If set to 0 then checking will be disabled.

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
Parameters:
[in]contentLengthThe maximum permissible content length for incoming SOAP actions, in bytes.

References g_maxContentLength, UPNP_E_FINISH, UPNP_E_SUCCESS, and UpnpSdkInit.

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.

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

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.

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

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]callbacksA structure that contains the callback functions.

References UPNP_E_FINISH, UPNP_E_INVALID_PARAM, UPNP_E_SUCCESS, UpnpSdkInit, UpnpVirtualDir_set_CloseCallback(), UpnpVirtualDir_set_GetInfoCallback(), UpnpVirtualDir_set_OpenCallback(), UpnpVirtualDir_set_ReadCallback(), UpnpVirtualDir_set_SeekCallback(), and UpnpVirtualDir_set_WriteCallback().

int UpnpSetWebServerRootDir ( const char *  rootDir)

Sets the document root directory for the internal web server.

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

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

Note:
This function is not available when the web server is not compiled into the UPnP Library.
Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_ARGUMENT: rootDir is an invalid directory.
Parameters:
[in]rootDirPath of the root directory of the web server.

Referenced by TvDeviceStart().

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

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

This operation is synchronous.

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

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_URL: The PublisherUrl is not a valid URL.
  • UPNP_E_INVALID_PARAM: Either TimeOut or Fun or PublisherUrl is not a valid pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
  • UPNP_E_NETWORK_ERROR: A network error occured (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_BIND: An error occurred binding the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_OUTOF_SOCKET: An error occurred creating the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused the subscription request (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
Parameters:
HndThe handle of the control point that is subscribing.
PublisherUrlThe URL of the service to subscribe to.
TimeOutThe requested subscription time. Upon return, it contains the actual subscription time returned from the service.
FunPointer to the callback function for this subscribe request.
CookieA user data value passed to the callback function when invoked.

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

void UpnpThreadDistribution ( struct UpnpNonblockParam Param)

Unregisters a control point application, unsubscribing all active subscriptions.

This function unregisters a client registered with UpnpRegisterclient or UpnpRegisterclient2. 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]HndThe handle of the control point instance to unregister.

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

Referenced by UpnpFinish().

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

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

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

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

References UpnpPrintf(), and UpnpUnRegisterRootDeviceLowPower().

Referenced by TvDeviceStop(), and UpnpFinish().

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

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
Parameters:
[in]HndThe 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.

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

Referenced by UpnpUnRegisterRootDevice().

int UpnpUnSubscribe ( UpnpClient_Handle  Hnd,
const Upnp_SID  SubsId 
)

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

This is a synchronous call.

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

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

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

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
  • UPNP_E_INVALID_SID: The SubsId is not a valid SID.
  • UPNP_E_INVALID_PARAM: Fun is not a valid callback function pointer.
  • UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
  • UPNP_E_NETWORK_ERROR: A network error occured (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_BIND: An error occurred binding the socket (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_SOCKET_CONNECT: An error occurred connecting to PublisherUrl (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_OUTOF_SOCKET: An error occurred creating a socket ( returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_BAD_RESPONSE: An error occurred in response from the publisher (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
  • UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused the subscription request (returned in the UpnpEventSubscribe.ErrCode field as part of the callback).
Parameters:
[in]HndThe handle of the subscribed control point.
[in]SubsIdThe ID returned when the control point subscribed to the service.
[in]FunPointer to a callback function to be called when the operation is complete.
[in]CookiePointer to user data to pass to the callback function when invoked.

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

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

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

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

Referenced by UpnpSetVirtualDirCallbacks().

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

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

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

Referenced by UpnpSetVirtualDirCallbacks().

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

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

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

Referenced by UpnpSetVirtualDirCallbacks().

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

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

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

Referenced by UpnpSetVirtualDirCallbacks().

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

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

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

Referenced by UpnpSetVirtualDirCallbacks().

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

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

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

Referenced by UpnpSetVirtualDirCallbacks().

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

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

Returns:
An integer representing one of the following:
  • UPNP_E_SUCCESS: The operation completed successfully.
  • UPNP_E_INVALID_PARAM: Either handle, buf or size is not a valid pointer.
  • UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
  • UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
Parameters:
[in]handleThe handle of the connection created by the call to UpnpOpenHttpPost.
[in]bufThe buffer to be posted.
[in]sizeThe size, in bytes of buf.
[in]timeoutA timeout value sent with the request during which a response is expected from the server, failing which, an error is reported.
static int WinsockInit ( void  ) [static]

(Windows Only) Initializes the Windows Winsock library.

Returns:
UPNP_E_SUCCESS on success, UPNP_E_INIT_FAILED on failure.

References UPNP_E_INIT_FAILED, and UPNP_E_SUCCESS.

Referenced by UpnpInitPreamble().


Variable Documentation

WebServerState bWebServerState = WEB_SERVER_DISABLED

Flag to indicate the state of web server

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

size_t g_maxContentLength = DEFAULT_SOAP_CONTENT_LENGTH

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

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

a local dir which serves as webserver root

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

unsigned gIF_INDEX = (unsigned)-1
char gIF_IPV4[INET_ADDRSTRLEN] = { '\0' }

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

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

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

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

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

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

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

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

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

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

Referenced by UpnpGetIfInfo().

ithread_mutex_t GlobalClientSubscribeMutex

Mutex to synchronize the subscription handling at the client side.

Referenced by UpnpFinish(), and UpnpInitMutexes().

ithread_rwlock_t GlobalHndRWLock

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

Referenced by UpnpFinish(), and UpnpInitMutexes().

Mini server thread pool.

Referenced by StartMiniServer().

Receive thread pool.

Referenced by readFromSSDPSocket(), and ssdp_handle_ctrlpt_msg().

ithread_mutex_t gSDKInitMutex = PTHREAD_MUTEX_INITIALIZER

Initialization mutex.

Referenced by UpnpInit().

ithread_mutex_t gUUIDMutex

Mutex to synchronize the uuid creation process.

Referenced by UpnpFinish(), and UpnpInitMutexes().

unsigned short LOCAL_PORT_V4

local IPv4 port for the mini-server

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

unsigned short LOCAL_PORT_V6

local IPv6 port for the mini-server

Referenced by gena_subscribe(), and UpnpInitStartServers().

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

Referenced by UpnpRegisterClient(), and UpnpUnRegisterClient().

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

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

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

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

int UpnpSdkInit = 0