Logo Search packages:      
Sourcecode: libupnp4 version File versions  Download package

upnp.h File Reference


Detailed Description

Definition in file upnp.h.

#include "ixml.h"
#include "upnpconfig.h"
#include "UpnpGlobal.h"
#include "UpnpInet.h"
#include <sys/param.h>
#include "ActionComplete.h"
#include "ActionRequest.h"
#include "Discovery.h"
#include "Event.h"
#include "EventSubscribe.h"
#include "FileInfo.h"
#include "StateVarComplete.h"
#include "StateVarRequest.h"
#include "SubscriptionRequest.h"

Go to the source code of this file.

Constants and Types

enum  Upnp_DescType_e { UPNPREG_URL_DESC, UPNPREG_FILENAME_DESC, UPNPREG_BUF_DESC }
 Specifies the type of description in UpnpRegisterRootDevice2. More...
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  UpnpOpenFileMode { UPNP_READ, UPNP_WRITE }
typedef enum Upnp_DescType_e Upnp_DescType
typedef enum Upnp_EventType_e Upnp_EventType
typedef int(* Upnp_FunPtr )(Upnp_EventType EventType, void *Event, void *Cookie)
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 int UpnpClient_Handle
 Returned when a control point application registers with UpnpRegisterClient.
typedef int UpnpDevice_Handle
 Returned when a device application registers with UpnpRegisterRootDevice or UpnpRegisterRootDevice2.

Web Server API

typedef void * UpnpWebFileHandle
 The type of handle returned by the web server for open requests.
typedef int(* VDCallback_Close )(UpnpWebFileHandle fileHnd)
 Close callback function prototype.
typedef int(* VDCallback_GetInfo )(const char *filename, UpnpFileInfo *info)
 Get-info callback function prototype.
typedef UpnpWebFileHandle(* VDCallback_Open )(const char *filename, enum UpnpOpenFileMode Mode)
 Open callback function prototype.
typedef int(* VDCallback_Read )(UpnpWebFileHandle fileHnd, char *buf, size_t buflen)
 Read callback function prototype.
typedef int(* VDCallback_Seek )(UpnpWebFileHandle fileHnd, off_t offset, int origin)
 Seek callback function prototype.
typedef int(* VDCallback_Write )(UpnpWebFileHandle fileHnd, char *buf, size_t buflen)
 Write callback function prototype.
EXPORT_SPEC int UpnpAddVirtualDir (const char *dirName)
 Adds a virtual directory mapping.
EXPORT_SPEC int UpnpEnableWebserver (int enable)
 Enables or disables the webserver.
EXPORT_SPEC int UpnpIsWebserverEnabled ()
 Returns TRUE if the webserver is enabled, or FALSE if it is not.
EXPORT_SPEC void UpnpRemoveAllVirtualDirs ()
 Removes all virtual directory mappings.
EXPORT_SPEC int UpnpRemoveVirtualDir (const char *dirName)
 Removes a virtual directory mapping made with UpnpAddVirtualDir.
EXPORT_SPEC int UpnpSetWebServerRootDir (const char *rootDir)
 Sets the document root directory for the internal web server.
EXPORT_SPEC int UpnpVirtualDir_set_CloseCallback (VDCallback_Close callback)
 Sets the close callback function to be used to access a virtual directory.
EXPORT_SPEC int UpnpVirtualDir_set_GetInfoCallback (VDCallback_GetInfo callback)
 Sets the get_info callback function to be used to access a virtual directory.
EXPORT_SPEC int UpnpVirtualDir_set_OpenCallback (VDCallback_Open callback)
 Sets the open callback function to be used to access a virtual directory.
EXPORT_SPEC int UpnpVirtualDir_set_ReadCallback (VDCallback_Read callback)
 Sets the read callback function to be used to access a virtual directory.
EXPORT_SPEC int UpnpVirtualDir_set_SeekCallback (VDCallback_Seek callback)
 Sets the seek callback function to be used to access a virtual directory.
EXPORT_SPEC int UpnpVirtualDir_set_WriteCallback (VDCallback_Write callback)
 Sets the write callback function to be used to access a virtual directory.

Defines

#define INVALID_SOCKET   (SOCKET)(~0)
#define LINE_SIZE   180
#define MNFT_NAME_SIZE   64
#define MODL_DESC_SIZE   64
#define MODL_NAME_SIZE   32
#define NAME_SIZE   256
#define NUM_HANDLE   200
#define SERL_NUMR_SIZE   64
#define SOCKET   int
#define UPNP_INFINITE   -1
#define UPNP_UNTIL_CLOSE   -4
#define UPNP_USING_CHUNKED   -3
#define UpnpCloseSocket   close
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_ALREADY_REGISTERED   -120
 A client or a device is already registered.
