pupnp (libupnp) snapshot from SourceForge: git clone git://pupnp.git.sourceforge...
[igd2-for-linux:pandonghui1211s-igd2-for-linux.git] / pupnp_branch-1.6.x / upnp / src / inc / service_table.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 SERVICE_TABLE_H
34 #define SERVICE_TABLE_H
35
36
37 /*!
38  * \file
39  */
40
41
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45
46
47 #include "config.h"
48 #include "uri.h"
49 #include "ixml.h"
50 #include "upnp.h"
51 #include "upnpdebug.h"
52
53
54 #include <stdio.h>
55 #include <time.h>
56
57
58 #define SID_SIZE  41
59
60
61 #ifdef INCLUDE_DEVICE_APIS
62
63
64 typedef struct SUBSCRIPTION {
65         Upnp_SID sid;
66         int eventKey;
67         int ToSendEventKey;
68         time_t expireTime;
69         int active;
70         URL_list DeliveryURLs;
71         struct SUBSCRIPTION *next;
72 } subscription;
73
74
75 typedef struct SERVICE_INFO {
76         DOMString       serviceType;
77         DOMString       serviceId;
78         char            *SCPDURL ;
79         char            *controlURL;
80         char            *eventURL;
81         DOMString       UDN;
82         int             active;
83         int             TotalSubscriptions;
84         subscription    *subscriptionList;
85         struct SERVICE_INFO      *next;
86 } service_info;
87
88
89 typedef struct SERVICE_TABLE {
90         DOMString URLBase;
91         service_info *serviceList;
92         service_info *endServiceList;
93 } service_table;
94
95
96 /* Functions for Subscriptions */
97
98
99 /*!
100  * \brief Makes a copy of the subscription.
101  *
102  * \return HTTP_SUCCESS on Sucess.
103  */
104 int copy_subscription(
105         /*! [in] Source subscription. */
106         subscription *in,
107         /*! [in] Destination subscription. */
108         subscription *out);
109
110
111 /*
112  * \brief Remove the subscription represented by the const Upnp_SID sid parameter
113  * from the service table and update the service table.
114  */
115 void RemoveSubscriptionSID(
116         /*! [in] Subscription ID. */
117         Upnp_SID sid,
118         /*! [in] Service object providing the list of subscriptions. */
119         service_info *service);
120
121
122 /*!
123  * \brief Return the subscription from the service table that matches
124  * const Upnp_SID sid value.
125  *
126  * \return Pointer to the matching subscription node.
127  */
128 subscription *GetSubscriptionSID(
129         /*! [in] Subscription ID. */
130         const Upnp_SID sid,
131         /*! [in] Service object providing the list of subscriptions. */
132         service_info *service); 
133   
134
135 /*!
136  * \brief Gets pointer to the first subscription node in the service table.
137  *
138  * \return Pointer to the first subscription node.
139  */
140 subscription *GetFirstSubscription(
141         /*! [in] Service object providing the list of subscriptions. */
142         service_info *service);
143
144
145 /*!
146  * \brief Get current and valid subscription from the service table.
147  *
148  * \return Pointer to the next subscription node.
149  */
150 subscription *GetNextSubscription(
151         /*! [in] Service object providing the list of subscriptions. */
152         service_info *service,
153         /*! [in] Current subscription object. */
154         subscription *current);
155
156
157 /*!
158  * \brief Free's the memory allocated for storing the URL of the subscription.
159  */
160 void freeSubscription(
161         /*! [in] Subscription object to be freed. */
162         subscription *sub);
163
164
165 /*!
166  * \brief Free's memory allocated for all the subscriptions in the service table.
167  */
168 void freeSubscriptionList(
169         /*! [in] Head of the subscription list. */
170         subscription * head);
171
172
173 /*!
174  * \brief Traverses through the service table and returns a pointer to the
175  * service node that matches a known service id and a known UDN.
176  *
177  * \return Pointer to the matching service_info node.
178  */
179 service_info *FindServiceId(
180         /*! [in] Service table. */
181         service_table *table, 
182         /*! [in] String representing the service id to be found among those
183          * in the table. */
184         const char *serviceId,
185         /*! [in] String representing the UDN to be found among those in the
186          * table. */
187         const char *UDN);
188
189
190 /*!
191  * \brief Traverses the service table and finds the node whose event URL Path
192  * matches a know value.
193  *
194  * \return Pointer to the service list node from the service table whose event
195  * URL matches a known event URL.
196  */
197 service_info *FindServiceEventURLPath(
198         /*! [in] Service table. */
199         service_table *table,
200         /*! [in] Event URL path used to find a service from the table. */
201         char *eventURLPath);
202
203
204 /*!
205  * \brief Traverses the service table and finds the node whose control URL Path
206  * matches a know value.
207  *
208  * \return Pointer to the service list node from the service table whose control
209  * URL Path matches a known value.
210  */
211 service_info * FindServiceControlURLPath(
212         /*! [in] Service table. */
213         service_table *table,
214         /*! [in] Control URL path used to find a service from the table. */
215         const char *controlURLPath);
216
217
218 /*!
219  * \brief For debugging purposes prints information from the service passed
220  * into the function.
221  */
222 #ifdef DEBUG
223 void printService(
224         /*! [in] Service whose information is to be printed. */
225         service_info *service,
226         /*! [in] Debug level specified to the print function. */
227         Upnp_LogLevel level,
228         /*! [in] Debug module specified to the print function. */
229         Dbg_Module module);
230 #else
231 static UPNP_INLINE void printService(
232         service_info *service,
233         Upnp_LogLevel level,
234         Dbg_Module module) {}
235 #endif
236
237
238 /*!
239  * \brief For debugging purposes prints information of each service from the
240  * service table passed into the function.
241  */
242 #ifdef DEBUG
243 void printServiceList(
244         /*! [in] Service whose information is to be printed. */
245         service_info *service,
246         /*! [in] Debug level specified to the print function. */
247         Upnp_LogLevel level,
248         /*! [in] Debug module specified to the print function. */
249         Dbg_Module module);
250 #else
251 static UPNP_INLINE void printServiceList(
252         service_info *service,
253         Upnp_LogLevel level,
254         Dbg_Module module) {}
255 #endif
256
257
258 /*!
259  * \brief For debugging purposes prints the URL base of the table and information
260  * of each service from the service table passed into the function.
261  */
262 #ifdef DEBUG
263 void printServiceTable(
264         /*! [in] Service table to be printed. */
265         service_table *table,
266         /*! [in] Debug level specified to the print function. */
267         Upnp_LogLevel level,
268         /*! [in] Debug module specified to the print function. */
269         Dbg_Module module);
270 #else
271 static UPNP_INLINE void printServiceTable(
272         service_table *table,
273         Upnp_LogLevel level,
274         Dbg_Module module) {}
275 #endif
276
277
278 /*!
279  * \brief Free's memory allocated for the various components of the service
280  * entry in the service table.
281  */
282 void freeService(
283         /*! [in] Service information that is to be freed. */
284         service_info *in);
285
286
287 /*!
288  * \brief Free's memory allocated for the various components of each service
289  * entry in the service table.
290  */
291 void freeServiceList(
292         /*! [in] Head of the service list to be freed. */
293         service_info *head);
294
295
296 /*!
297  * \brief Free's dynamic memory in table (does not free table, only memory
298  * within the structure).
299  */
300 void freeServiceTable(
301         /*! [in] Service table whose internal memory needs to be freed. */
302         service_table *table);
303
304
305 /*!
306  * \brief This function assumes that services for a particular root device are
307  * placed linearly in the service table, and in the order in which they are
308  * found in the description document all services for this root device are
309  * removed from the list.
310  *
311  * \return An integer.
312  */
313 int removeServiceTable(
314         /*! [in] XML node information. */
315         IXML_Node *node,
316         /*! [in] Service table from which services will be removed. */
317         service_table *in);
318
319
320 /*!
321  * \brief Add Service to the table.
322  */
323 int addServiceTable(
324         /*! [in] XML node information. */
325         IXML_Node *node,
326         /*! [in] Service table that will be initialized with services. */
327         service_table *in,
328         /*! [in] Default base URL on which the URL will be returned to the
329          * service list. */
330         const char *DefaultURLBase);
331
332
333 /*!
334  * \brief Retrieve service from the table.
335  *
336  * \return An integer
337  */
338 int getServiceTable(
339         /*! [in] XML node information. */
340         IXML_Node *node,
341         /*! [in] Output parameter which will contain the service list and URL. */
342         service_table *out,
343         /*! [in] Default base URL on which the URL will be returned. */
344         const char *DefaultURLBase);
345
346
347 /*      Misc helper functions   */
348
349
350 /*!
351  * \brief Returns the clone of the element value.
352  *
353  * \note Value must be freed with DOMString_free.
354  *
355  * \return DOMString
356  */
357 DOMString getElementValue(
358         /*! [in] Input node which provides the list of child nodes. */
359         IXML_Node *node);
360
361
362 /*!
363  * \brief Traverses through a list of XML nodes to find the node with the
364  * known element name.
365  *
366  * \return
367  *      \li 1 - On Success
368  *      \li 0 - On Failure
369  */
370 int getSubElement(
371         /*! [in] Sub element name to be searched for. */
372         const char *element_name,
373         /*! [in] Input node which provides the list of child nodes. */
374         IXML_Node *node, 
375         /*! [out] Ouput node to which the matched child node is returned. */
376         IXML_Node **out);
377
378
379 #endif /* INCLUDE_DEVICE_APIS */
380
381 #ifdef __cplusplus
382 }
383 #endif
384
385 #endif /* SERVICE_TABLE */
386