upnp.h File Reference

#include <stdio.h>
#include "ixml.h"
#include "upnpconfig.h"
#include <netinet/in.h>

Go to the source code of this file.

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
struct  virtual_Dir_List
struct  user_HTTP_Header_List

Defines

#define UPNP_E_OUTOF_CONTEXT   -103
#define UPNP_E_BUFFER_TOO_SMALL   -106
#define UPNP_E_INVALID_SID   -109
#define UPNP_E_INVALID_DEVICE   -110
#define UPNP_E_BAD_REQUEST   -114
#define UPNP_E_FILE_WRITE_ERROR   -209
#define UPNP_E_EVENT_PROTOCOL   -300
#define UPNP_E_NO_WEB_SERVER   -505
#define UPNP_E_OUTOF_BOUNDS   -506
#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
The API



#define EXPORT_SPEC
#define UpnpCloseSocket   close
#define UPNP_SOCKETERROR   -1
#define UPNP_INVALID_SOCKET   -1
#define SOCKET   int
#define NUM_HANDLE   200
#define LINE_SIZE   180
#define NAME_SIZE   256
#define HEADER_SIZE   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
UPNP_E_SUCCESS [0]

{ UPNP_E_SUCCESS} signifies that 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.



#define UPNP_E_SUCCESS   0
UPNP_E_INVALID_HANDLE [-100]

{ UPNP_E_INVALID_HANDLE} signifies that the handle passed to a function is not a recognized as a valid handle.



#define UPNP_E_INVALID_HANDLE   -100
UPNP_E_INVALID_PARAM [-101]

{ UPNP_E_INVALID_PARAM} signifies that one or more of the parameters passed to the function is not valid. Refer to the documentation for each function for more information on the valid ranges of the parameters.



#define UPNP_E_INVALID_PARAM   -101
UPNP_E_OUTOF_HANDLE [-102]

{ UPNP_E_OUTOF_HANDLE} signifies that 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.



#define UPNP_E_OUTOF_HANDLE   -102
UPNP_E_OUTOF_MEMORY [-104]

{ UPNP_E_OUTOF_MEMORY} signifies that not enough resources are currently available to complete the operation. Most operations require some free memory in order to complete their work.



#define UPNP_E_OUTOF_MEMORY   -104
UPNP_E_INIT [-105]

{ UPNP_E_INIT} signifies that 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.



#define UPNP_E_INIT   -105
UPNP_E_INVALID_DESC [-107]

{ UPNP_E_INVALID_DESC} signifies that the description document passed to { UpnpRegisterRootDevice} or { UpnpRegisterRootDevice2} is an invalid description document.



#define UPNP_E_INVALID_DESC   -107
UPNP_E_INVALID_URL [-108]

{ UPNP_E_INVALID_URL} signifies that a 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.



#define UPNP_E_INVALID_URL   -108
UPNP_E_INVALID_SERVICE [-111]

{ UPNP_E_INVALID_SERVICE} is returned only by { UpnpNotify}, { UpnpNotifyExt}, { UpnpAcceptSubscription}, and { UpnpAcceptSubscriptionExt} to signify that the device ID/service ID pair does not refer to a valid service.



#define UPNP_E_INVALID_SERVICE   -111
UPNP_E_BAD_RESPONSE [-113]

{ UPNP_E_BAD_RESPONSE} signifies that 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.



#define UPNP_E_BAD_RESPONSE   -113
UPNP_E_INVALID_ACTION [-115]

{ UPNP_E_INVALID_ACTION} signifies that the SOAP action message is invalid. This can be because the DOM document passed to the function was malformed or the action message is not correct for the given action.



#define UPNP_E_INVALID_ACTION   -115
UPNP_E_FINISH [-116]

{ UPNP_E_FINISH} signifies that { UpnpInit} has not been called, or that { UpnpFinish} has already been called. None of the API functions operate until { UpnpInit} successfully completes.



#define UPNP_E_FINISH   -116
UPNP_E_INIT_FAILED [-117]

{ UPNP_E_INIT_FAILED} signifies that { UpnpInit} cannot complete. The typical reason is failure to allocate sufficient resources.



#define UPNP_E_INIT_FAILED   -117
UPNP_E_URL_TOO_BIG [-118]

{ UPNP_E_URL_TOO_BIG} signifies that the URL passed into a function is too long. The SDK limits URLs to 180 characters in length.



#define UPNP_E_URL_TOO_BIG   -118
UPNP_E_BAD_HTTPMSG [-119]

{ UPNP_E_BAD_HTTPMSG} signifies that 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}).



#define UPNP_E_BAD_HTTPMSG   -119
UPNP_E_ALREADY_REGISTERED [-120]

{ UPNP_E_ALREADY_REGISTERED} signifies that a client or a device is already registered. The SDK currently has a limit of one registered client and one registered device per process.



#define UPNP_E_ALREADY_REGISTERED   -120
UPNP_E_NETWORK_ERROR [-200]

{ UPNP_E_NETWORK_ERROR} signifies that 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.



#define UPNP_E_NETWORK_ERROR   -200
UPNP_E_SOCKET_WRITE [-201]

{ UPNP_E_SOCKET_WRITE} signifies an error 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}).



#define UPNP_E_SOCKET_WRITE   -201
UPNP_E_SOCKET_READ [-202]

{ UPNP_E_SOCKET_READ} signifies an error 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_READ   -202
UPNP_E_SOCKET_BIND [-203]

{ UPNP_E_SOCKET_BIND} signifies that 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}).



#define UPNP_E_SOCKET_BIND   -203
UPNP_E_SOCKET_CONNECT [-204]

{ UPNP_E_SOCKET_CONNECT} signifies that 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}).



#define UPNP_E_SOCKET_CONNECT   -204
UPNP_E_OUTOF_SOCKET [-205]

{ UPNP_E_OUTOF_SOCKET} signifies that 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}).



#define UPNP_E_OUTOF_SOCKET   -205
UPNP_E_LISTEN [-206]

{ UPNP_E_LISTEN} signifies that 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_LISTEN   -206
UPNP_E_TIMEDOUT [-207]

{ UPNP_E_TIMEDOUT} signifies that 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.



#define UPNP_E_TIMEDOUT   -207
UPNP_E_SOCKET_ERROR [-208]

{ UPNP_E_SOCKET_ERROR} is the generic socket error code for conditions not covered by other error codes. This error can be returned by any function that performs network operations.



#define UPNP_E_SOCKET_ERROR   -208
UPNP_E_CANCELED [-210]

{ UPNP_E_CANCELED} signifies that the operation was canceled. This error can be returned by any function that allows for external cancelation.



#define UPNP_E_CANCELED   -210
UPNP_E_SUBSCRIBE_UNACCEPTED [-301]

{ UPNP_E_SUBSCRIBE_UNACCEPTED} signifies that a subscription request was rejected from the remote side.



#define UPNP_E_SUBSCRIBE_UNACCEPTED   -301
UPNP_E_UNSUBSCRIBE_UNACCAPTED [-302]

