From 9326b73d06ba3f038549f32025936ff14353ddae Mon Sep 17 00:00:00 2001 From: Marcelo Roberto Jimenez Date: Sun, 4 May 2008 19:56:15 +0000 Subject: [PATCH] Doxygenation. git-svn-id: https://pupnp.svn.sourceforge.net/svnroot/pupnp/trunk@366 119443c7-1b9e-41f8-b6fc-b9c35fce742c --- Doxyfile | 6 +- upnp/inc/ActionRequest.h | 2 +- upnp/inc/Discovery.h | 4 +- upnp/inc/Event.h | 2 +- upnp/inc/EventSubscribe.h | 6 +- upnp/inc/String.h | 4 + upnp/inc/SubscriptionRequest.h | 2 +- upnp/inc/upnp.h | 2994 +++++++++++++++----------------- upnp/inc/upnpdebug.h | 83 +- upnp/src/api/upnpapi.c | 524 ++---- upnp/src/api/upnpdebug.c | 58 +- upnp/src/inc/VirtualDir.h | 38 +- 12 files changed, 1715 insertions(+), 2008 deletions(-) diff --git a/Doxyfile b/Doxyfile index 462421d..c78da76 100644 --- a/Doxyfile +++ b/Doxyfile @@ -31,7 +31,7 @@ PROJECT_NAME = libUPnP # This could be handy for archiving the generated documentation or # if some version control system is used. -PROJECT_NUMBER = 1.4.7 +PROJECT_NUMBER = 1.8.0 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. @@ -322,7 +322,7 @@ INLINE_INFO = YES # alphabetically by member name. If set to NO the members will appear in # declaration order. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the # brief documentation of file, namespace and class members alphabetically @@ -1029,7 +1029,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = DEBUG # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/upnp/inc/ActionRequest.h b/upnp/inc/ActionRequest.h index 9ae6f6f..24fe79a 100644 --- a/upnp/inc/ActionRequest.h +++ b/upnp/inc/ActionRequest.h @@ -9,7 +9,7 @@ extern "C" { #endif /* __cplusplus */ -/** Returned as part of a {\bf UPNP_CONTROL_ACTION_COMPLETE} callback. */ +/** Returned as part of a \b UPNP_CONTROL_ACTION_COMPLETE callback. */ typedef struct {} UpnpActionRequest; diff --git a/upnp/inc/Discovery.h b/upnp/inc/Discovery.h index 4ac5667..d8fde98 100644 --- a/upnp/inc/Discovery.h +++ b/upnp/inc/Discovery.h @@ -9,7 +9,7 @@ extern "C" { #endif /* __cplusplus */ -/** Returned in a {\bf UPNP_DISCOVERY_RESULT} callback. */ +/** Returned in a \b UPNP_DISCOVERY_RESULT callback. */ typedef struct {} UpnpDiscovery; @@ -31,7 +31,7 @@ UpnpDiscovery *UpnpDiscovery_dup(const UpnpDiscovery *p); /** Assignment operator */ void UpnpDiscovery_assign(UpnpDiscovery *q, const UpnpDiscovery *p); -/** The result code of the {\bf UpnpSearchAsync} call. */ +/** The result code of the \b UpnpSearchAsync call. */ int UpnpDiscovery_get_ErrCode(const UpnpDiscovery *p); void UpnpDiscovery_set_ErrCode(UpnpDiscovery *p, int n); diff --git a/upnp/inc/Event.h b/upnp/inc/Event.h index 8be3349..a909842 100644 --- a/upnp/inc/Event.h +++ b/upnp/inc/Event.h @@ -9,7 +9,7 @@ extern "C" { #endif /* __cplusplus */ -/** Returned along with a {\bf UPNP_EVENT_RECEIVED} callback. */ +/** Returned along with a \b UPNP_EVENT_RECEIVED callback. */ typedef struct {} UpnpEvent; diff --git a/upnp/inc/EventSubscribe.h b/upnp/inc/EventSubscribe.h index 75f423d..49be9cf 100644 --- a/upnp/inc/EventSubscribe.h +++ b/upnp/inc/EventSubscribe.h @@ -9,8 +9,8 @@ extern "C" { #endif /* __cplusplus */ -/** Returned along with a {\bf UPNP_EVENT_SUBSCRIBE_COMPLETE} or - * {\bf UPNP_EVENT_UNSUBSCRIBE_COMPLETE} callback. */ +/** Returned along with a \b UPNP_EVENT_SUBSCRIBE_COMPLETE or + * \b UPNP_EVENT_UNSUBSCRIBE_COMPLETE callback. */ typedef struct {} UpnpEventSubscribe; @@ -38,7 +38,7 @@ int UpnpEventSubscribe_get_TimeOut(const UpnpEventSubscribe *p); void UpnpEventSubscribe_set_TimeOut(UpnpEventSubscribe *p, int n); /** The SID for this subscription. For subscriptions, this only - * contains a valid SID if the {\bf Upnp_EventSubscribe.result} field + * contains a valid SID if the \b Upnp_EventSubscribe.result field * contains a {\tt UPNP_E_SUCCESS} result code. For unsubscriptions, * this contains the SID from which the subscription is being * unsubscribed. */ diff --git a/upnp/inc/String.h b/upnp/inc/String.h index bcf2473..a64dc2d 100644 --- a/upnp/inc/String.h +++ b/upnp/inc/String.h @@ -4,11 +4,15 @@ #define STRING_H +/** \file */ + + #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ +/** Type of the string objects inside libupnp. */ typedef struct {} UpnpString; diff --git a/upnp/inc/SubscriptionRequest.h b/upnp/inc/SubscriptionRequest.h index 5a325e9..294ab02 100644 --- a/upnp/inc/SubscriptionRequest.h +++ b/upnp/inc/SubscriptionRequest.h @@ -9,7 +9,7 @@ extern "C" { #endif /* __cplusplus */ -/** Returned along with a {\bf UPNP_EVENT_SUBSCRIPTION_REQUEST} callback. */ +/** Returned along with a \b UPNP_EVENT_SUBSCRIPTION_REQUEST callback. */ typedef struct {} UpnpSubscriptionRequest; diff --git a/upnp/inc/upnp.h b/upnp/inc/upnp.h index 21f2f16..e7dddbd 100644 --- a/upnp/inc/upnp.h +++ b/upnp/inc/upnp.h @@ -32,9 +32,12 @@ #ifndef UPNP_H #define UPNP_H -/** @name The API */ -/*! @{ */ +/*! \file */ + + +/*! \defgroup TheApi The UPnP API */ +/*@{*/ #if defined MYLIB_LARGEFILE_SENSITIVE && _FILE_OFFSET_BITS+0 != 64 @@ -136,372 +139,274 @@ #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 +#define UPNP_E_INVALID_DEVICE -110 -/** @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. +/*! \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_INVALID_INTERFACE [-121] - * {\tt UPNP_E_INVALID_INTERFACE} signifies that the interface provided to - * {\bf UpnpInit2} is unknown or does not have a valid IPv4 or IPv6 - * address configured. +/*! \brief The interface provided to \b UpnpInit2 is unknown or does not have a valid + * IPv4 or IPv6 address configured. */ -/*! @{ */ -#define UPNP_E_INVALID_INTERFACE -121 -/*! @} */ +#define UPNP_E_INVALID_INTERFACE -121 -/** @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 A network error occurred. + * + * It is the generic error code for network problems that are not covered under + * one of the more specific error codes. The typical meaning is the SDK failed + * to read the local IP address or had problems configuring one of the sockets. */ -/*! @{ */ -#define UPNP_E_NETWORK_ERROR -200 -/*! @} */ +#define UPNP_E_NETWORK_ERROR -200 -/** @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 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_WRITE -201 -/*! @} */ +#define UPNP_E_SOCKET_WRITE -201 -/** @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 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_READ -202 -/*! @} */ +#define UPNP_E_SOCKET_READ -202 -/** @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 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_BIND -203 -/*! @} */ +#define UPNP_E_SOCKET_BIND -203 -/** @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 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_SOCKET_CONNECT -204 -/*! @} */ +#define UPNP_E_SOCKET_CONNECT -204 -/** @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 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_OUTOF_SOCKET -205 -/*! @} */ +#define UPNP_E_OUTOF_SOCKET -205 -/** @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 had a problem setting the socket to listen for incoming + * connections. + * + * This error only happens during initialization (i.e. \b UpnpInit). */ -/*! @{ */ -#define UPNP_E_LISTEN -206 -/*! @} */ +#define UPNP_E_LISTEN -206 -/** @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 Too much time elapsed before the required number of bytes were sent + * or received over a socket. + * + * This error can be returned by any function that performs network operations. */ -/*! @{ */ -#define UPNP_E_TIMEDOUT -207 -/*! @} */ +#define UPNP_E_TIMEDOUT -207 -/** @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 Generic socket error code for conditions not covered by other error + * codes. + * + * This error can be returned by any function that performs network operations. */ -/*! @{ */ -#define UPNP_E_SOCKET_ERROR -208 -/*! @} */ +#define UPNP_E_SOCKET_ERROR -208 -#define UPNP_E_FILE_WRITE_ERROR -209 +#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 The operation was canceled. + * + * This error can be returned by any function that allows for external cancelation. */ -/*! @{ */ -#define UPNP_E_CANCELED -210 -/*! @} */ +#define UPNP_E_CANCELED -210 -#define UPNP_E_EVENT_PROTOCOL -300 +#define UPNP_E_EVENT_PROTOCOL -300 -/** @name UPNP_E_SUBSCRIBE_UNACCEPTED [-301] - * {\tt UPNP_E_SUBSCRIBE_UNACCEPTED} signifies that a subscription - * request was rejected from the remote side. +/*! \brief A subscription request was rejected from the remote side. */ -/*! @{ */ -#define UPNP_E_SUBSCRIBE_UNACCEPTED -301 -/*! @} */ +#define UPNP_E_SUBSCRIBE_UNACCEPTED -301 -/** @name UPNP_E_UNSUBSCRIBE_UNACCEPTED [-302] - * {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED} signifies that an unsubscribe - * request was rejected from the remote side. +/*! \brief An unsubscribe request was rejected from the remote side. */ -/*! @{ */ -#define UPNP_E_UNSUBSCRIBE_UNACCEPTED -302 -/*! @} */ +#define UPNP_E_UNSUBSCRIBE_UNACCEPTED -302 -/** @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 The remote host did not accept the notify sent from the local device. */ -/*! @{ */ -#define UPNP_E_NOTIFY_UNACCEPTED -303 -/*! @} */ +#define UPNP_E_NOTIFY_UNACCEPTED -303 -/** @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 One or more of the parameters passed to a function is invalid. + * + * Refer to the individual function descriptions for the acceptable ranges for + * parameters. */ -/*! @{ */ -#define UPNP_E_INVALID_ARGUMENT -501 -/*! @} */ +#define UPNP_E_INVALID_ARGUMENT -501 -/** @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 The filename passed to one of the device registration functions was + * not found or was not accessible. */ -/*! @{ */ -#define UPNP_E_FILE_NOT_FOUND -502 -/*! @} */ +#define UPNP_E_FILE_NOT_FOUND -502 -/** @name UPNP_E_FILE_READ_ERROR [-503] - * {\tt UPNP_E_FILE_READ_ERROR} signifies an error when reading a file. +/*! \brief An error happened while reading a file. */ -/*! @{ */ -#define UPNP_E_FILE_READ_ERROR -503 -/*! @} */ +#define UPNP_E_FILE_READ_ERROR -503 -/** @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 The file name of the description document passed to + * \b UpnpRegisterRootDevice2 does not end in ".xml". */ -/*! @{ */ -#define UPNP_E_EXT_NOT_XML -504 -/*! @} */ +#define UPNP_E_EXT_NOT_XML -504 -#define UPNP_E_NO_WEB_SERVER -505 -#define UPNP_E_OUTOF_BOUNDS -506 +#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 response to a SOAP request did not contain the required XML + * constructs. */ -/*! @{ */ -#define UPNP_E_NOT_FOUND -507 -/*! @} */ +#define UPNP_E_NOT_FOUND -507 -/** @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. +/*! \brief Generic error code for internal conditions not covered by other + * error codes. */ -/*! @{ */ -#define UPNP_E_INTERNAL_ERROR -911 -/*! @} */ +#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 @@ -540,182 +445,183 @@ #include "SubscriptionRequest.h" +/*! \name Constants, and Types */ +/*! @{ */ + enum UpnpOpenFileMode { UPNP_READ, UPNP_WRITE }; - -/*! @name Constants, Structures, 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. */ +/*! 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. */ +/*! 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 */ - /** Received by a device when a control point issues a control - * request. The {\bf Event} parameter contains a pointer to a {\bf - * UpnpActionRequest} structure containing the action. The application - * stores the results of the action in this structure. */ + /*! 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, - /** A {\bf UpnpSendActionAsync} call completed. The {\bf Event} - * parameter contains a pointer to a {\bf UpnpActionComplete} structure - * with the results of the action. */ + /*! 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, - /** Received by a device when a query for a single service variable - * arrives. The {\bf Event} parameter contains a pointer to a {\bf - * UpnpStateVarRequest} structure containing the name of the variable - * and value. */ + /*! 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 UpnpGetServiceVarStatus} call completed. The {\bf Event} - * parameter contains a pointer to a {\bf UpnpStateVarComplete} structure - * containing the value for the variable. */ + /*! 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, /* * Discovery callbacks */ - /** Received by a control point when a new device or service is available. - * The {\bf Event} parameter contains a pointer to a {\bf - * UpnpDiscovery} structure with the information about the device - * or service. */ + /*! 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, - /** Received by a control point when a device or service shuts down. The {\bf - * Event} parameter contains a pointer to a {\bf UpnpDiscovery} - * structure containing the information about the device or - * service. */ + /*! 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, - /** Received by a control point when a matching device or service responds. - * The {\bf Event} parameter contains a pointer to a {\bf - * UpnpDiscovery} structure containing the information about - * the reply to the search request. */ + /*! 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, - /** 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}. */ + /*! 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, /* * Eventing callbacks */ - /** Received by a device when a subscription arrives. - * The {\bf Event} parameter contains a pointer to a {\bf - * UpnpSubscriptionRequest} 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}. + /*! 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, - /** Received by a control point when an event arrives. The {\bf - * Event} parameter contains a {\bf UpnpEvent} structure - * with the information about the event. */ + /*! 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, - /** A {\bf UpnpRenewSubscriptionAsync} call completed. The status of - * the renewal is in the {\bf Event} parameter as a {\bf - * Upnp_Event_Subscription} structure. */ + /*! 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, - /** A {\bf UpnpSubscribeAsync} call completed. The status of the - * subscription is in the {\bf Event} parameter as a {\bf - * Upnp_Event_Subscription} structure. */ + /*! 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, - /** A {\bf UpnpUnSubscribeAsync} call completed. The status of the - * subscription is in the {\bf Event} parameter as a {\bf - * UpnpEventSubscribe} structure. */ + /*! 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, - /** The auto-renewal of a client subscription failed. - * The {\bf Event} parameter is a {\bf UpnpEventSubscribe} structure - * with the error code set appropriately. The subscription is no longer - * valid. */ + /*! 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 {\bf Event} parameter is a {\bf UpnpEventSubscribe} - * structure. The subscription is no longer valid. */ + /*! 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. */ + /*! Search for all devices and services on the network. */ UPNP_S_ALL, - /** Search for all root devices on the network. */ + /*! Search for all root devices on the network. */ UPNP_S_ROOT, - /** Search for a particular device type or a particular device instance. */ + /*! Search for a particular device type or a particular device instance. */ UPNP_S_DEVICE, - /** Search for a particular service type, possibly on a particular + /*! 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 }; @@ -723,7 +629,7 @@ enum Upnp_DescType_e { typedef enum Upnp_DescType_e Upnp_DescType; -/** All callback functions share the same prototype, documented below. +/*! All callback functions share the same prototype, documented below. * Note that any memory passed to the callback function * is valid only during the callback and should be copied if it * needs to persist. This callback function needs to be thread @@ -732,17 +638,17 @@ typedef enum Upnp_DescType_e Upnp_DescType; * 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 * in the future to communicate results back to the SDK. @@ -751,236 +657,231 @@ typedef int (*Upnp_FunPtr)(IN Upnp_EventType EventType, IN void *Event, IN void /*! @} */ /* Constants, Structures, and Types */ + #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ -/*! @name Initialization and Registration */ + +/*! \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. + + +/*! \brief Initializes the Linux SDK for UPnP Devices. * - * 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. + * \deprecated Kept for backwards compatibility. Use UpnpInit2 for new + * implementations. * - * If unspecified, the SDK will use the first adapter's IP address - * and an arbitrary port. + * 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. * - * This call is synchronous. + * 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. * - * @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} */ + * 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. */ + IN const char *HostIP, + /*! Local Port to listen for incoming connections + * \c NULL will pick an arbitrary free port. */ + IN unsigned short DestPort); -/*! @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. +/*! \brief Initializes the Linux SDK for UPnP Devices. * - * Optionally, the application can specify an interface name (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. + * 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. * - * If unspecified, the SDK will use the first suitable interface and an - * arbitrary port. + * Optionally, the application can specify an interface name (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. * - * This call is synchronous. + * If unspecified, the SDK will use the first suitable interface and an + * arbitrary port. * - * @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. - * \item {\tt UPNP_E_INVALID_INTERFACE}: IfName is invalid or doees not - * have a valid IPv4 or IPv6 addresss configured. - * \end{itemize} */ + * 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. + * \li \c UPNP_E_INVALID_INTERFACE: IfName is invalid or does not + * have a valid IPv4 or IPv6 addresss configured. + */ EXPORT_SPEC int UpnpInit2( - IN const char *IfName, /** The interface name to use by the UPnP SDK - operations. Examples: "eth0", "xl0", - "Local Area Connection", {\tt NULL} to - use the first suitable interface. */ - IN unsigned short DestPort /** The destination port number to use. 0 - will pick an arbitrary free port. */ - ); + /*! The interface name to use by the UPnP SDK operations. + * Examples: "eth0", "xl0", "Local Area Connection", \c NULL to + * use the first suitable interface. */ + IN const char *IfName, + /*! Local Port to listen for incoming connections. + * \c NULL will pick an arbitrary free port. */ + IN 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. - * - * @return [unsigned short] The port on which an internal server is - * listening for IPv4 UPnP related requests. - */ -EXPORT_SPEC unsigned short UpnpGetServerPort(void); -/** 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 IPv6 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 UpnpGetServerPort6(void); +EXPORT_SPEC unsigned short UpnpGetServerPort(); -/** If {\tt NULL} is used as the IPv4 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 internal server IPv6 UPnP listening port. * - * @return [char*] The IPv4 address 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 IPv6 UPnP + * related requests. + * \li On error: 0 is returned if \b UpnpInit has not succeeded. */ -EXPORT_SPEC char * UpnpGetServerIpAddress(void); +EXPORT_SPEC unsigned short UpnpGetServerPort6(); -/** If {\tt NULL} is used as the IPv6 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 IPv6 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 * UpnpGetServerIp6Address(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. + +/*! \brief Returns the local IPv6 listening ip address. * - * {\bf UpnpRegisterClient} is a synchronous call and generates no callbacks. - * Callbacks can occur as soon as this function returns. + * If \c NULL is used as the IPv6 address in \b UpnpInit, then this function can + * be used to retrieve the actual interface address on which device is running. * - * @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} + * \return + * \li On success: The IPv6 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 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. */ - ); +EXPORT_SPEC char *UpnpGetServerIp6Address(); -/** {\bf UpnpRegisterRootDevice} registers a device application with + +/*! \b 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} + * can also register as control points (see \b UpnpRegisterClient * to get a control point handle to perform control point * functionality). * - * {\bf UpnpRegisterRootDevice} is synchronous and does not generate + * \b UpnpRegisterRootDevice is synchronous and does not generate * any 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_DESC}: The description document was not - * a valid device description. - * \item {\tt UPNP_E_INVALID_URL}: The URL for the description document + * \return [int] 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. */ - ); + /*! Pointer to a string containing the description URL for this root device + * instance. */ + IN const char *DescUrl, + /*! Pointer to the callback function for receiving asynchronous events. */ + IN Upnp_FunPtr Callback, + /*! Pointer to user data returned with the callback function when invoked. */ + IN const void *Cookie, + /*! Pointer to a variable to store the new device handle. */ + OUT UpnpDevice_Handle *Hnd); -/** {\bf UpnpRegisterRootDevice2} is similar to {\bf UpnpRegisterRootDevice}, +/*! \b UpnpRegisterRootDevice2 is 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 {\bf UpnpSetWebServerRootDir}) before calling this function. + * (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. {\tt config_baseURL = 0}.) + * required (i.e. config_baseURL = 0.) * - * {\bf UpnpRegisterRootDevice2} is synchronous and does not generate + * \b 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} + * \verbatim 1) Description specified as a URL: descriptionType == UPNPREG_URL_DESC description is the URL @@ -993,187 +894,204 @@ EXPORT_SPEC int UpnpRegisterRootDevice( descriptionType == UPNPREG_BUF_DESC description is pointer to a memory buffer bufferLen == length of memory buffer - \end{verbatim} + \endverbatim * - * @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 + * \return [int] 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. - * \item {\tt UPNP_E_INVALID_DESC}: The description document is not + * \li \c 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 + * \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. - * \item {\tt UPNP_E_URL_TOO_BIG}: Length of the URL is bigger than the + * \li \c 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 + * \li \c UPNP_E_FILE_NOT_FOUND: The description file could not * be found. - * \item {\tt UPNP_E_FILE_READ_ERROR}: An error occurred reading the + * \li \c UPNP_E_FILE_READ_ERROR: An error occurred reading the * description file. - * \item {\tt UPNP_E_INVALID_URL}: The URL to the description document + * \li \c 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 + * \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. - * \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. */ - ); + /*! The type of the description document. */ + IN Upnp_DescType descriptionType, + /*! Treated as a URL, file name or memory buffer depending on + * description type. */ + IN const char* description, + /*! The length of memory buffer if passing a description in a buffer, + * otherwise it is ignored. */ + IN size_t bufferLen, + /*! If nonzero, \c URLBase of description document is configured and + * the description is served using the internal web server. */ + IN int config_baseURL, + /*! Pointer to the callback function for receiving asynchronous events. */ + IN Upnp_FunPtr Fun, + /*! Pointer to user data returned with the callback function when + * invoked. */ + IN const void* Cookie, + /*! Pointer to a variable to store the new device handle. */ + OUT UpnpDevice_Handle* Hnd); -/** {\bf UpnpRegisterRootDevice3} registers a device application for a +/*! \b UpnpRegisterRootDevice3 registers a device application for a * specific address family 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 + * \b UpnpRegisterClient to get a control point handle to perform * control point functionality). * - * {\bf UpnpRegisterRootDevice} is synchronous and does not generate + * \b UpnpRegisterRootDevice is synchronous and does not generate * any 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 + * \return [int] 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. - * \item {\tt UPNP_E_INVALID_DESC}: The description document was not + * \li \c 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 + * \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 UpnpRegisterRootDevice3( - 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. */ - IN const int AddressFamily /** Address family of this device. Can be - AF_INET for an IPv4 device, or AF_INET6 - for an IPv6 device. Defaults to AF_INET. */ - ); + /*! Pointer to a string containing the description URL for this root + * device instance. */ + IN const char *DescUrl, + /*! Pointer to the callback function for receiving asynchronous events. */ + IN Upnp_FunPtr Callback, + /*! Pointer to user data returned with the callback function when + * invoked. */ + IN const void *Cookie, + /*! Pointer to a variable to store the new device handle. */ + OUT UpnpDevice_Handle *Hnd, + /*! Address family of this device. Can be AF_INET for an IPv4 device, or + * AF_INET6 for an IPv6 device. Defaults to AF_INET. */ + IN const int AddressFamily); -/** {\bf UpnpUnRegisterClient} unregisters a control point application, - * unsubscribing all active subscriptions. After this call, the - * {\bf UpnpClient_Handle} is no longer valid. +/*! \brief Registers a control point application with the UPnP Library. * - * {\bf UpnpUnRegisterClient} is a synchronous call and generates no - * callbacks. The SDK generates no more callbacks after this - * function returns. + * A control point 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_INVALID_HANDLE}: The handle is not a valid control - * point handle. - * \end{itemize} */ + * \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( + /*! Pointer to a function for receiving asynchronous events. */ + IN Upnp_FunPtr Callback, + /*! Pointer to user data returned with the callback function when invoked. */ + IN const void *Cookie, + /*! Pointer to a variable to store the new control point handle. */ + OUT 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 UpnpClient_Handle Hnd /** The handle of the control point instance - to unregister. */ - ); + /*! The handle of the control point instance to unregister. */ + IN UpnpClient_Handle Hnd); -/** 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 + +/*! \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. * - * {\bf UpnpUnRegisterRootDevice} is a synchronous call and generates no + * \b 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} + * \return [int] 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. */ - ); + /*! The handle of the root device instance to unregister. */ + IN UpnpDevice_Handle); -/** OBSOLETE METHOD : use {\bf UpnpSetMaxContentLength} instead. +/*! \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} ). + * \b UpnpSetMaxContentLength ). */ EXPORT_SPEC int UpnpSetContentLength( - IN UpnpClient_Handle Hnd, - IN int contentLength - ); + /*! The handle of the device instance for which the coincoming content + * length needs to be set. */ + IN UpnpClient_Handle Hnd, + /*! Permissible content length */ + IN int contentLength); -/** Sets the maximum content-length that the SDK will process on an incoming +/*! 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} + * The default maximum content-length is \c 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} + * \return [int] 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. */ - ); + /*! The maximum permissible content length for incoming SOAP actions, + * in bytes. */ + IN size_t contentLength); /*! @} */ /* Initialization and Registration */ @@ -1185,64 +1103,59 @@ EXPORT_SPEC int UpnpSetMaxContentLength( ****************************************************************************** ******************************************************************************/ -/*! @name Discovery */ +/*! \name Discovery */ /*! @{ */ -/** {\bf UpnpSearchAsync} searches for devices matching the given +/*! \b 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, + * \b UpnpRegisterClient call, for each matching root device, * device, or service. The application specifies the search type by the - * {\bf Target} parameter. + * \b Target parameter. * * Note that there is no way for the SDK to distinguish which client * instance issued a particular search. Therefore, the client can get * search callbacks that do not match the original criteria of the search. * Also, the application will receive multiple callbacks for each search. * - * @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 [int] 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_PARAM}: {\bf Target} is {\tt NULL}. - * \end{itemize} */ + * \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. */ + IN 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. */ + IN int Mx, + /*! The search target as defined in the UPnP Device Architecture v1.0 + * specification. */ + IN const char *Target, + /*! The user data to pass when the callback function is invoked. */ + IN const void *Cookie); -/** {\bf UpnpSendAdvertisement} sends out the discovery announcements for +/*! \b UpnpSendAdvertisement sends out the discovery announcements for * all devices and services for a device. Each announcement is made with * the same expiration time. * - * {\bf UpnpSendAdvertisement} is a synchronous call. + * \b UpnpSendAdvertisement is a synchronous 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_HANDLE}: The handle is not a valid + * \return [int] 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. - * \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to + * \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to * send future advertisements. - * \end{itemize} */ 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. */ + IN UpnpDevice_Handle Hnd, + /*! The expiration age, in seconds, of the announcements. */ + IN int Exp); /*! @} */ /* Discovery */ @@ -1254,223 +1167,226 @@ EXPORT_SPEC int UpnpSendAdvertisement( ****************************************************************************** ******************************************************************************/ -/*! @name Control */ +/*! \name Control */ /*! @{ */ -/** {\bf UpnpGetServiceVarStatus} queries the state of a state +/*! \deprecated \b 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}. + * return code indicates an SDK error code. Note that the use of this + * function is deprecated by the UPnP Forum. * - * @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 [int] 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}: {\bf ActionUrl} is not a valid URL. - * \item {\tt UPNP_E_INVALID_DESC}: The XML document was not + * \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. - * \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 + * \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. - * \item {\tt UPNP_SOAP_E_INVALID_VAR}: The given variable is invalid + * \li \c UPNP_SOAP_E_INVALID_VAR: The given variable is invalid * according to the device. - * \end{itemize} */ 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}. */ - ); + /*! The handle of the control point. */ + IN UpnpClient_Handle Hnd, + /*! The URL of the service. */ + IN const char *ActionURL, + /*! The name of the variable to query. */ + IN const char *VarName, + /*! The pointer to store the value for \b VarName. The SDK allocates + * this string and the caller needs to free it using + * \b ixmlFreeDOMString. */ + OUT 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}. + +/*! \deprecated \b UpnpGetServiceVarStatusAsync queries the state of a variable of a + * service, generating a callback when the operation is complete. + * Note that the use of this function is deprecated by the UPnP Forum. * - * @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 [int] 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 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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! The handle of the control point. */ + IN UpnpClient_Handle Hnd, + /*! The URL of the service. */ + IN const char *ActionURL, + /*! The name of the variable to query. */ + IN const char *VarName, + /*! Pointer to a callback function to be invoked when the operation + * is complete. */ + IN Upnp_FunPtr Fun, + /*! Pointer to user data to pass to the callback function when invoked. */ + IN const void *Cookie); -/** {\bf UpnpSendAction} sends a message to change a state variable + +/*! \b UpnpSendAction sends a message to change a state variable * in a service. This is a synchronous call that does not return until the * action is complete. * * Note that a positive return value indicates a SOAP-protocol error code. - * In this case, the error description can be retrieved from {\bf RespNode}. + * 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 + * \return [int] 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}: {\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 + * \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. - * \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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! The handle of the control point sending the action. */ + IN UpnpClient_Handle Hnd, + /*! The action URL of the service. */ + IN const char *ActionURL, + /*! The type of the service. */ + IN const char *ServiceType, + /*! This parameter is ignored and must be \c NULL. */ + IN const char *DevUDN, + /*! The DOM document for the action. */ + IN IXML_Document *Action, + /*! The DOM document for the response to the action. The SDK allocates + * this document and the caller needs to free it. */ + OUT IXML_Document **RespNode); -/** {\bf UpnpSendActionEx} sends a message to change a state variable + +/*! \b UpnpSendActionEx sends a message to change a state variable * in a service. This is a synchronous call that does not return until the * action is complete. * * Note that a positive return value indicates a SOAP-protocol error code. - * In this case, the error description can be retrieved from {\bf RespNode}. + * 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 + * \return [int] 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}: {\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 + * \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. - * \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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! The handle of the control point sending the action. */ + IN UpnpClient_Handle Hnd, + /*! The action URL of the service. */ + IN const char *ActionURL, + /*! The type of the service. */ + IN const char *ServiceType, + /*! This parameter is ignored and must be \c NULL. */ + IN const char *DevUDN, + /*! The DOM document for the SOAP header. This may be \c NULL if the + * header is not required. */ + IN IXML_Document *Header, + /*! The DOM document for the action. */ + IN IXML_Document *Action, + /*! The DOM document for the response to the action. The SDK allocates + * this document and the caller needs to free it. */ + OUT IXML_Document **RespNode); -/** {\bf UpnpSendActionAsync} sends a message to change a state variable + +/*! \b 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 + * See \b 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. + * \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 + * \return [int] 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}: {\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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! The handle of the control point sending the action. */ + IN UpnpClient_Handle Hnd, + /*! The action URL of the service. */ + IN const char *ActionURL, + /*! The type of the service. */ + IN const char *ServiceType, + /*! This parameter is ignored and must be \c NULL. */ + IN const char *DevUDN, + /*! The DOM document for the action to perform on this device. */ + IN IXML_Document *Action, + /*! Pointer to a callback function to be invoked when the operation + * completes. */ + IN Upnp_FunPtr Fun, + /*! Pointer to user data that to be passed to the callback when + * invoked. */ + IN const void *Cookie); -/** {\bf UpnpSendActionExAsync} sends a message to change a state variable + +/*! \b 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 + * See \b 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. + * \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 + * \return [int] 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}: {\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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! The handle of the control point sending the action. */ + IN UpnpClient_Handle Hnd, + /*! The action URL of the service. */ + IN const char *ActionURL, + /*! The type of the service. */ + IN const char *ServiceType, + /*! This parameter is ignored and must be \c NULL. */ + IN const char *DevUDN, + /*! The DOM document for the SOAP header. This may be \c NULL if the + * header is not required. */ + IN IXML_Document *Header, + /*! The DOM document for the action to perform on this device. */ + IN IXML_Document *Action, + /*! Pointer to a callback function to be invoked when the operation + * completes. */ + IN Upnp_FunPtr Fun, + /*! Pointer to user data that to be passed to the callback when + * invoked. */ + IN const void *Cookie); /*! @} */ /* Control */ @@ -1482,498 +1398,479 @@ EXPORT_SPEC int UpnpSendActionExAsync( ****************************************************************************** ******************************************************************************/ -/*! @name Eventing */ +/*! \name Eventing */ /*! @{ */ -/** {\bf UpnpAcceptSubscription} accepts a subscription request and sends +/*! \b 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 + * \c UPNP_EVENT_SUBSCRIPTION_REQUEST callback. This function is * synchronous and generates no callbacks. * - * {\bf UpnpAcceptSubscription} can be called during the execution of + * \b 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 + * \return [int] 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. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId * pair refers to an invalid service. - * \item {\tt UPNP_E_INVALID_SID}: The specified subscription ID is not + * \li \c 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 + * \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. - * \end{itemize} */ EXPORT_SPEC int UpnpAcceptSubscription( - /** The handle of the device. */ + /*! The handle of the device. */ IN UpnpDevice_Handle Hnd, - /** The device ID of the subdevice of the service generating the event. */ + /*! The device ID of the subdevice of the service generating the event. */ IN const char *DevID, - /** The unique service identifier of the service generating the event. */ + /*! The unique service identifier of the service generating the event. */ IN const char *ServID, - /** Pointer to an array of event variables. */ + /*! Pointer to an array of event variables. */ IN const char **VarName, - /** Pointer to an array of values for the event variables. */ + /*! Pointer to an array of values for the event variables. */ IN const char **NewVal, - /** The number of event variables in {\bf VarName}. */ + /*! The number of event variables in \b VarName. */ IN int cVariables, - /** The subscription ID of the newly registered control point. */ + /*! The subscription ID of the newly registered control point. */ IN const Upnp_SID SubsId); -/** {\bf UpnpAcceptSubscriptionExt} is similar to {\bf UpnpAcceptSubscription} +/*! \b UpnpAcceptSubscriptionExt is similar to \b 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. * - * {\bf UpnpAcceptSubscriptionExt} can be called during the execution of + * \b UpnpAcceptSubscriptionExt 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 + * \return [int] 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. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId * pair refers to an invalid service. - * \item {\tt UPNP_E_INVALID_SID}: The specified subscription ID is not + * \li \c 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} + * \li \c UPNP_E_INVALID_PARAM: Either \b VarName, + * \b NewVal, \b DevID, \b ServID, or \b PropSet * is not a valid pointer. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to * complete this operation. - * \end{itemize} */ 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. */ - ); + /*! The handle of the device. */ + IN UpnpDevice_Handle Hnd, + /*! The device ID of the subdevice of the service generating the event. */ + IN const char *DevID, + /*! The unique service identifier of the service generating the event. */ + IN const char *ServID, + /*! 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 IXML_Document *PropSet, + /*! The subscription ID of the newly registered control point. */ + IN Upnp_SID SubsId); -/** {\bf UpnpNotify} sends out an event change notification to all + +/*! \b UpnpNotify sends out an event change notification to all * control points subscribed to a particular service. This function is * synchronous and generates no callbacks. * - * {\bf UpnpNotify} may be called during a callback function to send out + * \b UpnpNotify may be called during a callback function to send out * a notification. * - * @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 + * \return [int] 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. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b 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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! The handle to the device sending the event. */ + IN UpnpDevice_Handle, + /*! The device ID of the subdevice of the service generating the event. */ + IN const char *DevID, + /*! The unique identifier of the service generating the event. */ + IN const char *ServID, + /*! Pointer to an array of variables that have changed. */ + IN const char **VarName, + /*! Pointer to an array of new values for those variables. */ + IN const char **NewVal, + /*! The count of variables included in this notification. */ + IN int cVariables); -/** {\bf UpnpNotifyExt} is similar to {\bf UpnpNotify} except that it takes + +/*! \b UpnpNotifyExt is similar to \b 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. * - * {\bf UpnpNotifyExt} may be called during a callback function to send out + * \b UpnpNotifyExt may be called during a callback function to send out * a notification. * - * @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 + * \return [int] 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. - * \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId} + * \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b 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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! The handle to the device sending the event. */ + IN UpnpDevice_Handle, + /*! The device ID of the subdevice of the service generating the event. */ + IN const char *DevID, + /*! The unique identifier of the service generating the event. */ + IN const char *ServID, + /*! 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 IXML_Document *PropSet); -/** {\bf UpnpRenewSubscription} renews a subscription that is about to + +/*! \b UpnpRenewSubscription renews a subscription that is about to * expire. This function 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_INVALID_HANDLE}: The handle is not a valid control + * \return [int] 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_PARAM}: {\bf Timeout} is not a valid pointer. - * \item {\tt UPNP_E_INVALID_SID}: The SID being passed to this function + * \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. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured. - * \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing + * \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. - * \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 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 + * \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. - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused + * \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused * the subscription renew. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to * complete this operation. - * \end{itemize} */ 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 const Upnp_SID SubsId /** The ID for the subscription to renew. */ - ); + /*! The handle of the control point that is renewing the subscription. */ + IN UpnpClient_Handle Hnd, + /*! Pointer to a variable containing the requested subscription time. + * Upon return, it contains the actual renewal time. */ + INOUT int *TimeOut, + /*! The ID for the subscription to renew. */ + IN const Upnp_SID SubsId); -/** {\bf UpnpRenewSubscriptionAsync} renews a subscription that is about + +/*! \b UpnpRenewSubscriptionAsync renews a subscription that is about * to expire, generating a callback when the operation is complete. * * Note that many of the error codes for this function are returned in - * the {\bf UpnpEventSubscribe} structure. In those cases, the function - * returns {\tt UPNP_E_SUCCESS} and the appropriate error code will - * be in the {\bf UpnpEventSubscribe.ErrCode} field in the {\bf Event} + * 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 [int] 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_SID}: The {\bf SubsId} is not a valid + * \li \c UPNP_E_INVALID_SID: The \b 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 + * \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. - * \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured (returned in - * the {\bf UpnpEventSubscribe.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 - * to a socket (returned in the {\bf UpnpEventSubscribe.ErrCode} + * \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). - * \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 UpnpEventSubscribe.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 UpnpEventSubscribe.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 - * UpnpEventSubscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating socket ( - * returned in the {\bf UpnpEventSubscribe.ErrCode} field as + * \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). - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher (returned in the {\bf - * UpnpEventSubscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription request (returned in the {\bf - * UpnpEventSubscribe.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 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. */ - ); + /*! The handle of the control point that is renewing the subscription. */ + IN UpnpClient_Handle Hnd, + /*! The requested subscription time. The actual timeout value is + * returned when the callback function is called. */ + IN int TimeOut, + /*! The ID for the subscription to renew. */ + IN Upnp_SID SubsId, + /*! Pointer to a callback function to be invoked when the renewal is + * complete. */ + IN Upnp_FunPtr Fun, + /*! Pointer to user data passed to the callback function when invoked. */ + IN const void *Cookie); -/** {\bf UpnpSetMaxSubscriptions} sets the maximum number of subscriptions + +/*! \b 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. * - * @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 + * \return [int] 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. - * \end{itemize} */ 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. */ + IN UpnpDevice_Handle Hnd, + /*! The maximum number of subscriptions to be allowed per service. */ + IN int MaxSubscriptions); -/** {\bf UpnpSetMaxSubscriptionTimeOut} sets the maximum time-out accepted + +/*! \b 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. * - * @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 + * \return [int] 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. - * \end{itemize} */ 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. */ + IN UpnpDevice_Handle Hnd, + /*! The maximum subscription time-out to be accepted. */ + IN int MaxSubscriptionTimeOut); -/** {\bf UpnpSubscribe} registers a control point to receive event + +/*! \b UpnpSubscribe registers a control point to receive event * notifications from another device. This operation 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_INVALID_HANDLE}: The handle is not a valid control + * \return [int] 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}: {\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 + * \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. - * \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 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 + * \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. - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused + * \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused * the subscription request. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to * complete this operation. - * \end{itemize} */ 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). */ - ); + /*! The handle of the control point. */ + IN UpnpClient_Handle Hnd, + /*! The URL of the service to subscribe to. */ + IN const char *PublisherUrl, + /*! Pointer to a variable containing the requested subscription time. + * Upon return, it contains the actual subscription time returned from + * the service. */ + INOUT int *TimeOut, + /*! Pointer to a variable to receive the subscription ID (SID). */ + OUT 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 UpnpEventSubscribe} structure. In those cases, the function - * returns {\tt UPNP_E_SUCCESS} and the appropriate error code will - * be in the {\bf UpnpEventSubscribe.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 [int] 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 UpnpEventSubscribe.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 UpnpEventSubscribe.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 UpnpEventSubscribe.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 UpnpEventSubscribe.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 - * UpnpEventSubscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating the - * socket (returned in the {\bf UpnpEventSubscribe.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 - * UpnpEventSubscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription request (returned in the {\bf - * UpnpEventSubscribe.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. */ + IN UpnpClient_Handle Hnd, + /*! The URL of the service to subscribe to. */ + IN const char *PublisherUrl, + /*! The requested subscription time. Upon return, it contains the actual + * subscription time returned from the service. */ + IN int TimeOut, + /*! Pointer to the callback function for this subscribe request. */ + IN Upnp_FunPtr Fun, + /*! A user data value passed to the callback function when invoked. */ + IN 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. + +/*! \b UpnpUnSubscribe removes the subscription of a control point from a + * service previously subscribed to using \b UpnpSubscribe or + * \b UpnpSubscribeAsync. This is a synchronous 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_HANDLE}: The handle is not a valid control + * \return [int] 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_SID}: The {\bf SubsId} is not a valid + * \li \c UPNP_E_INVALID_SID: The \b 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 + * \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. - * \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 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 + * \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. - * \item {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED}: The publisher refused + * \li \c 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 + * \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to * complete this operation. - * \end{itemize} */ EXPORT_SPEC int UpnpUnSubscribe( - IN UpnpClient_Handle Hnd, /** The handle of the subscribed control - point. */ - IN const Upnp_SID SubsId /** The ID returned when the control point - subscribed to the service. */ - ); + /*! The handle of the subscribed control point. */ + IN UpnpClient_Handle Hnd, + /*! The ID returned when the control point subscribed to the service. */ + IN 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 + +/*! \b UpnpUnSubscribeAsync 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 {\bf UpnpEventSubscribe} structure. In those cases, the function - * returns {\tt UPNP_E_SUCCESS} and the appropriate error code will - * be in the {\bf UpnpEventSubscribe.ErrCode} field in the {\bf Event} + * 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 [int] 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_SID}: The {\bf SubsId} is not a valid SID. - * \item {\tt UPNP_E_INVALID_PARAM}: {\bf Fun} is not a valid callback + * \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. - * \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to + * \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 UpnpEventSubscribe.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 - * to a socket (returned in the {\bf - * 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_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 - * {\bf UpnpEventSubscribe.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 UpnpEventSubscribe.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 - * UpnpEventSubscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket ( - * returned in the {\bf UpnpEventSubscribe.ErrCode} field as + * \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). - * \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from - * the publisher (returned in the {\bf - * UpnpEventSubscribe.ErrCode} field as part of the callback). - * \item {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED}: The publisher refused - * the subscription request (returned in the {\bf - * UpnpEventSubscribe.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 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. */ - ); + /*! The handle of the subscribed control point. */ + IN UpnpClient_Handle Hnd, + /*! The ID returned when the control point subscribed to the service. */ + IN Upnp_SID SubsId, + /*! Pointer to a callback function to be called when the operation is + * complete. */ + IN Upnp_FunPtr Fun, + /*! Pointer to user data to pass to the callback function when invoked. */ + IN const void *Cookie); + /*! @} */ /* Eventing */ @@ -1986,388 +1883,365 @@ EXPORT_SPEC int UpnpUnSubscribeAsync( ****************************************************************************** ******************************************************************************/ -/*! @name Control Point HTTP API */ +/*! \name Control Point HTTP API */ /*! @{ */ -/** {\bf UpnpDownloadUrlItem} downloads a file specified in a URL. - * The SDK allocates the memory for {\bf outBuf} and the +/*! \b UpnpDownloadUrlItem 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 [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 + * \return [int] 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. - * \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. - * \end{itemize} */ 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. */ - ); + /*! URL of an item to download. */ + IN const char *url, + /*! Buffer to store the downloaded item. */ + OUT char **outBuf, + /*! HTTP header value content type if present. It should be at least + * \c LINE_SIZE bytes in size. */ + OUT 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. + +/*! \b UpnpOpenHttpGet gets a file specified in a URL. + * The SDK allocates the memory for \b handle and + * \b contentType, the application is responsible for freeing this memory. * - * @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} + * \return [int] 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 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. */ - ); + /*! The URL of an item to get. */ + IN const char *url, + /*! A pointer to store the handle for this connection. */ + IN OUT void **handle, + /*! A buffer to store the media type of the item. */ + IN OUT char **contentType, + /*! A pointer to store the length of the item. */ + IN OUT int *contentLength, + /*! The status returned on receiving a response message. */ + IN OUT int *httpStatus, + /*! 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 int timeout); -/** {\bf UpnpOpenHttpGetProxy} gets a file specified in a URL through the + +/*! \b 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. + * The SDK allocates the memory for \b handle and + * \b contentType, the application is responsible for freeing this memory. * - * @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} + * \return [int] 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 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. */ - ); + /*! The URL of an item to get. */ + IN const char *url, + /*! The URL of the proxy. */ + IN const char *proxy_str, + /*! A pointer to store the handle for this connection. */ + IN OUT void **handle, + /*! A buffer to store the media type of the item. */ + IN OUT char **contentType, + /*! A pointer to store the length of the item. */ + IN OUT int *contentLength, + /*! The status returned on receiving a response message. */ + IN OUT int *httpStatus, + /*! 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 int timeout); -/** {\bf UpnpOpenHttpGetEx} gets specified number of bytes from a file + +/*! \b 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. + * request. The SDK allocates the memory for \b handle and + * \b contentType, the application is responsible for freeing this memory. * - * @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} + * \return [int] 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. */ - ); + /*! The URL of the item to get. */ + IN const char *url, + /*! A pointer to store the handle for this connection. */ + IN OUT void **handle, + /*! A buffer to store the media type of the item. */ + IN OUT char **contentType, + /*! A buffer to store the length of the item. */ + IN OUT int *contentLength, + /*! The status returned on receiving a response message from the remote server. */ + IN OUT int *httpStatus, + /*! An integer value representing the low end of a range to retrieve. */ + IN int lowRange, + /*! An integer value representing the high end of a range to retrieve. */ + IN int highRange, + /*! 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 int timeout); -/** {\bf UpnpReadHttpGet} gets specified number of bytes from a file + +/*! \b UpnpReadHttpGet 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 [int] 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. */ - ); + /*! The token created by the call to \b UpnpOpenHttpGet. */ + IN void *handle, + /*! The buffer to store the read item. */ + IN OUT char *buf, + /*! The size of the buffer to be read. */ + IN OUT unsigned int *size, + /*! 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 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 [int] 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. */ - ); + /*! The token created by the call to \b UpnpOpenHttpGet. */ + IN void *handle, + /*! The number of bytes received. */ + OUT unsigned int *length, + /*! The content length. */ + OUT 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 [int] 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 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 [int] 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); -/** {\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 [int] 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. */ - ); + /*! The URL in which to send the POST request. */ + IN const char *url, + /*! A pointer in which to store the handle for this connection. This + * handle is required for futher operations over this connection. */ + IN OUT void **handle, + /*! A buffer to store the media type of content being sent. */ + IN const char *contentType, + /*! The length of the content, in bytes, being posted. */ + IN int contentLength, + /*! The time out value sent with the request during which a response + * is expected from the receiver, failing which, an error is reported. */ + IN 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. +/*! \b UpnpWriteHttpPost 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 [int] 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. */ - ); + /*! The handle of the connection created by the call to + * \b UpnpOpenHttpPost. */ + IN void *handle, + /*! The buffer to be posted. */ + IN char *buf, + /*! The size, in bytes of \b buf. */ + IN unsigned int *size, + /*! A timeout value sent with the request during which a response is + * expected from the server, failing which, an error is reported. */ + IN int timeout); -/** {\bf UpnpCloseHttpPost} sends and receives any pending data, closes the + +/*! \b UpnpCloseHttpPost sends and receives any pending data, closes the * connection with the server, and frees memory allocated during the - * {\bfUpnpOpenHttpPost} call. + * \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 + * \return [int] 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. - * \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 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. */ - ); + /*! The handle of the connection to close, created by the call to + * \b UpnpOpenHttpPost. */ + IN void *handle, + /*! A pointer to a buffer to store the final status of the connection. */ + IN OUT int *httpStatus, + /*! A time out value sent with the request during which a response is + * expected from the server, failing which, an error is reported. */ + IN int timeout); -/** {\bf UpnpDownloadXmlDoc} downloads an XML document specified in a URL. +/*! \b 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. * - * @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} + * \return [int] 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. - * \item {\tt UPNP_E_INVALID_DESC}: The XML document was not + * \li \c 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 + * \li \c UPNP_E_INVALID_URL: The \b url is not a valid * URL. - * \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to + * \li \c 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 + * \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. - * \end{itemize} */ 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. */ - ); + /*! URL of the XML document. */ + IN const char *url, + /*! A pointer in which to store the XML document. */ + OUT IXML_Document **xmlDoc); + /*! @} */ /* Control Point HTTP API */ @@ -2379,29 +2253,26 @@ EXPORT_SPEC int UpnpDownloadXmlDoc( ****************************************************************************** ******************************************************************************/ -/*! @name Web Server API */ +/*! \name Web Server API */ /*! @{ */ -/** {\bf UpnpSetWebServerRootDir} sets the document root directory for +/*! \b 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 + * To disable the web server, pass \c NULL for \b 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} + * \return [int] 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( - /** Path of the root directory of the web server. */ + /*! Path of the root directory of the web server. */ IN const char *rootDir); @@ -2410,179 +2281,156 @@ typedef void *UpnpWebFileHandle; typedef int (*VDCallback_GetInfo)( - /** The name of the file to query. */ + /*! The name of the file to query. */ IN const char *filename, - /** Pointer to a structure to store the information on the file. */ + /*! Pointer to a structure to store the information on the file. */ OUT UpnpFileInfo *info); -/** {\bf UpnpVirtualDir_set_GetInfoCallback} sets the get_info callback function +/*! \b UpnpVirtualDir_set_GetInfoCallback sets the get_info callback function * to be used to access a virtual directory. * - * @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 callback} is not a valid pointer. - * \end{itemize} + * \return [int] An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b callback is not a valid pointer. */ EXPORT_SPEC int UpnpVirtualDir_set_GetInfoCallback(VDCallback_GetInfo callback); typedef UpnpWebFileHandle (*VDCallback_Open)( - /** The name of the file to open. */ + /*! The name of the file to open. */ IN const char *filename, - /** The mode in which to open the file. - * Valid values are {\tt UPNP_READ} or {\tt UPNP_WRITE}. */ + /*! The mode in which to open the file. + * Valid values are \c UPNP_READ or \c UPNP_WRITE. */ IN enum UpnpOpenFileMode Mode); -/** {\bf UpnpVirtualDir_set_OpenCallback} sets the open callback function +/*! \b UpnpVirtualDir_set_OpenCallback sets the open callback function * to be used to access a virtual directory. * - * @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 callback} is not a valid pointer. - * \end{itemize} + * \return [int] An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b callback is not a valid pointer. */ EXPORT_SPEC int UpnpVirtualDir_set_OpenCallback(VDCallback_Open callback); typedef int (*VDCallback_Read) ( - /** The handle of the file to read. */ + /*! The handle of the file to read. */ IN UpnpWebFileHandle fileHnd, - /** The buffer in which to place the data. */ + /*! The buffer in which to place the data. */ OUT char *buf, - /** The size of the buffer (i.e. the number of bytes to read). */ + /*! The size of the buffer (i.e. the number of bytes to read). */ IN size_t buflen); -/** {\bf UpnpVirtualDir_set_ReadCallback} sets the read callback function +/*! \b UpnpVirtualDir_set_ReadCallback sets the read callback function * to be used to access a virtual directory. * - * @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 callback} is not a valid pointer. - * \end{itemize} + * \return [int] An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b callback is not a valid pointer. */ EXPORT_SPEC int UpnpVirtualDir_set_ReadCallback(VDCallback_Read callback); typedef int (*VDCallback_Write) ( - /** The handle of the file to write. */ + /*! The handle of the file to write. */ IN UpnpWebFileHandle fileHnd, - /** The buffer with the bytes to write. */ + /*! The buffer with the bytes to write. */ IN char *buf, - /** The number of bytes to write. */ + /*! The number of bytes to write. */ IN size_t buflen); -/** {\bf UpnpVirtualDir_set_WriteCallback} sets the write callback function +/*! \b UpnpVirtualDir_set_WriteCallback sets the write callback function * to be used to access a virtual directory. * - * @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 callback} is not a valid pointer. - * \end{itemize} + * \return [int] An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b callback is not a valid pointer. */ EXPORT_SPEC int UpnpVirtualDir_set_WriteCallback(VDCallback_Write callback); typedef int (*VDCallback_Seek) ( - /** The handle of the file to move the file pointer. */ + /*! The handle of the file to move the file pointer. */ IN UpnpWebFileHandle fileHnd, - /** The number of bytes to move in the file. Positive values + /*! The number of bytes to move in the file. Positive values * move foward and negative values move backward. Note that - * this must be positive if the {\bf origin} is {\tt SEEK_SET}. */ + * this must be positive if the \b origin is \c SEEK_SET. */ IN off_t offset, - /** The position to move relative to. It can be {\tt SEEK_CUR} - * to move relative to the current position, {\tt SEEK_END} to - * move relative to the end of the file, or {\tt SEEK_SET} to + /*! The position to move relative to. It can be \c SEEK_CUR + * to move relative to the current position, \c SEEK_END to + * move relative to the end of the file, or \c SEEK_SET to * specify an absolute offset. */ IN int origin); -/** {\bf UpnpVirtualDir_set_SeekCallback} sets the seek callback function +/*! \b UpnpVirtualDir_set_SeekCallback sets the seek callback function * to be used to access a virtual directory. * - * @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 callback} is not a valid pointer. - * \end{itemize} + * \return [int] An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b callback is not a valid pointer. */ EXPORT_SPEC int UpnpVirtualDir_set_SeekCallback(VDCallback_Seek callback); typedef int (*VDCallback_Close) ( - /** The handle of the file to close. */ + /*! The handle of the file to close. */ IN UpnpWebFileHandle fileHnd); -/** {\bf UpnpVirtualDir_set_CloseCallback} sets the close callback function +/*! \b UpnpVirtualDir_set_CloseCallback sets the close callback function * to be used to access a virtual directory. * - * @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 callback} is not a valid pointer. - * \end{itemize} + * \return [int] An integer representing one of the following: + * \li \c UPNP_E_SUCCESS: The operation completed successfully. + * \li \c UPNP_E_INVALID_ARGUMENT: \b callback is not a valid pointer. */ EXPORT_SPEC int UpnpVirtualDir_set_CloseCallback(VDCallback_Close callback); -/** {\bf UpnpEnableWebServer} enables or disables the webserver. A value of - * {\tt TRUE} enables the webserver, {\tt FALSE} disables it. +/*! \b UpnpEnableWebServer enables or disables the webserver. A value of + * \c TRUE enables the webserver, \c 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} + * \return [int] 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 UpnpEnableWebserver( - /** {\tt TRUE} to enable, {\tt FALSE} to disable. */ + /*! \c TRUE to enable, \c FALSE to disable. */ IN int enable); -/** {\bf UpnpIsWebServerEnabled} returns {\tt TRUE} if the webserver is - * enabled, or {\tt FALSE} if it is not. +/*! \b UpnpIsWebServerEnabled 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 [int] 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. +/*! \b UpnpAddVirtualDir adds a virtual directory mapping. * * All webserver requests containing the given directory are read using - * functions contained in a {\bf VirtualDirCallbacks} structure registered - * via {\bf UpnpSetVirtualDirCallbacks}. + * functions contained in a \b VirtualDirCallbacks structure registered + * via \b 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} + * \return [int] 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( - /** The name of the new directory mapping to add. */ + /*! The name of the new directory mapping to add. */ IN const char *dirName); -/** {\bf UpnpRemoveVirtualDir} removes a virtual directory mapping made with - * {\bf UpnpAddVirtualDir}. +/*! \b UpnpRemoveVirtualDir 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 [int] 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( - /** The name of the virtual directory mapping to remove. */ + /*! The name of the virtual directory mapping to remove. */ IN const char *dirName); -/** {\bf UpnpRemoveAllVirtualDirs} removes all virtual directory mappings. - * - * @return [void] This function does not return a value. - * +/*! \b UpnpRemoveAllVirtualDirs removes all virtual directory mappings. */ EXPORT_SPEC void UpnpRemoveAllVirtualDirs(); EXPORT_SPEC void UpnpFree( - /** The item to free. */ + /*! The item to free. */ IN void *item); /*! @} */ /* Web Server API */ @@ -2591,7 +2439,7 @@ EXPORT_SPEC void UpnpFree( } #endif /* __cplusplus */ -/*! @} */ /* The API */ +/*@}*/ /* TheAPI */ #endif /* UPNP_H */ diff --git a/upnp/inc/upnpdebug.h b/upnp/inc/upnpdebug.h index e5a06c4..ccf1f51 100644 --- a/upnp/inc/upnpdebug.h +++ b/upnp/inc/upnpdebug.h @@ -33,11 +33,18 @@ #ifndef UPNP_DEBUG_H #define UPNP_DEBUG_H + +/*! \file */ + + +#include "ThreadPool.h" #include "upnp.h" #include "upnpconfig.h" + #include + #ifdef __cplusplus extern "C" { #endif @@ -269,35 +276,6 @@ static UPNP_INLINE void UpnpPrintf( #endif /* DEBUG */ -/*************************************************************************** - * Function : UpnpDisplayBanner - * - * Parameters: - * IN FILE *fd: file descriptor where the banner will be written - * IN char **lines: The buffer that will be written - * IN int size: Size of the buffer - * IN int starLength: This parameter provides the width of the banner - * - * Description: - * This functions takes the buffer and writes the buffer in the file as - * per the requested banner - * Returns: void - ***************************************************************************/ -#ifdef DEBUG -void UpnpDisplayBanner( - FILE *fd, - const char **lines, - size_t size, - int starlength); -#else -static UPNP_INLINE void UpnpDisplayBanner( - FILE *fd, - const char **lines, - size_t size, - int starlength) {} -#endif - - /*************************************************************************** * Function : UpnpDisplayFileAndLine * @@ -324,6 +302,53 @@ static UPNP_INLINE void UpnpDisplayFileAndLine( int DbgLineNo) {} #endif + +/*! \brief Writes the buffer in the file as per the requested banner + * + * \param [in] fd file descriptor where the banner will be written + * \param [in] lines: The buffer that will be written + * \param [in] size: Size of the buffer + * \param [in] starLength: This parameter provides the width of the banner + */ +#ifdef DEBUG +void UpnpDisplayBanner( + FILE *fd, + const char **lines, + size_t size, + int starlength); +#else +static UPNP_INLINE void UpnpDisplayBanner( + FILE *fd, + const char **lines, + size_t size, + int starlength) {} +#endif + + +/*! \brief Prints thread pool statistics. + * + * \param [in] tp The thread pool + * \param [in] DbgFileName the file name that called this function, use the + * macro __FILE__. + * \param [in] DbgLineNo the line number that the function was called, use + * the macro __LINE__. + * \param [in] msg message. + */ +#ifdef DEBUG +void PrintThreadPoolStats( + ThreadPool *tp, + const char *DbgFileName, + int DbgLineNo, + const char *msg); +#else +static UPNP_INLINE void PrintThreadPoolStats( + ThreadPool *tp, + const char *DbgFileName, + int DbgLineNo, + const char *msg) {} +#endif + + /*! @} */ #ifdef __cplusplus diff --git a/upnp/src/api/upnpapi.c b/upnp/src/api/upnpapi.c index 8001e76..21e5137 100644 --- a/upnp/src/api/upnpapi.c +++ b/upnp/src/api/upnpapi.c @@ -163,392 +163,236 @@ int UpnpSdkDeviceregisteredV6 = 0; Upnp_SID gUpnpSdkNLSuuid; -/**************************************************************************** - * Function: UpnpInit2 - * - * Parameters: - * IN const char * IfName: Name of local interface. - * IN short DestPort: Local Port to listen for incoming connections. - * - * Description: - * - Initializes the UPnP SDK. - * - Checks IfName interface. If NULL, we find a suitable interface for - * operation. - * - * Returns: - * UPNP_E_SUCCESS on success, nonzero on failure. - * UPNP_E_INIT_FAILED if Initialization fails. - * UPNP_E_INIT if UPnP is already initialized. - * UPNP_E_INVALID_INTERFACE if interface provided is not configured with at - * least one valid IP address. - *****************************************************************************/ -int UpnpInit2( IN const char *IfName, - IN unsigned short DestPort ) +/******************************************************************************/ +int UpnpInit(IN const char *HostIP, IN unsigned short DestPort) { - int retVal; + int retVal; - ithread_mutex_lock( &gSDKInitMutex ); + ithread_mutex_lock( &gSDKInitMutex ); - // Check if we're already initialized. - if( UpnpSdkInit == 1 ) { - ithread_mutex_unlock( &gSDKInitMutex ); - return UPNP_E_INIT; - } + // Check if we're already initialized. + if( UpnpSdkInit == 1 ) { + ithread_mutex_unlock( &gSDKInitMutex ); + return UPNP_E_INIT; + } - // Perform initialization preamble. - retVal = UpnpInitPreamble(); - if( retVal != UPNP_E_SUCCESS ) { - ithread_mutex_unlock( &gSDKInitMutex ); - return retVal; - } + // Perform initialization preamble. + retVal = UpnpInitPreamble(); + if( retVal != UPNP_E_SUCCESS ) { + ithread_mutex_unlock( &gSDKInitMutex ); + return retVal; + } - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "UpnpInit2 with IfName=%s, DestPort=%d.\n", - IfName ? IfName : "", DestPort ); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "UpnpInit with HostIP=%s, DestPort=%d.\n", + HostIP ? HostIP : "", DestPort ); - // Retrieve interface information (Addresses, index, etc). - retVal = UpnpGetIfInfo( IfName ); - if( retVal != UPNP_E_SUCCESS ) { - ithread_mutex_unlock( &gSDKInitMutex ); - return retVal; - } + // Verify HostIP, if provided, or find it ourselves. + if( HostIP != NULL ) { + strncpy( gIF_IPV4, HostIP, sizeof(gIF_IPV4) ); + } else { + if( getlocalhostname( gIF_IPV4, sizeof(gIF_IPV4) ) != UPNP_E_SUCCESS ) { + return UPNP_E_INIT_FAILED; + } + } - // Set the UpnpSdkInit flag to 1 to indicate we're sucessfully initialized. - UpnpSdkInit = 1; + // Set the UpnpSdkInit flag to 1 to indicate we're sucessfully initialized. + UpnpSdkInit = 1; - // Finish initializing the SDK. - retVal = UpnpInitStartServers( DestPort ); - if( retVal != UPNP_E_SUCCESS ) { - UpnpSdkInit = 0; - ithread_mutex_unlock( &gSDKInitMutex ); - return retVal; - } + // Finish initializing the SDK. + retVal = UpnpInitStartServers( DestPort ); + if( retVal != UPNP_E_SUCCESS ) { + UpnpSdkInit = 0; + ithread_mutex_unlock( &gSDKInitMutex ); + return retVal; + } - ithread_mutex_unlock( &gSDKInitMutex ); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Host Ip: %s Host Port: %d\n", gIF_IPV4, + LOCAL_PORT_V4 ); - return UPNP_E_SUCCESS; + ithread_mutex_unlock( &gSDKInitMutex ); + + return UPNP_E_SUCCESS; } -/**************************************************************************** - * Function: UpnpInit - * - * Parameters: - * IN const char * HostIP: Local IP Address - * IN short DestPort: Local Port to listen for incoming connections. - * - * Description: - * ** DEPRECATED: Kept for backwards compatibility. ** - * Use UpnpInit2 for new implementations. - * - Initializes the UPnP SDK. - * - Checks HostIP address. If NULL, we find a suitable IP for operation. - * - * Returns: - * UPNP_E_SUCCESS on success, nonzero on failure. - * UPNP_E_INIT_FAILED if Initialization fails. - * UPNP_E_INIT if UPnP is already initialized. - *****************************************************************************/ -int UpnpInit( IN const char *HostIP, - IN unsigned short DestPort ) +/******************************************************************************/ +int UpnpInit2(IN const char *IfName, IN unsigned short DestPort) { - int retVal; + int retVal; - ithread_mutex_lock( &gSDKInitMutex ); + ithread_mutex_lock( &gSDKInitMutex ); - // Check if we're already initialized. - if( UpnpSdkInit == 1 ) { - ithread_mutex_unlock( &gSDKInitMutex ); - return UPNP_E_INIT; - } + // Check if we're already initialized. + if( UpnpSdkInit == 1 ) { + ithread_mutex_unlock( &gSDKInitMutex ); + return UPNP_E_INIT; + } - // Perform initialization preamble. - retVal = UpnpInitPreamble(); - if( retVal != UPNP_E_SUCCESS ) { - ithread_mutex_unlock( &gSDKInitMutex ); - return retVal; - } + // Perform initialization preamble. + retVal = UpnpInitPreamble(); + if( retVal != UPNP_E_SUCCESS ) { + ithread_mutex_unlock( &gSDKInitMutex ); + return retVal; + } - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "UpnpInit with HostIP=%s, DestPort=%d.\n", - HostIP ? HostIP : "", DestPort ); + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "UpnpInit2 with IfName=%s, DestPort=%d.\n", + IfName ? IfName : "", DestPort ); - // Verify HostIP, if provided, or find it ourselves. - if( HostIP != NULL ) { - strncpy( gIF_IPV4, HostIP, sizeof(gIF_IPV4) ); - } else { - if( getlocalhostname( gIF_IPV4, sizeof(gIF_IPV4) ) != UPNP_E_SUCCESS ) { - return UPNP_E_INIT_FAILED; - } - } + // Retrieve interface information (Addresses, index, etc). + retVal = UpnpGetIfInfo( IfName ); + if( retVal != UPNP_E_SUCCESS ) { + ithread_mutex_unlock( &gSDKInitMutex ); + return retVal; + } - // Set the UpnpSdkInit flag to 1 to indicate we're sucessfully initialized. - UpnpSdkInit = 1; + // Set the UpnpSdkInit flag to 1 to indicate we're sucessfully initialized. + UpnpSdkInit = 1; - // Finish initializing the SDK. - retVal = UpnpInitStartServers( DestPort ); - if( retVal != UPNP_E_SUCCESS ) { - UpnpSdkInit = 0; - ithread_mutex_unlock( &gSDKInitMutex ); - return retVal; - } + // Finish initializing the SDK. + retVal = UpnpInitStartServers( DestPort ); + if( retVal != UPNP_E_SUCCESS ) { + UpnpSdkInit = 0; + ithread_mutex_unlock( &gSDKInitMutex ); + return retVal; + } - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Host Ip: %s Host Port: %d\n", gIF_IPV4, - LOCAL_PORT_V4 ); + ithread_mutex_unlock( &gSDKInitMutex ); - ithread_mutex_unlock( &gSDKInitMutex ); - - return UPNP_E_SUCCESS; + return UPNP_E_SUCCESS; } -/**************************************************************************** - * Function: PrintThreadPoolStats - * - * Parameters: - * - * Description: - * - * Return Values: (none) - *****************************************************************************/ -#ifdef DEBUG -static void -PrintThreadPoolStats( - ThreadPool *tp, - const char *DbgFileName, - int DbgLineNo, - const char *msg) -{ - ThreadPoolStats stats; - ThreadPoolGetStats(tp, &stats); - UpnpPrintf(UPNP_INFO, API, DbgFileName, DbgLineNo, - "%s\n" - "High Jobs pending: %d\n" - "Med Jobs Pending: %d\n" - "Low Jobs Pending: %d\n" - "Average wait in High Q in milliseconds: %lf\n" - "Average wait in Med Q in milliseconds: %lf\n" - "Average wait in Low Q in milliseconds: %lf\n" - "Max Threads Used: %d\n" - "Worker Threads: %d\n" - "Persistent Threads: %d\n" - "Idle Threads: %d\n" - "Total Threads: %d\n" - "Total Work Time: %lf\n" - "Total Idle Time: %lf\n", - msg, - stats.currentJobsHQ, - stats.currentJobsMQ, - stats.currentJobsLQ, - stats.avgWaitHQ, - stats.avgWaitMQ, - stats.avgWaitLQ, - stats.maxThreads, - stats.workerThreads, - stats.persistentThreads, - stats.idleThreads, - stats.totalThreads, - stats.totalWorkTime, - stats.totalIdleTime); -} -#else /* DEBUG */ -static UPNP_INLINE void -PrintThreadPoolStats( - ThreadPool *tp, - const char *DbgFileName, - int DbgLineNo, - const char *msg) -{ -} -#endif /* DEBUG */ - - -/**************************************************************************** - * Function: UpnpFinish - * - * Parameters: NONE - * - * Description: - * Checks for pending jobs and threads - * Unregisters either the client or device - * Shuts down the Timer Thread - * Stops the Mini Server - * Uninitializes the Thread Pool - * For Win32 cleans up Winsock Interface - * Cleans up mutex objects - * - * Return Values: - * UPNP_E_SUCCESS on success, nonzero on failure. - *****************************************************************************/ -int -UpnpFinish() +/******************************************************************************/ +int UpnpFinish() { #ifdef INCLUDE_DEVICE_APIS - UpnpDevice_Handle device_handle; + UpnpDevice_Handle device_handle; #endif #ifdef INCLUDE_CLIENT_APIS - UpnpClient_Handle client_handle; + UpnpClient_Handle client_handle; #endif - struct Handle_Info *temp; + struct Handle_Info *temp; #ifdef WIN32 -// WSACleanup(); + // WSACleanup(); #endif - if( UpnpSdkInit != 1 ) { - return UPNP_E_FINISH; - } + if( UpnpSdkInit != 1 ) { + return UPNP_E_FINISH; + } - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Inside UpnpFinish : UpnpSdkInit is :%d:\n", UpnpSdkInit ); - if( UpnpSdkInit == 1 ) { - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "UpnpFinish : UpnpSdkInit is ONE\n" ); - } - PrintThreadPoolStats(&gSendThreadPool, __FILE__, __LINE__, "Send Thread Pool"); - PrintThreadPoolStats(&gRecvThreadPool, __FILE__, __LINE__, "Recv Thread Pool"); - PrintThreadPoolStats(&gMiniServerThreadPool, __FILE__, __LINE__, "MiniServer Thread Pool"); + UpnpPrintf(UPNP_INFO, API, __FILE__, __LINE__, + "Inside UpnpFinish: UpnpSdkInit is %d\n", UpnpSdkInit); + if (UpnpSdkInit == 1) { + UpnpPrintf(UPNP_INFO, API, __FILE__, __LINE__, + "UpnpFinish: UpnpSdkInit is ONE\n"); + } + PrintThreadPoolStats(&gSendThreadPool, __FILE__, __LINE__, "Send Thread Pool"); + PrintThreadPoolStats(&gRecvThreadPool, __FILE__, __LINE__, "Recv Thread Pool"); + PrintThreadPoolStats(&gMiniServerThreadPool, __FILE__, __LINE__, "MiniServer Thread Pool"); #ifdef INCLUDE_DEVICE_APIS - if( GetDeviceHandleInfo( AF_INET, &device_handle, &temp ) == HND_DEVICE ) - UpnpUnRegisterRootDevice( device_handle ); - if( GetDeviceHandleInfo( AF_INET6, &device_handle, &temp ) == HND_DEVICE ) - UpnpUnRegisterRootDevice( device_handle ); + if (GetDeviceHandleInfo(AF_INET, &device_handle, &temp) == HND_DEVICE ) { + UpnpUnRegisterRootDevice(device_handle); + } + if (GetDeviceHandleInfo(AF_INET6, &device_handle, &temp) == HND_DEVICE ) { + UpnpUnRegisterRootDevice(device_handle); + } #endif #ifdef INCLUDE_CLIENT_APIS - if( GetClientHandleInfo( &client_handle, &temp ) == HND_CLIENT ) - UpnpUnRegisterClient( client_handle ); + if (GetClientHandleInfo(&client_handle, &temp) == HND_CLIENT) { + UpnpUnRegisterClient( client_handle ); + } #endif - TimerThreadShutdown( &gTimerThread ); - StopMiniServer(); + TimerThreadShutdown(&gTimerThread); + StopMiniServer(); #if EXCLUDE_WEB_SERVER == 0 - web_server_destroy(); + web_server_destroy(); #endif - ThreadPoolShutdown(&gMiniServerThreadPool); - ThreadPoolShutdown(&gRecvThreadPool); - ThreadPoolShutdown(&gSendThreadPool); + ThreadPoolShutdown(&gMiniServerThreadPool); + ThreadPoolShutdown(&gRecvThreadPool); + ThreadPoolShutdown(&gSendThreadPool); - PrintThreadPoolStats(&gSendThreadPool, __FILE__, __LINE__, "Send Thread Pool"); - PrintThreadPoolStats(&gRecvThreadPool, __FILE__, __LINE__, "Recv Thread Pool"); - PrintThreadPoolStats(&gMiniServerThreadPool, __FILE__, __LINE__, "MiniServer Thread Pool"); + PrintThreadPoolStats(&gSendThreadPool, __FILE__, __LINE__, "Send Thread Pool"); + PrintThreadPoolStats(&gRecvThreadPool, __FILE__, __LINE__, "Recv Thread Pool"); + PrintThreadPoolStats(&gMiniServerThreadPool, __FILE__, __LINE__, "MiniServer Thread Pool"); #ifdef INCLUDE_CLIENT_APIS - ithread_mutex_destroy(&GlobalClientSubscribeMutex); + ithread_mutex_destroy(&GlobalClientSubscribeMutex); #endif - ithread_rwlock_destroy(&GlobalHndRWLock); - ithread_mutex_destroy(&gUUIDMutex); + ithread_rwlock_destroy(&GlobalHndRWLock); + ithread_mutex_destroy(&gUUIDMutex); - // remove all virtual dirs - UpnpRemoveAllVirtualDirs(); + // remove all virtual dirs + UpnpRemoveAllVirtualDirs(); - // allow static linking + // allow static linking #ifdef WIN32 #ifdef PTW32_STATIC_LIB - pthread_win32_thread_detach_np(); + pthread_win32_thread_detach_np(); #endif #endif - UpnpSdkInit = 0; - UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, - "Exiting UpnpFinish : UpnpSdkInit is :%d:\n", UpnpSdkInit); - UpnpCloseLog(); - - return UPNP_E_SUCCESS; + UpnpSdkInit = 0; + UpnpPrintf( UPNP_INFO, API, __FILE__, __LINE__, + "Exiting UpnpFinish : UpnpSdkInit is :%d:\n", UpnpSdkInit); + UpnpCloseLog(); + return UPNP_E_SUCCESS; } -/*************************** End of UpnpFinish *****************************/ -/****************************************************************************** - * Function: UpnpGetServerPort - * - * Parameters: NONE - * - * Description: - * Gives back the IPv4 listening miniserver port. - * - * Return Values: - * local port on success, zero on failure. - *****************************************************************************/ -unsigned short -UpnpGetServerPort( void ) + +/******************************************************************************/ +unsigned short UpnpGetServerPort() { + if (UpnpSdkInit != 1) { + return 0; + } - if( UpnpSdkInit != 1 ) - return 0; - - return LOCAL_PORT_V4; + return LOCAL_PORT_V4; } -/****************************************************************************** - * Function: UpnpGetServerPort6 - * - * Parameters: NONE - * - * Description: - * Gives back the IPv6 listening miniserver port. - * - * Return Values: - * local port on success, zero on failure. - *****************************************************************************/ -unsigned short -UpnpGetServerPort6( void ) +/******************************************************************************/ +unsigned short UpnpGetServerPort6() { + if (UpnpSdkInit != 1) { + return 0; + } - if( UpnpSdkInit != 1 ) - return 0; - - return LOCAL_PORT_V6; + return LOCAL_PORT_V6; } -/*************************************************************************** - * Function: UpnpGetServerIpAddress - * - * Parameters: NONE - * - * Description: - * Gives back the local IPv4 ipaddress. - * - * Return Values: char * - * return the IPv4 address string on success else NULL of failure - ***************************************************************************/ -char * -UpnpGetServerIpAddress( void ) +/*****************************************************************************/ +char *UpnpGetServerIpAddress() { + if (UpnpSdkInit != 1) { + return NULL; + } - if( UpnpSdkInit != 1 ) - return NULL; - - return gIF_IPV4; + return gIF_IPV4; } -/*************************************************************************** - * Function: UpnpGetServerIp6Address - * - * Parameters: NONE - * - * Description: - * Gives back the local IPv6 ipaddress. - * - * Return Values: char * - * return the IPv6 address string on success else NULL of failure - ***************************************************************************/ -char * -UpnpGetServerIp6Address( void ) +/*****************************************************************************/ +char *UpnpGetServerIp6Address() { + if( UpnpSdkInit != 1 ) { + return NULL; + } - if( UpnpSdkInit != 1 ) - return NULL; - - return gIF_IPV6; + return gIF_IPV6; } + #ifdef INCLUDE_DEVICE_APIS #if 0 -/**************************************************************************** +/***************************************************************************** * Function: UpnpAddRootDevice * * Parameters: @@ -1497,29 +1341,11 @@ UpnpRegisterRootDevice3( IN const char *DescUrl, #ifdef INCLUDE_CLIENT_APIS -/************************************************************************** - * Function: UpnpRegisterClient - * - * Parameters: - * IN Upnp_FunPtr Fun: 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. - * - * Description: - * This function 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. - * - * Return Values: int - * - ***************************************************************************/ -int -UpnpRegisterClient( IN Upnp_FunPtr Fun, - IN const void *Cookie, - OUT UpnpClient_Handle * Hnd ) +/*****************************************************************************/ +int UpnpRegisterClient( + IN Upnp_FunPtr Fun, + IN const void *Cookie, + OUT UpnpClient_Handle *Hnd) { struct Handle_Info *HInfo; @@ -1568,29 +1394,13 @@ UpnpRegisterClient( IN Upnp_FunPtr Fun, "Exiting UpnpRegisterClient \n" ); return UPNP_E_SUCCESS; - -} /****************** End of UpnpRegisterClient *********************/ +} #endif // INCLUDE_CLIENT_APIS -/**************************************************************************** - * Function: UpnpUnRegisterClient - * - * Parameters: - * IN UpnpClient_Handle Hnd: The handle of the control point instance - * to unregister - * Description: - * This function unregisters a client registered with - * UpnpRegisterclient or UpnpRegisterclient2. After this call, the - * UpnpDevice_Handle Hnd is no longer valid. The UPnP Library generates - * no more callbacks after this function returns. - * - * Return Values: - * UPNP_E_SUCCESS on success, nonzero on failure. - *****************************************************************************/ +/*****************************************************************************/ #ifdef INCLUDE_CLIENT_APIS -int -UpnpUnRegisterClient( IN UpnpClient_Handle Hnd ) +int UpnpUnRegisterClient(IN UpnpClient_Handle Hnd) { struct Handle_Info *HInfo; ListNode *node = NULL; @@ -1638,7 +1448,7 @@ UpnpUnRegisterClient( IN UpnpClient_Handle Hnd ) "Exiting UpnpUnRegisterClient \n" ); return UPNP_E_SUCCESS; -} /****************** End of UpnpUnRegisterClient *********************/ +} #endif // INCLUDE_CLIENT_APIS //----------------------------------------------------------------------------- @@ -5151,17 +4961,11 @@ UpnpFree( IN void *item ) /************************************************************************** * Function: UpnpSetContentLength - * OBSOLETE METHOD : use {\bf UpnpSetMaxContentLength} instead. + * OBSOLETE METHOD: use UpnpSetMaxContentLength() instead. ***************************************************************************/ -int -UpnpSetContentLength( IN UpnpClient_Handle Hnd, - /** The handle of the device instance - for which the coincoming content length needs - to be set. */ - - IN int contentLength - /** Permissible content length */ - ) +int UpnpSetContentLength( + IN UpnpClient_Handle Hnd, + IN int contentLength) { int errCode = UPNP_E_SUCCESS; struct Handle_Info *HInfo = NULL; diff --git a/upnp/src/api/upnpdebug.c b/upnp/src/api/upnpdebug.c index d2f0fab..ff48fe0 100644 --- a/upnp/src/api/upnpdebug.c +++ b/upnp/src/api/upnpdebug.c @@ -339,20 +339,6 @@ void UpnpDisplayFileAndLine( #endif -/*************************************************************************** - * Function : UpnpDisplayBanner - * - * Parameters: - * IN FILE *fd: file descriptor where the banner will be written - * IN char **lines: The buffer that will be written - * IN int size: Size of the buffer - * IN int starLength: This parameter provides the width of the banner - * - * Description: - * This functions takes the buffer and writes the buffer in the file as - * per the requested banner - * Returns: void - ***************************************************************************/ #ifdef DEBUG void UpnpDisplayBanner( IN FILE * fd, @@ -407,4 +393,46 @@ void UpnpDisplayBanner( free( leftMargin ); } #endif - + + +#ifdef DEBUG +void PrintThreadPoolStats( + ThreadPool *tp, + const char *DbgFileName, + int DbgLineNo, + const char *msg) +{ + ThreadPoolStats stats; + ThreadPoolGetStats(tp, &stats); + UpnpPrintf(UPNP_INFO, API, DbgFileName, DbgLineNo, + "%s\n" + "High Jobs pending: %d\n" + "Med Jobs Pending: %d\n" + "Low Jobs Pending: %d\n" + "Average wait in High Q in milliseconds: %lf\n" + "Average wait in Med Q in milliseconds: %lf\n" + "Average wait in Low Q in milliseconds: %lf\n" + "Max Threads Used: %d\n" + "Worker Threads: %d\n" + "Persistent Threads: %d\n" + "Idle Threads: %d\n" + "Total Threads: %d\n" + "Total Work Time: %lf\n" + "Total Idle Time: %lf\n", + msg, + stats.currentJobsHQ, + stats.currentJobsMQ, + stats.currentJobsLQ, + stats.avgWaitHQ, + stats.avgWaitMQ, + stats.avgWaitLQ, + stats.maxThreads, + stats.workerThreads, + stats.persistentThreads, + stats.idleThreads, + stats.totalThreads, + stats.totalWorkTime, + stats.totalIdleTime); +} +#endif + diff --git a/upnp/src/inc/VirtualDir.h b/upnp/src/inc/VirtualDir.h index f9e66ea..c01524b 100644 --- a/upnp/src/inc/VirtualDir.h +++ b/upnp/src/inc/VirtualDir.h @@ -4,7 +4,7 @@ #define VIRTUALDIR_H -/** The {\bf VirtualDirCallbacks} structure contains the pointers to +/** The \b VirtualDirCallbacks structure contains the pointers to * file-related callback functions a device application can register to * virtualize URLs. */ @@ -16,43 +16,41 @@ struct VirtualDirCallbacks /** Called by the web server to open a file. The callback should return * a valid handle if the file can be opened. Otherwise, it should return - * {\tt NULL} to signify an error. */ + * \c NULL to signify an error. */ VDCallback_Open open; /** Called by the web server to perform a sequential read from an open - * file. The callback should copy {\bf buflen} bytes from the file into + * file. The callback should copy \b buflen bytes from the file into * the buffer. - * @return [int] An integer representing one of the following: - * \begin{itemize} - * \item {\tt 0}: The file contains no more data (EOF). - * \item {\tt >0}: A successful read of the number of bytes in the - * return code. - * \item {\tt <0}: An error occurred reading the file. - * \end{itemzie} + * @return An integer representing one of the following: + * \li 0: The file contains no more data (EOF). + * \li > 0: A successful read of the number of bytes in the + * return code. + * \li < 0: An error occurred reading the file. */ VDCallback_Read read; /** Called by the web server to perform a sequential write to an open - * file. The callback should write {\bf buflen} bytes into the file from + * file. The callback should write \b buflen bytes into the file from * the buffer. It should return the actual number of bytes written, - * which might be less than {\bf buflen} in the case of a write error. + * which might be less than \b buflen in the case of a write error. */ VDCallback_Write write; /** Called by the web server to move the file pointer, or offset, into - * an open file. The {\bf origin} parameter determines where to start - * moving the file pointer. A value of {\tt SEEK_CUR} moves the - * file pointer relative to where it is. The {\bf offset} parameter can + * an open file. The \b origin parameter determines where to start + * moving the file pointer. A value of \c SEEK_CUR moves the + * file pointer relative to where it is. The \b offset parameter can * be either positive (move forward) or negative (move backward). - * {\tt SEEK_END} moves relative to the end of the file. A positive - * {\bf offset} extends the file. A negative {\bf offset} moves backward - * in the file. Finally, {\tt SEEK_SET} moves to an absolute position in - * the file. In this case, {\bf offset} must be positive. The callback + * \c SEEK_END moves relative to the end of the file. A positive + * \b offset extends the file. A negative \b offset moves backward + * in the file. Finally, \c SEEK_SET moves to an absolute position in + * the file. In this case, \b offset must be positive. The callback * should return 0 on a successful seek or a non-zero value on an error. */ VDCallback_Seek seek; - /** Called by the web server to close a file opened via the {\bf open} + /** Called by the web server to close a file opened via the \b open * callback. It should return 0 on success, or a non-zero value on an * error. */