libUPnP  1.6.17
Data Structures | Defines
upnp.h File Reference
#include "ixml.h"
#include "upnpconfig.h"
#include "UpnpGlobal.h"
#include "UpnpInet.h"
#include "UpnpString.h"
Include dependency graph for upnp.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

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

Functions

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.

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)

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.

Detailed Description