{ UPNP_E_UNSUBSCRIBE_UNACCEPTED} signifies that an unsubscribe request was rejected from the remote side.



#define UPNP_E_UNSUBSCRIBE_UNACCEPTED   -302
UPNP_E_NOTIFY_UNACCEPTED [-303]

{ UPNP_E_NOTIFY_UNACCEPTED} signifies that the remote host did not accept the notify sent from the local device.



#define UPNP_E_NOTIFY_UNACCEPTED   -303
UPNP_E_INVALID_ARGUMENT [-501]

{ UPNP_E_INVALID_ARGUMENT} signifies that one or more of the parameters passed to a function is invalid. Refer to the individual function descriptions for the acceptable ranges for parameters.



#define UPNP_E_INVALID_ARGUMENT   -501
UPNP_E_FILE_NOT_FOUND [-502]

{ UPNP_E_FILE_NOT_FOUND} signifies that the filename passed to one of the device registration functions was not found or was not accessible.



#define UPNP_E_FILE_NOT_FOUND   -502
UPNP_E_FILE_READ_ERROR [-503]

{ UPNP_E_FILE_READ_ERROR} signifies an error when reading a file.



#define UPNP_E_FILE_READ_ERROR   -503
UPNP_E_EXT_NOT_XML [-504]

{ UPNP_E_EXT_NOT_XML} signifies that the file name of the description document passed to { UpnpRegisterRootDevice2} does not end in ".xml".



#define UPNP_E_EXT_NOT_XML   -504
UPNP_E_NOT_FOUND [-507]

{ UPNP_E_NOT_FOUND} signifies that the response to a SOAP request did not contain the required XML constructs.



#define UPNP_E_NOT_FOUND   -507
UPNP_E_INTERNAL_ERROR [-911]

{ UPNP_E_INTERNAL_ERROR} is the generic error code for internal conditions not covered by other error codes.



#define UPNP_E_INTERNAL_ERROR   -911

Typedefs

Constants, Structures, and Types



typedef int UpnpClient_Handle
typedef int UpnpDevice_Handle

Enumerations

enum  UpnpOpenFileMode { UPNP_READ, UPNP_WRITE }

Functions

Initialization and Registration



EXPORT_SPEC int UpnpInit (IN const char *HostIP, IN unsigned short DestPort, IN int maxHTTPTimeoutRetries, IN void *thread_cleanup)
EXPORT_SPEC int UpnpFinish ()
EXPORT_SPEC unsigned short UpnpGetServerPort (void)
EXPORT_SPEC char * UpnpGetServerIpAddress (void)
EXPORT_SPEC int UpnpRegisterClient (IN Upnp_FunPtr Callback, IN const void *Cookie, OUT UpnpClient_Handle *Hnd)
EXPORT_SPEC int UpnpRegisterRootDevice (IN const char *DescUrl, IN Upnp_FunPtr Callback, IN const void *Cookie, OUT UpnpDevice_Handle *Hnd)
EXPORT_SPEC int UpnpRegisterRootDevice2 (IN Upnp_DescType descriptionType, IN const char *description, IN size_t bufferLen, IN int config_baseURL, IN Upnp_FunPtr Fun, IN const void *Cookie, OUT UpnpDevice_Handle *Hnd)
EXPORT_SPEC int UpnpUnRegisterClient (IN UpnpClient_Handle Hnd)
EXPORT_SPEC int UpnpUnRegisterRootDevice (IN UpnpDevice_Handle)
EXPORT_SPEC int UpnpSetContentLength (IN UpnpClient_Handle Hnd, IN int contentLength)
EXPORT_SPEC int UpnpSetMaxContentLength (IN size_t contentLength)
Discovery



EXPORT_SPEC int UpnpSearchAsync (IN UpnpClient_Handle Hnd, IN int Mx, IN const char *Target, IN const void *Cookie)
EXPORT_SPEC int UpnpSendAdvertisement (IN UpnpDevice_Handle Hnd, IN int Exp)
Control



EXPORT_SPEC int UpnpGetServiceVarStatus (IN UpnpClient_Handle Hnd, IN const char *ActionURL, IN const char *VarName, OUT DOMString *StVarVal)
EXPORT_SPEC int UpnpGetServiceVarStatusAsync (IN UpnpClient_Handle Hnd, IN const char *ActionURL, IN const char *VarName, IN Upnp_FunPtr Fun, IN const void *Cookie)
EXPORT_SPEC int UpnpSendAction (IN UpnpClient_Handle Hnd, IN const char *ActionURL, IN const char *ServiceType, IN const char *DevUDN, IN IXML_Document *Action, OUT IXML_Document **RespNode)
EXPORT_SPEC int UpnpSendActionEx (IN UpnpClient_Handle Hnd, IN const char *ActionURL, IN const char *ServiceType, IN const char *DevUDN, IN IXML_Document *Header, IN IXML_Document *Action, OUT IXML_Document **RespNode)
EXPORT_SPEC int UpnpSendActionAsync (IN UpnpClient_Handle Hnd, IN const char *ActionURL, IN const char *ServiceType, IN const char *DevUDN, IN IXML_Document *Action, IN Upnp_FunPtr Fun, IN const void *Cookie)
EXPORT_SPEC int UpnpSendActionExAsync (IN UpnpClient_Handle Hnd, IN const char *ActionURL, IN const char *ServiceType, IN const char *DevUDN, IN IXML_Document *Header, IN IXML_Document *Action, IN Upnp_FunPtr Fun, IN const void *Cookie)
Eventing



EXPORT_SPEC int UpnpAcceptSubscription (IN UpnpDevice_Handle Hnd, IN const char *DevID, IN const char *ServID, IN const char **VarName, IN const char **NewVal, IN int cVariables, IN Upnp_SID SubsId)
EXPORT_SPEC int UpnpAcceptSubscriptionExt (IN UpnpDevice_Handle Hnd, IN const char *DevID, IN const char *ServID, IN IXML_Document *PropSet, IN Upnp_SID SubsId)
EXPORT_SPEC int UpnpNotify (IN UpnpDevice_Handle, IN const char *DevID, IN const char *ServID, IN const char **VarName, IN const char **NewVal, IN int cVariables)
EXPORT_SPEC int UpnpNotifyExt (IN UpnpDevice_Handle, IN const char *DevID, IN const char *ServID, IN IXML_Document *PropSet)
EXPORT_SPEC int UpnpRenewSubscription (IN UpnpClient_Handle Hnd, INOUT int *TimeOut, IN Upnp_SID SubsId)
EXPORT_SPEC int UpnpRenewSubscriptionAsync (IN UpnpClient_Handle Hnd, IN int TimeOut, IN Upnp_SID SubsId, IN Upnp_FunPtr Fun, IN const void *Cookie)
EXPORT_SPEC int UpnpSetMaxSubscriptions (IN UpnpDevice_Handle Hnd, IN int MaxSubscriptions)
EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut (IN UpnpDevice_Handle Hnd, IN int MaxSubscriptionTimeOut)
EXPORT_SPEC int UpnpSubscribe (IN UpnpClient_Handle Hnd, IN const char *PublisherUrl, INOUT int *TimeOut, OUT Upnp_SID SubsId)
EXPORT_SPEC int UpnpSubscribeAsync (IN UpnpClient_Handle Hnd, IN const char *PublisherUrl, IN int TimeOut, IN Upnp_FunPtr Fun, IN const void *Cookie)
EXPORT_SPEC int UpnpUnSubscribe (IN UpnpClient_Handle Hnd, IN Upnp_SID SubsId)
EXPORT_SPEC int UpnpUnSubscribeAsync (IN UpnpClient_Handle Hnd, IN Upnp_SID SubsId, IN Upnp_FunPtr Fun, IN const void *Cookie)
Control Point HTTP API



