#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] | |
| #define | UPNP_E_SUCCESS 0 |
UPNP_E_INVALID_HANDLE [-100] | |
| #define | UPNP_E_INVALID_HANDLE -100 |
UPNP_E_INVALID_PARAM [-101] | |
| #define | UPNP_E_INVALID_PARAM -101 |
UPNP_E_OUTOF_HANDLE [-102] | |
| #define | UPNP_E_OUTOF_HANDLE -102 |
UPNP_E_OUTOF_MEMORY [-104] | |
| #define | UPNP_E_OUTOF_MEMORY -104 |
UPNP_E_INIT [-105] | |
| #define | UPNP_E_INIT -105 |
UPNP_E_INVALID_DESC [-107] | |
| #define | UPNP_E_INVALID_DESC -107 |
UPNP_E_INVALID_URL [-108] | |
| #define | UPNP_E_INVALID_URL -108 |
UPNP_E_INVALID_SERVICE [-111] | |
| #define | UPNP_E_INVALID_SERVICE -111 |
UPNP_E_BAD_RESPONSE [-113] | |
| #define | UPNP_E_BAD_RESPONSE -113 |
UPNP_E_INVALID_ACTION [-115] | |
| #define | UPNP_E_INVALID_ACTION -115 |
UPNP_E_FINISH [-116] | |
| #define | UPNP_E_FINISH -116 |
UPNP_E_INIT_FAILED [-117] | |
| #define | UPNP_E_INIT_FAILED -117 |
UPNP_E_URL_TOO_BIG [-118] | |
| #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] | |
| #define | UPNP_E_ALREADY_REGISTERED -120 |
UPNP_E_NETWORK_ERROR [-200] | |
| #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] | |
| #define | UPNP_E_LISTEN -206 |
UPNP_E_TIMEDOUT [-207] | |
| #define | UPNP_E_TIMEDOUT -207 |
UPNP_E_SOCKET_ERROR [-208] | |
| #define | UPNP_E_SOCKET_ERROR -208 |
UPNP_E_CANCELED [-210] | |
| #define | UPNP_E_CANCELED -210 |
UPNP_E_SUBSCRIBE_UNACCEPTED [-301] | |
| #define | UPNP_E_SUBSCRIBE_UNACCEPTED -301 |
UPNP_E_UNSUBSCRIBE_UNACCAPTED [-302] | |
| #define | UPNP_E_UNSUBSCRIBE_UNACCEPTED -302 |
UPNP_E_NOTIFY_UNACCEPTED [-303] | |
| #define | UPNP_E_NOTIFY_UNACCEPTED -303 |
UPNP_E_INVALID_ARGUMENT [-501] | |
| #define | UPNP_E_INVALID_ARGUMENT -501 |
UPNP_E_FILE_NOT_FOUND [-502] | |
| #define | UPNP_E_FILE_NOT_FOUND -502 |
UPNP_E_FILE_READ_ERROR [-503] | |
| #define | UPNP_E_FILE_READ_ERROR -503 |
UPNP_E_EXT_NOT_XML [-504] | |
| #define | UPNP_E_EXT_NOT_XML -504 |
UPNP_E_NOT_FOUND [-507] | |
| #define | UPNP_E_NOT_FOUND -507 |
UPNP_E_INTERNAL_ERROR [-911] | |
| #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 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_INVALID_ACTION -115 |
Definition at line 235 of file upnp.h.
Referenced by ConnectionManagerService::process_action_request(), and ContentDirectoryService::process_action_request().
| #define UPNP_E_SUCCESS 0 |
Definition at line 134 of file upnp.h.
Referenced by ActionRequest::ActionRequest(), register_web_callbacks(), Server::shutdown(), ActionRequest::update(), ConnectionManagerService::upnp_action_GetCurrentConnectionIDs(), ConnectionManagerService::upnp_action_GetProtocolInfo(), Server::upnp_callback(), and Server::upnp_init().
| #define UPNP_SOAP_E_INVALID_ARGS 402 |
Definition at line 469 of file upnp.h.
Referenced by ContentDirectoryService::upnp_action_Browse().
| typedef struct sockaddr_in SOCKADDRIN |
| typedef enum Upnp_DescType_e Upnp_DescType |
| typedef enum Upnp_EventType_e Upnp_EventType |
| 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.
| typedef char Upnp_SID[44] |
| typedef enum Upnp_SType_e Upnp_SType |
| typedef int UpnpClient_Handle |
| typedef int UpnpDevice_Handle |
| typedef void* UpnpWebFileHandle |
| typedef struct user_HTTP_Header_List userHTTPHeaderList |
| typedef struct virtual_Dir_List virtualDirList |
| enum Upnp_DescType_e |
| enum Upnp_EventType_e |
| 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. |
| enum Upnp_SType_e |
| enum UpnpOpenFileMode |
| 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.
| 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.
| 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.
| 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}.
| 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.
| EXPORT_SPEC int UpnpCloseHttpGet | ( | IN void * | handle | ) |
{ UpnpCloseHttpGet} closes the connection and frees memory that was allocated for the { handle} parameter.
| 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.
| 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.
| 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.
| 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.
| 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.
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.
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.
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}.
| 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}.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
Note: In case of return values, the status code parameter of the passed in handle value may provide additional information on the return value.
| 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.
| 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.
| 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}
| 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.
| EXPORT_SPEC void UpnpRemoveAllVirtualDirs | ( | ) |
{ UpnpRemoveAllVirtualDirs} removes all virtual directory mappings.
| EXPORT_SPEC int UpnpRemoveCustomHTTPHeader | ( | IN const char * | header_string | ) |
{ UpnpRemoveHTTPHeader} removes a header that was previously added with { UpnpAddHTTPHeader}.
| 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}.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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. |
1.6.1