From 0d625bd2e1267d25eb4bd202c4730ff363fd0f30 Mon Sep 17 00:00:00 2001 From: Marcelo Roberto Jimenez Date: Tue, 16 Nov 2010 22:47:22 -0200 Subject: [PATCH] Some Doxygen on sample_util. --- upnp/sample/common/sample_util.c | 177 ++--------------- upnp/sample/common/sample_util.h | 326 +++++++++++++------------------ 2 files changed, 152 insertions(+), 351 deletions(-) diff --git a/upnp/sample/common/sample_util.c b/upnp/sample/common/sample_util.c index fbfe1ea..2f953a5 100644 --- a/upnp/sample/common/sample_util.c +++ b/upnp/sample/common/sample_util.c @@ -54,18 +54,6 @@ state_update gStateUpdateFun = NULL; /*! mutex to control displaying of events */ ithread_mutex_t display_mutex; -/******************************************************************************* - * SampleUtil_Initialize - * - * Description: - * Initializes the sample util. Must be called before any sample util - * functions. May be called multiple times. - * But the initialization is done only once. - * - * Parameters: - * print_function - print function to use in SampleUtil_Print - * - ******************************************************************************/ int SampleUtil_Initialize(print_string print_function) { if (initialize_init) { @@ -87,14 +75,6 @@ int SampleUtil_Initialize(print_string print_function) return UPNP_E_SUCCESS; } -/******************************************************************************* - * SampleUtil_RegisterUpdateFunction - * - * Description: - * - * Parameters: - * - ******************************************************************************/ int SampleUtil_RegisterUpdateFunction(state_update update_function) { if (initialize_register) { @@ -105,15 +85,6 @@ int SampleUtil_RegisterUpdateFunction(state_update update_function) return UPNP_E_SUCCESS; } -/******************************************************************************* - * SampleUtil_Finish - * - * Description: - * Releases Resources held by sample util. - * - * Parameters: - * - ******************************************************************************/ int SampleUtil_Finish() { ithread_mutex_destroy(&display_mutex); @@ -125,21 +96,7 @@ int SampleUtil_Finish() return UPNP_E_SUCCESS; } -/******************************************************************************* - * SampleUtil_GetElementValue - * - * Description: - * Given a DOM node such as 11, this routine - * extracts the value (e.g., 11) from the node and returns it as - * a string. The string must be freed by the caller using - * free. - * - * Parameters: - * node -- The DOM node from which to extract the value - * - ******************************************************************************/ - -char *SampleUtil_GetElementValue(IN IXML_Element *element) +char *SampleUtil_GetElementValue(IXML_Element *element) { IXML_Node *child = ixmlNode_getFirstChild((IXML_Node *)element); char *temp = NULL; @@ -151,20 +108,7 @@ char *SampleUtil_GetElementValue(IN IXML_Element *element) return temp; } -/******************************************************************************* - * SampleUtil_GetFirstServiceList - * - * Description: - * Given a DOM node representing a UPnP Device Description Document, - * this routine parses the document and finds the first service list - * (i.e., the service list for the root device). The service list - * is returned as a DOM node list. - * - * Parameters: - * node -- The DOM node from which to extract the service list - * - ******************************************************************************/ -IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc) +IXML_NodeList *SampleUtil_GetFirstServiceList(IXML_Document *doc) { IXML_NodeList *ServiceList = NULL; IXML_NodeList *servlistnodelist = NULL; @@ -176,7 +120,6 @@ IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc) /* we only care about the first service list, from the root * device */ servlistnode = ixmlNodeList_item(servlistnodelist, 0); - /* create as list of DOM nodes */ ServiceList = ixmlElement_getElementsByTagName( (IXML_Element *)servlistnode, "service"); @@ -192,23 +135,24 @@ IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc) * Obtain the service list * n == 0 the first * n == 1 the next in the device list, etc.. - * */ -IXML_NodeList *SampleUtil_GetNthServiceList(IN IXML_Document *doc , int n) +static IXML_NodeList *SampleUtil_GetNthServiceList( + /*! [in] . */ + IXML_Document *doc, + /*! [in] . */ + int n) { IXML_NodeList *ServiceList = NULL; IXML_NodeList *servlistnodelist = NULL; IXML_Node *servlistnode = NULL; - /* - * ixmlDocument_getElementsByTagName() + /* ixmlDocument_getElementsByTagName() * Returns a NodeList of all Elements that match the given * tag name in the order in which they were encountered in a preorder * traversal of the Document tree. * * return (NodeList*) A pointer to a NodeList containing the - * matching items or NULL on an error. - */ + * matching items or NULL on an error. */ SampleUtil_Print("SampleUtil_GetNthServiceList called : n = %d\n", n); servlistnodelist = ixmlDocument_getElementsByTagName(doc, "serviceList"); @@ -223,8 +167,7 @@ IXML_NodeList *SampleUtil_GetNthServiceList(IN IXML_Document *doc , int n) * numerical index. * * return (Node*) A pointer to a Node or NULL if there was an - * error. - */ + * error. */ servlistnode = ixmlNodeList_item(servlistnodelist, n); assert(servlistnode != 0); @@ -241,20 +184,7 @@ IXML_NodeList *SampleUtil_GetNthServiceList(IN IXML_Document *doc , int n) return ServiceList; } -/******************************************************************************* - * SampleUtil_GetFirstDocumentItem - * - * Description: - * Given a document node, this routine searches for the first element - * named by the input string item, and returns its value as a string. - * String must be freed by caller using free. - * Parameters: - * doc -- The DOM document from which to extract the value - * item -- The item to search for - * - ******************************************************************************/ -char *SampleUtil_GetFirstDocumentItem( - IN IXML_Document *doc, IN const char *item) +char *SampleUtil_GetFirstDocumentItem(IXML_Document *doc, const char *item) { IXML_NodeList *nodeList = NULL; IXML_Node *textNode = NULL; @@ -299,20 +229,7 @@ epilogue: return ret; } -/******************************************************************************* - * SampleUtil_GetFirstElementItem - * - * Description: - * Given a DOM element, this routine searches for the first element - * named by the input string item, and returns its value as a string. - * The string must be freed using free. - * Parameters: - * node -- The DOM element from which to extract the value - * item -- The item to search for - * - ******************************************************************************/ -char *SampleUtil_GetFirstElementItem( - IN IXML_Element *element, IN const char *item) +char *SampleUtil_GetFirstElementItem(IXML_Element *element, const char *item) { IXML_NodeList *nodeList = NULL; IXML_Node *textNode = NULL; @@ -346,17 +263,7 @@ char *SampleUtil_GetFirstElementItem( return ret; } -/******************************************************************************* - * SampleUtil_PrintEventType - * - * Description: - * Prints a callback event type as a string. - * - * Parameters: - * S -- The callback event - * - ******************************************************************************/ -void SampleUtil_PrintEventType(IN Upnp_EventType S) +void SampleUtil_PrintEventType(Upnp_EventType S) { switch (S) { /* Discovery */ @@ -410,18 +317,7 @@ void SampleUtil_PrintEventType(IN Upnp_EventType S) } } -/******************************************************************************* - * SampleUtil_PrintEvent - * - * Description: - * Prints callback event structure details. - * - * Parameters: - * EventType -- The type of callback event - * Event -- The callback event structure - * - ******************************************************************************/ -int SampleUtil_PrintEvent(IN Upnp_EventType EventType, IN void *Event) +int SampleUtil_PrintEvent(Upnp_EventType EventType, void *Event) { ithread_mutex_lock(&display_mutex); @@ -572,7 +468,6 @@ int SampleUtil_PrintEvent(IN Upnp_EventType EventType, IN void *Event) UpnpStateVarComplete_get_CurrentVal(sv_event)); break; } - /* GENA */ case UPNP_EVENT_SUBSCRIPTION_REQUEST: { UpnpSubscriptionRequest *sr_event = (UpnpSubscriptionRequest *)Event; @@ -655,25 +550,8 @@ int SampleUtil_PrintEvent(IN Upnp_EventType EventType, IN void *Event) return 0; } -/******************************************************************************* - * SampleUtil_FindAndParseService - * - * Description: - * This routine finds the first occurance of a service in a DOM representation - * of a description document and parses it. - * - * Parameters: - * DescDoc -- The DOM description document - * location -- The location of the description document - * serviceSearchType -- The type of service to search for - * serviceId -- OUT -- The service ID - * eventURL -- OUT -- The event URL for the service - * controlURL -- OUT -- The control URL for the service - * - ******************************************************************************/ -int SampleUtil_FindAndParseService( - IN IXML_Document *DescDoc, IN const char *location, IN char *serviceType, - OUT char **serviceId, OUT char **eventURL, OUT char **controlURL) +int SampleUtil_FindAndParseService(IXML_Document *DescDoc, const char *location, + char *serviceType, char **serviceId, char **eventURL, char **controlURL) { int i; int length; @@ -759,20 +637,7 @@ int SampleUtil_FindAndParseService( return found; } -/******************************************************************************* - * SampleUtil_Print - * - * Description: - * Provides platform-specific print functionality. This function should be - * called when you want to print content suitable for console output (i.e., - * in a large text box or on a screen). If your device/operating system is - * not supported here, you should add a port. - * - * Parameters: - * Same as printf() - * - ******************************************************************************/ -int SampleUtil_Print(char *fmt, ...) +int SampleUtil_Print(const char *fmt, ...) { #define MAX_BUF (8 * 1024) va_list ap; @@ -795,14 +660,6 @@ int SampleUtil_Print(char *fmt, ...) return rc; } -/******************************************************************************* - * SampleUtil_StateUpdate - * - * Description: - * - * Parameters: - * - ******************************************************************************/ void SampleUtil_StateUpdate(const char *varName, const char *varValue, const char *UDN, eventType type) { diff --git a/upnp/sample/common/sample_util.h b/upnp/sample/common/sample_util.h index 836a93e..fe56d1e 100644 --- a/upnp/sample/common/sample_util.h +++ b/upnp/sample/common/sample_util.h @@ -29,30 +29,28 @@ * ******************************************************************************/ - #ifndef SAMPLE_UTIL_H #define SAMPLE_UTIL_H +/*! + * \file + */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ - #include "ithread.h" #include "ixml.h" /* for IXML_Document, IXML_Element */ #include "upnp.h" /* for Upnp_EventType */ #include "upnptools.h" - #include #include - /* mutex to control displaying of events */ extern ithread_mutex_t display_mutex; - typedef enum { STATE_UPDATE = 0, DEVICE_ADDED = 1, @@ -60,233 +58,179 @@ typedef enum { GET_VAR_COMPLETE = 3 } eventType; +/*! + * \brief Given a DOM node such as 11, this routine + * extracts the value (e.g., 11) from the node and returns it as + * a string. The string must be freed by the caller using free. + * + * \return The DOM node as a string. + */ +char *SampleUtil_GetElementValue( + /*! [in] The DOM node from which to extract the value. */ + IXML_Element *element); -/******************************************************************************** - * SampleUtil_GetElementValue +/*! + * \brief Given a DOM node representing a UPnP Device Description Document, + * this routine parses the document and finds the first service list + * (i.e., the service list for the root device). The service list + * is returned as a DOM node list. The NodeList must be freed using + * NodeList_free. * - * Description: - * Given a DOM node such as 11, this routine - * extracts the value (e.g., 11) from the node and returns it as - * a string. The string must be freed by the caller using - * free. - * - * Parameters: - * node -- The DOM node from which to extract the value - * - ********************************************************************************/ -char *SampleUtil_GetElementValue(IN IXML_Element *element); + * \return The service list is returned as a DOM node list. + */ +IXML_NodeList *SampleUtil_GetFirstServiceList( + /*! [in] The DOM node from which to extract the service list. */ + IXML_Document *doc); -/******************************************************************************** - * SampleUtil_GetFirstServiceList - * - * Description: - * Given a DOM node representing a UPnP Device Description Document, - * this routine parses the document and finds the first service list - * (i.e., the service list for the root device). The service list - * is returned as a DOM node list. The NodeList must be freed using - * NodeList_free. - * - * Parameters: - * node -- The DOM node from which to extract the service list - * - ********************************************************************************/ +/*! + * \brief Given a document node, this routine searches for the first element + * named by the input string item, and returns its value as a string. + * String must be freed by caller using free. + */ +char *SampleUtil_GetFirstDocumentItem( + /*! [in] The DOM document from which to extract the value. */ + IXML_Document *doc, + /*! [in] The item to search for. */ + const char *item); -IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc); +/*! + * \brief Given a DOM element, this routine searches for the first element + * named by the input string item, and returns its value as a string. + * The string must be freed using free. + */ +char *SampleUtil_GetFirstElementItem( + /*! [in] The DOM element from which to extract the value. */ + IXML_Element *element, + /*! [in] The item to search for. */ + const char *item); +/*! + * \brief Prints a callback event type as a string. + */ +void SampleUtil_PrintEventType( + /*! [in] The callback event. */ + Upnp_EventType S); -/******************************************************************************** - * SampleUtil_GetFirstDocumentItem - * - * Description: - * Given a document node, this routine searches for the first element - * named by the input string item, and returns its value as a string. - * String must be freed by caller using free. - * Parameters: - * doc -- The DOM document from which to extract the value - * item -- The item to search for - * - ********************************************************************************/ -char *SampleUtil_GetFirstDocumentItem(IN IXML_Document *doc, IN const char *item); +/*! + * \brief Prints callback event structure details. + */ +int SampleUtil_PrintEvent( + /*! [in] The type of callback event. */ + Upnp_EventType EventType, + /*! [in] The callback event structure. */ + void *Event); - - -/******************************************************************************** - * SampleUtil_GetFirstElementItem - * - * Description: - * Given a DOM element, this routine searches for the first element - * named by the input string item, and returns its value as a string. - * The string must be freed using free. - * Parameters: - * node -- The DOM element from which to extract the value - * item -- The item to search for - * - ********************************************************************************/ -char *SampleUtil_GetFirstElementItem(IN IXML_Element *element, IN const char *item); - -/******************************************************************************** - * SampleUtil_PrintEventType - * - * Description: - * Prints a callback event type as a string. - * - * Parameters: - * S -- The callback event - * - ********************************************************************************/ -void SampleUtil_PrintEventType(IN Upnp_EventType S); - -/******************************************************************************** - * SampleUtil_PrintEvent - * - * Description: - * Prints callback event structure details. - * - * Parameters: - * EventType -- The type of callback event - * Event -- The callback event structure - * - ********************************************************************************/ -int SampleUtil_PrintEvent(IN Upnp_EventType EventType, - IN void *Event); - -/******************************************************************************** - * SampleUtil_FindAndParseService - * - * Description: - * This routine finds the first occurance of a service in a DOM representation - * of a description document and parses it. Note that this function currently - * assumes that the eventURL and controlURL values in the service definitions - * are full URLs. Relative URLs are not handled here. - * - * Parameters: - * DescDoc -- The DOM description document - * location -- The location of the description document - * serviceSearchType -- The type of service to search for - * serviceId -- OUT -- The service ID - * eventURL -- OUT -- The event URL for the service - * controlURL -- OUT -- The control URL for the service - * - ********************************************************************************/ +/*! + * \brief This routine finds the first occurance of a service in a DOM + * representation of a description document and parses it. Note that this + * function currently assumes that the eventURL and controlURL values in + * the service definitions are full URLs. Relative URLs are not handled here. + */ int SampleUtil_FindAndParseService ( - IN IXML_Document *DescDoc, - IN const char* location, - IN char *serviceType, - OUT char **serviceId, - OUT char **eventURL, - OUT char **controlURL); + /*! [in] The DOM description document. */ + IXML_Document *DescDoc, + /*! [in] The location of the description document. */ + const char *location, + /*! [in] The type of service to search for. */ + char *serviceType, + /*! [out] The service ID. */ + char **serviceId, + /*! [out] The event URL for the service. */ + char **eventURL, + /*! [out] The control URL for the service. */ + char **controlURL); +/*! + * \brief Prototype for displaying strings. All printing done by the device, + * control point, and sample util, ultimately use this to display strings + * to the user. + */ +typedef void (*print_string)( + /*! [in] Format. */ + const char *string); -/******************************************************************************** - * print_string - * - * Description: - * Prototype for displaying strings. All printing done by the device, - * control point, and sample util, ultimately use this to display strings - * to the user. - * - * Parameters: - * const char * string. - * - ********************************************************************************/ -typedef void (*print_string)(const char *string); - -/*global print function used by sample util */ +/*! global print function used by sample util */ extern print_string gPrintFun; -/******************************************************************************** - * state_update - * - * Description: - * Prototype for passing back state changes - * - * Parameters: - * const char * varName - * const char * varValue - * const char * UDN - * int newDevice - ********************************************************************************/ +/*! + * \brief Prototype for passing back state changes. + */ typedef void (*state_update)( + /*! [in] . */ const char *varName, + /*! [in] . */ const char *varValue, + /*! [in] . */ const char *UDN, + /*! [in] . */ eventType type); -/*global state update function used by smaple util */ +/*! global state update function used by smaple util */ extern state_update gStateUpdateFun; -/******************************************************************************** - * SampleUtil_Initialize - * - * Description: - * Initializes the sample util. Must be called before any sample util - * functions. May be called multiple times. - * - * Parameters: - * print_function - print function to use in SampleUtil_Print - * - ********************************************************************************/ -int SampleUtil_Initialize(print_string print_function); +/*! + * \brief Initializes the sample util. Must be called before any sample util + * functions. May be called multiple times. + */ +int SampleUtil_Initialize( + /*! [in] Print function to use in SampleUtil_Print. */ + print_string print_function); -/******************************************************************************** - * SampleUtil_Finish - * - * Description: - * Releases Resources held by sample util. - * - * Parameters: - * - ********************************************************************************/ +/*! + * \brief Releases Resources held by sample util. + */ int SampleUtil_Finish(); -/******************************************************************************** - * SampleUtil_Print +/*! + * \brief Function emulating printf that ultimately calls the registered print + * function with the formatted string. * - * Description: - * Function emulating printf that ultimately calls the registered print - * function with the formatted string. + * Provides platform-specific print functionality. This function should be + * called when you want to print content suitable for console output (i.e., + * in a large text box or on a screen). If your device/operating system is + * not supported here, you should add a port. * - * Parameters: - * fmt - format (see printf) - * . . . - variable number of args. (see printf) - * - ********************************************************************************/ -int SampleUtil_Print(char *fmt, ...); + * \return The same as printf. + */ +int SampleUtil_Print( + /*! [in] Format (see printf). */ + const char *fmt, + /*! [in] Format data. */ + ...) +#if (__GNUC__ >= 3) + /* This enables printf like format checking by the compiler */ + __attribute__((format (__printf__, 1, 2))) +#endif +; -/******************************************************************************** - * SampleUtil_RegisterUpdateFunction - * - * Description: - * - * Parameters: - * - ********************************************************************************/ -int SampleUtil_RegisterUpdateFunction(state_update update_function); +/*! + * \brief + */ +int SampleUtil_RegisterUpdateFunction( + /*! [in] . */ + state_update update_function); -/******************************************************************************** - * SampleUtil_StateUpdate - * - * Description: - * - * Parameters: - * - ********************************************************************************/ +/*! + * \brief + */ void SampleUtil_StateUpdate( + /*! [in] . */ const char *varName, + /*! [in] . */ const char *varValue, + /*! [in] . */ const char *UDN, + /*! [in] . */ eventType type); #ifdef __cplusplus }; #endif /* __cplusplus */ - #ifdef WIN32 #define snprintf _snprintf #define strcasecmp stricmp #endif - #endif /* SAMPLE_UTIL_H */