EXPORT_SPEC int UpnpDownloadUrlItem (IN const char *url, OUT char **outBuf, OUT char *contentType)
EXPORT_SPEC int UpnpOpenHttpGet (IN const char *url, IN OUT void **handle, IN OUT char **contentType, IN OUT off_t *contentLength, IN OUT int *httpStatus, IN int timeout)
EXPORT_SPEC int UpnpOpenHttpGetProxy (IN const char *url, IN const char *proxy_str, IN OUT void **handle, IN OUT char **contentType, IN OUT off_t *contentLength, IN OUT int *httpStatus, IN int timeout)
EXPORT_SPEC int UpnpOpenHttpGetEx (IN const char *url, IN OUT void **handle, IN OUT char **contentType, IN OUT off_t *contentLength, IN OUT int *httpStatus, IN int lowRange, IN int highRange, IN int timeout)
EXPORT_SPEC int UpnpReadHttpGet (IN void *handle, IN OUT char *buf, IN OUT off_t *size, IN int timeout)
EXPORT_SPEC int UpnpHttpGetProgress (IN void *handle, OUT off_t *length, OUT off_t *total)
EXPORT_SPEC int UpnpCancelHttpGet (IN void *handle)
EXPORT_SPEC int UpnpCloseHttpGet (IN void *handle)
EXPORT_SPEC int UpnpOpenHttpPost (IN const char *url, IN OUT void **handle, IN const char *contentType, IN int contentLength, IN int timeout)
EXPORT_SPEC int UpnpWriteHttpPost (IN void *handle, IN char *buf, IN off_t *size, IN int timeout)
EXPORT_SPEC int UpnpCloseHttpPost (IN void *handle, IN OUT int *httpStatus, IN int timeout)
EXPORT_SPEC int UpnpDownloadXmlDoc (IN const char *url, OUT IXML_Document **xmlDoc)
Web Server API



EXPORT_SPEC int UpnpSetWebServerRootDir (IN const char *rootDir)
EXPORT_SPEC int UpnpAddCustomHTTPHeader (IN const char *header_string)
EXPORT_SPEC int UpnpRemoveCustomHTTPHeader (IN const char *header_string)
EXPORT_SPEC void UpnpRemoveAllCustomHTTPHeaders ()
EXPORT_SPEC int UpnpSetVirtualDirCallbacks (IN struct UpnpVirtualDirCallbacks *callbacks)
EXPORT_SPEC int UpnpEnableWebserver (IN int enable)
EXPORT_SPEC int UpnpIsWebserverEnabled ()
EXPORT_SPEC int UpnpAddVirtualDir (IN const char *dirName)
EXPORT_SPEC int UpnpRemoveVirtualDir (IN const char *dirName)
EXPORT_SPEC void UpnpRemoveAllVirtualDirs ()
EXPORT_SPEC void UpnpFree (IN void *item)

UPnP_EventType

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.



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
}
typedef enum Upnp_EventType_e Upnp_EventType
typedef char Upnp_SID [44]

Upnp_SType

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.



enum  Upnp_SType_e { UPNP_S_ALL, UPNP_S_ROOT, UPNP_S_DEVICE, UPNP_S_SERVICE }
typedef enum Upnp_SType_e Upnp_SType

Upnp_DescType

Specifies the type of description in { UpnpRegisterRootDevice2}. These values control how { UpnpRegisterRootDevice2} interprets the { description} parameter.



enum  Upnp_DescType_e { UPNPREG_URL_DESC, UPNPREG_FILENAME_DESC, UPNPREG_BUF_DESC }
typedef enum Upnp_DescType_e Upnp_DescType
typedef struct sockaddr_in SOCKADDRIN
typedef void * UpnpWebFileHandle
typedef struct virtual_Dir_List virtualDirList
typedef struct
user_HTTP_Header_List 
userHTTPHeaderList
typedef int(* Upnp_FunPtr )(IN Upnp_EventType EventType, IN void *Event, IN void *Cookie)

Define Documentation

#define EXPORT_SPEC

Definition at line 83 of file upnp.h.

#define HEADER_SIZE   256

Definition at line 107 of file upnp.h.

#define LINE_SIZE   180

Definition at line 105 of file upnp.h.

#define MNFT_NAME_SIZE   64

Definition at line 108 of file upnp.h.

#define MODL_DESC_SIZE   64

Definition at line 111 of file upnp.h.

#define MODL_NAME_SIZE   32

Definition at line 109 of file upnp.h.

#define NAME_SIZE   256

Definition at line 106 of file upnp.h.

#define NUM_HANDLE   200

Definition at line 104 of file upnp.h.

#define SERL_NUMR_SIZE   64

Definition at line 110 of file upnp.h.

#define SOCKET   int

Definition at line 94 of file upnp.h.

#define UPNP_E_ALREADY_REGISTERED   -120

Definition at line 279 of file upnp.h.

#define UPNP_E_BAD_HTTPMSG   -119

Definition at line 270 of file upnp.h.

#define UPNP_E_BAD_REQUEST   -114

Definition at line 227 of file upnp.h.

Referenced by Server::upnp_actions(), Server::upnp_callback(), and Server::upnp_subscriptions().

#define UPNP_E_BAD_RESPONSE   -113

Definition at line 224 of file upnp.h.

#define UPNP_E_BUFFER_TOO_SMALL   -106

Definition at line 184 of file upnp.h.

#define UPNP_E_CANCELED   -210

Definition at line 386 of file upnp.h.

#define UPNP_E_EVENT_PROTOCOL   -300

Definition at line 389 of file upnp.h.

#define UPNP_E_EXT_NOT_XML   -504

Definition at line 445 of file upnp.h.

#define UPNP_E_FILE_NOT_FOUND   -502

Definition at line 430 of file upnp.h.

#define UPNP_E_FILE_READ_ERROR   -503

Definition at line 437 of file upnp.h.

#define UPNP_E_FILE_WRITE_ERROR   -209

Definition at line 378 of file upnp.h.

#define UPNP_E_FINISH   -116

Definition at line 244 of file upnp.h.

#define UPNP_E_INIT   -105