#define UPNP_E_BAD_HTTPMSG   -119
 The HTTP message contains invalid message headers.
#define UPNP_E_BAD_REQUEST   -114
#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_BUFFER_TOO_SMALL   -106
#define UPNP_E_CANCELED   -210
 The operation was canceled.
#define UPNP_E_EVENT_PROTOCOL   -300
#define UPNP_E_EXT_NOT_XML   -504
 The file name of the description document passed to UpnpRegisterRootDevice2 does not end in ".xml".
#define UPNP_E_FILE_NOT_FOUND   -502
 The filename passed to one of the device registration functions was not found or was not accessible.
#define UPNP_E_FILE_READ_ERROR   -503
 An error happened while reading a file.
#define UPNP_E_FILE_WRITE_ERROR   -209
#define UPNP_E_FINISH   -116
 UpnpInit has not been called, or UpnpFinish has already been called.
#define UPNP_E_INIT   -105
 The SDK has already been initialized.
#define UPNP_E_INIT_FAILED   -117
 UpnpInit cannot complete.
#define UPNP_E_INTERNAL_ERROR   -911
 Generic error code for internal conditions not covered by other error codes.
#define UPNP_E_INVALID_ACTION   -115
 The SOAP action message is invalid.
#define UPNP_E_INVALID_ARGUMENT   -501
 One or more of the parameters passed to a function is invalid.
#define UPNP_E_INVALID_DESC   -107
 The description document passed to UpnpRegisterRootDevice or UpnpRegisterRootDevice2 is invalid.
#define UPNP_E_INVALID_DEVICE   -110
#define UPNP_E_INVALID_HANDLE   -100
 The handle passed to a function is not a recognized as a valid handle.
#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_INVALID_PARAM   -101
 One or more of the parameters passed to the function is not valid.
#define UPNP_E_INVALID_SERVICE   -111
 The device ID/service ID pair does not refer to a valid service.
#define UPNP_E_INVALID_SID   -109
#define UPNP_E_INVALID_URL   -108
 An URL passed into the function is invalid.
#define UPNP_E_LISTEN   -206
 The SDK had a problem setting the socket to listen for incoming connections.
#define UPNP_E_NETWORK_ERROR   -200
 A network error occurred.
#define UPNP_E_NO_WEB_SERVER   -505
#define UPNP_E_NOT_FOUND   -507
 The response to a SOAP request did not contain the required XML constructs.
#define UPNP_E_NOTIFY_UNACCEPTED   -303
 The remote host did not accept the notify sent from the local device.
#define UPNP_E_OUTOF_BOUNDS   -506
#define UPNP_E_OUTOF_CONTEXT   -103
#define UPNP_E_OUTOF_HANDLE   -102
 The SDK does not have any more space for additional handles.
#define UPNP_E_OUTOF_MEMORY   -104
 Not enough resources are currently available to complete the operation.
#define UPNP_E_OUTOF_SOCKET   -205
 The SDK cannot create any more sockets.
#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_SOCKET_ERROR   -208
 Generic socket error code for conditions not covered by other error codes.
#define UPNP_E_SOCKET_READ   -202
 An error happened while reading from a socket.
#define UPNP_E_SOCKET_WRITE   -201
 An error happened while writing to a socket.
#define UPNP_E_SUBSCRIBE_UNACCEPTED   -301
 A subscription request was rejected from the remote side.
#define UPNP_E_SUCCESS   0
 The operation completed successfully.
#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_UNSUBSCRIBE_UNACCEPTED   -302
 An unsubscribe request was rejected from the remote side.
#define UPNP_E_URL_TOO_BIG   -118
 The URL passed into a function is too long.
#define UPNP_SOAP_E_ACTION_FAILED   501
#define UPNP_SOAP_E_INVALID_ACTION   401
#define UPNP_SOAP_E_INVALID_ARGS   402
#define UPNP_SOAP_E_INVALID_VAR   404
#define UPNP_SOAP_E_OUT_OF_SYNC   403

Functions

Eventing
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC int UpnpRenewSubscription (UpnpClient_Handle Hnd, int *TimeOut, const Upnp_SID SubsId)
 Renews a subscription that is about to expire.
EXPORT_SPEC 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.
EXPORT_SPEC int UpnpSetMaxSubscriptions (UpnpDevice_Handle Hnd, int MaxSubscriptions)
 Sets the maximum number of subscriptions accepted per service.
EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut (UpnpDevice_Handle Hnd, int MaxSubscriptionTimeOut)
 Sets the maximum time-out accepted for a subscription request or renewal.
