libUPnP  1.8.0
sample_util.h
00001 /*******************************************************************************
00002  *
00003  * Copyright (c) 2000-2003 Intel Corporation 
00004  * All rights reserved. 
00005  *
00006  * Redistribution and use in source and binary forms, with or without 
00007  * modification, are permitted provided that the following conditions are met: 
00008  *
00009  * - Redistributions of source code must retain the above copyright notice, 
00010  * this list of conditions and the following disclaimer. 
00011  * - Redistributions in binary form must reproduce the above copyright notice, 
00012  * this list of conditions and the following disclaimer in the documentation 
00013  * and/or other materials provided with the distribution. 
00014  * - Neither name of Intel Corporation nor the names of its contributors 
00015  * may be used to endorse or promote products derived from this software 
00016  * without specific prior written permission.
00017  * 
00018  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00019  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00020  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
00021  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
00022  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00023  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
00024  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
00025  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
00026  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00027  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  ******************************************************************************/
00031 
00032 
00033 #ifndef SAMPLE_UTIL_H
00034 #define SAMPLE_UTIL_H
00035 
00036 
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif /* __cplusplus */
00040 
00041 
00042 #include "ithread.h"
00043 #include "ixml.h" /* for IXML_Document, IXML_Element */
00044 #include "upnp.h" /* for Upnp_EventType */
00045 #include "upnptools.h"
00046 
00047 
00048 #include <stdlib.h>
00049 #include <string.h>
00050 
00051 
00052 /* mutex to control displaying of events */
00053 extern ithread_mutex_t display_mutex;
00054 
00055 
00056 typedef enum {
00057         STATE_UPDATE = 0,
00058         DEVICE_ADDED = 1,
00059         DEVICE_REMOVED = 2,
00060         GET_VAR_COMPLETE = 3
00061 } eventType;
00062 
00063 
00064 /********************************************************************************
00065  * SampleUtil_GetElementValue
00066  *
00067  * Description: 
00068  *       Given a DOM node such as <Channel>11</Channel>, this routine
00069  *       extracts the value (e.g., 11) from the node and returns it as 
00070  *       a string. The string must be freed by the caller using 
00071  *       free.
00072  *
00073  * Parameters:
00074  *   node -- The DOM node from which to extract the value
00075  *
00076  ********************************************************************************/
00077 char *SampleUtil_GetElementValue(IN IXML_Element *element);
00078 
00079 /********************************************************************************
00080  * SampleUtil_GetFirstServiceList
00081  *
00082  * Description: 
00083  *       Given a DOM node representing a UPnP Device Description Document,
00084  *       this routine parses the document and finds the first service list
00085  *       (i.e., the service list for the root device).  The service list
00086  *       is returned as a DOM node list. The NodeList must be freed using
00087  *       NodeList_free.
00088  *
00089  * Parameters:
00090  *   node -- The DOM node from which to extract the service list
00091  *
00092  ********************************************************************************/
00093 
00094 IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc); 
00095 
00096 
00097 /********************************************************************************
00098  * SampleUtil_GetFirstDocumentItem
00099  *
00100  * Description: 
00101  *       Given a document node, this routine searches for the first element
00102  *       named by the input string item, and returns its value as a string.
00103  *       String must be freed by caller using free.
00104  * Parameters:
00105  *   doc -- The DOM document from which to extract the value
00106  *   item -- The item to search for
00107  *
00108  ********************************************************************************/
00109 char *SampleUtil_GetFirstDocumentItem(IN IXML_Document *doc, IN const char *item); 
00110 
00111 
00112 
00113 /********************************************************************************
00114  * SampleUtil_GetFirstElementItem
00115  *
00116  * Description: 
00117  *       Given a DOM element, this routine searches for the first element
00118  *       named by the input string item, and returns its value as a string.
00119  *       The string must be freed using free.
00120  * Parameters:
00121  *   node -- The DOM element from which to extract the value
00122  *   item -- The item to search for
00123  *
00124  ********************************************************************************/
00125 char *SampleUtil_GetFirstElementItem(IN IXML_Element *element, IN const char *item); 
00126 
00127 /********************************************************************************
00128  * SampleUtil_PrintEventType
00129  *
00130  * Description: 
00131  *       Prints a callback event type as a string.
00132  *
00133  * Parameters:
00134  *   S -- The callback event
00135  *
00136  ********************************************************************************/
00137 void SampleUtil_PrintEventType(IN Upnp_EventType S);
00138 
00139 /********************************************************************************
00140  * SampleUtil_PrintEvent
00141  *
00142  * Description: 
00143  *       Prints callback event structure details.
00144  *
00145  * Parameters:
00146  *   EventType -- The type of callback event
00147  *   Event -- The callback event structure
00148  *
00149  ********************************************************************************/
00150 int SampleUtil_PrintEvent(IN Upnp_EventType EventType, 
00151                           IN void *Event);
00152 
00153 /********************************************************************************
00154  * SampleUtil_FindAndParseService
00155  *
00156  * Description: 
00157  *       This routine finds the first occurance of a service in a DOM representation
00158  *       of a description document and parses it.  Note that this function currently
00159  *       assumes that the eventURL and controlURL values in the service definitions
00160  *       are full URLs.  Relative URLs are not handled here.
00161  *
00162  * Parameters:
00163  *   DescDoc -- The DOM description document
00164  *   location -- The location of the description document
00165  *   serviceSearchType -- The type of service to search for
00166  *   serviceId -- OUT -- The service ID
00167  *   eventURL -- OUT -- The event URL for the service
00168  *   controlURL -- OUT -- The control URL for the service
00169  *
00170  ********************************************************************************/
00171 int SampleUtil_FindAndParseService (
00172         IN IXML_Document *DescDoc,
00173         IN const char* location, 
00174         IN char *serviceType,
00175         OUT char **serviceId, 
00176         OUT char **eventURL,
00177         OUT char **controlURL);
00178 
00179 
00180 /********************************************************************************
00181  * print_string
00182  *
00183  * Description: 
00184  *       Prototype for displaying strings. All printing done by the device,
00185  *       control point, and sample util, ultimately use this to display strings 
00186  *       to the user.
00187  *
00188  * Parameters:
00189  *   const char * string.
00190  *
00191  ********************************************************************************/
00192 typedef void (*print_string)(const char *string);
00193 
00194 //global print function used by sample util
00195 extern print_string gPrintFun;
00196 
00197 /********************************************************************************
00198  * state_update
00199  *
00200  * Description: 
00201  *     Prototype for passing back state changes
00202  *
00203  * Parameters:
00204  *   const char * varName
00205  *   const char * varValue
00206  *   const char * UDN
00207  *   int          newDevice
00208  ********************************************************************************/
00209 typedef void (*state_update)(
00210         const char *varName,
00211         const char *varValue,
00212         const char *UDN,
00213         eventType type);
00214 
00215 //global state update function used by smaple util
00216 extern state_update gStateUpdateFun;
00217 
00218 /********************************************************************************
00219  * SampleUtil_Initialize
00220  *
00221  * Description: 
00222  *     Initializes the sample util. Must be called before any sample util 
00223  *     functions. May be called multiple times.
00224  *
00225  * Parameters:
00226  *   print_function - print function to use in SampleUtil_Print
00227  *
00228  ********************************************************************************/
00229 int SampleUtil_Initialize(print_string print_function);
00230 
00231 /********************************************************************************
00232  * SampleUtil_Finish
00233  *
00234  * Description: 
00235  *     Releases Resources held by sample util.
00236  *
00237  * Parameters:
00238  *
00239  ********************************************************************************/
00240 int SampleUtil_Finish();
00241 
00242 /********************************************************************************
00243  * SampleUtil_Print
00244  *
00245  * Description: 
00246  *     Function emulating printf that ultimately calls the registered print 
00247  *     function with the formatted string.
00248  *
00249  * Parameters:
00250  *   fmt - format (see printf)
00251  *   . . .  - variable number of args. (see printf)
00252  *
00253  ********************************************************************************/
00254 int SampleUtil_Print(char *fmt, ...);
00255 
00256 /********************************************************************************
00257  * SampleUtil_RegisterUpdateFunction
00258  *
00259  * Description: 
00260  *
00261  * Parameters:
00262  *
00263  ********************************************************************************/
00264 int SampleUtil_RegisterUpdateFunction(state_update update_function);
00265 
00266 /********************************************************************************
00267  * SampleUtil_StateUpdate
00268  *
00269  * Description: 
00270  *
00271  * Parameters:
00272  *
00273  ********************************************************************************/
00274 void SampleUtil_StateUpdate(
00275         const char *varName,
00276         const char *varValue,
00277         const char *UDN,
00278         eventType type);
00279 
00280 #ifdef __cplusplus
00281 };
00282 #endif /* __cplusplus */
00283 
00284 
00285 #ifdef WIN32
00286         #define snprintf        _snprintf
00287         #define strcasecmp      stricmp
00288 #endif
00289 
00290 
00291 #endif /* SAMPLE_UTIL_H */
00292