Definition at line 181 of file upnp.h.

#define UPNP_E_INIT_FAILED   -117

Definition at line 252 of file upnp.h.

#define UPNP_E_INTERNAL_ERROR   -911

Definition at line 464 of file upnp.h.

#define UPNP_E_INVALID_ACTION   -115
#define UPNP_E_INVALID_ARGUMENT   -501

Definition at line 421 of file upnp.h.

#define UPNP_E_INVALID_DESC   -107

Definition at line 192 of file upnp.h.

#define UPNP_E_INVALID_DEVICE   -110

Definition at line 206 of file upnp.h.

#define UPNP_E_INVALID_HANDLE   -100

Definition at line 142 of file upnp.h.

#define UPNP_E_INVALID_PARAM   -101

Definition at line 151 of file upnp.h.

#define UPNP_E_INVALID_SERVICE   -111

Definition at line 215 of file upnp.h.

#define UPNP_E_INVALID_SID   -109

Definition at line 205 of file upnp.h.

#define UPNP_E_INVALID_URL   -108

Definition at line 202 of file upnp.h.

#define UPNP_E_LISTEN   -206

Definition at line 357 of file upnp.h.

#define UPNP_E_NETWORK_ERROR   -200

Definition at line 290 of file upnp.h.

#define UPNP_E_NO_WEB_SERVER   -505

Definition at line 448 of file upnp.h.

#define UPNP_E_NOT_FOUND   -507

Definition at line 456 of file upnp.h.

#define UPNP_E_NOTIFY_UNACCEPTED   -303

Definition at line 412 of file upnp.h.

#define UPNP_E_OUTOF_BOUNDS   -506

Definition at line 449 of file upnp.h.

#define UPNP_E_OUTOF_CONTEXT   -103

Definition at line 163 of file upnp.h.

#define UPNP_E_OUTOF_HANDLE   -102

Definition at line 160 of file upnp.h.

#define UPNP_E_OUTOF_MEMORY   -104

Definition at line 171 of file upnp.h.

#define UPNP_E_OUTOF_SOCKET   -205

Definition at line 348 of file upnp.h.

#define UPNP_E_SOCKET_BIND   -203

Definition at line 324 of file upnp.h.

Referenced by main().

#define UPNP_E_SOCKET_CONNECT   -204

Definition at line 336 of file upnp.h.

#define UPNP_E_SOCKET_ERROR   -208

Definition at line 375 of file upnp.h.

Referenced by main().

#define UPNP_E_SOCKET_READ   -202

Definition at line 312 of file upnp.h.

#define UPNP_E_SOCKET_WRITE   -201

Definition at line 301 of file upnp.h.

#define UPNP_E_SUBSCRIBE_UNACCEPTED   -301

Definition at line 396 of file upnp.h.

#define UPNP_E_SUCCESS   0
#define UPNP_E_TIMEDOUT   -207

Definition at line 366 of file upnp.h.

#define UPNP_E_UNSUBSCRIBE_UNACCEPTED   -302

Definition at line 404 of file upnp.h.

#define UPNP_E_URL_TOO_BIG   -118

Definition at line 259 of file upnp.h.

#define UPNP_INFINITE   -1

Definition at line 112 of file upnp.h.

#define UPNP_INVALID_SOCKET   -1

Definition at line 92 of file upnp.h.

#define UPNP_SOAP_E_ACTION_FAILED   501

Definition at line 472 of file upnp.h.

#define UPNP_SOAP_E_INVALID_ACTION   401

Definition at line 468 of file upnp.h.

#define UPNP_SOAP_E_INVALID_ARGS   402

Definition at line 469 of file upnp.h.

Referenced by ContentDirectoryService::upnp_action_Browse().

#define UPNP_SOAP_E_INVALID_VAR   404

Definition at line 471 of file upnp.h.

#define UPNP_SOAP_E_OUT_OF_SYNC   403

Definition at line 470 of file upnp.h.

#define UPNP_SOCKETERROR   -1

Definition at line 91 of file upnp.h.

#define UPNP_UNTIL_CLOSE   -4

Definition at line 115 of file upnp.h.

#define UPNP_USING_CHUNKED   -3

Definition at line 114 of file upnp.h.

#define UpnpCloseSocket   close

Definition at line 87 of file upnp.h.


Typedef Documentation

typedef struct sockaddr_in SOCKADDRIN

Definition at line 812 of file upnp.h.

Definition at line 689 of file upnp.h.

Definition at line 630 of file upnp.h.

typedef int(* Upnp_FunPtr)(IN Upnp_EventType EventType, IN void *Event, IN 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.

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

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.

Definition at line 1067 of file upnp.h.

typedef char Upnp_SID[44]

The { Upnp_SID} 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.

Definition at line 637 of file upnp.h.

typedef enum Upnp_SType_e Upnp_SType

Definition at line 666 of file upnp.h.

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.

Definition at line 496 of file upnp.h.

typedef int UpnpDevice_Handle

Returned when a device application registers with { UpnpRegisterRootDevice} or { UpnpRegisterRootDevice2}. Device handles can only be used with functions that operate with a device handle.

Definition at line 502 of file upnp.h.

typedef void* UpnpWebFileHandle

Definition at line 933 of file upnp.h.


Enumeration Type Documentation

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.

Definition at line 674 of file upnp.h.

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 { Upnp_Action_Request} 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 { Upnp_Action_Complete} 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 { Upnp_State_Var_Request} 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 { Upnp_State_Var_Complete} 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 { Upnp_Discovery} structure with the information about the device or service.

UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE 

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

UPNP_DISCOVERY_SEARCH_RESULT 

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

UPNP_DISCOVERY_SEARCH_TIMEOUT 

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

UPNP_EVENT_SUBSCRIPTION_REQUEST 

Received by a device when a subscription arrives. The { Event} parameter contains a pointer to a { Upnp_Subscription_Request} 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 { Upnp_Event} 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 { Upnp_Event_Subscribe} structure.

UPNP_EVENT_AUTORENEWAL_FAILED 

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

UPNP_EVENT_SUBSCRIPTION_EXPIRED 

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

Definition at line 511 of file upnp.h.

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.

Definition at line 648 of file upnp.h.

Enumerator:
UPNP_READ 
UPNP_WRITE 

Definition at line 487 of file upnp.h.


Function Documentation

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

{ UpnpAcceptSubscription} 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.

{ UpnpAcceptSubscription} can be called during the execution of a callback function.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
DevID The handle of the device.
ServID The device ID of the subdevice of the service generating the event.
VarName The unique service identifier of the service generating the event.
NewVal Pointer to an array of event variables.
cVariables Pointer to an array of values for the event variables.
SubsId The number of event variables in { VarName}. The subscription ID of the newly registered control point.
EXPORT_SPEC int UpnpAcceptSubscriptionExt ( IN UpnpDevice_Handle  Hnd,
IN const char *  DevID,
IN const char *  ServID,
IN IXML_Document PropSet,
IN Upnp_SID  SubsId 
)

{ UpnpAcceptSubscriptionExt} is 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.

{ UpnpAcceptSubscriptionExt} can be called during the execution of a callback function.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
DevID The handle of the device.
ServID The device ID of the subdevice of the service generating the event.
PropSet The unique service identifier of the service generating the event.
SubsId The DOM document for the property set. Property set documents must conform to the XML schema defined in section 4.3 of the Universal Plug and Play Device Architecture specification. The subscription ID of the newly registered control point.

Referenced by ConnectionManagerService::process_subscription_request(), and ContentDirectoryService::process_subscription_request().

EXPORT_SPEC int UpnpAddCustomHTTPHeader ( IN const char *  header_string  ) 

{ UpnpAddHTTPHeader} add a custom header to the internal web server. All HTTP responses will contain the specified header.

Returns:
[int] An integer representing one of the following: {itemize} { UPPN_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_ARGUMENT}: { header_string} is empty. {itemize}
Parameters:
header_string Header to add (
termination not needed)

Referenced by Server::upnp_init().

EXPORT_SPEC int UpnpAddVirtualDir ( IN const char *  dirName  ) 

{ UpnpAddVirtualDir} adds a virtual directory mapping.

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

Returns:
[int] An integer representing one of the following: {itemize} { UPPN_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_ARGUMENT}: { dirName} is not valid. {itemize}
Parameters:
dirName The name of the new directory mapping to add.

Referenced by Server::upnp_init().

EXPORT_SPEC int UpnpCancelHttpGet ( IN void *  handle  ) 

{ UpnpCancelHttpGet} set the cancel flag of the { handle} parameter.

Returns:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_PARAM}: { handle} is not a valid pointer. {itemize}
EXPORT_SPEC int UpnpCloseHttpGet ( IN void *  handle  ) 