EXPORT_SPEC int UpnpSubscribe (UpnpClient_Handle Hnd, const char *PublisherUrl, int *TimeOut, Upnp_SID SubsId)
 Registers a control point to receive event notifications from another device.
EXPORT_SPEC 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.
EXPORT_SPEC int UpnpUnSubscribe (UpnpClient_Handle Hnd, const Upnp_SID SubsId)
 Removes the subscription of a control point from a service previously subscribed to using UpnpSubscribe or UpnpSubscribeAsync.
EXPORT_SPEC 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
EXPORT_SPEC int UpnpCancelHttpGet (void *handle)
 Set the cancel flag of the handle parameter.
EXPORT_SPEC int UpnpCloseHttpGet (void *handle)
 Closes the connection and frees memory that was allocated for the handle parameter.
EXPORT_SPEC 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.
EXPORT_SPEC int UpnpDownloadUrlItem (const char *url, char **outBuf, char *contentType)
 Downloads a file specified in a URL.
EXPORT_SPEC int UpnpDownloadXmlDoc (const char *url, IXML_Document **xmlDoc)
 Downloads an XML document specified in a URL.
EXPORT_SPEC int UpnpHttpGetProgress (void *handle, unsigned int *length, unsigned int *total)
 Retrieve progress information of a http-get transfer.
EXPORT_SPEC int UpnpOpenHttpGet (const char *url, void **handle, char **contentType, int *contentLength, int *httpStatus, int timeout)
 Gets a file specified in a URL.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC int UpnpReadHttpGet (void *handle, char *buf, unsigned int *size, int timeout)
 Gets specified number of bytes from a file specified in a URL.
EXPORT_SPEC int UpnpWriteHttpPost (void *handle, char *buf, unsigned int *size, int timeout)
 Sends a request to a server to copy the contents of a buffer to the URI specified in the UpnpOpenHttpPost call.
Initialization and Registration
EXPORT_SPEC int UpnpFinish ()
 Terminates the Linux SDK for UPnP Devices.
EXPORT_SPEC char * UpnpGetServerIp6Address ()
 Returns the local IPv6 listening ip address.
EXPORT_SPEC char * UpnpGetServerIpAddress ()
 Returns the local IPv4 listening ip address.
EXPORT_SPEC unsigned short UpnpGetServerPort ()
 Returns the internal server IPv4 UPnP listening port.
EXPORT_SPEC unsigned short UpnpGetServerPort6 ()
 Returns the internal server IPv6 UPnP listening port.
EXPORT_SPEC int UpnpInit (const char *HostIP, unsigned short DestPort)
 Initializes the Linux SDK for UPnP Devices.
EXPORT_SPEC int UpnpInit2 (const char *IfName, unsigned short DestPort)
 Initializes the Linux SDK for UPnP Devices.
EXPORT_SPEC int UpnpRegisterClient (Upnp_FunPtr Callback, const void *Cookie, UpnpClient_Handle *Hnd)
 Registers a control point application with the UPnP Library.
EXPORT_SPEC int UpnpRegisterRootDevice (const char *DescUrl, Upnp_FunPtr Callback, const void *Cookie, UpnpDevice_Handle *Hnd)
 Registers a device application with the UPnP Library.
EXPORT_SPEC 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.
EXPORT_SPEC int UpnpRegisterRootDevice3 (const char *DescUrl, Upnp_FunPtr Callback, const void *Cookie, UpnpDevice_Handle *Hnd, const int AddressFamily)
 Registers a device application for a specific address family with the UPnP library.
EXPORT_SPEC int UpnpSetContentLength (UpnpClient_Handle Hnd, int contentLength)
EXPORT_SPEC int UpnpSetMaxContentLength (size_t contentLength)
 Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses.
EXPORT_SPEC int UpnpUnRegisterClient (UpnpClient_Handle Hnd)
 Unregisters a control point application, unsubscribing all active subscriptions.
EXPORT_SPEC int UpnpUnRegisterRootDevice (UpnpDevice_Handle Hnd)
 Unregisters a root device registered with UpnpRegisterRootDevice or UpnpRegisterRootDevice2.
Control
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
EXPORT_SPEC 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.
Discovery
EXPORT_SPEC int UpnpSearchAsync (UpnpClient_Handle Hnd, int Mx, const char *TTarget_constarget_const, const void *Cookie_const)
 Searches for devices matching the given search target.
EXPORT_SPEC int UpnpSendAdvertisement (UpnpDevice_Handle Hnd, int Exp)
 Sends out the discovery announcements for all devices and services for a device.


Generated by  Doxygen 1.6.0   Back to index