libUPnP  1.8.0
sample_util.h
1 /*******************************************************************************
2  *
3  * Copyright (c) 2000-2003 Intel Corporation
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are met:
8  *
9  * - Redistributions of source code must retain the above copyright notice,
10  * this list of conditions and the following disclaimer.
11  * - Redistributions in binary form must reproduce the above copyright notice,
12  * this list of conditions and the following disclaimer in the documentation
13  * and/or other materials provided with the distribution.
14  * - Neither name of Intel Corporation nor the names of its contributors
15  * may be used to endorse or promote products derived from this software
16  * without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR
22  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
25  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
26  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
27  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  *
30  ******************************************************************************/
31 
32 
33 #ifndef SAMPLE_UTIL_H
34 #define SAMPLE_UTIL_H
35 
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif /* __cplusplus */
40 
41 
42 #include "ithread.h"
43 #include "ixml.h" /* for IXML_Document, IXML_Element */
44 #include "upnp.h" /* for Upnp_EventType */
45 #include "upnptools.h"
46 
47 
48 #include <stdlib.h>
49 #include <string.h>
50 
51 
52 /* mutex to control displaying of events */
53 extern ithread_mutex_t display_mutex;
54 
55 
56 typedef enum {
57  STATE_UPDATE = 0,
58  DEVICE_ADDED = 1,
59  DEVICE_REMOVED = 2,
60  GET_VAR_COMPLETE = 3
61 } eventType;
62 
63 
64 /********************************************************************************
65  * SampleUtil_GetElementValue
66  *
67  * Description:
68  * Given a DOM node such as <Channel>11</Channel>, this routine
69  * extracts the value (e.g., 11) from the node and returns it as
70  * a string. The string must be freed by the caller using
71  * free.
72  *
73  * Parameters:
74  * node -- The DOM node from which to extract the value
75  *
76  ********************************************************************************/
77 char *SampleUtil_GetElementValue(IN IXML_Element *element);
78 
79 /********************************************************************************
80  * SampleUtil_GetFirstServiceList
81  *
82  * Description:
83  * Given a DOM node representing a UPnP Device Description Document,
84  * this routine parses the document and finds the first service list
85  * (i.e., the service list for the root device). The service list
86  * is returned as a DOM node list. The NodeList must be freed using
87  * NodeList_free.
88  *
89  * Parameters:
90  * node -- The DOM node from which to extract the service list
91  *
92  ********************************************************************************/
93 
94 IXML_NodeList *SampleUtil_GetFirstServiceList(IN IXML_Document *doc);
95 
96 
97 /********************************************************************************
98  * SampleUtil_GetFirstDocumentItem
99  *
100  * Description:
101  * Given a document node, this routine searches for the first element
102  * named by the input string item, and returns its value as a string.
103  * String must be freed by caller using free.
104  * Parameters:
105  * doc -- The DOM document from which to extract the value
106  * item -- The item to search for
107  *
108  ********************************************************************************/
109 char *SampleUtil_GetFirstDocumentItem(IN IXML_Document *doc, IN const char *item);
110 
111 
112 
113 /********************************************************************************
114  * SampleUtil_GetFirstElementItem
115  *
116  * Description:
117  * Given a DOM element, this routine searches for the first element
118  * named by the input string item, and returns its value as a string.
119  * The string must be freed using free.
120  * Parameters:
121  * node -- The DOM element from which to extract the value
122  * item -- The item to search for
123  *
124  ********************************************************************************/
125 char *SampleUtil_GetFirstElementItem(IN IXML_Element *element, IN const char *item);
126 
127 /********************************************************************************
128  * SampleUtil_PrintEventType
129  *
130  * Description:
131  * Prints a callback event type as a string.
132  *
133  * Parameters:
134  * S -- The callback event
135  *
136  ********************************************************************************/
137 void SampleUtil_PrintEventType(IN Upnp_EventType S);
138 
139 /********************************************************************************
140  * SampleUtil_PrintEvent
141  *
142  * Description:
143  * Prints callback event structure details.
144  *
145  * Parameters:
146  * EventType -- The type of callback event
147  * Event -- The callback event structure
148  *
149  ********************************************************************************/
150 int SampleUtil_PrintEvent(IN Upnp_EventType EventType,
151  IN void *Event);
152 
153 /********************************************************************************
154  * SampleUtil_FindAndParseService
155  *
156  * Description:
157  * This routine finds the first occurance of a service in a DOM representation
158  * of a description document and parses it. Note that this function currently
159  * assumes that the eventURL and controlURL values in the service definitions
160  * are full URLs. Relative URLs are not handled here.
161  *
162  * Parameters:
163  * DescDoc -- The DOM description document
164  * location -- The location of the description document
165  * serviceSearchType -- The type of service to search for
166  * serviceId -- OUT -- The service ID
167  * eventURL -- OUT -- The event URL for the service
168  * controlURL -- OUT -- The control URL for the service
169  *
170  ********************************************************************************/
171 int SampleUtil_FindAndParseService (
172  IN IXML_Document *DescDoc,
173  IN const char* location,
174  IN char *serviceType,
175  OUT char **serviceId,
176  OUT char **eventURL,
177  OUT char **controlURL);
178 
179 
180 /********************************************************************************
181  * print_string
182  *
183  * Description:
184  * Prototype for displaying strings. All printing done by the device,
185  * control point, and sample util, ultimately use this to display strings
186  * to the user.
187  *
188  * Parameters:
189  * const char * string.
190  *
191  ********************************************************************************/
192 typedef void (*print_string)(const char *string);
193 
194 //global print function used by sample util
195 extern print_string gPrintFun;
196 
197 /********************************************************************************
198  * state_update
199  *
200  * Description:
201  * Prototype for passing back state changes
202  *
203  * Parameters:
204  * const char * varName
205  * const char * varValue
206  * const char * UDN
207  * int newDevice
208  ********************************************************************************/
209 typedef void (*state_update)(
210  const char *varName,
211  const char *varValue,
212  const char *UDN,
213  eventType type);
214 
215 //global state update function used by smaple util
216 extern state_update gStateUpdateFun;
217 
218 /********************************************************************************
219  * SampleUtil_Initialize
220  *
221  * Description:
222  * Initializes the sample util. Must be called before any sample util
223  * functions. May be called multiple times.
224  *
225  * Parameters:
226  * print_function - print function to use in SampleUtil_Print
227  *
228  ********************************************************************************/
229 int SampleUtil_Initialize(print_string print_function);
230 
231 /********************************************************************************
232  * SampleUtil_Finish
233  *
234  * Description:
235  * Releases Resources held by sample util.
236  *
237  * Parameters:
238  *
239  ********************************************************************************/
240 int SampleUtil_Finish();
241 
242 /********************************************************************************
243  * SampleUtil_Print
244  *
245  * Description:
246  * Function emulating printf that ultimately calls the registered print
247  * function with the formatted string.
248  *
249  * Parameters:
250  * fmt - format (see printf)
251  * . . . - variable number of args. (see printf)
252  *
253  ********************************************************************************/
254 int SampleUtil_Print(char *fmt, ...);
255 
256 /********************************************************************************
257  * SampleUtil_RegisterUpdateFunction
258  *
259  * Description:
260  *
261  * Parameters:
262  *
263  ********************************************************************************/
264 int SampleUtil_RegisterUpdateFunction(state_update update_function);
265 
266 /********************************************************************************
267  * SampleUtil_StateUpdate
268  *
269  * Description:
270  *
271  * Parameters:
272  *
273  ********************************************************************************/
274 void SampleUtil_StateUpdate(
275  const char *varName,
276  const char *varValue,
277  const char *UDN,
278  eventType type);
279 
280 #ifdef __cplusplus
281 };
282 #endif /* __cplusplus */
283 
284 
285 #ifdef WIN32
286  #define snprintf _snprintf
287  #define strcasecmp stricmp
288 #endif
289 
290 
291 #endif /* SAMPLE_UTIL_H */
292