{ UpnpCloseHttpGet} closes the connection and frees memory that was allocated for the { handle} parameter.

Returns:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_PARAM}: { handle} is not a valid pointer. {itemize}
EXPORT_SPEC int UpnpCloseHttpPost ( IN void *  handle,
IN OUT int *  httpStatus,
IN int  timeout 
)

{ UpnpCloseHttpPost} sends and receives any pending data, closes the connection with the server, and frees memory allocated during the {} call.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
httpStatus The handle of the connection to close, created by the call to { UpnpOpenHttpPost}.
timeout A pointer to a buffer to store the final status of the connection. A time out value sent with the request during which a response is expected from the server, failing which, an error is reported.
EXPORT_SPEC int UpnpDownloadUrlItem ( IN const char *  url,
OUT char **  outBuf,
OUT char *  contentType 
)

{ UpnpDownloadUrlItem} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
outBuf URL of an item to download.
contentType Buffer to store the downloaded item. HTTP header value content type if present. It should be at least { LINE_SIZE} bytes in size.
EXPORT_SPEC int UpnpDownloadXmlDoc ( IN const char *  url,
OUT IXML_Document **  xmlDoc 
)

{ UpnpDownloadXmlDoc} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
xmlDoc URL of the XML document. A pointer in which to store the XML document.
EXPORT_SPEC int UpnpEnableWebserver ( IN int  enable  ) 

{ UpnpEnableWebServer} enables or disables the webserver. A value of { TRUE} enables the webserver, { FALSE} disables it.

Returns:
[int] An integer representing one of the following: {itemize} { UPPN_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_ARGUMENT}: { enable} is not valid. {itemize}
Parameters:
enable { TRUE} to enable, { FALSE} to disable.
EXPORT_SPEC int UpnpFinish (  ) 

Terminates the Linux SDK for UPnP Devices. 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:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_FINISH}: The SDK is already terminated or it is not initialized. {itemize}

Referenced by Server::shutdown().

EXPORT_SPEC void UpnpFree ( IN void *  item  ) 
EXPORT_SPEC char* UpnpGetServerIpAddress ( void   ) 

If { NULL} is used as the IP address in { UpnpInit}, then this function can be used to retrieve the actual interface address on which device is running. If { UpnpInit} has not succeeded then { NULL} is returned.

Returns:
[char*] The IP address on which an internal server is listening for UPnP related requests.

Referenced by Server::getIP(), and Server::upnp_init().

EXPORT_SPEC unsigned short UpnpGetServerPort ( void   ) 

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. If { UpnpInit} has not succeeded then 0 is returned.

Returns:
[unsigned short] The port on which an internal server is listening for UPnP related requests.

Referenced by Server::getPort(), and Server::upnp_init().

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

{ UpnpGetServiceVarStatus} queries the state of a state variable of a service on another device. This is a synchronous call. A positive return value indicates a SOAP error code, whereas a negative return code indicates an SDK error code. { Note that the use of this function is deprecated by the UPnP Forum}.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
ActionURL The handle of the control point.
VarName The URL of the service.
StVarVal The name of the variable to query. The pointer to store the value for { VarName}. The SDK allocates this string and the caller needs to free it using { ixmlFreeDOMString}.
EXPORT_SPEC int UpnpGetServiceVarStatusAsync ( IN UpnpClient_Handle  Hnd,
IN const char *  ActionURL,
IN const char *  VarName,
IN Upnp_FunPtr  Fun,
IN const void *  Cookie 
)

{ UpnpGetServiceVarStatusAsync} queries the state of a variable of a service, generating a callback when the operation is complete. { Note that the use of this function is deprecated by the UPnP Forum}.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
ActionURL The handle of the control point.
VarName The URL of the service.
Fun The name of the variable to query.
Cookie Pointer to a callback function to be invoked when the operation is complete. Pointer to user data to pass to the callback function when invoked.
EXPORT_SPEC int UpnpHttpGetProgress ( IN void *  handle,
OUT off_t *  length,
OUT off_t *  total 
)

{ UpnpHttpGetProgress} rettrieve progress information of a http-get transfer.

Returns:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_PARAM}: Either { handle}, { length} or { total} is not a valid pointer. {itemize}
Parameters:
length The token created by the call to { UpnpOpenHttpGet}.
total The number of bytes received. The content length.
EXPORT_SPEC int UpnpInit ( IN const char *  HostIP,
IN unsigned short  DestPort,
IN int  maxHTTPTimeoutRetries,
IN void *  thread_cleanup 
)

Initializes the Linux SDK for UPnP Devices. 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 IP 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 adapter's IP address and an arbitrary port.

This call is synchronous.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
DestPort The host IP address to use, in string format, for example "192.168.0.1", or { NULL} to use the first adapter's IP address.
maxHTTPTimeoutRetries The destination port number to use. 0 will pick an arbitrary free port.
thread_cleanup maximum number of retries when select times out on sending data, use a negative value to disable this feature * A user defined callback function that will get triggered each time a thread dies (only for threads that were calling other user callbacks). We need this to allow extra cleanup, for example for MySQL

Referenced by Server::upnp_init().

EXPORT_SPEC int UpnpIsWebserverEnabled (  ) 

