generic-library/libupnp
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Some Doxygen on sample_util.

Browse Source 
(cherry picked from commit 0d625bd2e1267d25eb4bd202c4730ff363fd0f30)
This commit is contained in:
Marcelo Roberto Jimenez 2010-11-16 22:47:22 -02:00
parent 5d6bcabd45
commit d92e26779a
2 changed files with 152 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
upnp/sample/common/sample_util.c
View File

@ -54,18 +54,6 @@ state_update gStateUpdateFun = NULL;
/*! mutex to control displaying of events */ /*! mutex to control displaying of events */
ithread_mutex_t display_mutex; 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) int SampleUtil_Initialize(print_string print_function)
{ {
if (initialize_init) { if (initialize_init) {
@ -87,14 +75,6 @@ int SampleUtil_Initialize(print_string print_function)
return UPNP_E_SUCCESS; return UPNP_E_SUCCESS;
} }
/*******************************************************************************
* SampleUtil_RegisterUpdateFunction
*
* Description:
*
* Parameters:
*
******************************************************************************/
int SampleUtil_RegisterUpdateFunction(state_update update_function) int SampleUtil_RegisterUpdateFunction(state_update update_function)
{ {
if (initialize_register) { if (initialize_register) {
@ -105,15 +85,6 @@ int SampleUtil_RegisterUpdateFunction(state_update update_function)
return UPNP_E_SUCCESS; return UPNP_E_SUCCESS;
} }
/*******************************************************************************
* SampleUtil_Finish
*
* Description:
* Releases Resources held by sample util.
*
* Parameters:
*
******************************************************************************/
int SampleUtil_Finish() int SampleUtil_Finish()
{ {
ithread_mutex_destroy(&display_mutex); ithread_mutex_destroy(&display_mutex);
@ -125,21 +96,7 @@ int SampleUtil_Finish()
return UPNP_E_SUCCESS; return UPNP_E_SUCCESS;
} }
/******************************************************************************* char *SampleUtil_GetElementValue(IXML_Element *element)
* SampleUtil_GetElementValue
*
* Description:
* Given a DOM node such as <Channel>11</Channel>, 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)
{ {
IXML_Node *child = ixmlNode_getFirstChild((IXML_Node *)element); IXML_Node *child = ixmlNode_getFirstChild((IXML_Node *)element);
char *temp = NULL; char *temp = NULL;
@ -151,20 +108,7 @@ char *SampleUtil_GetElementValue(IN IXML_Element *element)
return temp; return temp;
} }
/******************************************************************************* IXML_NodeList *SampleUtil_GetFirstServiceList(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.
*
* Parameters:
* node -- The DOM node from which to extract the service list
*
******************************************************************************/
IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc)
{ {
IXML_NodeList *ServiceList = NULL; IXML_NodeList *ServiceList = NULL;
IXML_NodeList *servlistnodelist = 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 /* we only care about the first service list, from the root
* device */ * device */
servlistnode = ixmlNodeList_item(servlistnodelist, 0); servlistnode = ixmlNodeList_item(servlistnodelist, 0);
/* create as list of DOM nodes */ /* create as list of DOM nodes */
ServiceList = ixmlElement_getElementsByTagName( ServiceList = ixmlElement_getElementsByTagName(
(IXML_Element *)servlistnode, "service"); (IXML_Element *)servlistnode, "service");
@ -192,23 +135,24 @@ IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc)
* Obtain the service list * Obtain the service list
* n == 0 the first * n == 0 the first
* n == 1 the next in the device list, etc.. * 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 *ServiceList = NULL;
IXML_NodeList *servlistnodelist = NULL; IXML_NodeList *servlistnodelist = NULL;
IXML_Node *servlistnode = NULL; IXML_Node *servlistnode = NULL;
/* /* ixmlDocument_getElementsByTagName()
* ixmlDocument_getElementsByTagName()
* Returns a NodeList of all Elements that match the given * Returns a NodeList of all Elements that match the given
* tag name in the order in which they were encountered in a preorder * tag name in the order in which they were encountered in a preorder
* traversal of the Document tree. * traversal of the Document tree.
* *
* return (NodeList*) A pointer to a NodeList containing the * 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); SampleUtil_Print("SampleUtil_GetNthServiceList called : n = %d\n", n);
servlistnodelist = servlistnodelist =
ixmlDocument_getElementsByTagName(doc, "serviceList"); ixmlDocument_getElementsByTagName(doc, "serviceList");
@ -223,8 +167,7 @@ IXML_NodeList *SampleUtil_GetNthServiceList(IN IXML_Document *doc , int n)
* numerical index. * numerical index.
* *
* return (Node*) A pointer to a Node or NULL if there was an * return (Node*) A pointer to a Node or NULL if there was an
* error. * error. */
*/
servlistnode = ixmlNodeList_item(servlistnodelist, n); servlistnode = ixmlNodeList_item(servlistnodelist, n);
assert(servlistnode != 0); assert(servlistnode != 0);
@ -241,20 +184,7 @@ IXML_NodeList *SampleUtil_GetNthServiceList(IN IXML_Document *doc , int n)
return ServiceList; return ServiceList;
} }
/******************************************************************************* char *SampleUtil_GetFirstDocumentItem(IXML_Document *doc, const char *item)
* 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)
{ {
IXML_NodeList *nodeList = NULL; IXML_NodeList *nodeList = NULL;
IXML_Node *textNode = NULL; IXML_Node *textNode = NULL;
@ -299,20 +229,7 @@ epilogue:
return ret; return ret;
} }
/******************************************************************************* char *SampleUtil_GetFirstElementItem(IXML_Element *element, const char *item)
* 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)
{ {
IXML_NodeList *nodeList = NULL; IXML_NodeList *nodeList = NULL;
IXML_Node *textNode = NULL; IXML_Node *textNode = NULL;
@ -346,17 +263,7 @@ char *SampleUtil_GetFirstElementItem(
return ret; return ret;
} }
/******************************************************************************* void SampleUtil_PrintEventType(Upnp_EventType S)
* SampleUtil_PrintEventType
*
* Description:
* Prints a callback event type as a string.
*
* Parameters:
* S -- The callback event
*
******************************************************************************/
void SampleUtil_PrintEventType(IN Upnp_EventType S)
{ {
switch (S) { switch (S) {
/* Discovery */ /* Discovery */
@ -410,18 +317,7 @@ void SampleUtil_PrintEventType(IN Upnp_EventType S)
} }
} }
/******************************************************************************* int SampleUtil_PrintEvent(Upnp_EventType EventType, void *Event)
* 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)
{ {
ithread_mutex_lock(&display_mutex); ithread_mutex_lock(&display_mutex);
@ -539,7 +435,6 @@ int SampleUtil_PrintEvent(IN Upnp_EventType EventType, IN void *Event)
SampleUtil_Print("CurrentVal = %s\n", sv_event->CurrentVal); SampleUtil_Print("CurrentVal = %s\n", sv_event->CurrentVal);
break; break;
} }
/* GENA */ /* GENA */
case UPNP_EVENT_SUBSCRIPTION_REQUEST: { case UPNP_EVENT_SUBSCRIPTION_REQUEST: {
struct Upnp_Subscription_Request *sr_event = struct Upnp_Subscription_Request *sr_event =
@ -607,25 +502,8 @@ int SampleUtil_PrintEvent(IN Upnp_EventType EventType, IN void *Event)
return 0; return 0;
} }
/******************************************************************************* int SampleUtil_FindAndParseService(IXML_Document *DescDoc, const char *location,
* SampleUtil_FindAndParseService char *serviceType, char **serviceId, char **eventURL, char **controlURL)
*
* 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 i; int i;
int length; int length;
@ -711,20 +589,7 @@ int SampleUtil_FindAndParseService(
return found; return found;
} }
/******************************************************************************* int SampleUtil_Print(const char *fmt, ...)
* 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, ...)
{ {
#define MAX_BUF (8 * 1024) #define MAX_BUF (8 * 1024)
va_list ap; va_list ap;
@ -747,14 +612,6 @@ int SampleUtil_Print(char *fmt, ...)
return rc; return rc;
} }
/*******************************************************************************
* SampleUtil_StateUpdate
*
* Description:
*
* Parameters:
*
******************************************************************************/
void SampleUtil_StateUpdate(const char *varName, const char *varValue, void SampleUtil_StateUpdate(const char *varName, const char *varValue,
const char *UDN, eventType type) const char *UDN, eventType type)
{ {

298
upnp/sample/common/sample_util.h
View File

@ -29,30 +29,28 @@
* *
******************************************************************************/ ******************************************************************************/
#ifndef SAMPLE_UTIL_H #ifndef SAMPLE_UTIL_H
#define SAMPLE_UTIL_H #define SAMPLE_UTIL_H
/*!
* \file
*/
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif /* __cplusplus */ #endif /* __cplusplus */
#include "ithread.h" #include "ithread.h"
#include "ixml.h" /* for IXML_Document, IXML_Element */ #include "ixml.h" /* for IXML_Document, IXML_Element */
#include "upnp.h" /* for Upnp_EventType */ #include "upnp.h" /* for Upnp_EventType */
#include "upnptools.h" #include "upnptools.h"
#include <stdlib.h> #include <stdlib.h>
#include <string.h> #include <string.h>
/* mutex to control displaying of events */ /* mutex to control displaying of events */
extern ithread_mutex_t display_mutex; extern ithread_mutex_t display_mutex;
typedef enum { typedef enum {
STATE_UPDATE = 0, STATE_UPDATE = 0,
DEVICE_ADDED = 1, DEVICE_ADDED = 1,
@ -60,233 +58,179 @@ typedef enum {
GET_VAR_COMPLETE = 3 GET_VAR_COMPLETE = 3
} eventType; } eventType;
/*!
/******************************************************************************** * \brief Given a DOM node such as <Channel>11</Channel>, this routine
* SampleUtil_GetElementValue
*
* Description:
* Given a DOM node such as <Channel>11</Channel>, this routine
* extracts the value (e.g., 11) from the node and returns it as * extracts the value (e.g., 11) from the node and returns it as
* a string. The string must be freed by the caller using * a string. The string must be freed by the caller using free.
* free.
* *
* Parameters: * \return The DOM node as a string.
* node -- The DOM node from which to extract the value */
* char *SampleUtil_GetElementValue(
********************************************************************************/ /*! [in] The DOM node from which to extract the value. */
char *SampleUtil_GetElementValue(IN IXML_Element *element); IXML_Element *element);
/******************************************************************************** /*!
* SampleUtil_GetFirstServiceList * \brief Given a DOM node representing a UPnP Device Description Document,
*
* Description:
* Given a DOM node representing a UPnP Device Description Document,
* this routine parses the document and finds the first service list * this routine parses the document and finds the first service list
* (i.e., the service list for the root device). The 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 * is returned as a DOM node list. The NodeList must be freed using
* NodeList_free. * NodeList_free.
* *
* Parameters: * \return The service list is returned as a DOM node list.
* node -- The DOM node from which to extract the service list */
* IXML_NodeList *SampleUtil_GetFirstServiceList(
********************************************************************************/ /*! [in] The DOM node from which to extract the service list. */
IXML_Document *doc);
IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc); /*!
* \brief Given a document node, this routine searches for the first element
/********************************************************************************
* 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. * named by the input string item, and returns its value as a string.
* String must be freed by caller using free. * String must be freed by caller using free.
* Parameters: */
* doc -- The DOM document from which to extract the value char *SampleUtil_GetFirstDocumentItem(
* item -- The item to search for /*! [in] The DOM document from which to extract the value. */
* IXML_Document *doc,
********************************************************************************/ /*! [in] The item to search for. */
char *SampleUtil_GetFirstDocumentItem(IN IXML_Document *doc, IN const char *item); const char *item);
/*!
* \brief Given a DOM element, this routine searches for the first element
/********************************************************************************
* 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. * named by the input string item, and returns its value as a string.
* The string must be freed using free. * The string must be freed using free.
* Parameters: */
* node -- The DOM element from which to extract the value char *SampleUtil_GetFirstElementItem(
* item -- The item to search for /*! [in] The DOM element from which to extract the value. */
* IXML_Element *element,
********************************************************************************/ /*! [in] The item to search for. */
char *SampleUtil_GetFirstElementItem(IN IXML_Element *element, IN const char *item); const char *item);
/******************************************************************************** /*!
* SampleUtil_PrintEventType * \brief Prints a callback event type as a string.
* */
* Description: void SampleUtil_PrintEventType(
* Prints a callback event type as a string. /*! [in] The callback event. */
* Upnp_EventType S);
* Parameters:
* S -- The callback event
*
********************************************************************************/
void SampleUtil_PrintEventType(IN Upnp_EventType S);
/******************************************************************************** /*!
* SampleUtil_PrintEvent * \brief Prints callback event structure details.
* */
* Description: int SampleUtil_PrintEvent(
* Prints callback event structure details. /*! [in] The type of callback event. */
* Upnp_EventType EventType,
* Parameters: /*! [in] The callback event structure. */
* EventType -- The type of callback event void *Event);
* Event -- The callback event structure
*
********************************************************************************/
int SampleUtil_PrintEvent(IN Upnp_EventType EventType,
IN void *Event);
/******************************************************************************** /*!
* SampleUtil_FindAndParseService * \brief This routine finds the first occurance of a service in a DOM
* * representation of a description document and parses it. Note that this
* Description: * function currently assumes that the eventURL and controlURL values in
* This routine finds the first occurance of a service in a DOM representation * the service definitions are full URLs. Relative URLs are not handled here.
* 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
*
********************************************************************************/
int SampleUtil_FindAndParseService ( int SampleUtil_FindAndParseService (
IN IXML_Document *DescDoc, /*! [in] The DOM description document. */
IN const char* location, IXML_Document *DescDoc,
IN char *serviceType, /*! [in] The location of the description document. */
OUT char **serviceId, const char *location,
OUT char **eventURL, /*! [in] The type of service to search for. */
OUT char **controlURL); 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,
* print_string
*
* Description:
* Prototype for displaying strings. All printing done by the device,
* control point, and sample util, ultimately use this to display strings * control point, and sample util, ultimately use this to display strings
* to the user. * to the user.
* */
* Parameters: typedef void (*print_string)(
* const char * string. /*! [in] Format. */
* 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; extern print_string gPrintFun;
/******************************************************************************** /*!
* state_update * \brief Prototype for passing back state changes.
* */
* Description:
* Prototype for passing back state changes
*
* Parameters:
* const char * varName
* const char * varValue
* const char * UDN
* int newDevice
********************************************************************************/
typedef void (*state_update)( typedef void (*state_update)(
/*! [in] . */
const char *varName, const char *varName,
/*! [in] . */
const char *varValue, const char *varValue,
/*! [in] . */
const char *UDN, const char *UDN,
/*! [in] . */
eventType type); eventType type);
/*global state update function used by smaple util */ /*! global state update function used by smaple util */
extern state_update gStateUpdateFun; extern state_update gStateUpdateFun;
/******************************************************************************** /*!
* SampleUtil_Initialize * \brief Initializes the sample util. Must be called before any sample util
*
* Description:
* Initializes the sample util. Must be called before any sample util
* functions. May be called multiple times. * functions. May be called multiple times.
* */
* Parameters: int SampleUtil_Initialize(
* print_function - print function to use in SampleUtil_Print /*! [in] Print function to use in SampleUtil_Print. */
* print_string print_function);
********************************************************************************/
int SampleUtil_Initialize(print_string print_function);
/******************************************************************************** /*!
* SampleUtil_Finish * \brief Releases Resources held by sample util.
* */
* Description:
* Releases Resources held by sample util.
*
* Parameters:
*
********************************************************************************/
int SampleUtil_Finish(); int SampleUtil_Finish();
/******************************************************************************** /*!
* SampleUtil_Print * \brief Function emulating printf that ultimately calls the registered print
*
* Description:
* Function emulating printf that ultimately calls the registered print
* function with the formatted string. * function with the formatted string.
* *
* Parameters: * Provides platform-specific print functionality. This function should be
* fmt - format (see printf) * called when you want to print content suitable for console output (i.e.,
* . . . - variable number of args. (see printf) * in a large text box or on a screen). If your device/operating system is
* not supported here, you should add a port.
* *
********************************************************************************/ * \return The same as printf.
int SampleUtil_Print(char *fmt, ...); */
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 * \brief
* */
* Description: int SampleUtil_RegisterUpdateFunction(
* /*! [in] . */
* Parameters: state_update update_function);
*
********************************************************************************/
int SampleUtil_RegisterUpdateFunction(state_update update_function);
/******************************************************************************** /*!
* SampleUtil_StateUpdate * \brief
* */
* Description:
*
* Parameters:
*
********************************************************************************/
void SampleUtil_StateUpdate( void SampleUtil_StateUpdate(
/*! [in] . */
const char *varName, const char *varName,
/*! [in] . */
const char *varValue, const char *varValue,
/*! [in] . */
const char *UDN, const char *UDN,
/*! [in] . */
eventType type); eventType type);
#ifdef __cplusplus #ifdef __cplusplus
}; };
#endif /* __cplusplus */ #endif /* __cplusplus */
#ifdef WIN32 #ifdef WIN32
#define snprintf _snprintf #define snprintf _snprintf
#define strcasecmp stricmp #define strcasecmp stricmp
#endif #endif
#endif /* SAMPLE_UTIL_H */ #endif /* SAMPLE_UTIL_H */