diff --git a/upnp/Makefile.am b/upnp/Makefile.am index 6620246..be15a62 100644 --- a/upnp/Makefile.am +++ b/upnp/Makefile.am @@ -21,7 +21,8 @@ upnpincludedir = $(includedir)/upnp upnpinclude_HEADERS = \ inc/upnp.h \ inc/upnpdebug.h \ - inc/UpnpGlobal.h + inc/UpnpGlobal.h \ + inc/UpnpInet.h nodist_upnpinclude_HEADERS = inc/upnpconfig.h if ENABLE_TOOLS @@ -47,7 +48,6 @@ libupnp_la_SOURCES = \ src/inc/gena_device.h \ src/inc/global.h \ src/inc/gmtdate.h \ - src/inc/http_client.h \ src/inc/httpparser.h \ src/inc/httpreadwrite.h \ src/inc/md5.h \ @@ -111,7 +111,9 @@ libupnp_la_SOURCES += \ src/gena/gena_callback2.c # api -libupnp_la_SOURCES += src/api/upnpapi.c +libupnp_la_SOURCES += \ + src/api/upnpapi.c + if ENABLE_TOOLS libupnp_la_SOURCES += src/api/upnptools.c endif diff --git a/upnp/inc/UpnpInet.h b/upnp/inc/UpnpInet.h new file mode 100644 index 0000000..3d593c5 --- /dev/null +++ b/upnp/inc/UpnpInet.h @@ -0,0 +1,23 @@ + + +#ifndef UPNPINET_H +#define UPNPINET_H + + +/*! + * \file + * + * \brief Provides a platform independent way to include TCP/IP types and functions. + */ + + +#ifdef WIN32 + #include + #include +#else + #include +#endif + + +#endif /* UPNPINET_H */ + diff --git a/upnp/inc/upnp.h b/upnp/inc/upnp.h index 9d4dc37..0a1b8ad 100644 --- a/upnp/inc/upnp.h +++ b/upnp/inc/upnp.h @@ -29,65 +29,62 @@ * ******************************************************************************/ + #ifndef UPNP_H #define UPNP_H -/** @name The API */ -/*! @{ */ +/*! + * \file + * + * \defgroup UPnPAPI UPnP API + * + * @{ + */ -#if defined MYLIB_LARGEFILE_SENSITIVE && _FILE_OFFSET_BITS+0 != 64 - #if defined __GNUC__ - #warning libupnp requires largefile mode - use AC_SYS_LARGEFILE - #else - #error libupnp requires largefile mode - use AC_SYS_LARGEFILE - #endif -#endif - - -#include -#ifndef WIN32 - #include -#endif -#if (defined(BSD) && BSD >= 199306) - #include -#endif #include "ixml.h" #include "upnpconfig.h" #include "UpnpGlobal.h" +#include "UpnpInet.h" /* - * Defining this macro here gives some interesting information about unused - * functions in the code. Of course, this should never go uncommented on a - * release. + * \todo Document the exact reason of these include files and solve this + * include mess in an include file like UpnpTime.h */ -/*#define inline*/ - - -#ifndef WIN32 - #define UpnpCloseSocket close +#ifdef WIN32 + #include +#elif (defined(BSD) && BSD >= 199306) + #include #else + /* Other systems ??? */ +#endif + + +#ifdef WIN32 + /* Do not #include */ +#else + #include +#endif + + +#ifdef WIN32 + #include +#else + #define SOCKET int + #define INVALID_SOCKET (SOCKET)(~0) +#endif + + +#ifdef WIN32 #define UpnpCloseSocket closesocket #define fseeko fseek -#endif -#ifndef WIN32 - #define SOCKET int -#endif - - -#ifndef WIN32 - #include #else - #include - #include + #define UpnpCloseSocket close #endif -#include - - #define NUM_HANDLE 200 #define LINE_SIZE 180 #define NAME_SIZE 256 @@ -95,368 +92,318 @@ #define MODL_NAME_SIZE 32 #define SERL_NUMR_SIZE 64 #define MODL_DESC_SIZE 64 -#define UPNP_INFINITE -1 -#define UPNP_USING_CHUNKED -3 -#define UPNP_UNTIL_CLOSE -4 +#define UPNP_INFINITE -1 +#define UPNP_USING_CHUNKED -3 +#define UPNP_UNTIL_CLOSE -4 -/** @name 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. +/*! + * \name 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. + * + * @{ */ -/*! @{ */ -/** @name UPNP_E_SUCCESS [0] - * {\tt UPNP_E_SUCCESS} signifies that the operation completed successfully. - * For asynchronous functions, this only means that the packet generated by - * the operation was successfully transmitted on the network. The result of - * the entire operation comes as part of the callback for that operation. +/*! + * \brief The operation completed successfully. + * + * For asynchronous functions, this only means that the packet generated by + * the operation was successfully transmitted on the network. The result of + * the entire operation comes as part of the callback for that operation. */ -/*! @{ */ -#define UPNP_E_SUCCESS 0 -/*! @} */ +#define UPNP_E_SUCCESS 0 -/** @name UPNP_E_INVALID_HANDLE [-100] - * {\tt UPNP_E_INVALID_HANDLE} signifies that the handle passed to a - * function is not a recognized as a valid handle. +/*! + * \brief The handle passed to a function is not a recognized as a valid handle. */ -/*! @{ */ -#define UPNP_E_INVALID_HANDLE -100 -/*! @} */ +#define UPNP_E_INVALID_HANDLE -100 -/** @name UPNP_E_INVALID_PARAM [-101] - * {\tt UPNP_E_INVALID_PARAM} signifies that one or more of the parameters - * passed to the function is not valid. Refer to the documentation for each - * function for more information on the valid ranges of the parameters. +/*! + * \brief One or more of the parameters passed to the function is not valid. + * + * Refer to the documentation for each function for more information on the + * valid ranges of the parameters. */ -/*! @{ */ -#define UPNP_E_INVALID_PARAM -101 -/*! @} */ +#define UPNP_E_INVALID_PARAM -101 -/** @name UPNP_E_OUTOF_HANDLE [-102] - * {\tt UPNP_E_OUTOF_HANDLE} signifies that the SDK does not have any - * more space for additional handles. The SDK allocates space for only - * a few handles in order to conserve memory. +/*! + * \brief The SDK does not have any more space for additional handles. + * + * The SDK allocates space for only a few handles in order to conserve memory. */ -/*! @{ */ -#define UPNP_E_OUTOF_HANDLE -102 -/*! @} */ +#define UPNP_E_OUTOF_HANDLE -102 -#define UPNP_E_OUTOF_CONTEXT -103 +#define UPNP_E_OUTOF_CONTEXT -103 -/** @name UPNP_E_OUTOF_MEMORY [-104] - * {\tt UPNP_E_OUTOF_MEMORY} signifies that not enough resources are - * currently available to complete the operation. Most operations require - * some free memory in order to complete their work. +/*! + * \brief Not enough resources are currently available to complete the operation. + * + * Most operations require some free memory in order to complete their work. */ -/*! @{ */ -#define UPNP_E_OUTOF_MEMORY -104 -/*! @} */ +#define UPNP_E_OUTOF_MEMORY -104 -/** @name UPNP_E_INIT [-105] - * {\tt UPNP_E_INIT} signifies that the SDK has already been - * initialized. The SDK needs to be initialied only once per process. - * Any additional initialization attempts simply return this error with - * no other ill effects. +/*! + * \brief The SDK has already been initialized. + * + * The SDK needs to be initialied only once per process. Any additional + * initialization attempts simply return this error with no other ill effects. */ -/*! @{ */ -#define UPNP_E_INIT -105 -/*! @} */ +#define UPNP_E_INIT -105 -#define UPNP_E_BUFFER_TOO_SMALL -106 +#define UPNP_E_BUFFER_TOO_SMALL -106 -/** @name UPNP_E_INVALID_DESC [-107] - * {\tt UPNP_E_INVALID_DESC} signifies that the description document passed - * to {\bf UpnpRegisterRootDevice} or {\bf UpnpRegisterRootDevice2} is an - * invalid description document. +/*! + * \brief The description document passed to \b UpnpRegisterRootDevice or + * \b UpnpRegisterRootDevice2 is invalid. */ -/*! @{ */ -#define UPNP_E_INVALID_DESC -107 -/*! @} */ +#define UPNP_E_INVALID_DESC -107 -/** @name UPNP_E_INVALID_URL [-108] - * {\tt UPNP_E_INVALID_URL} signifies that a URL passed into the function - * is invalid. The actual cause is function specific, but in general, the - * URL itself might be malformed (e.g. have invalid characters in it) or - * the host might be unreachable. +/*! + * \brief An URL passed into the function is invalid. + * + * The actual cause is function specific, but in general, the URL itself + * might be malformed (e.g. have invalid characters in it) or the host might + * be unreachable. */ -/*! @{ */ -#define UPNP_E_INVALID_URL -108 -/*! @} */ +#define UPNP_E_INVALID_URL -108 -#define UPNP_E_INVALID_SID -109 -#define UPNP_E_INVALID_DEVICE -110 +#define UPNP_E_INVALID_SID -109 -/** @name UPNP_E_INVALID_SERVICE [-111] - * {\tt UPNP_E_INVALID_SERVICE} is returned only by {\bf UpnpNotify}, - * {\bf UpnpNotifyExt}, {\bf UpnpAcceptSubscription}, and - * {\bf UpnpAcceptSubscriptionExt} to signify that the device ID/service - * ID pair does not refer to a valid service. +#define UPNP_E_INVALID_DEVICE -110 + +/*! + * \brief The device ID/service ID pair does not refer to a valid service. + * + * Returned only by \b UpnpNotify, \b UpnpNotifyExt, \b UpnpAcceptSubscription, + * and \b UpnpAcceptSubscriptionExt. */ -/*! @{ */ -#define UPNP_E_INVALID_SERVICE -111 -/*! @} */ +#define UPNP_E_INVALID_SERVICE -111 -/** @name UPNP_E_BAD_RESPONSE [-113] - * {\tt UPNP_E_BAD_RESPONSE} signifies that the response received from the - * remote side of a connection is not correct for the protocol. This applies - * to the GENA, SOAP, and HTTP protocols. +/*! + * \brief The response received from the remote side of a connection is not correct + * for the protocol. + * + * This applies to the GENA, SOAP, and HTTP protocols. */ -/*! @{ */ -#define UPNP_E_BAD_RESPONSE -113 -/*! @} */ +#define UPNP_E_BAD_RESPONSE -113 -#define UPNP_E_BAD_REQUEST -114 +#define UPNP_E_BAD_REQUEST -114 -/** @name UPNP_E_INVALID_ACTION [-115] - * {\tt UPNP_E_INVALID_ACTION} signifies that the SOAP action message is - * invalid. This can be because the DOM document passed to the function was - * malformed or the action message is not correct for the given action. +/*! + * \brief The SOAP action message is invalid. + * + * This can be because the DOM document passed to the function was malformed or + * the action message is not correct for the given action. */ -/*! @{ */ -#define UPNP_E_INVALID_ACTION -115 -/*! @} */ +#define UPNP_E_INVALID_ACTION -115 -/** @name UPNP_E_FINISH [-116] - * {\tt UPNP_E_FINISH} signifies that {\bf UpnpInit} has not been called, or - * that {\bf UpnpFinish} has already been called. None of the API functions - * operate until {\bf UpnpInit} successfully completes. +/*! + * \brief \b UpnpInit has not been called, or \b UpnpFinish has already been called. + * + * None of the API functions operate until \b UpnpInit successfully completes. */ -/*! @{ */ -#define UPNP_E_FINISH -116 -/*! @} */ +#define UPNP_E_FINISH -116 -/** @name UPNP_E_INIT_FAILED [-117] - * {\tt UPNP_E_INIT_FAILED} signifies that {\bf UpnpInit} cannot complete. - * The typical reason is failure to allocate sufficient resources. +/*! + * \brief \b UpnpInit cannot complete. + * + * The typical reason is failure to allocate sufficient resources. */ -/*! @{ */ -#define UPNP_E_INIT_FAILED -117 -/*! @} */ +#define UPNP_E_INIT_FAILED -117 -/** @name UPNP_E_URL_TOO_BIG [-118] - * {\tt UPNP_E_URL_TOO_BIG} signifies that the URL passed into a function - * is too long. The SDK limits URLs to 180 characters in length. +/*! + * \brief The URL passed into a function is too long. + * + * The SDK limits URLs to 180 characters in length. */ -#define UPNP_E_URL_TOO_BIG -118 +#define UPNP_E_URL_TOO_BIG -118 -/** @name UPNP_E_BAD_HTTPMSG [-119] - * {\tt 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. {\bf UpnpSendAction}), GENA subscription - * message (e.g. {\bf UpnpSubscribe}), GENA event notifications (e.g. {\bf - * UpnpNotify}), and HTTP transfers (e.g. {\bf UpnpDownloadXmlDoc}). +/*! + * \brief 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. + * \b UpnpSendAction), GENA subscription message (e.g. \b UpnpSubscribe), + * GENA event notifications (e.g. \b UpnpNotify), and HTTP transfers (e.g. + * \b UpnpDownloadXmlDoc). */ -/*! @{ */ -#define UPNP_E_BAD_HTTPMSG -119 -/*! @} */ +#define UPNP_E_BAD_HTTPMSG -119 -/** @name UPNP_E_ALREADY_REGISTERED [-120] - * {\tt UPNP_E_ALREADY_REGISTERED} signifies that a client or a device is - * already registered. The SDK currently has a limit of one registered - * client and one registered device per process. +/*! + * \brief A client or a device is already registered. + * + * The SDK currently has a limit of one registered client and one registered + * device per process. */ -/*! @{ */ -#define UPNP_E_ALREADY_REGISTERED -120 -/*! @} */ +#define UPNP_E_ALREADY_REGISTERED -120 -/** @name UPNP_E_NETWORK_ERROR [-200] - * {\tt UPNP_E_NETWORK_ERROR} signifies that a network error occurred. It - * is the generic error code for network problems that are not covered under - * one of the more specific error codes. The typical meaning is the SDK - * failed to read the local IP address or had problems configuring one of - * the sockets. +/*! + * \brief The interface provided to \b UpnpInit2 is unknown or does not have a valid + * IPv4 or IPv6 address configured. */ -/*! @{ */ -#define UPNP_E_NETWORK_ERROR -200 -/*! @} */ +#define UPNP_E_INVALID_INTERFACE -121 -/** @name UPNP_E_SOCKET_WRITE [-201] - * {\tt 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. {\bf UpnpSearchAsync} or {\bf UpnpSendAdvertisement}), - * control (e.g. {\bf UpnpSendAction}), eventing (e.g. {\bf UpnpNotify}), - * and HTTP functions (e.g. {\bf UpnpDownloadXmlDoc}). +/*! + * \brief A network error occurred. + * + * It is the generic error code for network problems that are not covered under + * one of the more specific error codes. The typical meaning is the SDK failed + * to read the local IP address or had problems configuring one of the sockets. */ -/*! @{ */ -#define UPNP_E_SOCKET_WRITE -201 -/*! @} */ +#define UPNP_E_NETWORK_ERROR -200 -/** @name UPNP_E_SOCKET_READ [-202] - * {\tt 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. {\bf UpnpSearchAsync} or {\bf UpnpSendAdvertisement}), - * control (e.g. {\bf UpnpSendAction}), eventing (e.g. {\bf UpnpNotify}), - * and HTTP functions (e.g. {\bf UpnpDownloadXmlDoc}). +/*! + * \brief An error happened while writing to a socket. + * + * This occurs in any function that makes network connections, such as discovery + * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g. + * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. + * \b UpnpDownloadXmlDoc). */ -/*! @{ */ -#define UPNP_E_SOCKET_READ -202 -/*! @} */ +#define UPNP_E_SOCKET_WRITE -201 -/** @name UPNP_E_SOCKET_BIND [-203] - * {\tt 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. {\bf UpnpSearchAsync} or - * {\bf UpnpSendAdvertisement}), control (e.g. {\bf UpnpSendAction}), eventing - * (e.g. {\bf UpnpNotify}), and HTTP functions (e.g. - * {\bf UpnpDownloadXmlDoc}). +/*! + * \brief An error happened while reading from a socket. + * + * This occurs in any function that makes network connections, such as discovery + * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g. + * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. + * \b UpnpDownloadXmlDoc). */ -/*! @{ */ -#define UPNP_E_SOCKET_BIND -203 -/*! @} */ +#define UPNP_E_SOCKET_READ -202 -/** @name UPNP_E_SOCKET_CONNECT [-204] - * {\tt 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. {\bf UpnpSearchAsync} or - * {\bf UpnpSendAdvertisement}), control (e.g. {\bf UpnpSendAction}), eventing - * (e.g. {\bf UpnpNotify}), and HTTP functions (e.g. - * {\bf UpnpDownloadXmlDoc}). +/*! + * \brief 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. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g. + * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. + * \b UpnpDownloadXmlDoc). */ -/*! @{ */ -#define UPNP_E_SOCKET_CONNECT -204 -/*! @} */ +#define UPNP_E_SOCKET_BIND -203 -/** @name UPNP_E_OUTOF_SOCKET [-205] - * {\tt 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. {\bf UpnpSearchAsync} or - * {\bf UpnpSendAdvertisement}), control (e.g. {\bf UpnpSendAction}), eventing - * (e.g. {\bf UpnpNotify}), and HTTP functions (e.g. - * {\bf UpnpDownloadXmlDoc}). +/*! + * \brief The SDK had a problem connecting to a remote host. + * + * This occurs in any function that makes network connections, such as discovery + * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g. + * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. + * \b UpnpDownloadXmlDoc). */ -/*! @{ */ -#define UPNP_E_OUTOF_SOCKET -205 -/*! @} */ +#define UPNP_E_SOCKET_CONNECT -204 -/** @name UPNP_E_LISTEN [-206] - * {\tt UPNP_E_LISTEN} signifies that the SDK had a problem setting the - * socket to listen for incoming connections. This error only happens during - * initialization (i.e. {\bf UpnpInit}). +/*! + * \brief The SDK cannot create any more sockets. + * + * This occurs in any function that makes network connections, such as discovery + * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g. + * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. + * \b UpnpDownloadXmlDoc). */ -/*! @{ */ -#define UPNP_E_LISTEN -206 -/*! @} */ +#define UPNP_E_OUTOF_SOCKET -205 -/** @name UPNP_E_TIMEDOUT [-207] - * {\tt UPNP_E_TIMEDOUT} signifies that too much time elapsed before the - * required number of bytes were sent or received over a socket. This error - * can be returned by any function that performs network operations. +/*! + * \brief The SDK had a problem setting the socket to listen for incoming + * connections. + * + * This error only happens during initialization (i.e. \b UpnpInit). */ -/*! @{ */ -#define UPNP_E_TIMEDOUT -207 -/*! @} */ +#define UPNP_E_LISTEN -206 -/** @name UPNP_E_SOCKET_ERROR [-208] - * {\tt UPNP_E_SOCKET_ERROR} is the generic socket error code for - * conditions not covered by other error codes. This error can be returned - * by any function that performs network operations. +/*! + * \brief Too much time elapsed before the required number of bytes were sent + * or received over a socket. + * + * This error can be returned by any function that performs network operations. */ -/*! @{ */ -#define UPNP_E_SOCKET_ERROR -208 -/*! @} */ +#define UPNP_E_TIMEDOUT -207 -#define UPNP_E_FILE_WRITE_ERROR -209 - -/** @name UPNP_E_CANCELED [-210] - * {\tt UPNP_E_CANCELED} signifies that the operation was canceled. This - * error can be returned by any function that allows for external - * cancelation. +/*! + * \brief Generic socket error code for conditions not covered by other error + * codes. + * + * This error can be returned by any function that performs network operations. */ -/*! @{ */ -#define UPNP_E_CANCELED -210 -/*! @} */ +#define UPNP_E_SOCKET_ERROR -208 -#define UPNP_E_EVENT_PROTOCOL -300 +#define UPNP_E_FILE_WRITE_ERROR -209 -/** @name UPNP_E_SUBSCRIBE_UNACCEPTED [-301] - * {\tt UPNP_E_SUBSCRIBE_UNACCEPTED} signifies that a subscription - * request was rejected from the remote side. +/*! \brief The operation was canceled. + * + * This error can be returned by any function that allows for external cancelation. */ -/*! @{ */ -#define UPNP_E_SUBSCRIBE_UNACCEPTED -301 -/*! @} */ +#define UPNP_E_CANCELED -210 -/** @name UPNP_E_UNSUBSCRIBE_UNACCEPTED [-302] - * {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED} signifies that an unsubscribe - * request was rejected from the remote side. +#define UPNP_E_EVENT_PROTOCOL -300 + +/*! + * \brief A subscription request was rejected from the remote side. */ -/*! @{ */ -#define UPNP_E_UNSUBSCRIBE_UNACCEPTED -302 -/*! @} */ +#define UPNP_E_SUBSCRIBE_UNACCEPTED -301 -/** @name UPNP_E_NOTIFY_UNACCEPTED [-303] - * {\tt UPNP_E_NOTIFY_UNACCEPTED} signifies that the remote host did not - * accept the notify sent from the local device. +/*! + * \brief An unsubscribe request was rejected from the remote side. */ -/*! @{ */ -#define UPNP_E_NOTIFY_UNACCEPTED -303 -/*! @} */ +#define UPNP_E_UNSUBSCRIBE_UNACCEPTED -302 -/** @name UPNP_E_INVALID_ARGUMENT [-501] - * {\tt UPNP_E_INVALID_ARGUMENT} signifies that one or more of the parameters - * passed to a function is invalid. Refer to the individual function - * descriptions for the acceptable ranges for parameters. +/*! + * \brief The remote host did not accept the notify sent from the local device. */ -/*! @{ */ -#define UPNP_E_INVALID_ARGUMENT -501 -/*! @} */ +#define UPNP_E_NOTIFY_UNACCEPTED -303 -/** @name UPNP_E_FILE_NOT_FOUND [-502] - * {\tt UPNP_E_FILE_NOT_FOUND} signifies that the filename passed - * to one of the device registration functions was not found or was not - * accessible. +/*! + * \brief One or more of the parameters passed to a function is invalid. + * + * Refer to the individual function descriptions for the acceptable ranges for + * parameters. */ -/*! @{ */ -#define UPNP_E_FILE_NOT_FOUND -502 -/*! @} */ +#define UPNP_E_INVALID_ARGUMENT -501 -/** @name UPNP_E_FILE_READ_ERROR [-503] - * {\tt UPNP_E_FILE_READ_ERROR} signifies an error when reading a file. +/*! + * \brief The filename passed to one of the device registration functions was + * not found or was not accessible. */ -/*! @{ */ -#define UPNP_E_FILE_READ_ERROR -503 -/*! @} */ +#define UPNP_E_FILE_NOT_FOUND -502 -/** @name UPNP_E_EXT_NOT_XML [-504] - * {\tt UPNP_E_EXT_NOT_XML} signifies that the file name of the description - * document passed to {\bf UpnpRegisterRootDevice2} does not end in ".xml". +/*! + * \brief An error happened while reading a file. */ -/*! @{ */ -#define UPNP_E_EXT_NOT_XML -504 -/*! @} */ +#define UPNP_E_FILE_READ_ERROR -503 -#define UPNP_E_NO_WEB_SERVER -505 -#define UPNP_E_OUTOF_BOUNDS -506 - -/** @name UPNP_E_NOT_FOUND [-507] - * {\tt UPNP_E_NOT_FOUND} signifies that the response to a SOAP request - * did not contain the required XML constructs. +/*! + * \brief The file name of the description document passed to + * \b UpnpRegisterRootDevice2 does not end in ".xml". */ -/*! @{ */ -#define UPNP_E_NOT_FOUND -507 -/*! @} */ +#define UPNP_E_EXT_NOT_XML -504 -/** @name UPNP_E_INTERNAL_ERROR [-911] - * {\tt UPNP_E_INTERNAL_ERROR} is the generic error code for internal - * conditions not covered by other error codes. +#define UPNP_E_NO_WEB_SERVER -505 +#define UPNP_E_OUTOF_BOUNDS -506 + +/*! + * \brief The response to a SOAP request did not contain the required XML + * constructs. */ -/*! @{ */ -#define UPNP_E_INTERNAL_ERROR -911 -/*! @} */ +#define UPNP_E_NOT_FOUND -507 + +/*! + * \brief Generic error code for internal conditions not covered by other + * error codes. + */ +#define UPNP_E_INTERNAL_ERROR -911 /* SOAP-related 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 +#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 -/*! @} */ +/* @} ErrorCodes */ #ifndef OUT #define OUT @@ -470,208 +417,200 @@ #define INOUT #endif -#include "upnpdebug.h" -enum UpnpOpenFileMode{UPNP_READ, UPNP_WRITE}; -/*! @name Constants, Structures, and Types */ -/*! @{ */ +/*! + * \name Constants and Types + * + * @{ + */ -/** Returned when a control point application registers with {\bf - * UpnpRegisterClient}. Client handles can only be used with - * functions that operate with a client handle. */ +enum UpnpOpenFileMode +{ + UPNP_READ, + UPNP_WRITE +}; +/*! + * \brief Returned when a control point application registers with + * \b UpnpRegisterClient. + * + * Client handles can only be used with functions that operate with a client + * handle. + */ typedef int UpnpClient_Handle; -/** Returned when a device application registers with {\bf - * UpnpRegisterRootDevice} or {\bf UpnpRegisterRootDevice2}. Device handles - * can only be used with functions that operate with a device handle. */ - +/*! + * \brief Returned when a device application registers with + * \b UpnpRegisterRootDevice or \b UpnpRegisterRootDevice2. + * + * Device handles can only be used with functions that operate with a device + * handle. + */ typedef int UpnpDevice_Handle; -/** @name UPnP_EventType - @memo The reason code for an event callback. - @doc The {\bf Event} parameter will be different depending on the - reason for the callback. The descriptions for each event - type describe the contents of the {\bf Event} parameter. - */ - +/*! + * \brief The reason code for an event callback. + * + * The \b Event parameter will be different depending on the reason for the + * callback. The descriptions for each event type describe the contents of the + * \b Event parameter. + */ enum Upnp_EventType_e { + /* + * Control callbacks + */ - /* - * Control callbacks - */ + /*! Received by a device when a control point issues a control + * request. The \b Event parameter contains a pointer to a \b + * UpnpActionRequest structure containing the action. The application + * stores the results of the action in this structure. */ + UPNP_CONTROL_ACTION_REQUEST, - /** Received by a device when a control point issues a control - * request. The {\bf Event} parameter contains a pointer to a {\bf - * Upnp_Action_Request} structure containing the action. The application - * stores the results of the action in this structure. */ + /*! A \b UpnpSendActionAsync call completed. The \b Event + * parameter contains a pointer to a \b UpnpActionComplete structure + * with the results of the action. */ + UPNP_CONTROL_ACTION_COMPLETE, - UPNP_CONTROL_ACTION_REQUEST, + /*! Received by a device when a query for a single service variable + * arrives. The \b Event parameter contains a pointer to a \b + * UpnpStateVarRequest structure containing the name of the variable + * and value. */ + UPNP_CONTROL_GET_VAR_REQUEST, - /** A {\bf UpnpSendActionAsync} call completed. The {\bf Event} - * parameter contains a pointer to a {\bf Upnp_Action_Complete} structure - * with the results of the action. */ + /*! A \b UpnpGetServiceVarStatus call completed. The \b Event + * parameter contains a pointer to a \b UpnpStateVarComplete structure + * containing the value for the variable. */ + UPNP_CONTROL_GET_VAR_COMPLETE, - UPNP_CONTROL_ACTION_COMPLETE, + /* + * Discovery callbacks + */ - /** Received by a device when a query for a single service variable - * arrives. The {\bf Event} parameter contains a pointer to a {\bf - * Upnp_State_Var_Request} structure containing the name of the variable - * and value. */ + /*! Received by a control point when a new device or service is available. + * The \b Event parameter contains a pointer to a \b + * UpnpDiscovery structure with the information about the device + * or service. */ + UPNP_DISCOVERY_ADVERTISEMENT_ALIVE, - UPNP_CONTROL_GET_VAR_REQUEST, + /*! Received by a control point when a device or service shuts down. The \b + * Event parameter contains a pointer to a \b UpnpDiscovery + * structure containing the information about the device or + * service. */ + UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE, - /** A {\bf UpnpGetServiceVarStatus} call completed. The {\bf Event} - * parameter contains a pointer to a {\bf Upnp_State_Var_Complete} structure - * containing the value for the variable. */ + /*! Received by a control point when a matching device or service responds. + * The \b Event parameter contains a pointer to a \b + * UpnpDiscovery structure containing the information about + * the reply to the search request. */ + UPNP_DISCOVERY_SEARCH_RESULT, - UPNP_CONTROL_GET_VAR_COMPLETE, + /*! Received by a control point when the search timeout expires. The + * SDK generates no more callbacks for this search after this + * event. The \b Event parameter is \c NULL. */ + UPNP_DISCOVERY_SEARCH_TIMEOUT, - /* - * Discovery callbacks - */ + /* + * Eventing callbacks + */ - /** Received by a control point when a new device or service is available. - * The {\bf Event} parameter contains a pointer to a {\bf - * Upnp_Discovery} structure with the information about the device - * or service. */ + /*! Received by a device when a subscription arrives. + * The \b Event parameter contains a pointer to a \b + * UpnpSubscriptionRequest structure. At this point, the + * subscription has already been accepted. \b 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 \b UpnpAcceptSubscription. + */ + UPNP_EVENT_SUBSCRIPTION_REQUEST, - UPNP_DISCOVERY_ADVERTISEMENT_ALIVE, + /*! Received by a control point when an event arrives. The \b + * Event parameter contains a \b UpnpEvent structure + * with the information about the event. */ + UPNP_EVENT_RECEIVED, - /** Received by a control point when a device or service shuts down. The {\bf - * Event} parameter contains a pointer to a {\bf Upnp_Discovery} - * structure containing the information about the device or - * service. */ + /*! A \b UpnpRenewSubscriptionAsync call completed. The status of + * the renewal is in the \b Event parameter as a \b + * Upnp_Event_Subscription structure. */ + UPNP_EVENT_RENEWAL_COMPLETE, - UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE, + /*! A \b UpnpSubscribeAsync call completed. The status of the + * subscription is in the \b Event parameter as a \b + * Upnp_Event_Subscription structure. */ + UPNP_EVENT_SUBSCRIBE_COMPLETE, - /** Received by a control point when a matching device or service responds. - * The {\bf Event} parameter contains a pointer to a {\bf - * Upnp_Discovery} structure containing the information about - * the reply to the search request. */ + /*! A \b UpnpUnSubscribeAsync call completed. The status of the + * subscription is in the \b Event parameter as a \b + * UpnpEventSubscribe structure. */ + UPNP_EVENT_UNSUBSCRIBE_COMPLETE, - UPNP_DISCOVERY_SEARCH_RESULT, - - /** Received by a control point when the search timeout expires. The - * SDK generates no more callbacks for this search after this - * event. The {\bf Event} parameter is {\tt NULL}. */ - - UPNP_DISCOVERY_SEARCH_TIMEOUT, - - /* - * Eventing callbacks - */ - - /** Received by a device when a subscription arrives. - * The {\bf Event} parameter contains a pointer to a {\bf - * Upnp_Subscription_Request} structure. At this point, the - * subscription has already been accepted. {\bf 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 {\bf UpnpAcceptSubscription}. - */ - - UPNP_EVENT_SUBSCRIPTION_REQUEST, - - /** Received by a control point when an event arrives. The {\bf - * Event} parameter contains a {\bf Upnp_Event} structure - * with the information about the event. */ - - UPNP_EVENT_RECEIVED, - - /** A {\bf UpnpRenewSubscriptionAsync} call completed. The status of - * the renewal is in the {\bf Event} parameter as a {\bf - * Upnp_Event_Subscription} structure. */ - - UPNP_EVENT_RENEWAL_COMPLETE, - - /** A {\bf UpnpSubscribeAsync} call completed. The status of the - * subscription is in the {\bf Event} parameter as a {\bf - * Upnp_Event_Subscription} structure. */ - - UPNP_EVENT_SUBSCRIBE_COMPLETE, - - /** A {\bf UpnpUnSubscribeAsync} call completed. The status of the - * subscription is in the {\bf Event} parameter as a {\bf - * Upnp_Event_Subscribe} structure. */ - - UPNP_EVENT_UNSUBSCRIBE_COMPLETE, - - /** The auto-renewal of a client subscription failed. - * The {\bf Event} parameter is a {\bf Upnp_Event_Subscribe} structure - * with the error code set appropriately. The subscription is no longer - * valid. */ - - UPNP_EVENT_AUTORENEWAL_FAILED, - - /** A client subscription has expired. This will only occur - * if auto-renewal of subscriptions is disabled. - * The {\bf Event} parameter is a {\bf Upnp_Event_Subscribe} - * structure. The subscription is no longer valid. */ - - UPNP_EVENT_SUBSCRIPTION_EXPIRED + /*! The auto-renewal of a client subscription failed. + * The \b Event parameter is a \b UpnpEventSubscribe structure + * with the error code set appropriately. The subscription is no longer + * valid. */ + UPNP_EVENT_AUTORENEWAL_FAILED, + /*! A client subscription has expired. This will only occur + * if auto-renewal of subscriptions is disabled. + * The \b Event parameter is a \b UpnpEventSubscribe + * structure. The subscription is no longer valid. */ + UPNP_EVENT_SUBSCRIPTION_EXPIRED }; typedef enum Upnp_EventType_e Upnp_EventType; -/** The {\bf Upnp_SID} holds the subscription identifier for a subscription - between a client and a device. The SID is a string representation of - a globally unique id (GUID) and should not be modified. - */ - +/*! + * \brief Holds the subscription identifier for a subscription between a + * client and a device. + * + * The SID is a string representation of a globally unique id (GUID) and should + * not be modified. + */ typedef char Upnp_SID[44]; -/** @name Upnp_SType - @memo Represents the different types of searches that - can be performed using the SDK for UPnP Devices API. - @doc By specifying these different values to - {\bf UpnpSearchAsync}, the control point application - can control the scope of the search from all devices - to specific devices or services. - */ - +/*! + * \brief Represents the different types of searches that can be performed + * using the SDK for UPnP Devices API. + * + * By specifying these different values to \b UpnpSearchAsync, the control + * point application can control the scope of the search from all devices + * to specific devices or services. + */ enum Upnp_SType_e { + /*! Search for all devices and services on the network. */ + UPNP_S_ALL, - /** Search for all devices and services on the network. */ - UPNP_S_ALL, + /*! Search for all root devices on the network. */ + UPNP_S_ROOT, - /** Search for all root devices on the network. */ - UPNP_S_ROOT, + /*! Search for a particular device type or a particular device instance. */ + UPNP_S_DEVICE, - /** Search for a particular device type or a particular device - instance. */ - UPNP_S_DEVICE, - - /** Search for a particular service type, possibly on a particular - * device type or device instance. */ - UPNP_S_SERVICE - + /*! Search for a particular service type, possibly on a particular + * device type or device instance. */ + UPNP_S_SERVICE }; typedef enum Upnp_SType_e Upnp_SType; -/** @name Upnp_DescType - @memo Specifies the type of description in - {\bf UpnpRegisterRootDevice2}. - @doc These values control how {\bf UpnpRegisterRootDevice2} - interprets the {\bf description} parameter. - */ +/*! + * \brief Specifies the type of description in \b UpnpRegisterRootDevice2. + * + * These values control how \b UpnpRegisterRootDevice2 interprets the + * \b description parameter. + */ enum Upnp_DescType_e { - - /** The description is the URL to the description document. */ + /*! The description is the URL to the description document. */ UPNPREG_URL_DESC, - /** The description is a file name on the local file system + /*! The description is a file name on the local file system containing the description of the device. */ UPNPREG_FILENAME_DESC, - /** The description is a pointer to a character array containing + /*! The description is a pointer to a character array containing the XML description document. */ UPNPREG_BUF_DESC - }; typedef enum Upnp_DescType_e Upnp_DescType; @@ -1014,347 +953,377 @@ typedef struct virtual_Dir_List * however, because of this the callback cannot call SDK functions * unless explicitly noted. * - * \begin{verbatim} - int CallbackFxn( Upnp_EventType EventType, void* Event, void* Cookie ); - \end{verbatim} + * \verbatim + int CallbackFxn(Upnp_EventType EventType, void *Event, void *Cookie); + \endverbatim * - * where {\bf EventType} is the event that triggered the callback, - * {\bf Event} is a structure that denotes event-specific information for that - * event, and {\bf Cookie} is the user data passed when the callback was + * where \b EventType is the event that triggered the callback, + * \b Event is a structure that denotes event-specific information for that + * event, and \b Cookie is the user data passed when the callback was * registered. * - * See {\bf Upnp_EventType} for more information on the callback values and - * the associated {\bf Event} parameter. + * See \b Upnp_EventType for more information on the callback values and + * the associated \b Event parameter. * - * The return value of the callback is currently ignored. It may be used + * The return value of the callback is currently ignored. It may be used * in the future to communicate results back to the SDK. */ +typedef int (*Upnp_FunPtr)( + /*! [in] .*/ + Upnp_EventType EventType, + /*! [in] .*/ + void *Event, + /*! [in] .*/ + void *Cookie); -typedef int (*Upnp_FunPtr) ( - IN Upnp_EventType EventType, - IN void *Event, - IN void *Cookie - ); +/* @} Constants and Types */ -/*! @} */ /* Constants, Structures, and Types */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ -/*! @name Initialization and Registration */ -/*! @{ */ -/** 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 {\tt 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. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist - * to initialize the SDK. - * \item {\tt UPNP_E_INIT}: The SDK is already initialized. - * \item {\tt UPNP_E_INIT_FAILED}: The SDK initialization - * failed for an unknown reason. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_LISTEN}: An error occurred listening to a socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error ocurred creating a socket. - * \item {\tt UPNP_E_INTERNAL_ERROR}: An internal error ocurred. - * \end{itemize} */ +/*! + * \name Initialization and Registration + * + * @{ + */ + + +/*! + * \brief Initializes the Linux SDK for UPnP Devices. + * + * \deprecated Kept for backwards compatibility. Use UpnpInit2 for new + * implementations. + * + * 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 + * \c 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. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist + * to initialize the SDK. + * \li \c UPNP_E_INIT: The SDK is already initialized. + * \li \c UPNP_E_INIT_FAILED: The SDK initialization + * failed for an unknown reason. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_LISTEN: An error occurred listening to a socket. + * \li \c UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket. + * \li \c UPNP_E_INTERNAL_ERROR: An internal error ocurred. + */ EXPORT_SPEC int UpnpInit( - IN const char *HostIP, /** The host IP address to use, in - string format, for example "192.168.0.1", - or {\tt NULL} to use the first adapter's - IP address. */ - IN unsigned short DestPort /** The destination port number to use. 0 - will pick an arbitrary free port. */ - ); + /*! The host local IP address to use, in string format, for example + * "192.168.0.1", or \c NULL to use the first adapter's IP address. */ + const char *HostIP, + /*! Local Port to listen for incoming connections + * \c NULL will pick an arbitrary free port. */ + unsigned short DestPort); -/** 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 {\tt UPNP_E_FINISH} error code. + + +/*! + * \brief Terminates the Linux SDK for UPnP Devices. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_FINISH}: The SDK is already terminated or + * \li Checks for pending jobs and threads + * \li Unregisters either the client or device + * \li Shuts down the Timer Thread + * \li Stops the Mini Server + * \li Uninitializes the Thread Pool + * \li For Win32 cleans up Winsock Interface + * \li Cleans up mutex objects + * + * This function must be the last API function called. It should be called only + * once. Subsequent calls to this API return a \c UPNP_E_FINISH error code. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_FINISH: The SDK is already terminated or * it is not initialized. - * \end{itemize} */ - + */ EXPORT_SPEC int UpnpFinish(); -/** If '0' is used as the port number in {\bf UpnpInit}, then this - * function can be used to retrieve the actual port allocated to - * the SDK. If {\bf UpnpInit} has not succeeded then 0 is - * returned. + +/*! + * \brief Returns the internal server IPv4 UPnP listening port. * - * @return [unsigned short] The port on which an internal server is - * listening for UPnP related requests. + * If '0' is used as the port number in \b UpnpInit, then this function can be + * used to retrieve the actual port allocated to the SDK. + * + * \return + * \li On success: The port on which an internal server is listening for IPv4 UPnP + * related requests. + * \li On error: 0 is returned if \b UpnpInit has not succeeded. */ -EXPORT_SPEC unsigned short UpnpGetServerPort(void); +EXPORT_SPEC unsigned short UpnpGetServerPort(); -/** If {\tt NULL} is used as the IP address in {\bf UpnpInit}, then this - * function can be used to retrieve the actual interface address - * on which device is running. If {\bf UpnpInit} has not succeeded - * then {\tt NULL} is returned. + +/*! + * \brief Returns the local IPv4 listening ip address. * - * @return [char*] The IP address on which an internal server is listening - * for UPnP related requests. + * If \c NULL is used as the IPv4 address in \b UpnpInit, then this function can + * be used to retrieve the actual interface address on which device is running. + * + * \return + * \li On success: The IPv4 address on which an internal server is + * listening for UPnP related requests. + * \li On error: \c NULL is returned if \b UpnpInit has not succeeded. */ -EXPORT_SPEC char * UpnpGetServerIpAddress(void); +EXPORT_SPEC char *UpnpGetServerIpAddress(); -/** {\bf 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. - * - * {\bf UpnpRegisterClient} is a synchronous call and generates no callbacks. - * Callbacks can occur as soon as this function returns. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_FINISH}: The SDK is already terminated or - * is not initialized. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd} - * is not a valid pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * register this control point. - * \end{itemize} - */ -EXPORT_SPEC int UpnpRegisterClient( - IN Upnp_FunPtr Callback, /** Pointer to a function for receiving - asynchronous events. */ - IN const void *Cookie, /** Pointer to user data returned with the - callback function when invoked. */ - OUT UpnpClient_Handle *Hnd /** Pointer to a variable to store the - new control point handle. */ - ); - -/** {\bf 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 {\bf UpnpRegisterClient} - * to get a control point handle to perform control point - * functionality). +/*! + * \brief Registers a device application with the UPnP Library. * - * {\bf UpnpRegisterRootDevice} is synchronous and does not generate - * any callbacks. Callbacks can occur as soon as this function returns. + * A device application cannot make any other API calls until it registers + * using this function. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_FINISH}: The SDK is already terminated or - * is not initialized. - * \item {\tt UPNP_E_INVALID_DESC}: The description document was not - * a valid device description. - * \item {\tt UPNP_E_INVALID_URL}: The URL for the description document + * Device applications can also register as control points (see + * \b UpnpRegisterClient to get a control point handle to perform control + * point functionality). + * + * This is a synchronous call and does not generate any callbacks. Callbacks + * can occur as soon as this function returns. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_FINISH: The SDK is already terminated or is not + * initialized. + * \li \c UPNP_E_INVALID_DESC: The description document was not + * a valid device description. + * \li \c UPNP_E_INVALID_URL: The URL for the description document * is not valid. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd} - * is not a valid pointer or {\bf DescURL} is {\tt NULL}. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing + * \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd + * is not a valid pointer or \b DescURL is \c NULL. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently * allocated. - * \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to + * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to * register this root device. - * \end{itemize} */ - -EXPORT_SPEC int UpnpRegisterRootDevice( - IN const char *DescUrl, /** Pointer to a string containing the - description URL for this root device - instance. */ - IN Upnp_FunPtr Callback, /** Pointer to the callback function for - receiving asynchronous events. */ - IN const void *Cookie, /** Pointer to user data returned with the - callback function when invoked. */ - OUT UpnpDevice_Handle *Hnd /** Pointer to a variable to store the - new device handle. */ - ); - -/** {\bf UpnpRegisterRootDevice2} is similar to {\bf 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 {\bf 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. {\tt config_baseURL = 0}.) - * - * {\bf 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: - * \begin{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 - \end{verbatim} - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_FINISH}: The SDK is already terminated or - * is not initialized. - * \item {\tt UPNP_E_INVALID_DESC}: The description document is not - * a valid device description. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd} - * is not a valid pointer or {\bf DescURL} is {\tt NULL}. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the - * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently - * allocated. - * \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to - * register this root device. - * \item {\tt UPNP_E_URL_TOO_BIG}: Length of the URL is bigger than the - * internal buffer. - * \item {\tt UPNP_E_FILE_NOT_FOUND}: The description file could not - * be found. - * \item {\tt UPNP_E_FILE_READ_ERROR}: An error occurred reading the - * description file. - * \item {\tt UPNP_E_INVALID_URL}: The URL to the description document - * is invalid. - * \item {\tt UPNP_E_EXT_NOT_XML}: The URL to the description document - * or file should have a {\tt .xml} extension. - * \item {\tt UPNP_E_NO_WEB_SERVER}: The internal web server has been - * compiled out; the SDK cannot configure itself from the - * description document. - * \end{itemize} */ - -EXPORT_SPEC int UpnpRegisterRootDevice2( - IN Upnp_DescType descriptionType,/** The type of the description - document. */ - IN const char* description, /** Treated as a URL, file name or - memory buffer depending on - description type. */ - IN size_t bufferLen, /** The length of memory buffer if - passing a description in a buffer, - otherwise it is ignored. */ - IN int config_baseURL, /** If nonzero, {\tt URLBase} of - description document is - configured and the description - is served using the internal - web server. */ - IN Upnp_FunPtr Fun, /** Pointer to the callback function - for receiving asynchronous - events. */ - IN const void* Cookie, /** Pointer to user data returned - with the callback function when - invoked. */ - OUT UpnpDevice_Handle* Hnd /** Pointer to a variable to store - the new device handle. */ - ); - -/** {\bf UpnpUnRegisterClient} unregisters a control point application, - * unsubscribing all active subscriptions. After this call, the - * {\bf UpnpClient_Handle} is no longer valid. - * - * {\bf UpnpUnRegisterClient} is a synchronous call and generates no - * callbacks. The SDK generates no more callbacks after this - * function returns. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \end{itemize} */ - -EXPORT_SPEC int UpnpUnRegisterClient( - IN UpnpClient_Handle Hnd /** The handle of the control point instance - to unregister. */ - ); - -/** Unregisters a root device registered with {\bf UpnpRegisterRootDevice} or - * {\bf UpnpRegisterRootDevice2}. After this call, the - * {\bf UpnpDevice_Handle} is no longer valid. For all advertisements that - * have not yet expired, the SDK sends a device unavailable message - * automatically. - * - * {\bf UpnpUnRegisterRootDevice} is a synchronous call and generates no - * callbacks. Once this call returns, the SDK will no longer - * generate callbacks to the application. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid - * device handle. - * \end{itemize} */ +EXPORT_SPEC int UpnpRegisterRootDevice( + /*! [in] Pointer to a string containing the description URL for this root device + * instance. */ + const char *DescUrl, + /*! [in] Pointer to the callback function for receiving asynchronous events. */ + Upnp_FunPtr Callback, + /*! [in] Pointer to user data returned with the callback function when invoked. */ + const void *Cookie, + /*! [out] Pointer to a variable to store the new device handle. */ + UpnpDevice_Handle *Hnd); +/*! + * \brief Registers a device application with the UPnP Library. Similar to + * \b 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 \b UpnpSetWebServerRootDir) before calling this function. + * The only condition where the web server can be absent is if the + * description document is specified as a URL and no configuration is + * required (i.e. config_baseURL = 0.) + * + * This is a synchronous call and does not generate any callbacks. Callbacks + * can occur as soon as this function returns. + * + * Examples of using different types of description documents: + * \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 + \endverbatim + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_FINISH: The SDK is already terminated or + * is not initialized. + * \li \c UPNP_E_INVALID_DESC: The description document is not + * a valid device description. + * \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd + * is not a valid pointer or \b DescURL is \c NULL. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the + * socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. + * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to + * register this root device. + * \li \c UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the + * internal buffer. + * \li \c UPNP_E_FILE_NOT_FOUND: The description file could not + * be found. + * \li \c UPNP_E_FILE_READ_ERROR: An error occurred reading the + * description file. + * \li \c UPNP_E_INVALID_URL: The URL to the description document + * is invalid. + * \li \c UPNP_E_EXT_NOT_XML: The URL to the description document + * or file should have a .xml extension. + * \li \c UPNP_E_NO_WEB_SERVER: The internal web server has been + * compiled out; the SDK cannot configure itself from the + * description document. + */ +EXPORT_SPEC int UpnpRegisterRootDevice2( + /*! [in] The type of the description document. */ + Upnp_DescType descriptionType, + /*! [in] Treated as a URL, file name or memory buffer depending on + * description type. */ + const char* description, + /*! [in] The length of memory buffer if passing a description in a buffer, + * otherwise it is ignored. */ + size_t bufferLen, + /*! [in] If nonzero, \c URLBase of description document is configured and + * the description is served using the internal web server. */ + int config_baseURL, + /*! [in] Pointer to the callback function for receiving asynchronous events. */ + Upnp_FunPtr Fun, + /*! [in] Pointer to user data returned with the callback function when + * invoked. */ + const void* Cookie, + /*! [out] Pointer to a variable to store the new device handle. */ + UpnpDevice_Handle* Hnd); + + +/*! + * \brief Unregisters a root device registered with \b UpnpRegisterRootDevice or + * \b UpnpRegisterRootDevice2. + * + * After this call, the \b UpnpDevice_Handle is no longer valid. For all + * advertisements that have not yet expired, the SDK sends a device unavailable + * message automatically. + * + * This is a synchronous call and generates no callbacks. Once this call + * returns, the SDK will no longer generate callbacks to the application. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device handle. + */ EXPORT_SPEC int UpnpUnRegisterRootDevice( - IN UpnpDevice_Handle /** The handle of the root device instance to - unregister. */ - ); + /*! [in] The handle of the root device instance to unregister. */ + UpnpDevice_Handle Hnd); -/** OBSOLETE METHOD : use {\bf UpnpSetMaxContentLength} instead. +/*! + * \brief Registers a control point application with the UPnP Library. + * + * A control point application cannot make any other API calls until it + * registers using this function. + * + * \b UpnpRegisterClient is a synchronous call and generates no callbacks. + * Callbacks can occur as soon as this function returns. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_FINISH: The SDK is already terminated or + * is not initialized. + * \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd + * is not a valid pointer. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * register this control point. + */ +EXPORT_SPEC int UpnpRegisterClient( + /*! [in] Pointer to a function for receiving asynchronous events. */ + Upnp_FunPtr Callback, + /*! [in] Pointer to user data returned with the callback function when invoked. */ + const void *Cookie, + /*! [out] Pointer to a variable to store the new control point handle. */ + UpnpClient_Handle *Hnd); + + +/*! + * \brief Unregisters a control point application, unsubscribing all active + * subscriptions. + * + * This function unregisters a client registered with UpnpRegisterclient or + * UpnpRegisterclient2. After this call, the \b UpnpClient_Handle is no longer + * valid. The UPnP Library generates no more callbacks after this function + * returns. + * + * \b UpnpUnRegisterClient is a synchronous call and generates no + * callbacks. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle. + */ +EXPORT_SPEC int UpnpUnRegisterClient( + /*! [in] The handle of the control point instance to unregister. */ + UpnpClient_Handle Hnd); + + +/*! + * \deprecated Use \b UpnpSetMaxContentLength instead. + * * Warning: the Handle argument provided here is not used, so the effect - * of this function is global to the SDK (= same as - * {\bf UpnpSetMaxContentLength} ). + * of this function is global to the SDK (= same as \b UpnpSetMaxContentLength). */ EXPORT_SPEC int UpnpSetContentLength( - IN UpnpClient_Handle Hnd, - IN int contentLength - ); + /*! [in] The handle of the device instance for which the coincoming content + * length needs to be set. */ + UpnpClient_Handle Hnd, + /*! [in] Permissible content length */ + int 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 {\tt DEFAULT_SOAP_CONTENT_LENGTH} - * = 16K bytes. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \end{itemize} +/*! + * \brief 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 \c DEFAULT_SOAP_CONTENT_LENGTH + * = 16K bytes. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. */ EXPORT_SPEC int UpnpSetMaxContentLength( - IN size_t contentLength /** The maximum permissible content length - for incoming SOAP actions, in bytes. */ - ); + /*! [in] The maximum permissible content length for incoming SOAP actions, + * in bytes. */ + size_t contentLength); + + +/* @} Initialization and Registration */ -/*! @} */ /* Initialization and Registration */ /****************************************************************************** ****************************************************************************** @@ -1364,67 +1333,75 @@ EXPORT_SPEC int UpnpSetMaxContentLength( ****************************************************************************** ******************************************************************************/ -/*! @name Discovery */ -/*! @{ */ -/** {\bf UpnpSearchAsync} searches for devices matching the given - * search target. The function returns immediately and the SDK - * calls the default callback function, registered during the - * {\bf UpnpRegisterClient} call, for each matching root device, - * device, or service. The application specifies the search type by the - * {\bf Target} parameter. +/*! + * \name Discovery * - * 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. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf Target} is {\tt NULL}. - * \end{itemize} */ + * @{ + */ + +/*! + * \brief Searches for devices matching the given search target. + * + * The function returns immediately and the SDK calls the default callback + * function, registered during the \b UpnpRegisterClient call, for each + * matching root device, device, or service. The application specifies the + * search type by the \b Target parameter. + * + * This function searches for the devices for the provided maximum time. + * It is an asynchronous function. It schedules a search job and returns. + * The client is notified about the search results after search timer. + * + * Note that there is no way for the SDK to distinguish which client + * instance issued a particular search. Therefore, the client can get + * search callbacks that do not match the original criteria of the search. + * Also, the application will receive multiple callbacks for each search. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_PARAM: \b Target is \c NULL. + */ EXPORT_SPEC int UpnpSearchAsync( - IN UpnpClient_Handle Hnd, /** The handle of the client performing - the search. */ - IN int Mx, /** The time, in seconds, to wait for - responses. If the time is greater - than {\tt MAX_SEARCH_TIME} then the time is - set to {\tt MAX_SEARCH_TIME}. If the time is - less than {\tt MIN_SEARCH_TIME} then the - time is set to {\tt MIN_SEARCH_TIME}. */ - IN const char *Target, /** The search target as defined in the UPnP - Device Architecture v1.0 specification. */ - IN const void *Cookie /** The user data to pass when the callback - function is invoked. */ - ); + /*! The handle of the client performing the search. */ + UpnpClient_Handle Hnd, + /*! The time, in seconds, to wait for responses. If the time is greater + * than \c MAX_SEARCH_TIME then the time is set to \c MAX_SEARCH_TIME. + * If the time is less than \c MIN_SEARCH_TIME then the time is set to + * \c MIN_SEARCH_TIME. */ + int Mx, + /*! The search target as defined in the UPnP Device Architecture v1.0 + * specification. */ + const char *TTarget_constarget_const, + /*! The user data to pass when the callback function is invoked. */ + const void *Cookie_const); -/** {\bf UpnpSendAdvertisement} sends out the discovery announcements for - * all devices and services for a device. Each announcement is made with - * the same expiration time. +/*! + * \brief Sends out the discovery announcements for all devices and services + * for a device. * - * {\bf UpnpSendAdvertisement} is a synchronous call. + * Each announcement is made with the same expiration time. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid - * device handle. - * \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to - * send future advertisements. - * \end{itemize} + * This is a synchronous call. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid + * device handle. + * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to + * send future advertisements. */ EXPORT_SPEC int UpnpSendAdvertisement( - IN UpnpDevice_Handle Hnd, /** The device handle for which to send out the - announcements. */ - IN int Exp /** The expiration age, in seconds, of - the announcements. */ - ); + /*! The device handle for which to send out the announcements. */ + UpnpDevice_Handle Hnd, + /*! The expiration age, in seconds, of the announcements. */ + int Exp); + + +/* @} Discovery */ -/*! @} */ /* Discovery */ /****************************************************************************** ****************************************************************************** @@ -1434,231 +1411,249 @@ EXPORT_SPEC int UpnpSendAdvertisement( ****************************************************************************** ******************************************************************************/ -/*! @name Control */ -/*! @{ */ -/** {\bf 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. {\bf Note that the use of this - * function is deprecated by the UPnP Forum}. +/*! + * \name Control * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL. - * \item {\tt UPNP_E_INVALID_DESC}: The XML document was not - * found or it does not contain a valid XML description. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf StVarVal} is not a valid - * pointer or {\bf VarName} or {\bf ActionUrl} is {\tt NULL}. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \item {\tt UPNP_SOAP_E_INVALID_VAR}: The given variable is invalid - * according to the device. - * \end{itemize} + * @{ */ + +/*! + * \brief Queries the state of a state variable of a service on another device. + * + * \deprecated + * The use of this function is deprecated by the UPnP Forum. + * + * This is a synchronous call. + * + * A positive return value indicates a SOAP error code, whereas a negative + * return code indicates an SDK error code. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_URL: \b ActionUrl is not a valid URL. + * \li \c UPNP_E_INVALID_DESC: The XML document was not + * found or it does not contain a valid XML description. + * \li \c UPNP_E_INVALID_PARAM: \b StVarVal is not a valid + * pointer or \b VarName or \b ActionUrl is \c NULL. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. + * \li \c UPNP_SOAP_E_INVALID_VAR: The given variable is invalid + * according to the device. + */ EXPORT_SPEC int UpnpGetServiceVarStatus( - IN UpnpClient_Handle Hnd, /** The handle of the control point. */ - IN const char *ActionURL, /** The URL of the service. */ - IN const char *VarName, /** The name of the variable to query. */ - OUT DOMString *StVarVal /** The pointer to store the value - for {\bf VarName}. The SDK - allocates this string and the caller - needs to free it using - {\bf ixmlFreeDOMString}. */ - ); + /*! [in] The handle of the control point. */ + UpnpClient_Handle Hnd, + /*! [in] The URL of the service. */ + const char *ActionURL, + /*! [in] The name of the variable to query. */ + const char *VarName, + /*! [out] The pointer to store the value for \b VarName. The SDK allocates + * this string and the caller needs to free it using + * \b ixmlFreeDOMString. */ + DOMString *StVarVal); -/** {\bf UpnpGetServiceVarStatusAsync} queries the state of a variable of a - * service, generating a callback when the operation is complete. {\bf Note - * that the use of this function is deprecated by the UPnP Forum}. + +/*! + * \brief Queries the state of a variable of a service, generating a callback + * when the operation is complete. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf ActionUrl} is not a valid URL. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf VarName}, {\bf Fun} or - * {\bf ActionUrl} is not a valid pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * \deprecated + * The use of this function is deprecated by the UPnP Forum. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_URL: The \b ActionUrl is not a valid URL. + * \li \c UPNP_E_INVALID_PARAM: \b VarName, \b Fun or + * \b ActionUrl is not a valid pointer. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpGetServiceVarStatusAsync( - IN UpnpClient_Handle Hnd, /** The handle of the control point. */ - IN const char *ActionURL, /** The URL of the service. */ - IN const char *VarName, /** The name of the variable to query. */ - IN Upnp_FunPtr Fun, /** Pointer to a callback function to - be invoked when the operation is complete. */ - IN const void *Cookie /** Pointer to user data to pass to the - callback function when invoked. */ - ); + /*! [in] The handle of the control point. */ + UpnpClient_Handle Hnd, + /*! [in] The URL of the service. */ + const char *ActionURL, + /*! [in] The name of the variable to query. */ + const char *VarName, + /*! [in] Pointer to a callback function to be invoked when the operation + * is complete. */ + Upnp_FunPtr Fun, + /*! [in] Pointer to user data to pass to the callback function when invoked. */ + const void *Cookie); -/** {\bf 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. + +/*! + * \brief 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 {\bf RespNode}. - * A negative return value indicates an SDK error. + * Note that a positive return value indicates a SOAP-protocol error code. + * In this case, the error description can be retrieved from \b RespNode. + * A negative return value indicates an SDK error. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL. - * \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid. - * \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is not a - * valid device. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf ServiceType}, {\bf Action}, - * {\bf ActionUrl}, or - * {\bf RespNode} is not a valid pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_URL: \b ActionUrl is not a valid URL. + * \li \c UPNP_E_INVALID_ACTION: This action is not valid. + * \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is not a + * valid device. + * \li \c UPNP_E_INVALID_PARAM: \b ServiceType, \b Action, + * \b ActionUrl, or + * \b RespNode is not a valid pointer. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpSendAction( - IN UpnpClient_Handle Hnd, /** The handle of the control point - sending the action. */ - IN const char *ActionURL, /** The action URL of the service. */ - IN const char *ServiceType, /** The type of the service. */ - IN const char *DevUDN, /** This parameter is ignored and must be - {\tt NULL}. */ - IN IXML_Document *Action, /** The DOM document for the action. */ - OUT IXML_Document **RespNode /** The DOM document for the response - to the action. The SDK allocates - this document and the caller needs to free - it. */ - ); + /*! [in] The handle of the control point sending the action. */ + UpnpClient_Handle Hnd, + /*! [in] The action URL of the service. */ + const char *ActionURL, + /*! [in] The type of the service. */ + const char *ServiceType, + /*! [in] This parameter is ignored and must be \c NULL. */ + const char *DevUDN, + /*! [in] The DOM document for the action. */ + IXML_Document *Action, + /*! [out] The DOM document for the response to the action. The SDK allocates + * this document and the caller needs to free it. */ + IXML_Document **RespNode); -/** {\bf 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. + +/*! + * \brief Sends a message to change a state variable in a service. * - * Note that a positive return value indicates a SOAP-protocol error code. - * In this case, the error description can be retrieved from {\bf RespNode}. - * A negative return value indicates an SDK error. + * This is a synchronous call that does not return until the action is complete. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL. - * \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid. - * \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is not a - * valid device. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf ServiceType}, {\bf Action}, - * {\bf ActionUrl}, or - * {\bf RespNode} is not a valid pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * Note that a positive return value indicates a SOAP-protocol error code. + * In this case, the error description can be retrieved from \b RespNode. + * A negative return value indicates an SDK error. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_URL: \b ActionUrl is not a valid URL. + * \li \c UPNP_E_INVALID_ACTION: This action is not valid. + * \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is not a + * valid device. + * \li \c UPNP_E_INVALID_PARAM: \b ServiceType, \b Action, + * \b ActionUrl, or + * \b RespNode is not a valid pointer. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpSendActionEx( - IN UpnpClient_Handle Hnd, /** The handle of the control point - sending the action. */ - IN const char *ActionURL, /** The action URL of the service. */ - IN const char *ServiceType, /** The type of the service. */ - IN const char *DevUDN, /** This parameter is ignored and must be - {\tt NULL}. */ - IN IXML_Document *Header, /** The DOM document for the SOAP header. - This may be {\tt NULL} if the header is - not required. */ - IN IXML_Document *Action, /** The DOM document for the action. */ - OUT IXML_Document **RespNode /** The DOM document for the response - to the action. The SDK allocates - this document and the caller needs to free - it. */ - ); + /*! [in] The handle of the control point sending the action. */ + UpnpClient_Handle Hnd, + /*! [in] The action URL of the service. */ + const char *ActionURL, + /*! [in] The type of the service. */ + const char *ServiceType, + /*! [in] This parameter is ignored and must be \c NULL. */ + const char *DevUDN, + /*! [in] The DOM document for the SOAP header. This may be \c NULL if the + * header is not required. */ + IXML_Document *Header, + /*! [in] The DOM document for the action. */ + IXML_Document *Action, + /*! [out] The DOM document for the response to the action. The SDK allocates + * this document and the caller needs to free it. */ + IXML_Document **RespNode); -/** {\bf UpnpSendActionAsync} sends a message to change a state variable - * in a service, generating a callback when the operation is complete. - * See {\bf UpnpSendAction} for comments on positive return values. These - * positive return values are sent in the event struct associated with the - * {\tt UPNP_CONTROL_ACTION_COMPLETE} event. + +/*! + * \brief Sends a message to change a state variable in a service, generating a + * callback when the operation is complete. + * + * See \b UpnpSendAction for comments on positive return values. These + * positive return values are sent in the event struct associated with the + * \c UPNP_CONTROL_ACTION_COMPLETE event. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is an invalid URL. - * \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is an invalid device. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid - * callback function or {\bf ServiceType}, {\bf Act}, or - * {\bf ActionUrl} is {\tt NULL}. - * \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_URL: \b ActionUrl is an invalid URL. + * \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is an invalid device. + * \li \c UPNP_E_INVALID_PARAM: Either \b Fun is not a valid + * callback function or \b ServiceType, \b Act, or + * \b ActionUrl is \c NULL. + * \li \c UPNP_E_INVALID_ACTION: This action is not valid. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpSendActionAsync( - IN UpnpClient_Handle Hnd, /** The handle of the control point - sending the action. */ - IN const char *ActionURL, /** The action URL of the service. */ - IN const char *ServiceType, /** The type of the service. */ - IN const char *DevUDN, /** This parameter is ignored and must be - {\tt NULL}. */ - IN IXML_Document *Action, /** The DOM document for the action to - perform on this device. */ - IN Upnp_FunPtr Fun, /** Pointer to a callback function to - be invoked when the operation - completes. */ - IN const void *Cookie /** Pointer to user data that to be - passed to the callback when invoked. */ - ); + /*! [in] The handle of the control point sending the action. */ + UpnpClient_Handle Hnd, + /*! [in] The action URL of the service. */ + const char *ActionURL, + /*! [in] The type of the service. */ + const char *ServiceType, + /*! [in] This parameter is ignored and must be \c NULL. */ + const char *DevUDN, + /*! [in] The DOM document for the action to perform on this device. */ + IXML_Document *Action, + /*! [in] Pointer to a callback function to be invoked when the operation + * completes. */ + Upnp_FunPtr Fun, + /*! [in] Pointer to user data that to be passed to the callback when + * invoked. */ + const void *Cookie); -/** {\bf UpnpSendActionExAsync} sends a message to change a state variable - * in a service, generating a callback when the operation is complete. - * See {\bf UpnpSendAction} for comments on positive return values. These - * positive return values are sent in the event struct associated with the - * {\tt UPNP_CONTROL_ACTION_COMPLETE} event. + +/*! + * \brief Sends a message to change a state variable in a service, generating a + * callback when the operation is complete. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is an invalid URL. - * \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is an invalid device. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid - * callback function or {\bf ServiceType}, {\bf Act}, or - * {\bf ActionUrl} is {\tt NULL}. - * \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * See \b UpnpSendAction for comments on positive return values. These + * positive return values are sent in the event struct associated with the + * \c UPNP_CONTROL_ACTION_COMPLETE event. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_URL: \b ActionUrl is an invalid URL. + * \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is an invalid device. + * \li \c UPNP_E_INVALID_PARAM: Either \b Fun is not a valid + * callback function or \b ServiceType, \b Act, or + * \b ActionUrl is \c NULL. + * \li \c UPNP_E_INVALID_ACTION: This action is not valid. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpSendActionExAsync( - IN UpnpClient_Handle Hnd, /** The handle of the control point - sending the action. */ - IN const char *ActionURL, /** The action URL of the service. */ - IN const char *ServiceType, /** The type of the service. */ - IN const char *DevUDN, /** This parameter is ignored and must be - {\tt NULL}. */ - IN IXML_Document *Header, /** The DOM document for the SOAP header. - This may be {\tt NULL} if the header is - not required. */ - IN IXML_Document *Action, /** The DOM document for the action to - perform on this device. */ - IN Upnp_FunPtr Fun, /** Pointer to a callback function to - be invoked when the operation - completes. */ - IN const void *Cookie /** Pointer to user data that to be - passed to the callback when invoked. */ - ); + /*! [in] The handle of the control point sending the action. */ + UpnpClient_Handle Hnd, + /*! [in] The action URL of the service. */ + const char *ActionURL, + /*! [in] The type of the service. */ + const char *ServiceType, + /*! [in] This parameter is ignored and must be \c NULL. */ + const char *DevUDN, + /*! [in] The DOM document for the SOAP header. This may be \c NULL if the + * header is not required. */ + IXML_Document *Header, + /*! [in] The DOM document for the action to perform on this device. */ + IXML_Document *Action, + /*! [in] Pointer to a callback function to be invoked when the operation + * completes. */ + Upnp_FunPtr Fun, + /*! [in] Pointer to user data that to be passed to the callback when + * invoked. */ + const void *Cookie); + + +/*! @} Control */ -/*! @} */ /* Control */ /****************************************************************************** ****************************************************************************** @@ -1668,511 +1663,506 @@ EXPORT_SPEC int UpnpSendActionExAsync( ****************************************************************************** ******************************************************************************/ -/*! @name Eventing */ -/*! @{ */ -/** {\bf 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 - * {\tt UPNP_EVENT_SUBSCRIPTION_REQUEST} callback. This function is - * synchronous and generates no callbacks. +/*! + * \name Eventing * - * {\bf UpnpAcceptSubscription} can be called during the execution of - * a callback function. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device - * handle. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} - * pair refers to an invalid service. - * \item {\tt UPNP_E_INVALID_SID}: The specified subscription ID is not - * valid. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName}, - * {\bf NewVal}, {\bf DevID}, or {\bf ServID} is not a valid - * pointer or {\bf cVariables} is less than zero. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * @{ */ + +/*! + * \brief 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 + * \c UPNP_EVENT_SUBSCRIPTION_REQUEST callback. + * + * This function is synchronous and generates no callbacks. + * + * This function can be called during the execution of a callback function. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device + * handle. + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId + * pair refers to an invalid service. + * \li \c UPNP_E_INVALID_SID: The specified subscription ID is not + * valid. + * \li \c UPNP_E_INVALID_PARAM: Either \b VarName, + * \b NewVal, \b DevID, or \b ServID is not a valid + * pointer or \b cVariables is less than zero. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. + */ EXPORT_SPEC int UpnpAcceptSubscription( - IN UpnpDevice_Handle Hnd, /** The handle of the device. */ - IN const char *DevID, /** The device ID of the subdevice of the - service generating the event. */ - IN const char *ServID, /** The unique service identifier of the service - generating the event. */ - IN const char **VarName, /** Pointer to an array of event variables. */ - IN const char **NewVal, /** Pointer to an array of values for - the event variables. */ - IN int cVariables, /** The number of event variables in - {\bf VarName}. */ - IN Upnp_SID SubsId /** The subscription ID of the newly - registered control point. */ - ); + /*! [in] The handle of the device. */ + UpnpDevice_Handle Hnd, + /*! [in] The device ID of the subdevice of the service generating the event. */ + const char *DevID, + /*! [in] The unique service identifier of the service generating the event. */ + const char *ServID, + /*! [in] Pointer to an array of event variables. */ + const char **VarName, + /*! [in] Pointer to an array of values for the event variables. */ + const char **NewVal, + /*! [in] The number of event variables in \b VarName. */ + int cVariables, + /*! [in] The subscription ID of the newly registered control point. */ + const Upnp_SID SubsId); -/** {\bf UpnpAcceptSubscriptionExt} is similar to {\bf 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. + +/*! + * \brief Similar to \b UpnpAcceptSubscription() except that it takes a DOM + * document for the variables to event rather than an array of strings. * - * {\bf UpnpAcceptSubscriptionExt} can be called during the execution of - * a callback function. + * This function is sychronous and generates no callbacks. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device - * handle. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} - * pair refers to an invalid service. - * \item {\tt UPNP_E_INVALID_SID}: The specified subscription ID is not - * valid. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName}, - * {\bf NewVal}, {\bf DevID}, {\bf ServID}, or {\bf PropSet} - * is not a valid pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * This function can be called during the execution of a callback function. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device + * handle. + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId + * pair refers to an invalid service. + * \li \c UPNP_E_INVALID_SID: The specified subscription ID is not + * valid. + * \li \c UPNP_E_INVALID_PARAM: Either \b VarName, + * \b NewVal, \b DevID, \b ServID, or \b PropSet + * is not a valid pointer. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpAcceptSubscriptionExt( - IN UpnpDevice_Handle Hnd, /** The handle of the device. */ - IN const char *DevID, /** The device ID of the subdevice of the - service generating the event. */ - IN const char *ServID, /** The unique service identifier of the service - generating the event. */ - IN IXML_Document *PropSet, /** 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. */ - IN Upnp_SID SubsId /** The subscription ID of the newly - registered control point. */ - ); + /*! [in] The handle of the device. */ + UpnpDevice_Handle Hnd, + /*! [in] The device ID of the subdevice of the service generating the event. */ + const char *DevID, + /*! [in] The unique service identifier of the service generating the event. */ + const char *ServID, + /*! [in] 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. */ + IXML_Document *PropSet, + /*! [in] The subscription ID of the newly registered control point. */ + Upnp_SID SubsId); -/** {\bf UpnpNotify} sends out an event change notification to all - * control points subscribed to a particular service. This function is - * synchronous and generates no callbacks. + +/*! + * \brief Sends out an event change notification to all control points + * subscribed to a particular service. * - * {\bf UpnpNotify} may be called during a callback function to send out - * a notification. + * This function is synchronous and generates no callbacks. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device - * handle. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} - * pair refers to an invalid service. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName}, {\bf NewVal}, - * {\bf DevID}, or {\bf ServID} is not a valid pointer or - * {\bf cVariables} is less than zero. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * This function may be called during a callback function to send out a + * notification. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device + * handle. + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId + * pair refers to an invalid service. + * \li \c UPNP_E_INVALID_PARAM: Either \b VarName, \b NewVal, + * \b DevID, or \b ServID is not a valid pointer or + * \b cVariables is less than zero. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpNotify( - IN UpnpDevice_Handle, /** The handle to the device sending the event. */ - IN const char *DevID, /** The device ID of the subdevice of the service - generating the event. */ - IN const char *ServID, /** The unique identifier of the service - generating the event. */ - IN const char **VarName,/** Pointer to an array of variables that - have changed. */ - IN const char **NewVal, /** Pointer to an array of new values for - those variables. */ - IN int cVariables /** The count of variables included in this - notification. */ - ); + /*! [in] The handle to the device sending the event. */ + UpnpDevice_Handle, + /*! [in] The device ID of the subdevice of the service generating the event. */ + const char *DevID, + /*! [in] The unique identifier of the service generating the event. */ + const char *ServID, + /*! [in] Pointer to an array of variables that have changed. */ + const char **VarName, + /*! [in] Pointer to an array of new values for those variables. */ + const char **NewVal, + /*! [in] The count of variables included in this notification. */ + int cVariables); -/** {\bf UpnpNotifyExt} is similar to {\bf 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. + +/*! + * \brief Similar to \b UpnpNotify except that it takes a DOM document for the + * event rather than an array of strings. * - * {\bf UpnpNotifyExt} may be called during a callback function to send out - * a notification. + * This function is synchronous and generates no callbacks. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device - * handle. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} - * pair refers to an invalid service. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName}, {\bf NewVal}, - * {\bf DevID}, {\bf ServID}, or {\bf PropSet} - * is not a valid pointer or {\bf cVariables} is less than zero. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * This function may be called during a callback function to send out a + * notification. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device + * handle. + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId + * pair refers to an invalid service. + * \li \c UPNP_E_INVALID_PARAM: Either \b VarName, \b NewVal, + * \b DevID, \b ServID, or \b PropSet + * is not a valid pointer or \b cVariables is less than zero. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpNotifyExt( - IN UpnpDevice_Handle, /** The handle to the device sending the - event. */ - IN const char *DevID, /** The device ID of the subdevice of the - service generating the event. */ - IN const char *ServID, /** The unique identifier of the service - generating the event. */ - IN IXML_Document *PropSet /** 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. */ - ); + /*! [in] The handle to the device sending the event. */ + UpnpDevice_Handle, + /*! [in] The device ID of the subdevice of the service generating the event. */ + const char *DevID, + /*! [in] The unique identifier of the service generating the event. */ + const char *ServID, + /*! [in] 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. */ + IXML_Document *PropSet); -/** {\bf UpnpRenewSubscription} renews a subscription that is about to - * expire. This function is synchronous. + +/*! + * \brief Renews a subscription that is about to expire. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf Timeout} is not a valid pointer. - * \item {\tt UPNP_E_INVALID_SID}: The SID being passed to this function - * is not a valid subscription ID. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to - * {\bf PublisherUrl}. - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket. - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher. - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription renew. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * This function is synchronous. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_PARAM: \b Timeout is not a valid pointer. + * \li \c UPNP_E_INVALID_SID: The SID being passed to this function + * is not a valid subscription ID. + * \li \c UPNP_E_NETWORK_ERROR: A network error occured. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to + * \b PublisherUrl. + * \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating a socket. + * \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from + * the publisher. + * \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused + * the subscription renew. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpRenewSubscription( - IN UpnpClient_Handle Hnd, /** The handle of the control point that - is renewing the subscription. */ - INOUT int *TimeOut, /** Pointer to a variable containing the - requested subscription time. Upon return, - it contains the actual renewal time. */ - IN Upnp_SID SubsId /** The ID for the subscription to renew. */ - ); + /*! [in] The handle of the control point that is renewing the subscription. */ + UpnpClient_Handle Hnd, + /*! [in,out] Pointer to a variable containing the requested subscription time. + * Upon return, it contains the actual renewal time. */ + int *TimeOut, + /*! [in] The ID for the subscription to renew. */ + const Upnp_SID SubsId); -/** {\bf UpnpRenewSubscriptionAsync} renews a subscription that is about - * to expire, generating a callback when the operation is complete. + +/*! + * \brief 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 {\bf Upnp_Event_Subscribe} structure. In those cases, the function - * returns {\tt UPNP_E_SUCCESS} and the appropriate error code will - * be in the {\bf Upnp_Event_Subscribe.ErrCode} field in the {\bf Event} - * structure passed to the callback. + * Note that many of the error codes for this function are returned in + * the \b UpnpEventSubscribe structure. In those cases, the function + * returns \c UPNP_E_SUCCESS and the appropriate error code will + * be in the UpnpEventSubscribe.ErrCode field in the \b Event + * structure passed to the callback. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_SID}: The {\bf SubsId} is not a valid - * subscription ID. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid - * callback function pointer or {\bf Timeout} is less than zero - * but is not {\tt UPNP_INFINITE}. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured (returned in - * the {\bf Upnp_Event_Subscribe.ErrCode} field as part of the - * callback). - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket (returned in the {\bf Upnp_Event_Subscribe.ErrCode} - * field as part of the callback). - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket (returned in the - * {\bf Upnp_Event_Subscribe.ErrCode} field as part of the - * callback). - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding the socket - * (returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as - * part of the callback). - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to - * {\bf PublisherUrl} (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating socket ( - * returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as - * part of the callback). - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription request (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_SID: The \b SubsId is not a valid + * subscription ID. + * \li \c UPNP_E_INVALID_PARAM: Either \b Fun is not a valid + * callback function pointer or \b Timeout is less than zero + * but is not \c UPNP_INFINITE. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. + * \li \c UPNP_E_NETWORK_ERROR: A network error occured (returned in + * the UpnpEventSubscribe.ErrCode field as part of the + * callback). + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket (returned in the UpnpEventSubscribe.ErrCode + * field as part of the callback). + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket (returned in the + * UpnpEventSubscribe.ErrCode field as part of the + * callback). + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding the socket + * (returned in the UpnpEventSubscribe.ErrCode field as + * part of the callback). + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to + * \b PublisherUrl (returned in the \b + * UpnpEventSubscribe.ErrCode field as part of the callback). + * \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating socket ( + * returned in the UpnpEventSubscribe.ErrCode field as + * part of the callback). + * \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from + * the publisher (returned in the \b + * UpnpEventSubscribe.ErrCode field as part of the callback). + * \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused + * the subscription request (returned in the \b + * UpnpEventSubscribe.ErrCode field as part of the callback). */ - EXPORT_SPEC int UpnpRenewSubscriptionAsync( - IN UpnpClient_Handle Hnd, /** The handle of the control point that - is renewing the subscription. */ - IN int TimeOut, /** The requested subscription time. The - actual timeout value is returned when - the callback function is called. */ - IN Upnp_SID SubsId, /** The ID for the subscription to renew. */ - IN Upnp_FunPtr Fun, /** Pointer to a callback function to be - invoked when the renewal is complete. */ - IN const void *Cookie /** Pointer to user data passed - to the callback function when invoked. */ - ); + /*! [in] The handle of the control point that is renewing the subscription. */ + UpnpClient_Handle Hnd, + /*! [in] The requested subscription time. The actual timeout value is + * returned when the callback function is called. */ + int TimeOut, + /*! [in] The ID for the subscription to renew. */ + Upnp_SID SubsId, + /*! [in] Pointer to a callback function to be invoked when the renewal is + * complete. */ + Upnp_FunPtr Fun, + /*! [in] Pointer to user data passed to the callback function when invoked. */ + const void *Cookie); -/** {\bf 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. + +/*! + * \brief Sets the maximum number of subscriptions accepted per service. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device - * handle. - * \end{itemize} + * 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. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device + * handle. */ - EXPORT_SPEC int UpnpSetMaxSubscriptions( - IN UpnpDevice_Handle Hnd, /** The handle of the device for which - the maximum number of subscriptions is - being set. */ - IN int MaxSubscriptions /** The maximum number of subscriptions to be - allowed per service. */ - ); + /*! The handle of the device for which the maximum number of + * subscriptions is being set. */ + UpnpDevice_Handle Hnd, + /*! The maximum number of subscriptions to be allowed per service. */ + int MaxSubscriptions); -/** {\bf 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. + +/*! + * \brief Sets the maximum time-out accepted for a subscription request or + * renewal. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device - * handle. - * \end{itemize} + * 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. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device + * handle. */ - EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut( - IN UpnpDevice_Handle Hnd, /** The handle of the device for which - the maximum subscription time-out is - being set. */ - IN int MaxSubscriptionTimeOut /** The maximum subscription time-out to - be accepted. */ - ); + /*! The handle of the device for which the maximum subscription + * time-out is being set. */ + UpnpDevice_Handle Hnd, + /*! The maximum subscription time-out to be accepted. */ + int MaxSubscriptionTimeOut); -/** {\bf UpnpSubscribe} registers a control point to receive event - * notifications from another device. This operation is synchronous. + +/*! + * \brief Registers a control point to receive event notifications from another + * device. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_URL}: {\bf PublisherUrl} is not a valid URL. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf Timeout} is not a valid pointer - * or {\bf SubsId} or {\bf PublisherUrl} is {\tt NULL}. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to - * {\bf PublisherUrl}. - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket. - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher. - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription request. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * This operation is synchronous. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_URL: \b PublisherUrl is not a valid URL. + * \li \c UPNP_E_INVALID_PARAM: \b Timeout is not a valid pointer + * or \b SubsId or \b PublisherUrl is \c NULL. + * \li \c UPNP_E_NETWORK_ERROR: A network error occured. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to + * \b PublisherUrl. + * \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating a socket. + * \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from + * the publisher. + * \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused + * the subscription request. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpSubscribe( - IN UpnpClient_Handle Hnd, /** The handle of the control point. */ - IN const char *PublisherUrl, /** The URL of the service to subscribe to. */ - INOUT int *TimeOut, /** Pointer to a variable containing - the requested subscription time. Upon - return, it contains the actual - subscription time returned from the - service. */ - OUT Upnp_SID SubsId /** Pointer to a variable to receive the - subscription ID (SID). */ - ); + /*! [in] The handle of the control point. */ + UpnpClient_Handle Hnd, + /*! [in] The URL of the service to subscribe to. */ + const char *PublisherUrl, + /*! [in,out]Pointer to a variable containing the requested subscription time. + * Upon return, it contains the actual subscription time returned from + * the service. */ + int *TimeOut, + /*! [out] Pointer to a variable to receive the subscription ID (SID). */ + Upnp_SID SubsId); -/** {\bf UpnpSubscribeAsync} performs the same operation as - * {\bf UpnpSubscribe}, but returns immediately and calls the registered - * callback function when the operation is complete. + +/*! + * \brief Performs the same operation as \b 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 {\bf Upnp_Event_Subscribe} structure. In those cases, the function - * returns {\tt UPNP_E_SUCCESS} and the appropriate error code will - * be in the {\bf Upnp_Event_Subscribe.ErrCode} field in the {\bf Event} - * structure passed to the callback. + * Note that many of the error codes for this function are returned in + * the \b UpnpEventSubscribe structure. In those cases, the function + * returns \c UPNP_E_SUCCESS and the appropriate error code will + * be in the UpnpEventSubscribe.ErrCode field in the \b Event + * structure passed to the callback. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control * point handle. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf PublisherUrl} is not a valid + * \li \c UPNP_E_INVALID_URL: The \b PublisherUrl is not a valid * URL. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf TimeOut} or {\bf Fun} or - * {\bf PublisherUrl} is not a valid pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to + * \li \c UPNP_E_INVALID_PARAM: Either \b TimeOut or \b Fun or + * \b PublisherUrl is not a valid pointer. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to * complete this operation. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured (returned in - * the {\bf Upnp_Event_Subscribe.ErrCode} field as part of the + * \li \c UPNP_E_NETWORK_ERROR: A network error occured (returned in + * the UpnpEventSubscribe.ErrCode field as part of the * callback). - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing * to a socket (returned in the - * {\bf Upnp_Event_Subscribe.ErrCode} field as part of the + * UpnpEventSubscribe.ErrCode field as part of the * callback). - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading * from a socket (returned in the - * {\bf Upnp_Event_Subscribe.ErrCode} field as part of the + * UpnpEventSubscribe.ErrCode field as part of the * callback). - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding the socket - * (returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding the socket + * (returned in the UpnpEventSubscribe.ErrCode field as * part of the callback). - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to - * {\bf PublisherUrl} (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating the - * socket (returned in the {\bf Upnp_Event_Subscribe.ErrCode} + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to + * \b PublisherUrl (returned in the \b + * UpnpEventSubscribe.ErrCode field as part of the callback). + * \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating the + * socket (returned in the UpnpEventSubscribe.ErrCode * field as part of the callback). - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription request (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \end{itemize} + * \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from + * the publisher (returned in the \b + * UpnpEventSubscribe.ErrCode field as part of the callback). + * \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused + * the subscription request (returned in the \b + * UpnpEventSubscribe.ErrCode field as part of the callback). */ - EXPORT_SPEC int UpnpSubscribeAsync( - IN UpnpClient_Handle Hnd, /** The handle of the control point that - is subscribing. */ - IN const char *PublisherUrl, /** The URL of the service to subscribe - to. */ - IN int TimeOut, /** The requested subscription time. Upon - return, it contains the actual - subscription time returned from the - service. */ - IN Upnp_FunPtr Fun, /** Pointer to the callback function for - this subscribe request. */ - IN const void *Cookie /** A user data value passed to the - callback function when invoked. */ - ); + /*! The handle of the control point that is subscribing. */ + UpnpClient_Handle Hnd, + /*! The URL of the service to subscribe to. */ + const char *PublisherUrl, + /*! The requested subscription time. Upon return, it contains the actual + * subscription time returned from the service. */ + int TimeOut, + /*! Pointer to the callback function for this subscribe request. */ + Upnp_FunPtr Fun, + /*! A user data value passed to the callback function when invoked. */ + const void *Cookie); -/** {\bf UpnpUnSubscribe} removes the subscription of a control point from a - * service previously subscribed to using {\bf UpnpSubscribe} or - * {\bf UpnpSubscribeAsync}. This is a synchronous call. + +/*! + * \brief Removes the subscription of a control point from a service previously + * subscribed to using \b UpnpSubscribe or \b UpnpSubscribeAsync. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_SID}: The {\bf SubsId} is not a valid - * subscription ID. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to - * {\bf PublisherUrl}. - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error ocurred creating a socket. - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher. - * \item {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED}: The publisher refused - * the unsubscribe request (the client is still unsubscribed and - * no longer receives events). - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \end{itemize} + * This is a synchronous call. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_SID: The \b SubsId is not a valid + * subscription ID. + * \li \c UPNP_E_NETWORK_ERROR: A network error occured. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to + * \b PublisherUrl. + * \li \c UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket. + * \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from + * the publisher. + * \li \c UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused + * the unsubscribe request (the client is still unsubscribed and + * no longer receives events). + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. */ - EXPORT_SPEC int UpnpUnSubscribe( - IN UpnpClient_Handle Hnd, /** The handle of the subscribed control - point. */ - IN Upnp_SID SubsId /** The ID returned when the control point - subscribed to the service. */ - ); + /*! [in] The handle of the subscribed control point. */ + UpnpClient_Handle Hnd, + /*! [in] The ID returned when the control point subscribed to the service. */ + const Upnp_SID SubsId); -/** {\bf UpnpUnSubscribeAsync} removes a subscription of a control - * point from a service previously subscribed to using {\bf - * UpnpSubscribe} or {\bf UpnpSubscribeAsync}, generating a callback - * when the operation is complete. - * - * Note that many of the error codes for this function are returned in - * the {\bf Upnp_Event_Subscribe} structure. In those cases, the function - * returns {\tt UPNP_E_SUCCESS} and the appropriate error code will - * be in the {\bf Upnp_Event_Subscribe.ErrCode} field in the {\bf Event} - * structure passed to the callback. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \item {\tt UPNP_E_INVALID_SID}: The {\bf SubsId} is not a valid SID. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf Fun} is not a valid callback - * function pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * complete this operation. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured (returned in - * the {\bf Upnp_Event_Subscribe.ErrCode} field as part of the - * callback). - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket (returned in the - * {\bf Upnp_Event_Subscribe.ErrCode} field as part of the - * callback). - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding the socket - * (returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as - * part of the callback). - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to - * {\bf PublisherUrl} (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket ( - * returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as - * part of the callback). - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription request (returned in the {\bf - * Upnp_Event_Subscribe.ErrCode} field as part of the callback). - * \end{itemize} */ +/*! + * \brief Removes a subscription of a control point from a service previously + * subscribed to using \b UpnpSubscribe or \b UpnpSubscribeAsync, generating + * a callback when the operation is complete. + * + * Note that many of the error codes for this function are returned in + * the \b UpnpEventSubscribe structure. In those cases, the function + * returns \c UPNP_E_SUCCESS and the appropriate error code will + * be in the UpnpEventSubscribe.ErrCode field in the \b Event + * structure passed to the callback. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control + * point handle. + * \li \c UPNP_E_INVALID_SID: The \b SubsId is not a valid SID. + * \li \c UPNP_E_INVALID_PARAM: \b Fun is not a valid callback + * function pointer. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * complete this operation. + * \li \c UPNP_E_NETWORK_ERROR: A network error occured (returned in + * the UpnpEventSubscribe.ErrCode field as part of the + * callback). + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket (returned in the UpnpEventSubscribe.ErrCode + * field as part of the callback). + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket (returned in the + * UpnpEventSubscribe.ErrCode field as part of the + * callback). + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding the socket + * (returned in the UpnpEventSubscribe.ErrCode field as + * part of the callback). + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to + * \b PublisherUrl (returned in the UpnpEventSubscribe.ErrCode + * field as part of the callback). + * \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating a socket ( + * returned in the UpnpEventSubscribe.ErrCode field as + * part of the callback). + * \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from + * the publisher (returned in the UpnpEventSubscribe.ErrCode + * field as part of the callback). + * \li \c UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused + * the subscription request (returned in the + * UpnpEventSubscribe.ErrCode field as part of the callback). + */ EXPORT_SPEC int UpnpUnSubscribeAsync( - IN UpnpClient_Handle Hnd, /** The handle of the subscribed control - point. */ - IN Upnp_SID SubsId, /** The ID returned when the - control point subscribed to the service. */ - IN Upnp_FunPtr Fun, /** Pointer to a callback function to be - called when the operation is complete. */ - IN const void *Cookie /** Pointer to user data to pass to the - callback function when invoked. */ - ); + /*! [in] The handle of the subscribed control point. */ + UpnpClient_Handle Hnd, + /*! [in] The ID returned when the control point subscribed to the service. */ + Upnp_SID SubsId, + /*! [in] Pointer to a callback function to be called when the operation is + * complete. */ + Upnp_FunPtr Fun, + /*! [in] Pointer to user data to pass to the callback function when invoked. */ + const void *Cookie); + + +/*! @} Eventing */ -/*! @} */ /* Eventing */ /****************************************************************************** @@ -2183,401 +2173,389 @@ EXPORT_SPEC int UpnpUnSubscribeAsync( ****************************************************************************** ******************************************************************************/ -/*! @name Control Point HTTP API */ -/*! @{ */ - -/** {\bf UpnpDownloadUrlItem} downloads a file specified in a URL. - * The SDK allocates the memory for {\bf 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. +/*! + * \name Control Point HTTP API * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf outBuf} - * or {\bf contentType} is not a valid pointer. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid - * URL. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * download this file. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a - * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently - * allocated. - * \end{itemize} + * @{ */ +/*! + * \brief Downloads a file specified in a URL. + * + * The SDK allocates the memory for \b 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. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b url, \b outBuf + * or \b contentType is not a valid pointer. + * \li \c UPNP_E_INVALID_URL: The \b url is not a valid + * URL. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * download this file. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a + * socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. + */ EXPORT_SPEC int UpnpDownloadUrlItem( - IN const char *url, /** URL of an item to download. */ - OUT char **outBuf, /** Buffer to store the downloaded item. */ - OUT char *contentType /** HTTP header value content type if - present. It should be at least - {\tt LINE_SIZE} bytes in size. */ - ); + /*! [in] URL of an item to download. */ + const char *url, + /*! [out] Buffer to store the downloaded item. */ + char **outBuf, + /*! [out] HTTP header value content type if present. It should be at least + * \c LINE_SIZE bytes in size. */ + char *contentType); -/** {\bf UpnpOpenHttpGet} gets a file specified in a URL. - * The SDK allocates the memory for {\bf handle} and - * {\bf contentType}, the application is responsible for freeing this memory. + +/*! + * \brief Gets a file specified in a URL. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle}, - * {\bf contentType}, {\bf contentLength} or {\bf httpStatus} - * is not a valid pointer. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid - * URL. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * download this file. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a - * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently - * allocated. - * \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the - * remote server. - * \end{itemize} + * The SDK allocates the memory for \b handle and \b contentType, the + * application is responsible for freeing this memory. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b url, \b handle, + * \b contentType, \b contentLength or \b httpStatus + * is not a valid pointer. + * \li \c UPNP_E_INVALID_URL: The \b url is not a valid + * URL. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * download this file. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a + * socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. + * \li \c UPNP_E_BAD_RESPONSE: A bad response was received from the + * remote server. */ - EXPORT_SPEC int UpnpOpenHttpGet( - IN const char *url, /** The URL of an item to get. */ - IN OUT void **handle, /** A pointer to store the handle for - this connection. */ - IN OUT char **contentType, /** A buffer to store the media type of - the item. */ - IN OUT int *contentLength, /** A pointer to store the length of the - item. */ - IN OUT int *httpStatus, /** The status returned on receiving a - response message. */ - IN int timeout /** 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. */ - ); + /*! [in] The URL of an item to get. */ + const char *url, + /*! [in,out] A pointer to store the handle for this connection. */ + void **handle, + /*! [in,out] A buffer to store the media type of the item. */ + char **contentType, + /*! [in,out] A pointer to store the length of the item. */ + int *contentLength, + /*! [in,out] The status returned on receiving a response message. */ + int *httpStatus, + /*! [in] 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. */ + int timeout); -/** {\bf UpnpOpenHttpGetProxy} gets a file specified in a URL through the - * specified proxy. - * The SDK allocates the memory for {\bf handle} and - * {\bf contentType}, the application is responsible for freeing this memory. + +/*! + * \brief Gets a file specified in a URL through the specified proxy. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle}, - * {\bf contentType}, {\bf contentLength} or {\bf httpStatus} - * is not a valid pointer. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid - * URL. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to - * download this file. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a - * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently - * allocated. - * \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the - * remote server. - * \end{itemize} + * The SDK allocates the memory for \b handle and \b contentType, the + * application is responsible for freeing this memory. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b url, \b handle, + * \b contentType, \b contentLength or \b httpStatus + * is not a valid pointer. + * \li \c UPNP_E_INVALID_URL: The \b url is not a valid + * URL. + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to + * download this file. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a + * socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. + * \li \c UPNP_E_BAD_RESPONSE: A bad response was received from the + * remote server. */ - EXPORT_SPEC int UpnpOpenHttpGetProxy( - IN const char *url, /** The URL of an item to get. */ - IN const char *proxy_str, /** The URL of the proxy. */ - IN OUT void **handle, /** A pointer to store the handle for - this connection. */ - IN OUT char **contentType, /** A buffer to store the media type of - the item. */ - IN OUT int *contentLength, /** A pointer to store the length of the - item. */ - IN OUT int *httpStatus, /** The status returned on receiving a - response message. */ - IN int timeout /** 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. */ - ); + /*! [in] The URL of an item to get. */ + const char *url, + /*! [in] The URL of the proxy. */ + const char *proxy_str, + /*! [in,out] A pointer to store the handle for this connection. */ + void **handle, + /*! [in,out] A buffer to store the media type of the item. */ + char **contentType, + /*! [in,out] A pointer to store the length of the item. */ + int *contentLength, + /*! [in,out] The status returned on receiving a response message. */ + int *httpStatus, + /*! [in] 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. */ + int timeout); -/** {\bf 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 {\bf handle} and - * {\bf contentType}, the application is responsible for freeing this memory. + +/*! + * \brief Gets specified number of bytes from a file specified in the URL. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle}, - * {\bf contentType}, {\bf contentLength} or {\bf httpStatus} + * 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 \b handle and \b contentType, the application is responsible for freeing + * this memory. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b url, \b handle, + * \b contentType, \b contentLength or \b httpStatus * is not a valid pointer. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid + * \li \c UPNP_E_INVALID_URL: The \b url is not a valid * URL. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to * download this file. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently * allocated. - * \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the + * \li \c UPNP_E_BAD_RESPONSE: A bad response was received from the * remote server. - * \end{itemize} */ - EXPORT_SPEC int UpnpOpenHttpGetEx( - IN const char *url, /** The URL of the item to get. */ - IN OUT void **handle, /** A pointer to store the handle for - this connection. */ - IN OUT char **contentType, /** A buffer to store the media type of the - item. */ - IN OUT int *contentLength, /** A buffer to store the length of the - item. */ - IN OUT int *httpStatus, /** The status returned on receiving a - response message from the remote - server. */ - IN int lowRange, /** An integer value representing the low - end of a range to retrieve. */ - IN int highRange, /** An integer value representing the high - end of a range to retrieve. */ - IN int timeout /** 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. */ - ); + /*! [in] The URL of the item to get. */ + const char *url, + /*! [in,out] A pointer to store the handle for this connection. */ + void **handle, + /*! [in,out] A buffer to store the media type of the item. */ + char **contentType, + /*! [in,out] A buffer to store the length of the item. */ + int *contentLength, + /*! [in,out] The status returned on receiving a response message from the remote server. */ + int *httpStatus, + /*! [in] An integer value representing the low end of a range to retrieve. */ + int lowRange, + /*! [in] An integer value representing the high end of a range to retrieve. */ + int highRange, + /*! [in] 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. */ + int timeout); -/** {\bf UpnpReadHttpGet} gets specified number of bytes from a file - * specified in a URL. + +/*! + * \brief Gets specified number of bytes from a file specified in a URL. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, {\bf buf} - * or {\bf size} is not a valid pointer. - * \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b handle, \b buf + * or \b size is not a valid pointer. + * \li \c UPNP_E_BAD_RESPONSE: A bad response was received from the * remote server. - * \item {\tt UPNP_E_BAD_HTTPMSG}: Either the request or response was in + * \li \c UPNP_E_BAD_HTTPMSG: Either the request or response was in * the incorrect format. - * \item {\tt UPNP_E_CANCELED}: another thread called UpnpCancelHttpGet. - * \end{itemize} + * \li \c UPNP_E_CANCELED: another thread called UpnpCancelHttpGet. * * Note: In case of return values, the status code parameter of the passed * in handle value may provide additional information on the return * value. */ - EXPORT_SPEC int UpnpReadHttpGet( - IN void *handle, /** The token created by the call to - {\bf UpnpOpenHttpGet}. */ - IN OUT char *buf, /** The buffer to store the read item. */ - IN OUT unsigned int *size, /** The size of the buffer to be read. */ - IN int timeout /** 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. */ - ); + /*! [in] The token created by the call to \b UpnpOpenHttpGet. */ + void *handle, + /*! [in,out] The buffer to store the read item. */ + char *buf, + /*! [in,out] The size of the buffer to be read. */ + unsigned int *size, + /*! [in] 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. */ + int timeout); -/** {\bf UpnpHttpGetProgress} rettrieve progress information of a http-get - * transfer. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, {\bf length} - * or {\bf total} is not a valid pointer. - * \end{itemize} + +/*! + * \brief Retrieve progress information of a http-get transfer. * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b handle, \b length + * or \b total is not a valid pointer. */ EXPORT_SPEC int UpnpHttpGetProgress( - IN void *handle, /** The token created by the call to - {\bf UpnpOpenHttpGet}. */ - OUT unsigned int *length, /** The number of bytes received. */ - OUT unsigned int *total /** The content length. */ - ); + /*! [in] The token created by the call to \b UpnpOpenHttpGet. */ + void *handle, + /*! [out] The number of bytes received. */ + unsigned int *length, + /*! [out] The content length. */ + unsigned int *total); -/** {\bf UpnpCancelHttpGet} set the cancel flag of the {\bf handle} - * parameter. +/*! + * \brief Set the cancel flag of the \b handle parameter. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf handle} is not a valid pointer. - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: \b handle is not a valid pointer. */ +EXPORT_SPEC int UpnpCancelHttpGet( + /*! [in] The handle of the connection created by the call to + * \b UpnpOpenHttpPost. */ + void *handle); -EXPORT_SPEC int UpnpCancelHttpGet(IN void *handle); - -/** {\bf UpnpCloseHttpGet} closes the connection and frees memory that was - * allocated for the {\bf handle} parameter. +/*! + * \brief Closes the connection and frees memory that was allocated for the + * \b handle parameter. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf handle} is not a valid pointer. - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: \b handle is not a valid pointer. */ - -EXPORT_SPEC int UpnpCloseHttpGet(IN void *handle); +EXPORT_SPEC int UpnpCloseHttpGet( + /*! [in] The handle of the connection created by the call to + * \b UpnpOpenHttpPost. */ + void *handle); -/** {\bf 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 {\bf handle} and - * {\bf contentType}, the application is responsible for freeing this memory. +/*! + * \brief 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. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle} - * or {\bf contentType} is not a valid pointer. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid + * The SDK allocates the memory for \b handle and \b contentType, the + * application is responsible for freeing this memory. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b url, \b handle + * or \b contentType is not a valid pointer. + * \li \c UPNP_E_INVALID_URL: The \b url is not a valid * URL. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to * download this file. - * \item {\tt UPNP_E_SOCKET_ERROR}: Error occured allocating a socket and + * \li \c UPNP_E_SOCKET_ERROR: Error occured allocating a socket and * resources or an error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing * to a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently * allocated. - * \end{itemize} */ - EXPORT_SPEC int UpnpOpenHttpPost( - IN const char *url, /** The URL in which to send the POST - request. */ - IN OUT void **handle, /** A pointer in which to store the - handle for this connection. This - handle is required for futher - operations over this connection. */ - IN const char *contentType, /** A buffer to store the media type of - content being sent. */ - IN int contentLength, /** The length of the content, in bytes, - being posted. */ - IN int timeout /** The time out value sent with the - request during which a response is - expected from the receiver, failing - which, an error is reported. */ - ); + /*! [in] The URL in which to send the POST request. */ + const char *url, + /*! [in,out] A pointer in which to store the handle for this connection. This + * handle is required for futher operations over this connection. */ + void **handle, + /*! [in] A buffer to store the media type of content being sent. */ + const char *contentType, + /*! [in] The length of the content, in bytes, being posted. */ + int contentLength, + /*! [in] The time out value sent with the request during which a response + * is expected from the receiver, failing which, an error is reported. */ + int timeout); -/** {\bf UpnpWriteHttpPost} sends a request to a server to copy the contents of - * a buffer to the URI specified in the {\bf UpnpOpenHttpPost} call. +/*! + * \brief Sends a request to a server to copy the contents of a buffer to the + * URI specified in the \b UpnpOpenHttpPost call. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, {\bf buf} - * or {\bf size} is not a valid pointer. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b handle, \b buf + * or \b size is not a valid pointer. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing * to a socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently * allocated. - * \end{itemize} */ - EXPORT_SPEC int UpnpWriteHttpPost( - IN void *handle, /** The handle of the connection created - by the call to {\bf UpnpOpenHttpPost}. */ - IN char *buf, /** The buffer to be posted. */ - IN unsigned int *size, /** The size, in bytes of {\bf buf}. */ - IN int timeout /** A timeout value sent with the request - during which a response is expected - from the server, failing which, an - error is reported. */ - ); + /*! [in] The handle of the connection created by the call to + * \b UpnpOpenHttpPost. */ + void *handle, + /*! [in] The buffer to be posted. */ + char *buf, + /*! [in] The size, in bytes of \b buf. */ + unsigned int *size, + /*! [in] A timeout value sent with the request during which a response is + * expected from the server, failing which, an error is reported. */ + int timeout); -/** {\bf UpnpCloseHttpPost} sends and receives any pending data, closes the - * connection with the server, and frees memory allocated during the - * {\bfUpnpOpenHttpPost} call. + +/*! + * \brief Sends and receives any pending data, closes the connection with the + * server, and frees memory allocated during the \b UpnpOpenHttpPost call. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, or - * {\bf httpStatus} is not a valid pointer. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently - * allocated. - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b handle, or + * \b httpStatus is not a valid pointer. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. */ - EXPORT_SPEC int UpnpCloseHttpPost( - IN void *handle, /** The handle of the connection to close, - created by the call to - {\bf UpnpOpenHttpPost}. */ - IN OUT int *httpStatus, /** A pointer to a buffer to store the - final status of the connection. */ - IN int timeout /** A time out value sent with the request - during which a response is expected from - the server, failing which, an error is - reported. */ - ); + /*! [in] The handle of the connection to close, created by the call to + * \b UpnpOpenHttpPost. */ + void *handle, + /*! [in,out] A pointer to a buffer to store the final status of the connection. */ + int *httpStatus, + /*! [in] A time out value sent with the request during which a response is + * expected from the server, failing which, an error is reported. */ + int timeout); -/** {\bf 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. +/*! + * \brief Downloads an XML document specified in a URL. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url} or {\bf xmlDoc} - * is not a valid pointer. - * \item {\tt UPNP_E_INVALID_DESC}: The XML document was not - * found or it does not contain a valid XML description. - * \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid - * URL. - * \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to - * download the XML document. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing - * to a socket. - * \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading - * from a socket. - * \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. - * \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the - * socket. - * \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently - * allocated. - * \end{itemize} + * The SDK parses the document and returns it in the form of a + * DOM document. The application is responsible for freeing the DOM document. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_PARAM: Either \b url or \b xmlDoc + * is not a valid pointer. + * \li \c UPNP_E_INVALID_DESC: The XML document was not + * found or it does not contain a valid XML description. + * \li \c UPNP_E_INVALID_URL: The \b url is not a valid + * URL. + * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to + * download the XML document. + * \li \c UPNP_E_NETWORK_ERROR: A network error occurred. + * \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing + * to a socket. + * \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading + * from a socket. + * \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket. + * \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the + * socket. + * \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently + * allocated. */ - EXPORT_SPEC int UpnpDownloadXmlDoc( - IN const char *url, /** URL of the XML document. */ - OUT IXML_Document **xmlDoc /** A pointer in which to store the - XML document. */ - ); + /*! [in] URL of the XML document. */ + const char *url, + /*! [out] A pointer in which to store the XML document. */ + IXML_Document **xmlDoc); -/*! @} */ /* Control Point HTTP API */ + +/*! @} Control Point HTTP API */ /****************************************************************************** ****************************************************************************** @@ -2587,130 +2565,103 @@ EXPORT_SPEC int UpnpDownloadXmlDoc( ****************************************************************************** ******************************************************************************/ -/*! @name Web Server API */ -/*! @{ */ - -/** {\bf 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 {\tt NULL} for {\bf 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. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPPN_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf rootDir} is an invalid - * directory. - * \end{itemize} +/*! + * \name Web Server API + * + * @{ + */ + +/*! + * \brief 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 \c NULL for \b rootDir; to activate, pass a valid directory + * string. + * + * \note This function is not available when the web server is not compiled + * into the UPnP Library. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b rootDir is an invalid directory. */ - EXPORT_SPEC int UpnpSetWebServerRootDir( - IN const char* rootDir /** Path of the root directory of the web - server. */ - ); + /*! [in] Path of the root directory of the web server. */ + const char *rootDir); -/** {\bf UpnpSetVirtualDirCallbacks} sets the callback function to be used to - * access a virtual directory. Refer to the description of - * {\bf UpnpVirtualDirCallbacks} for a description of the functions. + +/*! + * \brief Enables or disables the webserver. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPPN_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf callbacks} is not a valid - * pointer. - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b enable is not valid. */ - -EXPORT_SPEC int UpnpSetVirtualDirCallbacks( - IN struct UpnpVirtualDirCallbacks *callbacks /** Pointer to a structure - containing points to the - virtual interface - functions. */ - ); - -/** {\bf UpnpEnableWebServer} enables or disables the webserver. A value of - * {\tt TRUE} enables the webserver, {\tt FALSE} disables it. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPPN_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf enable} is not valid. - * \end{itemize} - */ - EXPORT_SPEC int UpnpEnableWebserver( - IN int enable /** {\tt TRUE} to enable, {\tt FALSE} to disable. */ - ); + /*! [in] \c TRUE to enable, \c FALSE to disable. */ + int enable); -/** {\bf UpnpIsWebServerEnabled} returns {\tt TRUE} if the webserver is - * enabled, or {\tt FALSE} if it is not. + +/*! + * \brief Returns \c TRUE if the webserver is enabled, or \c FALSE if it is not. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt TRUE}: The webserver is enabled. - * \item {\tt FALSE}: The webserver is not enabled - * \end{itemize} + * \return An integer representing one of the following: + * \li \c TRUE: The webserver is enabled. + * \li \c FALSE: The webserver is not enabled */ - EXPORT_SPEC int UpnpIsWebserverEnabled(); -/** {\bf UpnpAddVirtualDir} adds a virtual directory mapping. - * - * All webserver requests containing the given directory are read using - * functions contained in a {\bf UpnpVirtualDirCallbacks} structure registered - * via {\bf UpnpSetVirtualDirCallbacks}. - * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPPN_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf dirName} is not valid. - * \end{itemize} - */ +/*! + * \brief Adds a virtual directory mapping. + * + * All webserver requests containing the given directory are read using + * functions contained in a \b VirtualDirCallbacks structure registered + * via \b UpnpSetVirtualDirCallbacks. + * + * \note This function is not available when the web server is not + * compiled into the UPnP Library. + * + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b dirName is not valid. + */ EXPORT_SPEC int UpnpAddVirtualDir( - IN const char *dirName /** The name of the new directory mapping to add. - */ - ); + /*! [in] The name of the new directory mapping to add. */ + const char *dirName); -/** {\bf UpnpRemoveVirtualDir} removes a virtual directory mapping made with - * {\bf UpnpAddVirtualDir}. + +/*! + * \brief Removes a virtual directory mapping made with \b UpnpAddVirtualDir. * - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt UPPN_E_SUCCESS}: The operation completed successfully. - * \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf dirName} is not valid. - * \end{itemize} + * \return An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b dirName is not valid. */ - EXPORT_SPEC int UpnpRemoveVirtualDir( - IN const char *dirName /** The name of the virtual directory mapping to - remove. */ - ); + /*! [in] The name of the virtual directory mapping to remove. */ + const char *dirName); -/** {\bf UpnpRemoveAllVirtualDirs} removes all virtual directory mappings. - * - * @return [void] This function does not return a value. - * + +/*! + * \brief Removes all virtual directory mappings. */ +EXPORT_SPEC void UpnpRemoveAllVirtualDirs(); -EXPORT_SPEC void UpnpRemoveAllVirtualDirs( ); -EXPORT_SPEC void UpnpFree( - IN void *item /* The item to free. */ - ); +/* @} Web Server API */ + -/*! @} */ /* Web Server API */ #ifdef __cplusplus } #endif /* __cplusplus */ -/*! @} */ /* The API */ -#endif +/* @} UPnPAPI UPnP API */ + + +#endif /* UPNP_H */ diff --git a/upnp/src/api/upnpapi.c b/upnp/src/api/upnpapi.c index 3624eea..4689b9b 100644 --- a/upnp/src/api/upnpapi.c +++ b/upnp/src/api/upnpapi.c @@ -1736,25 +1736,7 @@ UpnpSubscribe( IN UpnpClient_Handle Hnd, #ifdef INCLUDE_CLIENT_APIS -/************************************************************************** - * Function: UpnpUnSubscribe - * - * Parameters: - * IN UpnpClient_Handle Hnd: The handle of the control point. - * IN Upnp_SID SubsId: The ID returned when the control point - * subscribed to the service. - * - * Description: - * This function removes the subscription of a control point from a - * service previously subscribed to using UpnpSubscribe or - * UpnpSubscribeAsync. This is a synchronous call. - * - * Return Values: int - * UPNP_E_SUCCESS if successful else sends appropriate error. - ***************************************************************************/ -int -UpnpUnSubscribe( IN UpnpClient_Handle Hnd, - IN Upnp_SID SubsId ) +int UpnpUnSubscribe(UpnpClient_Handle Hnd, const Upnp_SID SubsId) { struct Handle_Info *SInfo = NULL; int RetVal; @@ -1861,33 +1843,12 @@ UpnpUnSubscribeAsync( IN UpnpClient_Handle Hnd, return UPNP_E_SUCCESS; -} /****************** End of UpnpUnSubscribeAsync *********************/ +} #endif // INCLUDE_CLIENT_APIS #ifdef INCLUDE_CLIENT_APIS -/************************************************************************** - * Function: UpnpRenewSubscription - * - * Parameters: - * IN UpnpClient_Handle Hnd: The handle of the control point that - * is renewing the subscription. - * INOUT int *TimeOut: Pointer to a variable containing the - * requested subscription time. Upon return, - * it contains the actual renewal time. - * IN Upnp_SID SubsId: The ID for the subscription to renew. - * - * Description: - * This function renews a subscription that is about to - * expire. This function is synchronous. - * - * Return Values: int - * UPNP_E_SUCCESS if successful else sends appropriate error. - ***************************************************************************/ -int -UpnpRenewSubscription( IN UpnpClient_Handle Hnd, - INOUT int *TimeOut, - IN Upnp_SID SubsId ) +int UpnpRenewSubscription(UpnpClient_Handle Hnd, int *TimeOut, const Upnp_SID SubsId) { struct Handle_Info *SInfo = NULL; int RetVal; @@ -2158,40 +2119,14 @@ UpnpNotifyExt( IN UpnpDevice_Handle Hnd, #ifdef INCLUDE_DEVICE_APIS -/************************************************************************** - * Function: UpnpAcceptSubscription - * - * Parameters: - * IN UpnpDevice_Handle Hnd: The handle of the device. - * IN const char *DevID: The device ID of the subdevice of the - * service generating the event. - * IN const char *ServID: The unique service identifier of the - * service generating the event. - * IN const char **VarName: Pointer to an array of event variables. - * IN const char **NewVal: Pointer to an array of values for - * the event variables. - * IN int cVariables: The number of event variables in VarName. - * IN Upnp_SID SubsId: The subscription ID of the newly - * registered control point. - * - * Description: - * This function 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 sychronous - * and generates no callbacks. - * - * Return Values: int - * UPNP_E_SUCCESS if successful else sends appropriate error. - ***************************************************************************/ -int -UpnpAcceptSubscription( IN UpnpDevice_Handle Hnd, - IN const char *DevID_const, - IN const char *ServName_const, - IN const char **VarName_const, - IN const char **NewVal_const, - int cVariables, - IN Upnp_SID SubsId ) +int UpnpAcceptSubscription( + UpnpDevice_Handle Hnd, + const char *DevID_const, + const char *ServName_const, + const char **VarName_const, + const char **NewVal_const, + int cVariables, + const Upnp_SID SubsId) { struct Handle_Info *SInfo = NULL; int retVal; diff --git a/upnp/src/genlib/net/http/httpparser.c b/upnp/src/genlib/net/http/httpparser.c index 9a6cdb0..566635b 100644 --- a/upnp/src/genlib/net/http/httpparser.c +++ b/upnp/src/genlib/net/http/httpparser.c @@ -1,52 +1,65 @@ -/////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2000-2003 Intel Corporation -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither name of Intel Corporation nor the names of its contributors -// may be used to endorse or promote products derived from this software -// without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR -// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY -// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////// +/******************************************************************************* + * + * Copyright (c) 2000-2003 Intel Corporation + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither name of Intel Corporation nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + ******************************************************************************/ + + +/* + * \file + * + * \brief Contains functions for scanner and parser for http messages. + */ -/************************************************************************ -* Purpose: This file contains functions for scanner and parser for http -* messages. -************************************************************************/ #define _GNU_SOURCE // For strcasestr() in string.h + + #include "config.h" -#include -#include -#include -#include -#include + + #include "strintmap.h" #include "httpparser.h" #include "statcodes.h" #include "unixutil.h" +#include "upnpdebug.h" + + +#include +#include +#include +#include +#include +#include + + +/* entity positions */ -// entity positions #define NUM_HTTP_METHODS 9 static str_int_entry Http_Method_Table[NUM_HTTP_METHODS] = { @@ -122,8 +135,8 @@ str_int_entry Http_Header_Names[NUM_HTTP_HEADER_NAMES] = { * Note : ************************************************************************/ static UPNP_INLINE void -scanner_init( OUT scanner_t * scanner, - IN membuffer * bufptr ) +scanner_init( OUT scanner_t *scanner, + IN membuffer *bufptr ) { scanner->cursor = 0; scanner->msg = bufptr; @@ -395,12 +408,12 @@ scanner_get_str( IN scanner_t * scanner ) * * Note : ************************************************************************/ -#ifndef WIN32 -#warning The only use of the function 'scanner_pushback()' in the code is commented out. -#warning 'scanner_pushback()' is a candidate for removal. +#ifdef WIN32 + #pragma message ("The only use of the function 'scanner_pushback()' in the code is commented out.") + #pragma message ("'scanner_pushback()' is a candidate for removal.") #else -#pragma message ("The only use of the function 'scanner_pushback()' in the code is commented out.") -#pragma message ("'scanner_pushback()' is a candidate for removal.") + #warning The only use of the function 'scanner_pushback()' in the code is commented out. + #warning 'scanner_pushback()' is a candidate for removal. #endif static UPNP_INLINE void scanner_pushback( INOUT scanner_t * scanner, @@ -970,12 +983,12 @@ read_until_crlf( INOUT scanner_t * scanner, * PARSE_FAILURE * PARSE_INCOMPLETE ************************************************************************/ -#ifndef WIN32 -#warning There are currently no uses of the function 'skip_to_end_of_header()' in the code. -#warning 'skip_to_end_of_header()' is a candidate for removal. +#ifdef WIN32 + #pragma message("There are currently no uses of the function 'skip_to_end_of_header()' in the code.") + #pragma message("'skip_to_end_of_header()' is a candidate for removal.") #else -#pragma message("There are currently no uses of the function 'skip_to_end_of_header()' in the code.") -#pragma message("'skip_to_end_of_header()' is a candidate for removal.") + #warning There are currently no uses of the function 'skip_to_end_of_header()' in the code. + #warning 'skip_to_end_of_header()' is a candidate for removal. #endif static UPNP_INLINE int skip_to_end_of_header( INOUT scanner_t * scanner ) @@ -2496,26 +2509,15 @@ method_to_str( IN http_method_t method ) return index == -1 ? NULL : Http_Method_Table[index].name; } -/************************************************************************ -* Function: print_http_headers -* -* Parameters: -* http_message_t* hmsg ; HTTP Message object -* -* Description: -* -* Returns: -* void -************************************************************************/ + #ifdef DEBUG -void -print_http_headers( http_message_t * hmsg ) +void print_http_headers(http_message_t *hmsg) { ListNode *node; - // NNS: dlist_node *node; + /* NNS: dlist_node *node; */ http_header_t *header; - // print start line + /* print start line */ if( hmsg->is_request ) { printf( "method = %d, version = %d.%d, url = %.*s\n", hmsg->method, hmsg->major_version, hmsg->minor_version, @@ -2526,18 +2528,18 @@ print_http_headers( http_message_t * hmsg ) (int)hmsg->status_msg.length, hmsg->status_msg.buf); } - // print headers + /* print headers */ node = ListHead( &hmsg->headers ); - // NNS: node = dlist_first_node( &hmsg->headers ); + /* NNS: node = dlist_first_node( &hmsg->headers ); */ while( node != NULL ) { header = ( http_header_t * ) node->item; - // NNS: header = (http_header_t *)node->data; + /* NNS: header = (http_header_t *)node->data; */ printf( "hdr name: %.*s, value: %.*s\n", (int)header->name.length, header->name.buf, (int)header->value.length, header->value.buf ); node = ListNext( &hmsg->headers, node ); - // NNS: node = dlist_next( &hmsg->headers, node ); + /* NNS: node = dlist_next( &hmsg->headers, node ); */ } } #endif diff --git a/upnp/src/genlib/net/uri/uri.c b/upnp/src/genlib/net/uri/uri.c index a11cf19..9647043 100644 --- a/upnp/src/genlib/net/uri/uri.c +++ b/upnp/src/genlib/net/uri/uri.c @@ -1,227 +1,190 @@ -/////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2000-2003 Intel Corporation -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither name of Intel Corporation nor the names of its contributors -// may be used to endorse or promote products derived from this software -// without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR -// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY -// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////// +/******************************************************************************* + * + * Copyright (c) 2000-2003 Intel Corporation + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither name of Intel Corporation nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + ******************************************************************************/ + + +/*! + * \file + * + * \brief Contains functions for uri, url parsing utility. + */ -/************************************************************************ -* Purpose: This file contains functions for uri, url parsing utility. -************************************************************************/ #ifdef __FreeBSD__ -#include -#if __FreeBSD_version < 601103 -#include -#endif + #include + #if __FreeBSD_version < 601103 + #include + #endif #endif + + #include "config.h" + + #include "uri.h" -#ifdef WIN32 - #include "inet_pton.h" -#endif + +#include "upnpdebug.h" -/************************************************************************ -* Function : is_reserved -* -* Parameters : -* char in ; char to be matched for RESERVED characters -* -* Description : Returns a 1 if a char is a RESERVED char as defined in -* http://www.ietf.org/rfc/rfc2396.txt RFC explaining URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_reserved( char in ) +/*! + * \brief Returns a 1 if a char is a RESERVED char as defined in + * http://www.ietf.org/rfc/rfc2396.txt RFC explaining URIs). + * + * \return 1 if char is a RESERVED char. + */ +static int is_reserved( + /*! [in] Char to be matched for RESERVED characters. */ + char in) { - if( strchr( RESERVED, in ) ) - return 1; - else - return 0; + if (strchr(RESERVED, in)) { + return 1; + } else { + return 0; + } } -/************************************************************************ -* Function : is_mark -* -* Parameters : -* char in ; character to be matched for MARKED characters -* -* Description : Returns a 1 if a char is a MARK char as defined in -* http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_mark( char in ) + +/*! + * \brief Returns a 1 if a char is a MARK char as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * \return 1 if char is a MARKED char. + */ +int is_mark( + /*! [in] Char to be matched for MARKED characters. */ + char in) { - if( strchr( MARK, in ) ) - return 1; - else - return 0; + if (strchr(MARK, in)) { + return 1; + } else { + return 0; + } } -/************************************************************************ -* Function : is_unreserved -* -* Parameters : -* char in ; character to be matched for UNRESERVED characters -* -* Description : Returns a 1 if a char is an unreserved char as defined in -* http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_unreserved( char in ) + +/*! + * \brief Returns a 1 if a char is an UNRESERVED char as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * \return 1 if char is a UNRESERVED char. + */ +int is_unreserved( + /*! [in] Char to be matched for UNRESERVED characters. */ + char in) { - if( isalnum( in ) || ( is_mark( in ) ) ) - return 1; - else - return 0; + if (isalnum(in) || is_mark(in)) { + return 1; + } else { + return 0; + } } -/************************************************************************ -* Function : is_escaped -* -* Parameters : -* char * in ; character to be matched for ESCAPED characters -* -* Description : Returns a 1 if a char[3] sequence is escaped as defined -* in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* size of array is NOT checked (MUST be checked by caller) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_escaped( const char *in ) + +/*! + * \brief Returns a 1 if a char[3] sequence is ESCAPED as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * Size of array is NOT checked (MUST be checked by caller). + * + * \return 1 if char is a ESCAPED char. + */ +int is_escaped( + /*! [in] Char sequence to be matched for ESCAPED characters. */ + const char *in) { - - if( ( in[0] == '%' ) && ( isxdigit( in[1] ) ) && isxdigit( in[2] ) ) { - - return 1; - } else - return 0; + if (in[0] == '%' && isxdigit(in[1]) && isxdigit(in[2])) { + return 1; + } else { + return 0; + } } -/************************************************************************ -* Function : replace_escaped -* -* Parameters : -* char * in ; string of characters -* int index ; index at which to start checking the characters -* int *max ; -* -* Description : Replaces an escaped sequence with its unescaped version -* as in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* Size of array is NOT checked (MUST be checked by caller) -* -* Return : int ; -* -* Note : This function modifies the string. If the sequence is an -* escaped sequence it is replaced, the other characters in the -* string are shifted over, and NULL characters are placed at the -* end of the string. -************************************************************************/ -int -replace_escaped( char *in, - int index, - size_t *max ) + +int replace_escaped(char *in, int index, size_t *max) { - int tempInt = 0; - char tempChar = 0; - int i = 0; - int j = 0; + int tempInt = 0; + char tempChar = 0; + int i = 0; + int j = 0; - if( ( in[index] == '%' ) && ( isxdigit( in[index + 1] ) ) - && isxdigit( in[index + 2] ) ) { - //Note the "%2x", makes sure that we convert a maximum of two - //characters. - if( sscanf( &in[index + 1], "%2x", &tempInt ) != 1 ) - return 0; + if (in[index] == '%' && isxdigit(in[index + 1]) && isxdigit(in[index + 2])) { + /* Note the "%2x", makes sure that we convert a maximum of two + * characters. */ + if (sscanf(&in[index + 1], "%2x", &tempInt) != 1) { + return 0; + } - tempChar = ( char )tempInt; - - for( i = index + 3, j = index; j < ( *max ); i++, j++ ) { - in[j] = tempChar; - if( i < ( *max ) ) - tempChar = in[i]; - else - tempChar = 0; - } - ( *max ) -= 2; - return 1; - } else - return 0; + tempChar = ( char )tempInt; + for (i = index + 3, j = index; j < *max; i++, j++) { + in[j] = tempChar; + if (i < *max) { + tempChar = in[i]; + } else { + tempChar = 0; + } + } + *max -= 2; + return 1; + } else { + return 0; + } } -/************************************************************************ -* Function : parse_uric -* -* Parameters : -* char *in ; string of characters -* int max ; maximum limit -* token *out ; token object where the string of characters is -* copied -* -* Description : Parses a string of uric characters starting at in[0] -* as defined in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining -* URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_uric( const char *in, - int max, - token * out ) + +/*! + * \brief Parses a string of uric characters starting at in[0] as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * \return + */ +static int parse_uric( + /*! [in] String of characters. */ + const char *in, + /*! [in] Maximum limit. */ + int max, + /*! [out] Token object where the string of characters is copied. */ + token *out) { - int i = 0; + int i = 0; - while( ( i < max ) - && ( ( is_unreserved( in[i] ) ) || ( is_reserved( in[i] ) ) - || ( ( i + 2 < max ) && ( is_escaped( &in[i] ) ) ) ) ) { - i++; - } + while (i < max && + (is_unreserved(in[i]) || + is_reserved(in[i]) || + ((i + 2 < max) && is_escaped(&in[i])))) { + i++; + } - out->size = i; - out->buff = in; - return i; + out->size = i; + out->buff = in; + return i; } /************************************************************************ @@ -247,55 +210,27 @@ copy_sockaddr_in( const struct sockaddr_in *in, out->sin_addr.s_addr = in->sin_addr.s_addr; } -/************************************************************************ -* Function : copy_token -* -* Parameters : -* const token *in ; source token -* const char * in_base ; -* token * out ; destination token -* char * out_base ; -* -* Description : Tokens are generally pointers into other strings -* this copies the offset and size from a token (in) relative to -* one string (in_base) into a token (out) relative to another -* string (out_base) -* -* Return : void ; -* -* Note : -************************************************************************/ -static void -copy_token( const token * in, - const char *in_base, - token * out, - char *out_base ) +/*! + * \brief Tokens are generally pointers into other strings. This copies the + * offset and size from a token (in) relative to one string (in_base) into + * a token (out) relative to another string (out_base). + */ +static void copy_token( + /*! [in] Source token. */ + const token *in, + /*! [in] . */ + const char *in_base, + /*! [out] Destination token. */ + token *out, + /*! [in] . */ + char *out_base) { - out->size = in->size; - out->buff = out_base + ( in->buff - in_base ); + out->size = in->size; + out->buff = out_base + (in->buff - in_base); } -/************************************************************************ -* Function : copy_URL_list -* -* Parameters : -* URL_list *in ; Source URL list -* URL_list *out ; Destination URL list -* -* Description : Copies one URL_list into another. This includes -* dynamically allocating the out->URLs field (the full string), -* and the structures used to hold the parsedURLs. This memory MUST -* be freed by the caller through: free_URL_list(&out) -* -* Return : int ; -* HTTP_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On Failure to allocate memory -* -* Note : -************************************************************************/ -int -copy_URL_list( URL_list * in, - URL_list * out ) + +int copy_URL_list(URL_list *in, URL_list *out) { int len = strlen( in->URLs ) + 1; int i = 0; @@ -332,68 +267,34 @@ copy_URL_list( URL_list * in, &out->parsedURLs[i].hostport.IPv4address ); } out->size = in->size; + return HTTP_SUCCESS; - } -/************************************************************************ -* Function : free_URL_list -* -* Parameters : -* URL_list * list ; URL List object -* -* Description : Frees the memory associated with a URL_list. Frees the -* dynamically allocated members of of list. Does NOT free the -* pointer to the list itself ( i.e. does NOT free(list)) -* -* Return : void ; -* -* Note : -************************************************************************/ -void -free_URL_list( URL_list * list ) + +void free_URL_list(URL_list *list) { - if( list->URLs ) - free( list->URLs ); - if( list->parsedURLs ) - free( list->parsedURLs ); - list->size = 0; + if (list->URLs) { + free(list->URLs); + } + if (list->parsedURLs) { + free(list->parsedURLs); + } + list->size = 0; } -/************************************************************************ -* Function : print_uri -* -* Parameters : -* uri_type *in ; URI object -* -* Description : Function useful in debugging for printing a parsed uri. -* -* Return : void ; -* -* Note : -************************************************************************/ + #ifdef DEBUG -void print_uri( uri_type *in ) +void print_uri(uri_type *in) { - print_token( &in->scheme ); - print_token( &in->hostport.text ); - print_token( &in->pathquery ); - print_token( &in->fragment ); + print_token(&in->scheme); + print_token(&in->hostport.text); + print_token(&in->pathquery); + print_token(&in->fragment); } -#endif +#endif /* DEBUG */ + -/************************************************************************ -* Function : print_token -* -* Parameters : -* token * in ; token -* -* Description : Function useful in debugging for printing a token. -* -* Return : void ; -* -* Note : -************************************************************************/ #ifdef DEBUG void print_token(token * in) { @@ -405,149 +306,64 @@ void print_token(token * in) putchar( '\'' ); putchar( '\n' ); } -#endif +#endif /* DEBUG */ -/************************************************************************ -* Function : token_string_casecmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares buffer in the token object with the buffer -* in in2 -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_string_casecmp( - token * in1, - char *in2 ) + +int token_string_casecmp(token *in1, char *in2) { - int in2_length = strlen( in2 ); + int in2_length = strlen(in2); - if( in1->size != in2_length ) - return 1; - else - return strncasecmp( in1->buff, in2, in1->size ); + if (in1->size != in2_length) { + return 1; + } else { + return strncasecmp(in1->buff, in2, in1->size); + } } -/************************************************************************ -* Function : token_string_cmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares a null terminated string to a token (exact) -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int -token_string_cmp( token * in1, - char *in2 ) -{ - int in2_length = strlen( in2 ); - if( in1->size != in2_length ) - return 1; - else - return strncmp( in1->buff, in2, in1->size ); +int token_string_cmp(token * in1, char *in2) +{ + int in2_length = strlen(in2); + + if (in1->size != in2_length) { + return 1; + } else { + return strncmp(in1->buff, in2, in1->size); + } } -/************************************************************************ -* Function : token_cmp -* -* Parameters : -* token *in1 ; First token object whose buffer is to be compared -* token *in2 ; Second token object used for the comparison -* -* Description : Compares two tokens -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int -token_cmp( token * in1, - token * in2 ) + +int token_cmp(token *in1, token *in2) { - if( in1->size != in2->size ) - return 1; - else - return memcmp( in1->buff, in2->buff, in1->size ); + if (in1->size != in2->size) { + return 1; + } else { + return memcmp(in1->buff, in2->buff, in1->size); + } } -/************************************************************************ -* Function : parse_port -* -* Parameters : -* int max ; sets a maximum limit -* char * port ; port to be parsed. -* unsigned short * out ; out parameter where the port is parsed -* and converted into network format -* -* Description : parses a port (i.e. '4000') and converts it into a -* network ordered unsigned short int. -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_port( int max, - const char *port, - unsigned short *out ) + +int parse_port(int max, const char *port, unsigned short *out) { + const char *finger = port; + const char *max_ptr = finger + max; + unsigned short temp = 0; - const char *finger = port; - const char *max_ptr = finger + max; - unsigned short temp = 0; + while((finger < max_ptr) && (isdigit(*finger))) { + temp = temp * 10; + temp += *finger - '0'; + finger++; + } - while( ( finger < max_ptr ) && ( isdigit( *finger ) ) ) { - temp = temp * 10; - temp += ( *finger ) - '0'; - finger++; - } - - *out = htons( temp ); - return finger - port; + *out = htons(temp); + return finger - port; } -/************************************************************************ -* Function : parse_hostport -* -* Parameters : -* char *in ; string of characters representing host and port -* int max ; sets a maximum limit -* hostport_type *out ; out parameter where the host and port -* are represented as an internet address -* -* Description : Parses a string representing a host and port -* (e.g. "127.127.0.1:80" or "localhost") and fills out a -* hostport_type struct with internet address and a token -* representing the full host and port. uses gethostbyname. -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_hostport( const char *in, - int max, - hostport_type * out ) + +int parse_hostport( + const char *in, + int max, + hostport_type *out) { #define BUFFER_SIZE 8192 @@ -564,8 +380,7 @@ parse_hostport( const char *in, char *temp_host_name = NULL; int last_dot = -1; - out->text.size = 0; - out->text.buff = NULL; + memset( out, 0, sizeof(hostport_type) ); out->IPv4address.sin_port = htons( 80 ); //default port is 80 memset( &out->IPv4address.sin_zero, 0, 8 ); @@ -655,12 +470,12 @@ parse_hostport( const char *in, BUFFER_SIZE, &h, &errcode ); #else { - struct addrinfo hints, *res, *res0; + struct addrinfo hints, *res, *res0; h = NULL; - memset(&hints, 0, sizeof(hints)); - hints.ai_family = PF_INET; - hints.ai_socktype = SOCK_STREAM; + memset(&hints, 0, sizeof(hints)); + hints.ai_family = PF_INET; + hints.ai_socktype = SOCK_STREAM; errCode = getaddrinfo(temp_host_name, "http", &hints, &res0); if (!errCode) { @@ -710,28 +525,23 @@ parse_hostport( const char *in, } -/************************************************************************ -* Function : parse_scheme -* -* Parameters : -* char * in ; string of characters representing a scheme -* int max ; maximum number of characters -* token * out ; output parameter whose buffer is filled in with -* the scheme -* -* Description : parses a uri scheme starting at in[0] as defined in -* http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* (e.g. "http:" -> scheme= "http"). -* Note, string MUST include ':' within the max charcters -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_scheme( const char *in, - int max, - token * out ) +/*! + * \brief parses a uri scheme starting at in[0] as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * (e.g. "http:" -> scheme= "http"). + * + * \note String MUST include ':' within the max charcters. + * + * \return + */ +static int parse_scheme( + /*! [in] String of characters representing a scheme. */ + const char *in, + /*! [in] Maximum number of characters. */ + int max, + /*! [out] Output parameter whose buffer is filled in with the scheme. */ + token *out) { int i = 0; @@ -760,26 +570,8 @@ parse_scheme( const char *in, } -/************************************************************************ -* Function : remove_escaped_chars -* -* Parameters : -* INOUT char *in ; string of characters to be modified -* INOUT int *size ; size limit for the number of characters -* -* Description : removes http escaped characters such as: "%20" and -* replaces them with their character representation. i.e. -* "hello%20foo" -> "hello foo". The input IS MODIFIED in place. -* (shortened). Extra characters are replaced with NULL. -* -* Return : int ; -* UPNP_E_SUCCESS -* -* Note : -************************************************************************/ -int -remove_escaped_chars( INOUT char *in, - INOUT size_t *size ) + +int remove_escaped_chars(INOUT char *in, INOUT size_t *size ) { int i = 0; @@ -789,37 +581,8 @@ remove_escaped_chars( INOUT char *in, return UPNP_E_SUCCESS; } -/************************************************************************ -* Function : remove_dots -* -* Parameters : -* char *in ; string of characters from which "dots" have to be -* removed -* int size ; size limit for the number of characters -* -* Description : Removes ".", and ".." from a path. If a ".." can not -* be resolved (i.e. the .. would go past the root of the path) an -* error is returned. The input IS modified in place.) -* -* Return : int ; -* UPNP_E_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On failure to allocate memory -* UPNP_E_INVALID_URL - Failure to resolve URL -* -* Note : -* Examples -* char path[30]="/../hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_INVALID_URL -* char path[30]="/./hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_SUCCESS, -* in = "/hello" -* char path[30]="/./hello/foo/../goodbye" -> -* UPNP_E_SUCCESS, in = "/hello/goodbye" -************************************************************************/ -int -remove_dots( char *in, - int size ) +int remove_dots(char *in, size_t size) { char *copyTo = in; char *copyFrom = in; @@ -884,30 +647,8 @@ remove_dots( char *in, return UPNP_E_SUCCESS; } -/************************************************************************ -* Function : resolve_rel_url -* -* Parameters : -* char * base_url ; Base URL -* char * rel_url ; Relative URL -* -* Description : resolves a relative url with a base url returning a NEW -* (dynamically allocated with malloc) full url. If the base_url is -* NULL, then a copy of the rel_url is passed back if the rel_url -* is absolute then a copy of the rel_url is passed back if neither -* the base nor the rel_url are Absolute then NULL is returned. -* otherwise it tries and resolves the relative url with the base -* as described in: http://www.ietf.org/rfc/rfc2396.txt (RFCs -* explaining URIs) -* : resolution of '..' is NOT implemented, but '.' is resolved -* -* Return : char * ; -* -* Note : -************************************************************************/ -char * -resolve_rel_url( char *base_url, - char *rel_url ) + +char *resolve_rel_url(char *base_url, char *rel_url) { uri_type base; uri_type rel; @@ -994,8 +735,8 @@ resolve_rel_url( char *base_url, if( remove_dots( out_finger, strlen( out_finger ) ) != UPNP_E_SUCCESS ) { - free( out ); - //free(rel_url); + free(out); + /* free(rel_url); */ return NULL; } } @@ -1003,46 +744,23 @@ resolve_rel_url( char *base_url, } } } else { - free( out ); - //free(rel_url); + free(out); + /* free(rel_url); */ return NULL; } } } else { - free( out ); - //free(rel_url); + free(out); + /* free(rel_url); */ return NULL; } - //free(rel_url); + /* free(rel_url); */ return out; } -/************************************************************************ -* Function : parse_uri -* -* Parameters : -* char * in ; character string containing uri information to be -* parsed -* int max ; maximum limit on the number of characters -* uri_type * out ; out parameter which will have the parsed uri -* information -* -* Description : parses a uri as defined in http://www.ietf.org/rfc/ -* rfc2396.txt (RFC explaining URIs) -* Handles absolute, relative, and opaque uris. Parses into the -* following pieces: scheme, hostport, pathquery, fragment (path and -* query are treated as one token) -* Caller should check for the pieces they require. -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_uri( const char *in, - int max, - uri_type * out ) + +int parse_uri(const char *in, int max, uri_type *out) { int begin_path = 0; int begin_hostport = 0; @@ -1069,10 +787,7 @@ parse_uri( const char *in, return begin_path; } else { - out->hostport.IPv4address.sin_port = 0; - out->hostport.IPv4address.sin_addr.s_addr = 0; - out->hostport.text.size = 0; - out->hostport.text.buff = 0; + memset( &out->hostport, 0, sizeof(out->hostport) ); begin_path = begin_hostport; } @@ -1095,33 +810,22 @@ parse_uri( const char *in, return HTTP_SUCCESS; } -/************************************************************************ -* Function : parse_uri_and_unescape -* -* Parameters : -* char * in ; -* int max ; -* uri_type * out ; -* -* Description : Same as parse_uri, except that all strings are -* unescaped (%XX replaced by chars) -* -* Return : int ; -* -* Note: This modifies 'pathquery' and 'fragment' parts of the input -************************************************************************/ -int -parse_uri_and_unescape( char *in, - int max, - uri_type *out ) -{ - int ret; - if( ( ret = parse_uri( in, max, out ) ) != HTTP_SUCCESS ) - return ret; - if( out->pathquery.size > 0 ) - remove_escaped_chars( (char *)out->pathquery.buff, &out->pathquery.size ); - if( out->fragment.size > 0 ) - remove_escaped_chars( (char *)out->fragment.buff, &out->fragment.size ); - return HTTP_SUCCESS; +int parse_uri_and_unescape(char *in, int max, uri_type *out) +{ + int ret = parse_uri(in, max, out); + + if (ret != HTTP_SUCCESS) { + return ret; + } + + if (out->pathquery.size > 0) { + remove_escaped_chars((char *)out->pathquery.buff, &out->pathquery.size); + } + if (out->fragment.size > 0) { + remove_escaped_chars((char *)out->fragment.buff, &out->fragment.size); + } + + return HTTP_SUCCESS; } + diff --git a/upnp/src/inc/http_client.h b/upnp/src/inc/http_client.h deleted file mode 100644 index 1f45073..0000000 --- a/upnp/src/inc/http_client.h +++ /dev/null @@ -1,314 +0,0 @@ -/////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2000-2003 Intel Corporation -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither name of Intel Corporation nor the names of its contributors -// may be used to endorse or promote products derived from this software -// without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR -// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY -// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////// - -#ifndef _http_client_h_ -#define _http_client_h_ -#ifdef __cplusplus -#define EXTERN_C extern "C" -#else -#define EXTERN_C -#endif -#include "genlib/closesocket/upnpclosesocket.h" -#include -#include -#include -//#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include "tools/config.h" -#include "upnp.h" -//#include "upnp_debug.h" - - -#define HTTP_DATE_LENGTH 37 // length for HTTP DATE: - //"DATE: Sun, 01 Jul 2000 08:15:23 GMT" -#define SEPARATORS "()<>@,;:\\\"/[]?={} \t" -#define MARK "-_.!~*'()" -#define RESERVED ";/?:@&=+$," -#define HTTP_SUCCESS 1 -#define HTTP_E_BAD_URL UPNP_E_INVALID_URL -#define HTTP_E_READ_SOCKET UPNP_E_SOCKET_READ -#define HTTP_E_BIND_SOCKET UPNP_E_SOCKET_BIND -#define HTTP_E_WRITE_SOCKET UPNP_E_SOCKET_WRITE -#define HTTP_E_CONNECT_SOCKET UPNP_E_SOCKET_CONNECT -#define HTTP_E_SOCKET UPNP_E_OUTOF_SOCKET -#define HTTP_E_BAD_RESPONSE UPNP_E_BAD_RESPONSE -#define HTTP_E_BAD_REQUEST UPNP_E_BAD_REQUEST -#define HTTP_E_BAD_IP_ADDRESS UPNP_E_INVALID_URL -#define FALSE 0 -#define TAB 9 -#define CR 13 -#define LF 10 -#define RESPONSE_TIMEOUT 30 -#define SOCKET_BUFFER_SIZE 5000 - -enum hostType { HOSTNAME, IPv4address }; -enum pathType { ABS_PATH, REL_PATH, OPAQUE_PART }; -enum uriType { ABSOLUTE, RELATIVE }; - -//Buffer used to store data read from -//a socket during an http transfer -//in function read_bytes. -typedef struct SOCKET_BUFFER{ - char buff[SOCKET_BUFFER_SIZE]; - int size; - struct SOCKET_BUFFER *next; -} socket_buffer; - -//Buffer used in parsing -//http messages, urls, etc. -//generally this simply -//holds a pointer into a larger array -typedef struct TOKEN { - char * buff; - size_t size; -} token; - - -//Represents a host port: -//e.g. :"127.127.0.1:80" -//text is a token pointing to -//the full string representation -typedef struct HOSTPORT { - token text; //full host port - struct sockaddr_in IPv4address; //Network Byte Order -} hostport_type; - -//Represents a URI -//used in parse_uri and elsewhere -typedef struct URI{ - enum uriType type; - token scheme; - enum pathType path_type; - token pathquery; - token fragment; - hostport_type hostport; -} uri_type; - -//Represents a list of URLs as in -//the "callback" header of SUBSCRIBE -//message in GENA -//char * URLs holds dynamic memory -typedef struct URL_LIST { - int size; - char * URLs; //all the urls, delimited by <> - uri_type *parsedURLs; -} URL_list; - -typedef struct HTTP_HEADER { - token header; - token value; - struct HTTP_HEADER * next; -} http_header; - -typedef struct HTTP_STATUS_LINE{ - token http_version; - token status_code; - token reason_phrase; -} http_status; - -typedef struct HTTP_REQUEST_LINE { - token http_version; - uri_type request_uri; - token method; -} http_request; - -//Represents a parsed HTTP_MESSAGE -//head_list is dynamically allocated -typedef struct HTTP_MESSAGE { - http_status status; - http_request request; - http_header * header_list; - token content; -} http_message; - - -EXTERN_C int transferHTTP( char * request, char * toSend, - int toSendSize, char **out, char * Url); - - -EXTERN_C int transferHTTPRaw( char * toSend, int toSendSize, - char **out, char *URL); - -//helper function -EXTERN_C int transferHTTPparsedURL( char * request, - char * toSend, int toSendSize, - char **out, uri_type *URL); - -//assumes that char * out has enough space ( 38 characters) -//outputs the current time in the following null terminated string: -// "DATE: Sun, Jul 06 2000 08:53:01 GMT\r\n" -EXTERN_C void currentTmToHttpDate(char *out); - -//returns dynamic memory or NULL on error -EXTERN_C char * resolve_rel_url( char * base_url, char * rel_url); - -EXTERN_C int parse_uri( char * in, int max, uri_type * out); - -EXTERN_C int token_cmp( token *in1, token *in2); - -EXTERN_C int token_string_casecmp( token * in1, char * in2); - -EXTERN_C int token_string_cmp( token * in1, char * in2); - -EXTERN_C int parse_http_response( char * in, http_message * out, - int max_len); - -EXTERN_C int parse_http_request( char * in, http_message *out, - int max_len); - -EXTERN_C int search_for_header( http_message * in, - char * header, token *out_value); - - - -EXTERN_C int parse_hostport( char* in, int max, hostport_type *out ); - -EXTERN_C size_t write_bytes(int fd, char * bytes, size_t n, - int timeout); -EXTERN_C void free_http_message(http_message * message); -EXTERN_C int copy_URL_list( URL_list *in, URL_list *out); -EXTERN_C void free_URL_list(URL_list * list); -EXTERN_C int parse_port(int max, char * port, unsigned short int * out); - -EXTERN_C int parse_http_line( char * in, int max_size); -EXTERN_C int parse_not_LWS( char *in, token *out, int max_size); -EXTERN_C int parse_LWS( char * in, int max_size); -EXTERN_C int parse_token( char * in, token * out, int max_size); -EXTERN_C ssize_t readLine(int fd, char *out, int max, int *timeout); -EXTERN_C int remove_dots(char * in, int size); - - -#ifdef DEBUG -EXTERN_C void print_http_request( - http_message *message, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo); -#else -static inline void print_http_request( - http_message *message, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo) {} -#endif - -#ifdef DEBUG -EXTERN_C void print_http_response( - http_message *message, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo); -#else -static inline void print_http_response( - http_message *message, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo) {} -#endif - -#ifdef DEBUG -EXTERN_C void print_token( - token *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo); -#else -static inline void print_token( - token *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo) {} -#endif - -#ifdef DEBUG -EXTERN_C void print_status_line( - http_status *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo); -#else -static inline void print_status_line( - http_status *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo) {} -#endif - -#ifdef DEBUG -EXTERN_C void print_request_line( - http_request *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo); -#else -static inline void print_request_line( - http_request *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo) {} -#endif - -#ifdef DEBUG -EXTERN_C void print_uri( - uri_type *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo); -#else -static inline void print_uri( - uri_type *in, - Upnp_LogLevel DLevel, - Dbg_Module Module, - char *DbgFileName, - int DbgLineNo) {} -#endif - -#endif - diff --git a/upnp/src/inc/service_table.h b/upnp/src/inc/service_table.h index cfe042f..7705368 100644 --- a/upnp/src/inc/service_table.h +++ b/upnp/src/inc/service_table.h @@ -48,6 +48,7 @@ extern "C" { #include "uri.h" #include "ixml.h" #include "upnp.h" +#include "upnpdebug.h" #include @@ -131,139 +132,100 @@ subscription *GetSubscriptionSID( service_info *service); -//returns a pointer to the subscription with the SID, NULL if not found +/*! + * \brief Gets pointer to the first subscription node in the service table. + * + * \return Pointer to the first subscription node. + */ +subscription *GetFirstSubscription( + /*! [in] Service object providing the list of subscriptions. */ + service_info *service); -subscription * CheckSubscriptionSID(Upnp_SID sid,service_info * service); -//returns a pointer to the first subscription -subscription * GetFirstSubscription(service_info *service); +/*! + * \brief Get current and valid subscription from the service table. + * + * \return Pointer to the next subscription node. + */ +subscription *GetNextSubscription( + /*! [in] Service object providing the list of subscriptions. */ + service_info *service, + /*! [in] Current subscription object. */ + subscription *current); -/************************************************************************ -* Function : GetNextSubscription -* -* Parameters : -* service_info * service ; service object providing the list of -* subscriptions -* subscription *current ; current subscription object -* -* Description : Get current and valid subscription from the service -* table. -* -* Return : subscription * - Pointer to the next subscription node; -* -* Note : -************************************************************************/ -subscription * GetNextSubscription(service_info * service, subscription *current); -/************************************************************************ -* Function : freeSubscription -* -* Parameters : -* subscription * sub ; subscription to be freed -* -* Description : Free's the memory allocated for storing the URL of -* the subscription. -* -* Return : void ; -* -* Note : -************************************************************************/ -void freeSubscription(subscription * sub); +/*! + * \brief Free's the memory allocated for storing the URL of the subscription. + */ +void freeSubscription( + /*! [in] Subscription object to be freed. */ + subscription *sub); -/************************************************************************ -* Function : freeSubscriptionList -* -* Parameters : -* subscription * head ; head of the subscription list -* -* Description : Free's memory allocated for all the subscriptions -* in the service table. -* -* Return : void ; -* -* Note : -************************************************************************/ -void freeSubscriptionList(subscription * head); -/************************************************************************ -* Function : FindServiceId -* -* Parameters : -* service_table *table ; service table -* const char * serviceId ;string representing the service id -* to be found among those in the table -* const char * UDN ; string representing the UDN -* to be found among those in the table -* -* Description : Traverses through the service table and returns a -* pointer to the service node that matches a known service id -* and a known UDN -* -* Return : service_info * - pointer to the matching service_info node; -* -* Note : -************************************************************************/ -service_info *FindServiceId( service_table * table, - const char * serviceId, const char * UDN); +/*! + * \brief Free's memory allocated for all the subscriptions in the service table. + */ +void freeSubscriptionList( + /*! [in] Head of the subscription list. */ + subscription * head); -/************************************************************************ -* Function : FindServiceEventURLPath -* -* Parameters : -* service_table *table ; service table -* char * eventURLPath ; event URL path used to find a service -* from the table -* -* Description : Traverses the service table and finds the node whose -* event URL Path matches a know value -* -* Return : service_info * - pointer to the service list node from the -* service table whose event URL matches a known event URL; -* -* Note : -************************************************************************/ -service_info * FindServiceEventURLPath( service_table *table, - char * eventURLPath - ); -/************************************************************************ -* Function : FindServiceControlURLPath -* -* Parameters : -* service_table * table ; service table -* char * controlURLPath ; control URL path used to find a service -* from the table -* -* Description : Traverses the service table and finds the node whose -* control URL Path matches a know value -* -* Return : service_info * - pointer to the service list node from the -* service table whose control URL Path matches a known value; -* -* Note : -************************************************************************/ -service_info * FindServiceControlURLPath( service_table *table, - const char * controlURLPath); +/*! + * \brief Traverses through the service table and returns a pointer to the + * service node that matches a known service id and a known UDN. + * + * \return Pointer to the matching service_info node. + */ +service_info *FindServiceId( + /*! [in] Service table. */ + service_table *table, + /*! [in] String representing the service id to be found among those + * in the table. */ + const char *serviceId, + /*! [in] String representing the UDN to be found among those in the + * table. */ + const char *UDN); -/************************************************************************ -* Function : printService -* -* Parameters : -* service_info *service ;Service whose information is to be printed -* Upnp_LogLevel level ; Debug level specified to the print function -* Dbg_Module module ; Debug module specified to the print function -* -* Description : For debugging purposes prints information from the -* service passed into the function. -* -* Return : void ; -* -* Note : -************************************************************************/ + +/*! + * \brief Traverses the service table and finds the node whose event URL Path + * matches a know value. + * + * \return Pointer to the service list node from the service table whose event + * URL matches a known event URL. + */ +service_info *FindServiceEventURLPath( + /*! [in] Service table. */ + service_table *table, + /*! [in] Event URL path used to find a service from the table. */ + char *eventURLPath); + + +/*! + * \brief Traverses the service table and finds the node whose control URL Path + * matches a know value. + * + * \return Pointer to the service list node from the service table whose control + * URL Path matches a known value. + */ +service_info * FindServiceControlURLPath( + /*! [in] Service table. */ + service_table *table, + /*! [in] Control URL path used to find a service from the table. */ + const char *controlURLPath); + + +/*! + * \brief For debugging purposes prints information from the service passed + * into the function. + */ #ifdef DEBUG void printService( + /*! [in] Service whose information is to be printed. */ service_info *service, + /*! [in] Debug level specified to the print function. */ Upnp_LogLevel level, + /*! [in] Debug module specified to the print function. */ Dbg_Module module); #else static UPNP_INLINE void printService( @@ -272,25 +234,18 @@ static UPNP_INLINE void printService( Dbg_Module module) {} #endif -/************************************************************************ -* Function : printServiceList -* -* Parameters : -* service_info *service ; Service whose information is to be printed -* Upnp_LogLevel level ; Debug level specified to the print function -* Dbg_Module module ; Debug module specified to the print function -* -* Description : For debugging purposes prints information of each -* service from the service table passed into the function. -* -* Return : void ; -* -* Note : -************************************************************************/ + +/*! + * \brief For debugging purposes prints information of each service from the + * service table passed into the function. + */ #ifdef DEBUG void printServiceList( + /*! [in] Service whose information is to be printed. */ service_info *service, + /*! [in] Debug level specified to the print function. */ Upnp_LogLevel level, + /*! [in] Debug module specified to the print function. */ Dbg_Module module); #else static UPNP_INLINE void printServiceList( @@ -299,26 +254,18 @@ static UPNP_INLINE void printServiceList( Dbg_Module module) {} #endif -/************************************************************************ -* Function : printServiceTable -* -* Parameters : -* service_table * table ; Service table to be printed -* Upnp_LogLevel level ; Debug level specified to the print function -* Dbg_Module module ; Debug module specified to the print function -* -* Description : For debugging purposes prints the URL base of the table -* and information of each service from the service table passed into -* the function. -* -* Return : void ; -* -* Note : -************************************************************************/ + +/*! + * \brief For debugging purposes prints the URL base of the table and information + * of each service from the service table passed into the function. + */ #ifdef DEBUG void printServiceTable( + /*! [in] Service table to be printed. */ service_table *table, + /*! [in] Debug level specified to the print function. */ Upnp_LogLevel level, + /*! [in] Debug module specified to the print function. */ Dbg_Module module); #else static UPNP_INLINE void printServiceTable( @@ -327,150 +274,106 @@ static UPNP_INLINE void printServiceTable( Dbg_Module module) {} #endif -/************************************************************************ -* Function : freeService -* -* Parameters : -* service_info *in ; service information that is to be freed -* -* Description : Free's memory allocated for the various components -* of the service entry in the service table. -* -* Return : void ; -* -* Note : -************************************************************************/ -void freeService(service_info * in); -/************************************************************************ -* Function : freeServiceList -* -* Parameters : -* service_info * head ; Head of the service list to be freed -* -* Description : Free's memory allocated for the various components -* of each service entry in the service table. -* -* Return : void ; -* -* Note : -************************************************************************/ -void freeServiceList(service_info * head); +/*! + * \brief Free's memory allocated for the various components of the service + * entry in the service table. + */ +void freeService( + /*! [in] Service information that is to be freed. */ + service_info *in); -/************************************************************************ -* Function : freeServiceTable -* -* Parameters : -* service_table * table ; Service table whose memory needs to be -* freed -* -* Description : Free's dynamic memory in table. -* (does not free table, only memory within the structure) -* -* Return : void ; -* -* Note : -************************************************************************/ -void freeServiceTable(service_table * table); - -/************************************************************************ -* Function : removeServiceTable -* -* Parameters : -* IXML_Node *node ; XML node information -* service_table *in ; service table from which services will be -* removed -* -* Description : This function assumes that services for a particular -* root device are placed linearly in the service table, and in the -* order in which they are found in the description document -* all services for this root device are removed from the list -* -* Return : int ; -* -* Note : -************************************************************************/ -int removeServiceTable(IXML_Node *node, - service_table *in); +/*! + * \brief Free's memory allocated for the various components of each service + * entry in the service table. + */ +void freeServiceList( + /*! [in] Head of the service list to be freed. */ + service_info *head); -/************************************************************************ -* Function : addServiceTable -* -* Parameters : -* IXML_Node *node ; XML node information -* service_table *in ; service table that will be initialized with -* services -* const char *DefaultURLBase ; Default base URL on which the URL -* will be returned to the service list. -* -* Description : Add Service to the table. -* -* Return : int ; -* -* Note : -************************************************************************/ -int addServiceTable(IXML_Node *node, service_table *in, const char *DefaultURLBase); - -/************************************************************************ -* Function : getServiceTable -* -* Parameters : -* IXML_Node *node ; XML node information -* service_table *out ; output parameter which will contain the -* service list and URL -* const char *DefaultURLBase ; Default base URL on which the URL -* will be returned. -* -* Description : Retrieve service from the table -* -* Return : int ; -* -* Note : -************************************************************************/ -int getServiceTable(IXML_Node *node, service_table * out, const char * DefaultURLBase); +/*! + * \brief Free's dynamic memory in table (does not free table, only memory + * within the structure). + */ +void freeServiceTable( + /*! [in] Service table whose internal memory needs to be freed. */ + service_table *table); -/* Misc helper functions */ +/*! + * \brief This function assumes that services for a particular root device are + * placed linearly in the service table, and in the order in which they are + * found in the description document all services for this root device are + * removed from the list. + * + * \return An integer. + */ +int removeServiceTable( + /*! [in] XML node information. */ + IXML_Node *node, + /*! [in] Service table from which services will be removed. */ + service_table *in); -/************************************************************************ -* Function : getElementValue -* -* Parameters : -* IXML_Node *node ; Input node which provides the list of child -* nodes -* -* Description : Returns the clone of the element value -* -* Return : DOMString ; -* -* Note : value must be freed with DOMString_free -************************************************************************/ -DOMString getElementValue(IXML_Node *node); +/*! + * \brief Add Service to the table. + */ +int addServiceTable( + /*! [in] XML node information. */ + IXML_Node *node, + /*! [in] Service table that will be initialized with services. */ + service_table *in, + /*! [in] Default base URL on which the URL will be returned to the + * service list. */ + const char *DefaultURLBase); -/************************************************************************ -* Function : getSubElement -* -* Parameters : -* const char *element_name ; sub element name to be searched for -* IXML_Node *node ; Input node which provides the list of child -* nodes -* IXML_Node **out ; Ouput node to which the matched child node is -* returned. -* -* Description : Traverses through a list of XML nodes to find the -* node with the known element name. -* -* Return : int ; -* 1 - On Success -* 0 - On Failure -* -* Note : -************************************************************************/ -int getSubElement(const char *element_name, IXML_Node *node, - IXML_Node **out); + +/*! + * \brief Retrieve service from the table. + * + * \return An integer + */ +int getServiceTable( + /*! [in] XML node information. */ + IXML_Node *node, + /*! [in] Output parameter which will contain the service list and URL. */ + service_table *out, + /*! [in] Default base URL on which the URL will be returned. */ + const char *DefaultURLBase); + + +/* Misc helper functions */ + + +/*! + * \brief Returns the clone of the element value. + * + * \note Value must be freed with DOMString_free. + * + * \return DOMString + */ +DOMString getElementValue( + /*! [in] Input node which provides the list of child nodes. */ + IXML_Node *node); + + +/*! + * \brief Traverses through a list of XML nodes to find the node with the + * known element name. + * + * \return + * \li 1 - On Success + * \li 0 - On Failure + */ +int getSubElement( + /*! [in] Sub element name to be searched for. */ + const char *element_name, + /*! [in] Input node which provides the list of child nodes. */ + IXML_Node *node, + /*! [out] Ouput node to which the matched child node is returned. */ + IXML_Node **out); #endif /* INCLUDE_DEVICE_APIS */ @@ -479,5 +382,5 @@ int getSubElement(const char *element_name, IXML_Node *node, } #endif -#endif /* _SERVICE_TABLE */ +#endif /* SERVICE_TABLE */ diff --git a/upnp/src/inc/uri.h b/upnp/src/inc/uri.h index 1c3847c..69f4418 100644 --- a/upnp/src/inc/uri.h +++ b/upnp/src/inc/uri.h @@ -1,65 +1,75 @@ -/////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2000-2003 Intel Corporation -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither name of Intel Corporation nor the names of its contributors -// may be used to endorse or promote products derived from this software -// without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR -// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY -// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////// +/******************************************************************************* + * + * Copyright (c) 2000-2003 Intel Corporation + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither name of Intel Corporation nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + ******************************************************************************/ + #ifndef GENLIB_NET_URI_H #define GENLIB_NET_URI_H + +/*! + * \file + */ + + +#include "UpnpGlobal.h" /* for */ +#include "UpnpInet.h" + + +#include +#include +#include +#include +#include +#include +#include + + +#ifdef WIN32 +#else + #include /* for inet_pton() */ + #include /* for struct addrinfo */ +#endif + + +#ifdef WIN32 + #define strncasecmp strnicmp +#else + /* Other systems have strncasecmp */ +#endif + + #ifdef __cplusplus extern "C" { #endif -#include -#include -#include -//#include -#include -#include -#include -#include -#ifndef WIN32 - #include - #include - #include - #include - #include - #include -#else - #include - - #define strncasecmp strnicmp -#endif - -#include "upnp.h" -//#include - #define HTTP_DATE_LENGTH 37 // length for HTTP DATE: //"DATE: Sun, 01 Jul 2000 08:15:23 GMT" @@ -68,458 +78,520 @@ extern "C" { #define RESERVED ";/?:@&=+$,{}" //added {} for compatibility #define HTTP_SUCCESS 1 + #define FALSE 0 #define TAB 9 #define CR 13 #define LF 10 #define SOCKET_BUFFER_SIZE 5000 -enum hostType { HOSTNAME, IPv4address }; -enum pathType { ABS_PATH, REL_PATH, OPAQUE_PART }; -#ifndef WIN32 -// there is a conflict in windows with other symbols -enum uriType { ABSOLUTE, RELATIVE }; + +enum hostType { + HOSTNAME, + IPv4address +}; + + +enum pathType { + ABS_PATH, + REL_PATH, + OPAQUE_PART +}; + + +#ifdef WIN32 + /* there is a conflict in windows with other symbols */ + enum uriType { + absolute, + relative + }; #else -enum uriType { absolute, relative }; + enum uriType { + ABSOLUTE, + RELATIVE + }; #endif -/* Buffer used in parsinghttp messages, urls, etc. generally this simply -* holds a pointer into a larger array */ + +/*! + * \brief Buffer used in parsinghttp messages, urls, etc. generally this simply + * holds a pointer into a larger array. + */ typedef struct TOKEN { - const char *buff; - size_t size; + const char *buff; + size_t size; } token; -/* Represents a host port:e.g. :"127.127.0.1:80" -* text is a token pointing to the full string representation */ +/*! + * \brief Represents a host port: e.g. "127.127.0.1:80" text is a token + * pointing to the full string representation. + */ typedef struct HOSTPORT { - token text; //full host port - struct sockaddr_in IPv4address; //Network Byte Order + /*! Full host port. */ + token text; + /* Network Byte Order */ + struct sockaddr_in IPv4address; } hostport_type; -/* Represents a URI used in parse_uri and elsewhere */ + +/*! + * \brief Represents a URI used in parse_uri and elsewhere + */ typedef struct URI{ - enum uriType type; - token scheme; - enum pathType path_type; - token pathquery; - token fragment; - hostport_type hostport; + enum uriType type; + token scheme; + enum pathType path_type; + token pathquery; + token fragment; + hostport_type hostport; } uri_type; -/* Represents a list of URLs as in the "callback" header of SUBSCRIBE -* message in GENA -* char * URLs holds dynamic memory */ + +/*! + * \brief Represents a list of URLs as in the "callback" header of SUBSCRIBE + * message in GENA. "char *" URLs holds dynamic memory. + */ typedef struct URL_LIST { - int size; - char * URLs; //all the urls, delimited by <> - uri_type *parsedURLs; + /*! */ + int size; + /*! All the urls, delimited by <> */ + char *URLs; + /*! */ + uri_type *parsedURLs; } URL_list; -/************************************************************************ -* Function : replace_escaped -* -* Parameters : -* char * in ; string of characters -* int index ; index at which to start checking the characters -* size_t *max ; -* -* Description : Replaces an escaped sequence with its unescaped version -* as in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* Size of array is NOT checked (MUST be checked by caller) -* -* Return : int ; -* -* Note : This function modifies the string. If the sequence is an -* escaped sequence it is replaced, the other characters in the -* string are shifted over, and NULL characters are placed at the -* end of the string. -************************************************************************/ -int replace_escaped(char * in, int index, size_t *max); +/*! + * \brief Replaces an escaped sequence with its unescaped version as in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) + * + * Size of array is NOT checked (MUST be checked by caller) + * + * \note This function modifies the string. If the sequence is an escaped + * sequence it is replaced, the other characters in the string are shifted + * over, and NULL characters are placed at the end of the string. + * + * \return + */ +int replace_escaped( + /*! [in] String of characters. */ + char *in, + /*! [in] Index at which to start checking the characters. */ + int index, + /*! [out] . */ + size_t *max); -/************************************************************************ -* Function : copy_URL_list -* -* Parameters : -* URL_list *in ; Source URL list -* URL_list *out ; Destination URL list -* -* Description : Copies one URL_list into another. This includes -* dynamically allocating the out->URLs field (the full string), -* and the structures used to hold the parsedURLs. This memory MUST -* be freed by the caller through: free_URL_list(&out) -* -* Return : int ; -* HTTP_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On Failure to allocate memory -* -* Note : -************************************************************************/ -int copy_URL_list( URL_list *in, URL_list *out); -/************************************************************************ -* Function : free_URL_list -* -* Parameters : -* URL_list * list ; URL List object -* -* Description : Frees the memory associated with a URL_list. Frees the -* dynamically allocated members of of list. Does NOT free the -* pointer to the list itself ( i.e. does NOT free(list)) -* -* Return : void ; -* -* Note : -************************************************************************/ -void free_URL_list(URL_list * list); +/*! + * \brief Copies one URL_list into another. + * + * This includes dynamically allocating the out->URLs field (the full string), + * and the structures used to hold the parsedURLs. This memory MUST be freed + * by the caller through: free_URL_list(&out). + * + * \return + * \li HTTP_SUCCESS - On Success. + * \li UPNP_E_OUTOF_MEMORY - On Failure to allocate memory. + */ +int copy_URL_list( + /*! [in] Source URL list. */ + URL_list *in, + /*! [out] Destination URL list. */ + URL_list *out); -/************************************************************************ -* Function : print_uri -* -* Parameters : -* uri_type *in ; URI object -* -* Description : Function useful in debugging for printing a parsed uri. -* -* Return : void ; -* -* Note : -************************************************************************/ +/*! + * \brief Frees the memory associated with a URL_list. + * + * Frees the dynamically allocated members of of list. Does NOT free the + * pointer to the list itself ( i.e. does NOT free(list)). + */ +void free_URL_list( + /*! [in] URL list object. */ + URL_list *list); + + +/*! + * \brief Function useful in debugging for printing a parsed uri. + */ #ifdef DEBUG -void print_uri(uri_type *in); +void print_uri( + /*! [in] URI object to print. */ + uri_type *in); #else static UPNP_INLINE void print_uri(uri_type *in) {} #endif -/************************************************************************ -* Function : print_token -* -* Parameters : -* token * in ; -* -* Description : Function useful in debugging for printing a token. -* -* Return : void ; -* -* Note : -************************************************************************/ + +/*! + * \brief Function useful in debugging for printing a token. + */ #ifdef DEBUG -void print_token(token *in); +void print_token( + /*! [in] Token object to print. */ + token *in); #else static UPNP_INLINE void print_token(token * in) {} #endif -/************************************************************************ -* Function : token_string_casecmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares buffer in the token object with the buffer -* in in2 -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_string_casecmp( token * in1, char * in2); -/************************************************************************ -* Function : token_string_cmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares a null terminated string to a token (exact) -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_string_cmp( token * in1, char * in2); - -/************************************************************************ -* Function : token_cmp -* -* Parameters : -* token *in1 ; First token object whose buffer is to be compared -* token *in2 ; Second token object used for the comparison -* -* Description : Compares two tokens -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_cmp( token *in1, token *in2); - -/************************************************************************ -* Function : parse_port -* -* Parameters : -* int max ; sets a maximum limit -* char * port ; port to be parsed. -* unsigned short * out ; out parameter where the port is parsed -* and converted into network format -* -* Description : parses a port (i.e. '4000') and converts it into a -* network ordered unsigned short int. -* -* Return : int ; -* -* Note : -************************************************************************/ -int parse_port(int max, const char *port, unsigned short int *out); - -/************************************************************************ -* Function : parse_hostport -* -* Parameters : -* char *in ; string of characters representing host and port -* int max ; sets a maximum limit -* hostport_type *out ; out parameter where the host and port -* are represented as an internet address -* -* Description : Parses a string representing a host and port -* (e.g. "127.127.0.1:80" or "localhost") and fills out a -* hostport_type struct with internet address and a token -* representing the full host and port. uses gethostbyname. -* -* Return : int ; -* -* Note : -************************************************************************/ -int parse_hostport(const char *in, int max, hostport_type *out ); - -/************************************************************************ -* Function : remove_escaped_chars -* -* Parameters : -* INOUT char *in ; string of characters to be modified -* INOUT size_t *size ; size limit for the number of characters -* -* Description : removes http escaped characters such as: "%20" and -* replaces them with their character representation. i.e. -* "hello%20foo" -> "hello foo". The input IS MODIFIED in place. -* (shortened). Extra characters are replaced with NULL. -* -* Return : int ; -* UPNP_E_SUCCESS -* -* Note : -************************************************************************/ -int remove_escaped_chars(char *in, size_t *size); - -/************************************************************************ -* Function : remove_dots -* -* Parameters : -* char *in ; string of characters from which "dots" have to be -* removed -* int size ; size limit for the number of characters -* -* Description : Removes ".", and ".." from a path. If a ".." can not -* be resolved (i.e. the .. would go past the root of the path) an -* error is returned. The input IS modified in place.) -* -* Return : int ; -* UPNP_E_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On failure to allocate memory -* UPNP_E_INVALID_URL - Failure to resolve URL -* -* Note : -* Examples -* char path[30]="/../hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_INVALID_URL -* char path[30]="/./hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_SUCCESS, -* in = "/hello" -* char path[30]="/./hello/foo/../goodbye" -> -* UPNP_E_SUCCESS, in = "/hello/goodbye" - -************************************************************************/ -int remove_dots(char * in, int size); - -/************************************************************************ -* Function : resolve_rel_url -* -* Parameters : -* char * base_url ; Base URL -* char * rel_url ; Relative URL -* -* Description : resolves a relative url with a base url returning a NEW -* (dynamically allocated with malloc) full url. If the base_url is -* NULL, then a copy of the rel_url is passed back if the rel_url -* is absolute then a copy of the rel_url is passed back if neither -* the base nor the rel_url are Absolute then NULL is returned. -* otherwise it tries and resolves the relative url with the base -* as described in: http://www.ietf.org/rfc/rfc2396.txt (RFCs -* explaining URIs) -* : resolution of '..' is NOT implemented, but '.' is resolved -* -* Return : char * ; -* -* Note : -************************************************************************/ -char * resolve_rel_url( char * base_url, char * rel_url); - -/************************************************************************ -* Function : parse_uri -* -* Parameters : -* char * in ; character string containing uri information to be -* parsed -* int max ; maximum limit on the number of characters -* uri_type * out ; out parameter which will have the parsed uri -* information -* -* Description : parses a uri as defined in http://www.ietf.org/rfc/ -* rfc2396.txt (RFC explaining URIs) -* Handles absolute, relative, and opaque uris. Parses into the -* following pieces: scheme, hostport, pathquery, fragment (path and -* query are treated as one token) -* Caller should check for the pieces they require. -* -* Return : int ; -* -* Note : -************************************************************************/ -int parse_uri(const char * in, int max, uri_type * out); - -/************************************************************************ -* Function : parse_uri_and_unescape -* -* Parameters : -* char * in ; -* int max ; -* uri_type * out ; -* -* Description : Same as parse_uri, except that all strings are -* unescaped (%XX replaced by chars) -* -* Return : int ; -* -* Note: This modifies 'pathquery' and 'fragment' parts of the input -************************************************************************/ -int parse_uri_and_unescape(char * in, int max, uri_type * out); - -int parse_token( char * in, token * out, int max_size); - -/************************************************************************ -* commented #defines, functions and typdefs * -************************************************************************/ - -/************************************************************************ -* Commented #defines * -************************************************************************/ -//#define HTTP_E_BAD_URL UPNP_E_INVALID_URL -//#define HTTP_E_READ_SOCKET UPNP_E_SOCKET_READ -//#define HTTP_E_BIND_SOCKET UPNP_E_SOCKET_BIND -//#define HTTP_E_WRITE_SOCKET UPNP_E_SOCKET_WRITE -//#define HTTP_E_CONNECT_SOCKET UPNP_E_SOCKET_CONNECT -//#define HTTP_E_SOCKET UPNP_E_OUTOF_SOCKET -//#define HTTP_E_BAD_RESPONSE UPNP_E_BAD_RESPONSE -//#define HTTP_E_BAD_REQUEST UPNP_E_BAD_REQUEST -//#define HTTP_E_BAD_IP_ADDRESS UPNP_E_INVALID_URL - -//#define RESPONSE_TIMEOUT 30 - -/************************************************************************ -* Commented typedefs * -************************************************************************/ -//Buffer used to store data read from a socket during an http transfer -//in function read_bytes. -//typedef struct SOCKET_BUFFER{ -// char buff[SOCKET_BUFFER_SIZE]; -// int size; -// struct SOCKET_BUFFER *next; -//} socket_buffer; - -//typedef struct HTTP_HEADER { -// token header; -// token value; -// struct HTTP_HEADER * next; -//} http_header; - -//typedef struct HTTP_STATUS_LINE{ -// token http_version; -// token status_code; -// token reason_phrase; -//} http_status; - -//typedef struct HTTP_REQUEST_LINE { -// token http_version; -// uri_type request_uri; -// token method; -//} http_request; - -//Represents a parsed HTTP_MESSAGE head_list is dynamically allocated -//typedef struct HTTP_MESSAGE { -// http_status status; -// http_request request; -// http_header * header_list; -// token content; -//} http_message; - -/************************************************************************ -* Commented functions * -************************************************************************ - -EXTERN_C int transferHTTP( char * request, char * toSend, - int toSendSize, char **out, char * Url); +/*! + * \brief Compares buffer in the token object with the buffer in in2. + * + * \return + * \li < 0, if string1 is less than string2. + * \li == 0, if string1 is identical to string2 . + * \li > 0, if string1 is greater than string2. + */ +int token_string_casecmp( + /*! [in] Token object whose buffer is to be compared. */ + token *in1, + /*! [in] String of characters to compare with. */ + char *in2); -EXTERN_C int transferHTTPRaw( char * toSend, int toSendSize, - char **out, char *URL); +/*! + * \brief Compares a null terminated string to a token (exact). + * + * \return + * \li < 0, if string1 is less than string2. + * \li == 0, if string1 is identical to string2 . + * \li > 0, if string1 is greater than string2. + */ +int token_string_cmp( + /*! [in] Token object whose buffer is to be compared. */ + token *in1, + /*! [in] String of characters to compare with. */ + char *in2); -helper function -EXTERN_C int transferHTTPparsedURL( char * request, - char * toSend, int toSendSize, - char **out, uri_type *URL); -assumes that char * out has enough space ( 38 characters) -outputs the current time in the following null terminated string: - "DATE: Sun, Jul 06 2000 08:53:01 GMT\r\n" -EXTERN_C void currentTmToHttpDate(char *out); +/*! + * \brief Compares two tokens. + * + * \return + * \li < 0, if string1 is less than string2. + * \li == 0, if string1 is identical to string2 . + * \li > 0, if string1 is greater than string2. + */ +int token_cmp( + /*! [in] First token object whose buffer is to be compared. */ + token *in1, + /*! [in] Second token object used for the comparison. */ + token *in2); -EXTERN_C int parse_http_response( char * in, http_message * out, - int max_len); -EXTERN_C int parse_http_request( char * in, http_message *out, - int max_len); +/*! + * \brief Parses a port (i.e. '4000') and converts it into a network ordered + * unsigned short int. + * + * \return + */ +int parse_port( + /*! [in] Sets a maximum limit. */ + int max, + /*! [in] Port to be parsed. */ + const char *port, + /*! [out] Output parameter where the port is parsed and converted into + * network format. */ + unsigned short int *out); -EXTERN_C void print_http_message( http_message * message); -EXTERN_C int search_for_header( http_message * in, - char * header, token *out_value); -EXTERN_C void print_status_line(http_status *in); -EXTERN_C void print_request_line(http_request *in); -EXTERN_C int parse_http_line( char * in, int max_size); -EXTERN_C int parse_not_LWS( char *in, token *out, int max_size); -EXTERN_C int parse_LWS( char * in, int max_size); +/*! + * \brief Parses a string representing a host and port (e.g. "127.127.0.1:80" + * or "localhost") and fills out a hostport_type struct with internet address + * and a token representing the full host and port. + * + * Uses gethostbyname. + */ +int parse_hostport( + /*! [in] String of characters representing host and port. */ + const char *in, + /*! [in] Sets a maximum limit. */ + int max, + /*! [out] Output parameter where the host and port are represented as + * an internet address. */ + hostport_type *out); -EXTERN_C size_t write_bytes(int fd, char * bytes, size_t n, - int timeout); -EXTERN_C void free_http_message(http_message * message); -************************************************************************/ +/*! + * \brief Removes http escaped characters such as: "%20" and replaces them with + * their character representation. i.e. "hello%20foo" -> "hello foo". + * + * The input IS MODIFIED in place (shortened). Extra characters are replaced + * with \b NULL. + * + * \return UPNP_E_SUCCESS. + */ +int remove_escaped_chars( + /*! [in,out] String of characters to be modified. */ + char *in, + /*! [in,out] Size limit for the number of characters. */ + size_t *size); + + +/*! + * \brief Removes ".", and ".." from a path. + * + * If a ".." can not be resolved (i.e. the .. would go past the root of the + * path) an error is returned. + * + * The input IS modified in place.) + * + * \note Examples + * char path[30]="/../hello"; + * remove_dots(path, strlen(path)) -> UPNP_E_INVALID_URL + * char path[30]="/./hello"; + * remove_dots(path, strlen(path)) -> UPNP_E_SUCCESS, + * in = "/hello" + * char path[30]="/./hello/foo/../goodbye" -> + * UPNP_E_SUCCESS, in = "/hello/goodbye" + * + * \return + * \li UPNP_E_SUCCESS - On Success. + * \li UPNP_E_OUTOF_MEMORY - On failure to allocate memory. + * \li UPNP_E_INVALID_URL - Failure to resolve URL. + */ +int remove_dots( + /*! [in] String of characters from which "dots" have to be removed. */ + char *in, + /*! [in] Size limit for the number of characters. */ + size_t size); + + +/*! + * \brief resolves a relative url with a base url returning a NEW (dynamically + * allocated with malloc) full url. + * + * If the base_url is \b NULL, then a copy of the rel_url is passed back if + * the rel_url is absolute then a copy of the rel_url is passed back if neither + * the base nor the rel_url are Absolute then NULL is returned. Otherwise it + * tries and resolves the relative url with the base as described in + * http://www.ietf.org/rfc/rfc2396.txt (RFCs explaining URIs). + * + * The resolution of '..' is NOT implemented, but '.' is resolved. + * + * \return + */ +char *resolve_rel_url( + /*! [in] Base URL. */ + char *base_url, + /*! [in] Relative URL. */ + char *rel_url); + + +/*! + * \brief Parses a uri as defined in http://www.ietf.org/rfc/rfc2396.txt + * (RFC explaining URIs). + * + * Handles absolute, relative, and opaque uris. Parses into the following + * pieces: scheme, hostport, pathquery, fragment (path and query are treated + * as one token) + * + * Caller should check for the pieces they require. + * + * \return + */ +int parse_uri( + /*! [in] Character string containing uri information to be parsed. */ + const char *in, + /*! [in] Maximum limit on the number of characters. */ + int max, + /*! [out] Output parameter which will have the parsed uri information. */ + uri_type *out); + + +/*! + * \brief Same as parse_uri(), except that all strings are unescaped + * (%XX replaced by chars). + * + * \note This modifies 'pathquery' and 'fragment' parts of the input. + * + * \return + */ +int parse_uri_and_unescape( + /*! [in] Character string containing uri information to be parsed. */ + char *in, + /*! [in] Maximum limit on the number of characters. */ + int max, + /*! [out] Output parameter which will have the parsed uri information. */ + uri_type *out); + + +/*! + * \brief + * + * \return + */ +int parse_token( + /*! [in] . */ + char *in, + /*! [out] . */ + token *out, + /*! [in] . */ + int max_size); + + +/* Commented #defines, functions and typdefs */ + +#if 0 +#define HTTP_E_BAD_URL UPNP_E_INVALID_URL +#define HTTP_E_READ_SOCKET UPNP_E_SOCKET_READ +#define HTTP_E_BIND_SOCKET UPNP_E_SOCKET_BIND +#define HTTP_E_WRITE_SOCKET UPNP_E_SOCKET_WRITE +#define HTTP_E_CONNECT_SOCKET UPNP_E_SOCKET_CONNECT +#define HTTP_E_SOCKET UPNP_E_OUTOF_SOCKET +#define HTTP_E_BAD_RESPONSE UPNP_E_BAD_RESPONSE +#define HTTP_E_BAD_REQUEST UPNP_E_BAD_REQUEST +#define HTTP_E_BAD_IP_ADDRESS UPNP_E_INVALID_URL + +#define RESPONSE_TIMEOUT 30 +#endif + +#if 0 +/*! + * Buffer used to store data read from a socket during an http transfer in + * function read_bytes. + */ +typedef struct SOCKET_BUFFER{ + char buff[SOCKET_BUFFER_SIZE]; + int size; + struct SOCKET_BUFFER *next; +} socket_buffer; + + +typedef struct HTTP_HEADER { + token header; + token value; + struct HTTP_HEADER * next; +} http_header; + + +typedef struct HTTP_STATUS_LINE{ + token http_version; + token status_code; + token reason_phrase; +} http_status; + + +typedef struct HTTP_REQUEST_LINE { + token http_version; + uri_type request_uri; + token method; +} http_request; + + +/*! + * Represents a parsed HTTP_MESSAGE head_list is dynamically allocated + */ +typedef struct HTTP_MESSAGE { + http_status status; + http_request request; + http_header * header_list; + token content; +} http_message; +#endif + + +#if 0 +int transferHTTP( + char *request, + char *toSend, + int toSendSize, + char **out, + char *Url); + + +int transferHTTPRaw( + char *toSend, + int toSendSize, + char **out, + char *URL); + + +/*! + * \brief helper function. + */ +int transferHTTPparsedURL( + char *request, + char *toSend, + int toSendSize, + char **out, + uri_type *URL); + + +/*! + * \brief assumes that char * out has enough space ( 38 characters) + * outputs the current time in the following null terminated string: + * "DATE: Sun, Jul 06 2000 08:53:01 GMT\r\n" + */ +void currentTmToHttpDate( + char *out); + + +int parse_http_response( + char *in, + http_message *out, + int max_len); + + +int parse_http_request( + char *in, + http_message *out, + int max_len); + + +void print_http_message( + http_message *message); + + +int search_for_header( + http_message *in, + char *header, + token *out_value); + + +void print_status_line( + http_status *in); + + +void print_request_line( + http_request *in); + + +int parse_http_line( + char *in, + int max_size); + + +int parse_not_LWS( + char *in, + token *out, + int max_size); + + +int parse_LWS( + char *in, + int max_size); + + +size_t write_bytes( + int fd, + char *bytes, + size_t n, + int timeout); + + +void free_http_message( + http_message *message); + + +#endif + #ifdef __cplusplus } #endif -#endif // GENLIB_NET_URI_H + +#endif /* GENLIB_NET_URI_H */ diff --git a/upnp/src/ssdp/ssdp_device.c b/upnp/src/ssdp/ssdp_device.c index 94af8aa..27a2c30 100644 --- a/upnp/src/ssdp/ssdp_device.c +++ b/upnp/src/ssdp/ssdp_device.c @@ -1,60 +1,62 @@ -/////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2000-2003 Intel Corporation -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither name of Intel Corporation nor the names of its contributors -// may be used to endorse or promote products derived from this software -// without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR -// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY -// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////// +/************************************************************************** + * + * Copyright (c) 2000-2003 Intel Corporation + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither name of Intel Corporation nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + **************************************************************************/ + #include "config.h" + #ifdef INCLUDE_DEVICE_APIS #if EXCLUDE_SSDP == 0 + +#include "httpparser.h" +#include "httpreadwrite.h" +#include "ssdplib.h" +#include "statcodes.h" +#include "ThreadPool.h" +#include "unixutil.h" +#include "upnpapi.h" +#include "UpnpInet.h" + + #include #include #include -#include "ssdplib.h" -#include "upnpapi.h" -#include "ThreadPool.h" -#include "httpparser.h" -#include "httpreadwrite.h" -#include "statcodes.h" -#include "unixutil.h" - -#ifdef WIN32 - #include - #include -#endif /* WIN32 */ #define MSGTYPE_SHUTDOWN 0 #define MSGTYPE_ADVERTISEMENT 1 #define MSGTYPE_REPLY 2 + /************************************************************************ * Function : advertiseAndReplyThread * @@ -88,7 +90,7 @@ advertiseAndReplyThread( IN void *data ) * Function : ssdp_handle_device_request * * Parameters: -* IN http_message_t* hmsg: SSDP search request from the control point +* IN http_message_t *hmsg: SSDP search request from the control point * IN struct sockaddr_in* dest_addr: The address info of control point * * Description: @@ -101,7 +103,7 @@ advertiseAndReplyThread( IN void *data ) ***************************************************************************/ #ifdef INCLUDE_DEVICE_APIS void -ssdp_handle_device_request( IN http_message_t * hmsg, +ssdp_handle_device_request( IN http_message_t *hmsg, IN struct sockaddr_in *dest_addr ) { #define MX_FUDGE_FACTOR 10 @@ -337,7 +339,7 @@ CreateServicePacket( IN int msg_type, // NOTE: The CACHE-CONTROL and LOCATION headers are not present in // a shutdown msg, but are present here for MS WinMe interop. - + ret_code = http_MakeMessage( &buf, 1, 1, "Q" "sssdc" "sdc" "ssc" "ssc" "ssc" "S" "Xc" "sscc", @@ -397,7 +399,7 @@ DeviceAdvertisement( IN char *DevType, int ret_code; UpnpPrintf( UPNP_INFO, SSDP, __FILE__, __LINE__, - "In function SendDeviceAdvertisemenrt\n" ); + "In function DeviceAdvertisement\n" ); DestAddr.sin_family = AF_INET; DestAddr.sin_addr.s_addr = inet_addr( SSDP_IP ); @@ -412,7 +414,7 @@ DeviceAdvertisement( IN char *DevType, if( RootDev ) { sprintf( Mil_Usn, "%s::upnp:rootdevice", Udn ); CreateServicePacket( MSGTYPE_ADVERTISEMENT, "upnp:rootdevice", - Mil_Usn, Location, Duration, &msgs[0] ); + Mil_Usn, Location, Duration, &msgs[0] ); } // both root and sub-devices need to send these two messages // @@ -550,7 +552,7 @@ DeviceReply( IN struct sockaddr_in *DestAddr, IN int RootDev, IN char *Udn, IN char *Location, - IN int Duration ) + IN int Duration) { char *szReq[3], Mil_Nt[LINE_SIZE], @@ -624,7 +626,7 @@ int ServiceAdvertisement( IN char *Udn, IN char *ServType, IN char *Location, - IN int Duration ) + IN int Duration) { char Mil_Usn[LINE_SIZE]; char *szReq[1]; @@ -713,7 +715,7 @@ int ServiceShutdown( IN char *Udn, IN char *ServType, IN char *Location, - IN int Duration ) + IN int Duration) { char Mil_Usn[LINE_SIZE]; char *szReq[1]; @@ -762,7 +764,7 @@ DeviceShutdown( IN char *DevType, IN char *Udn, IN char *_Server, IN char *Location, - IN int Duration ) + IN int Duration) { struct sockaddr_in DestAddr; char *msgs[3]; diff --git a/upnp/src/urlconfig/urlconfig.c b/upnp/src/urlconfig/urlconfig.c index c2877d2..8b10575 100644 --- a/upnp/src/urlconfig/urlconfig.c +++ b/upnp/src/urlconfig/urlconfig.c @@ -1,51 +1,60 @@ -/////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2000-2003 Intel Corporation -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither name of Intel Corporation nor the names of its contributors -// may be used to endorse or promote products derived from this software -// without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR -// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY -// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////// +/************************************************************************** + * + * Copyright (c) 2000-2003 Intel Corporation + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither name of Intel Corporation nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + **************************************************************************/ + #include "config.h" -#include -#ifndef WIN32 - #include - #include - #include - #include -#else - #include -#endif + + +#include "membuffer.h" +#include "unixutil.h" #include "upnp.h" +#include "upnpdebug.h" +#include "UpnpInet.h" +#include "uri.h" +#include "urlconfig.h" #include "util.h" #include "webserver.h" -#include "uri.h" -#include "membuffer.h" -#include "urlconfig.h" -#include "unixutil.h" + + +#include +#include + + +#ifdef WIN32 +#else + #include + #include + #include +#endif + /************************************************************************ * Function : addrToString