{ UpnpIsWebServerEnabled} returns { TRUE} if the webserver is enabled, or { FALSE} if it is not.

Returns:
[int] An integer representing one of the following: {itemize} { TRUE}: The webserver is enabled. { FALSE}: The webserver is not enabled {itemize}
EXPORT_SPEC int UpnpNotify ( IN  UpnpDevice_Handle,
IN const char *  DevID,
IN const char *  ServID,
IN const char **  VarName,
IN const char **  NewVal,
IN int  cVariables 
)

{ UpnpNotify} sends out an event change notification to all control points subscribed to a particular service. This function is synchronous and generates no callbacks.

{ UpnpNotify} may be called during a callback function to send out a notification.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
DevID The handle to the device sending the event.
ServID The device ID of the subdevice of the service generating the event.
VarName The unique identifier of the service generating the event.
NewVal Pointer to an array of variables that have changed.
cVariables Pointer to an array of new values for those variables. The count of variables included in this notification.
EXPORT_SPEC int UpnpNotifyExt ( IN  UpnpDevice_Handle,
IN const char *  DevID,
IN const char *  ServID,
IN IXML_Document PropSet 
)

{ UpnpNotifyExt} is 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.

{ UpnpNotifyExt} may be called during a callback function to send out a notification.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
DevID The handle to the device sending the event.
ServID The device ID of the subdevice of the service generating the event.
PropSet The unique identifier of the service generating the event. The DOM document for the property set. Property set documents must conform to the XML schema defined in section 4.3 of the Universal Plug and Play Device Architecture specification.

Referenced by ConnectionManagerService::subscription_update(), and ContentDirectoryService::subscription_update().

EXPORT_SPEC int UpnpOpenHttpGet ( IN const char *  url,
IN OUT void **  handle,
IN OUT char **  contentType,
IN OUT off_t *  contentLength,
IN OUT int *  httpStatus,
IN int  timeout 
)

{ UpnpOpenHttpGet} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
handle The URL of an item to get.
contentType A pointer to store the handle for this connection.
contentLength A buffer to store the media type of the item.
httpStatus A pointer to store the length of the item.
timeout The status returned on receiving a response message. The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.
EXPORT_SPEC int UpnpOpenHttpGetEx ( IN const char *  url,
IN OUT void **  handle,
IN OUT char **  contentType,
IN OUT off_t *  contentLength,
IN OUT int *  httpStatus,
IN int  lowRange,
IN int  highRange,
IN int  timeout 
)

{ UpnpOpenHttpGetEx} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
handle The URL of the item to get.
contentType A pointer to store the handle for this connection.
contentLength A buffer to store the media type of the item.
httpStatus A buffer to store the length of the item.
lowRange The status returned on receiving a response message from the remote server.
highRange An integer value representing the low end of a range to retrieve.
timeout An integer value representing the high end of a range to retrieve. A time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.
EXPORT_SPEC int UpnpOpenHttpGetProxy ( IN const char *  url,
IN const char *  proxy_str,
IN OUT void **  handle,
IN OUT char **  contentType,
IN OUT off_t *  contentLength,
IN OUT int *  httpStatus,
IN int  timeout 
)

{ UpnpOpenHttpGetProxy} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
proxy_str The URL of an item to get.
handle The URL of the proxy.
contentType A pointer to store the handle for this connection.
contentLength A buffer to store the media type of the item.
httpStatus A pointer to store the length of the item.
timeout The status returned on receiving a response message. The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.
EXPORT_SPEC int UpnpOpenHttpPost ( IN const char *  url,
IN OUT void **  handle,
IN const char *  contentType,
IN int  contentLength,
IN int  timeout 
)

{ UpnpOpenHttpPost} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
handle The URL in which to send the POST request.
contentType A pointer in which to store the handle for this connection. This handle is required for futher operations over this connection.
contentLength A buffer to store the media type of content being sent.
timeout The length of the content, in bytes, being posted. The time out value sent with the request during which a response is expected from the receiver, failing which, an error is reported.
EXPORT_SPEC int UpnpReadHttpGet ( IN void *  handle,
IN OUT char *  buf,
IN OUT off_t *  size,
IN int  timeout 
)

{ UpnpReadHttpGet} gets specified number of bytes from a file specified in a URL.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}

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:
buf The token created by the call to { UpnpOpenHttpGet}.
size The buffer to store the read item.
timeout The size of the buffer to be read. The time out value sent with the request during which a response is expected from the server, failing which, an error is reported back to the user.
EXPORT_SPEC int UpnpRegisterClient ( IN Upnp_FunPtr  Callback,
IN const void *  Cookie,
OUT UpnpClient_Handle Hnd 
)

{ UpnpRegisterClient} registers a control point application with the SDK. 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
Cookie Pointer to a function for receiving asynchronous events.
Hnd Pointer to user data returned with the callback function when invoked. Pointer to a variable to store the new control point handle.
EXPORT_SPEC int UpnpRegisterRootDevice ( IN const char *  DescUrl,
IN Upnp_FunPtr  Callback,
IN const void *  Cookie,
OUT UpnpDevice_Handle Hnd 
)

{ UpnpRegisterRootDevice} registers a device application with the SDK. 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).

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

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
Callback Pointer to a string containing the description URL for this root device instance.
Cookie Pointer to the callback function for receiving asynchronous events.
Hnd Pointer to user data returned with the callback function when invoked. Pointer to a variable to store the new device handle.
EXPORT_SPEC int UpnpRegisterRootDevice2 ( IN Upnp_DescType  descriptionType,
IN const char *  description,
IN size_t  bufferLen,
IN int  config_baseURL,
IN Upnp_FunPtr  Fun,
IN const void *  Cookie,
OUT UpnpDevice_Handle Hnd 
)

{ UpnpRegisterRootDevice2} is 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}.)

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

Examples of using different types of description documents: {verbatim} 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 {verbatim}

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
description The type of the description document.
bufferLen Treated as a URL, file name or memory buffer depending on description type.
config_baseURL The length of memory buffer if passing a description in a buffer, otherwise it is ignored.
Fun If nonzero, { URLBase} of description document is configured and the description is served using the internal web server.
Cookie Pointer to the callback function for receiving asynchronous events.
Hnd Pointer to user data returned with the callback function when invoked. Pointer to a variable to store the new device handle.

Referenced by Server::upnp_init().

EXPORT_SPEC void UpnpRemoveAllCustomHTTPHeaders (  ) 

{ UpnpRemoveAll} removes all virtual directory mappings.

Returns:
[void] This function does not return a value.
EXPORT_SPEC void UpnpRemoveAllVirtualDirs (  ) 

{ UpnpRemoveAllVirtualDirs} removes all virtual directory mappings.

Returns:
[void] This function does not return a value.
EXPORT_SPEC int UpnpRemoveCustomHTTPHeader ( IN const char *  header_string  ) 

{ UpnpRemoveHTTPHeader} removes a header that was previously added with { UpnpAddHTTPHeader}.

Returns:
[int] An integer representing one of the following: {itemize} { UPPN_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_ARGUMENT}: { dirName} is not valid. {itemize}
Parameters:
header_string Name of the header to remove
EXPORT_SPEC int UpnpRemoveVirtualDir ( IN const char *  dirName  ) 

{ UpnpRemoveVirtualDir} removes a virtual directory mapping made with { UpnpAddVirtualDir}.

Returns:
[int] An integer representing one of the following: {itemize} { UPPN_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_ARGUMENT}: { dirName} is not valid. {itemize}
Parameters:
dirName The name of the virtual directory mapping to remove.
EXPORT_SPEC int UpnpRenewSubscription ( IN UpnpClient_Handle  Hnd,
INOUT int *  TimeOut,
IN Upnp_SID  SubsId 
)

{ UpnpRenewSubscription} renews a subscription that is about to expire. This function is synchronous.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
TimeOut The handle of the control point that is renewing the subscription.
SubsId Pointer to a variable containing the requested subscription time. Upon return, it contains the actual renewal time. The ID for the subscription to renew.
EXPORT_SPEC int UpnpRenewSubscriptionAsync ( IN UpnpClient_Handle  Hnd,
IN int  TimeOut,
IN Upnp_SID  SubsId,
IN Upnp_FunPtr  Fun,
IN const void *  Cookie 
)

{ UpnpRenewSubscriptionAsync} 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 { Upnp_Event_Subscribe} structure. In those cases, the function returns { UPNP_E_SUCCESS} and the appropriate error code will be in the { Upnp_Event_Subscribe.ErrCode} field in the { Event} structure passed to the callback.

Returns:
[int] An integer representing one of the following: {itemize} { 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 { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing to a socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_READ}: An error or timeout occurred reading from a socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_BIND}: An error occurred binding the socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_CONNECT}: An error occurred connecting to { PublisherUrl} (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_OUTOF_SOCKET}: An error occurred creating socket ( returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_BAD_RESPONSE}: An error occurred in response from the publisher (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused the subscription request (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). {itemize}
Parameters:
TimeOut The handle of the control point that is renewing the subscription.
SubsId The requested subscription time. The actual timeout value is returned when the callback function is called.
Fun The ID for the subscription to renew.
Cookie Pointer to a callback function to be invoked when the renewal is complete. Pointer to user data passed to the callback function when invoked.
EXPORT_SPEC int UpnpSearchAsync ( IN UpnpClient_Handle  Hnd,
IN int  Mx,
IN const char *  Target,
IN const void *  Cookie 
)

{ UpnpSearchAsync} 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.

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:
[int] An integer representing one of the following: {itemize} { 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}. {itemize}
Parameters:
Mx The handle of the client performing the search.
Target The time, in seconds, to wait for responses. If the time is greater than { MAX_SEARCH_TIME} then the time is set to { MAX_SEARCH_TIME}. If the time is less than { MIN_SEARCH_TIME} then the time is set to { MIN_SEARCH_TIME}.
Cookie The search target as defined in the UPnP Device Architecture v1.0 specification. The user data to pass when the callback function is invoked.
EXPORT_SPEC int UpnpSendAction ( IN UpnpClient_Handle  Hnd,
IN const char *  ActionURL,
IN const char *  ServiceType,
IN const char *  DevUDN,
IN IXML_Document Action,
OUT IXML_Document **  RespNode 
)

{ UpnpSendAction} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
ActionURL The handle of the control point sending the action.
ServiceType The action URL of the service.
DevUDN The type of the service.
Action This parameter is ignored and must be { NULL}.
RespNode The DOM document for the action. The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.
EXPORT_SPEC int UpnpSendActionAsync ( IN UpnpClient_Handle  Hnd,
IN const char *  ActionURL,
IN const char *  ServiceType,
IN const char *  DevUDN,
IN IXML_Document Action,
IN Upnp_FunPtr  Fun,
IN const void *  Cookie 
)

{ UpnpSendActionAsync} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
ActionURL The handle of the control point sending the action.
ServiceType The action URL of the service.
DevUDN The type of the service.
Action This parameter is ignored and must be { NULL}.
Fun The DOM document for the action to perform on this device.
Cookie Pointer to a callback function to be invoked when the operation completes. Pointer to user data that to be passed to the callback when invoked.
EXPORT_SPEC int UpnpSendActionEx ( IN UpnpClient_Handle  Hnd,
IN const char *  ActionURL,
IN const char *  ServiceType,
IN const char *  DevUDN,
IN IXML_Document Header,
IN IXML_Document Action,
OUT IXML_Document **  RespNode 
)

{ UpnpSendActionEx} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
ActionURL The handle of the control point sending the action.
ServiceType The action URL of the service.
DevUDN The type of the service.
Header This parameter is ignored and must be { NULL}.
Action The DOM document for the SOAP header. This may be { NULL} if the header is not required.
RespNode The DOM document for the action. The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.
EXPORT_SPEC int UpnpSendActionExAsync ( IN UpnpClient_Handle  Hnd,
IN const char *  ActionURL,
IN const char *  ServiceType,
IN const char *  DevUDN,
IN IXML_Document Header,
IN IXML_Document Action,
IN Upnp_FunPtr  Fun,
IN const void *  Cookie 
)

{ UpnpSendActionExAsync} 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:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
ActionURL The handle of the control point sending the action.
ServiceType The action URL of the service.
DevUDN The type of the service.
Header This parameter is ignored and must be { NULL}.
Action The DOM document for the SOAP header. This may be { NULL} if the header is not required.
Fun The DOM document for the action to perform on this device.
Cookie Pointer to a callback function to be invoked when the operation completes. Pointer to user data that to be passed to the callback when invoked.
EXPORT_SPEC int UpnpSendAdvertisement ( IN UpnpDevice_Handle  Hnd,
IN int  Exp 
)

{ UpnpSendAdvertisement} sends out the discovery announcements for all devices and services for a device. Each announcement is made with the same expiration time.

{ UpnpSendAdvertisement} is a synchronous call.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
Exp The device handle for which to send out the announcements. The expiration age, in seconds, of the announcements.

Referenced by Server::upnp_init().

EXPORT_SPEC int UpnpSetContentLength ( IN UpnpClient_Handle  Hnd,
IN int  contentLength 
)

OBSOLETE METHOD : 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} ).

EXPORT_SPEC int UpnpSetMaxContentLength ( IN 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. The default maximum content-length is { DEFAULT_SOAP_CONTENT_LENGTH} = 16K bytes.

Returns:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. {itemize}
Parameters:
contentLength The maximum permissible content length for incoming SOAP actions, in bytes.
EXPORT_SPEC int UpnpSetMaxSubscriptions ( IN UpnpDevice_Handle  Hnd,
IN int  MaxSubscriptions 
)

{ UpnpSetMaxSubscriptions} 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:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_HANDLE}: The handle is not a valid device handle. {itemize}
Parameters:
MaxSubscriptions The handle of the device for which the maximum number of subscriptions is being set. The maximum number of subscriptions to be allowed per service.
EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut ( IN UpnpDevice_Handle  Hnd,
IN int  MaxSubscriptionTimeOut 
)

{ UpnpSetMaxSubscriptionTimeOut} 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:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_HANDLE}: The handle is not a valid device handle. {itemize}
Parameters:
MaxSubscriptionTimeOut The handle of the device for which the maximum subscription time-out is being set. The maximum subscription time-out to be accepted.
EXPORT_SPEC int UpnpSetVirtualDirCallbacks ( IN struct UpnpVirtualDirCallbacks callbacks  ) 

{ UpnpSetVirtualDirCallbacks} sets the callback function to be used to access a virtual directory. Refer to the description of { UpnpVirtualDirCallbacks} for a description of the functions.

Returns:
[int] An integer representing one of the following: {itemize} { UPPN_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_ARGUMENT}: { callbacks} is not a valid pointer. {itemize}
Parameters:
callbacks Pointer to a structure containing points to the virtual interface functions.

Referenced by register_web_callbacks().

EXPORT_SPEC int UpnpSetWebServerRootDir ( IN const char *  rootDir  ) 

{ UpnpSetWebServerRootDir} 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 that this function is not available when the web server is not compiled into the SDK.

Returns:
[int] An integer representing one of the following: {itemize} { UPPN_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_ARGUMENT}: { rootDir} is an invalid directory. {itemize}
Parameters:
rootDir Path of the root directory of the web server.

Referenced by Server::upnp_init().

EXPORT_SPEC int UpnpSubscribe ( IN UpnpClient_Handle  Hnd,
IN const char *  PublisherUrl,
INOUT int *  TimeOut,
OUT Upnp_SID  SubsId 
)

{ UpnpSubscribe} registers a control point to receive event notifications from another device. This operation is synchronous.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
PublisherUrl The handle of the control point.
TimeOut The URL of the service to subscribe to.
SubsId Pointer to a variable containing the requested subscription time. Upon return, it contains the actual subscription time returned from the service. Pointer to a variable to receive the subscription ID (SID).
EXPORT_SPEC int UpnpSubscribeAsync ( IN UpnpClient_Handle  Hnd,
IN const char *  PublisherUrl,
IN int  TimeOut,
IN Upnp_FunPtr  Fun,
IN const void *  Cookie 
)

{ UpnpSubscribeAsync} 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 { Upnp_Event_Subscribe} structure. In those cases, the function returns { UPNP_E_SUCCESS} and the appropriate error code will be in the { Upnp_Event_Subscribe.ErrCode} field in the { Event} structure passed to the callback.

Returns:
[int] An integer representing one of the following: {itemize} { 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 { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing to a socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_READ}: An error or timeout occurred reading from a socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_BIND}: An error occurred binding the socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_CONNECT}: An error occurred connecting to { PublisherUrl} (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_OUTOF_SOCKET}: An error occurred creating the socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_BAD_RESPONSE}: An error occurred in response from the publisher (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused the subscription request (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). {itemize}
Parameters:
PublisherUrl The handle of the control point that is subscribing.
TimeOut The URL of the service to subscribe to.
Fun The requested subscription time. Upon return, it contains the actual subscription time returned from the service.
Cookie Pointer to the callback function for this subscribe request. A user data value passed to the callback function when invoked.
EXPORT_SPEC int UpnpUnRegisterClient ( IN UpnpClient_Handle  Hnd  ) 

{ UpnpUnRegisterClient} unregisters a control point application, unsubscribing all active subscriptions. After this call, the { UpnpClient_Handle} is no longer valid.

{ UpnpUnRegisterClient} is a synchronous call and generates no callbacks. The SDK generates no more callbacks after this function returns.

Returns:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_HANDLE}: The handle is not a valid control point handle. {itemize}
Parameters:
Hnd The handle of the control point instance to unregister.
EXPORT_SPEC int UpnpUnRegisterRootDevice ( IN  UpnpDevice_Handle  ) 

Unregisters a root device registered with { UpnpRegisterRootDevice} or { UpnpRegisterRootDevice2}. 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.

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

Returns:
[int] An integer representing one of the following: {itemize} { UPNP_E_SUCCESS}: The operation completed successfully. { UPNP_E_INVALID_HANDLE}: The handle is not a valid device handle. {itemize}
Parameters:
UpnpDevice_Handle The handle of the root device instance to unregister.

Referenced by Server::shutdown(), and Server::upnp_init().

EXPORT_SPEC int UpnpUnSubscribe ( IN UpnpClient_Handle  Hnd,
IN Upnp_SID  SubsId 
)

{ UpnpUnSubscribe} removes the subscription of a control point from a service previously subscribed to using { UpnpSubscribe} or { UpnpSubscribeAsync}. This is a synchronous call.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
SubsId The handle of the subscribed control point. The ID returned when the control point subscribed to the service.
EXPORT_SPEC int UpnpUnSubscribeAsync ( IN UpnpClient_Handle  Hnd,
IN Upnp_SID  SubsId,
IN Upnp_FunPtr  Fun,
IN const void *  Cookie 
)

{ UpnpUnSubscribeAsync} 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 { Upnp_Event_Subscribe} structure. In those cases, the function returns { UPNP_E_SUCCESS} and the appropriate error code will be in the { Upnp_Event_Subscribe.ErrCode} field in the { Event} structure passed to the callback.

Returns:
[int] An integer representing one of the following: {itemize} { 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 { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing to a socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_READ}: An error or timeout occurred reading from a socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_BIND}: An error occurred binding the socket (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_SOCKET_CONNECT}: An error occurred connecting to { PublisherUrl} (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket ( returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_BAD_RESPONSE}: An error occurred in response from the publisher (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). { UPNP_E_UNSUBSCRIBE_UNACCEPTED}: The publisher refused the subscription request (returned in the { Upnp_Event_Subscribe.ErrCode} field as part of the callback). {itemize}
Parameters:
SubsId The handle of the subscribed control point.
Fun The ID returned when the control point subscribed to the service.
Cookie Pointer to a callback function to be called when the operation is complete. Pointer to user data to pass to the callback function when invoked.
EXPORT_SPEC int UpnpWriteHttpPost ( IN void *  handle,
IN char *  buf,
IN off_t *  size,
IN int  timeout 
)

{ UpnpWriteHttpPost} sends a request to a server to copy the contents of a buffer to the URI specified in the { UpnpOpenHttpPost} call.

Returns:
[int] An integer representing one of the following: {itemize} { 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. {itemize}
Parameters:
buf The handle of the connection created by the call to { UpnpOpenHttpPost}.
size The buffer to be posted.
timeout The size, in bytes of { buf}. A timeout value sent with the request during which a response is expected from the server, failing which, an error is reported.

Generated on Fri Mar 26 20:16:55 2010 for MediaTomb by  doxygen 1.6.1