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 / gena.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 GENA_H
34 #define GENA_H
35
36
37 /*!
38  * \file
39  */
40
41
42 #include "config.h"
43
44
45 #include <string.h>
46 #include <time.h>
47
48
49 #include "client_table.h"
50 #include "httpparser.h"
51 #include "miniserver.h"
52 #include "service_table.h"
53 #include "sock.h"
54 #include "ThreadPool.h"
55 #include "upnp.h"
56 #include "uri.h"
57
58
59 #ifdef __cplusplus
60         #define EXTERN_C extern "C"
61 #else /* __cplusplus */
62         #ifndef EXTERN_C
63                 #define EXTERN_C 
64         #endif /* EXTERN_C */
65 #endif /* __cplusplus */
66
67
68 /*!
69  * \brief XML version comment. Not used because it is not interopeable with
70  * other UPnP vendors.
71  */
72 #define XML_VERSION "<?xml version='1.0' encoding='ISO-8859-1' ?>\n"
73 #define XML_PROPERTYSET_HEADER \
74         "<e:propertyset xmlns:e=\"urn:schemas-upnp-org:event-1-0\">\n"
75
76
77 #define UNABLE_MEMORY "HTTP/1.1 500 Internal Server Error\r\n\r\n"
78 #define UNABLE_SERVICE_UNKNOWN "HTTP/1.1 404 Not Found\r\n\r\n"
79 #define UNABLE_SERVICE_NOT_ACCEPT "HTTP/1.1 503 Service Not Available\r\n\r\n"
80
81
82 #define NOT_IMPLEMENTED "HTTP/1.1 501 Not Implemented\r\n\r\n"
83 #define BAD_REQUEST "HTTP/1.1 400 Bad Request\r\n\r\n"
84 #define INVALID_NT BAD_CALLBACK
85 #define BAD_CALLBACK "HTTP/1.1 412 Precondition Failed\r\n\r\n" 
86 #define HTTP_OK_CRLF "HTTP/1.1 200 OK\r\n\r\n"
87 #define HTTP_OK_STR "HTTP/1.1 200 OK\r\n"
88 #define INVALID_SID BAD_CALLBACK
89 #define MISSING_SID BAD_CALLBACK
90 #define MAX_CONTENT_LENGTH 20
91 #define MAX_SECONDS 10
92 #define MAX_EVENTS 20
93 #define MAX_PORT_SIZE 10
94
95
96 #define GENA_E_BAD_RESPONSE UPNP_E_BAD_RESPONSE
97 #define GENA_E_BAD_SERVICE UPNP_E_INVALID_SERVICE
98 #define GENA_E_SUBSCRIPTION_UNACCEPTED UPNP_E_SUBSCRIBE_UNACCEPTED
99 #define GENA_E_BAD_SID UPNP_E_INVALID_SID
100 #define GENA_E_UNSUBSCRIBE_UNACCEPTED UPNP_E_UNSUBSCRIBE_UNACCEPTED
101 #define GENA_E_NOTIFY_UNACCEPTED UPNP_E_NOTIFY_UNACCEPTED
102 #define GENA_E_NOTIFY_UNACCEPTED_REMOVE_SUB -9
103 #define GENA_E_BAD_HANDLE UPNP_E_INVALID_HANDLE
104
105
106 #define XML_ERROR -5
107 #define XML_SUCCESS UPNP_E_SUCCESS
108 #define GENA_SUCCESS UPNP_E_SUCCESS
109
110
111 #define CALLBACK_SUCCESS 0
112 #define DEFAULT_TIMEOUT 1801
113
114
115 extern ithread_mutex_t GlobalClientSubscribeMutex;
116
117
118 /*!
119  * \brief Locks the subscription.
120  */
121 #define SubscribeLock() \
122         UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
123                 "Trying Subscribe Lock");  \
124         ithread_mutex_lock(&GlobalClientSubscribeMutex); \
125         UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
126                 "Subscribe Lock");
127
128
129 /*!
130  * \brief Unlocks the subscription.
131  */
132 #define SubscribeUnlock() \
133         UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
134                 "Trying Subscribe UnLock"); \
135         ithread_mutex_unlock(&GlobalClientSubscribeMutex); \
136         UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
137                 "Subscribe UnLock");
138
139
140 /*!
141  * Structure to send NOTIFY message to all subscribed control points
142  */
143 typedef struct NOTIFY_THREAD_STRUCT {
144         char *headers;
145         DOMString propertySet;
146         char *servId;
147         char *UDN;
148         Upnp_SID sid;
149         int eventKey;
150         int *reference_count;
151         UpnpDevice_Handle device_handle;
152 } notify_thread_struct;
153
154
155 /*!
156  * \brief This is the callback function called by the miniserver to handle
157  *      incoming GENA requests.
158  *
159  * \return UPNP_E_SUCCESS if successful, otherwise appropriate error code.
160  */
161 EXTERN_C void genaCallback(
162         /*! [in] represents the parse state of the request */
163         http_parser_t *parser, 
164         /*! [in] HTTP message containing GENA request */
165         http_message_t* request,
166         /*! [in,out] Structure containing information about the socket */
167         SOCKINFO *info);
168
169  
170 /*!
171  * \brief This function subscribes to a PublisherURL (also mentioned as EventURL
172  * in some places).
173  *
174  * It sends SUBSCRIBE http request to service processes request. Finally adds a
175  * Subscription to the clients subscription list, if service responds with OK.
176  *
177  * \return UPNP_E_SUCCESS if service response is OK, otherwise returns the 
178  *      appropriate error code
179  */
180 #ifdef INCLUDE_CLIENT_APIS
181 EXTERN_C int genaSubscribe(
182         /*! [in] The client handle. */
183         UpnpClient_Handle client_handle,
184         /*! [in] Of the form: "http://134.134.156.80:4000/RedBulb/Event */
185         const char *PublisherURL,
186         /*! [in,out] requested Duration:
187          * \li if -1, then "infinite".
188          * \li in the OUT case: actual Duration granted by Service,
189          *      -1 for infinite. */
190         int *TimeOut,
191         /*! [out] sid of subscription, memory passed in by caller. */
192         Upnp_SID out_sid);
193 #endif /* INCLUDE_CLIENT_APIS */
194
195
196 /*!
197  * \brief Unsubscribes a SID.
198  *
199  * It first validates the SID and client_handle,copies the subscription, sends
200  * UNSUBSCRIBE http request to service processes request and finally removes
201  * the subscription.
202  *
203  * \return UPNP_E_SUCCESS if service response is OK, otherwise returns the
204  *      appropriate error code.
205  */
206 #ifdef INCLUDE_CLIENT_APIS
207 EXTERN_C int genaUnSubscribe(
208         /*! [in] UPnP client handle. */
209         UpnpClient_Handle client_handle,
210         /*! [in] The subscription ID. */
211         const Upnp_SID in_sid);
212 #endif /* INCLUDE_CLIENT_APIS */
213
214
215 /*!
216  * \brief Unsubcribes all the outstanding subscriptions and cleans the
217  *      subscription list.
218  *
219  * This function is called when control point unregisters.
220  *
221  * \returns UPNP_E_SUCCESS if successful, otherwise returns the appropriate
222  *      error code.
223  */
224 #ifdef INCLUDE_CLIENT_APIS
225 EXTERN_C int genaUnregisterClient(
226         /*! [in] Handle containing all the control point related information. */
227         UpnpClient_Handle client_handle);
228 #endif /* INCLUDE_CLIENT_APIS */
229
230
231 /*
232  * DEVICE
233  */
234
235
236 /*!
237  * \brief Cleans the service table of the device.
238  *
239  * \return UPNP_E_SUCCESS if successful, otherwise returns GENA_E_BAD_HANDLE
240  */
241 #ifdef INCLUDE_DEVICE_APIS
242 EXTERN_C int genaUnregisterDevice(
243         /*! [in] Handle of the root device */
244         UpnpDevice_Handle device_handle);
245 #endif /* INCLUDE_CLIENT_APIS */
246
247
248 /*!
249  * \brief Renews a SID.
250  *
251  * It first validates the SID and client_handle and copies the subscription.
252  * It sends RENEW (modified SUBSCRIBE) http request to service and processes
253  * the response.
254  *
255  * \return UPNP_E_SUCCESS if service response is OK, otherwise the
256  *      appropriate error code.
257  */
258 #ifdef INCLUDE_CLIENT_APIS
259 EXTERN_C int genaRenewSubscription(
260         /*! [in] Client handle. */
261         UpnpClient_Handle client_handle,
262         /*! [in] Subscription ID. */
263         const Upnp_SID in_sid,
264         /*! [in,out] requested Duration, if -1, then "infinite". In the OUT case:
265          * actual Duration granted by Service, -1 for infinite. */
266         int *TimeOut);
267 #endif /* INCLUDE_CLIENT_APIS */
268
269
270 /*!
271  * \brief Sends a notification to all the subscribed control points.
272  *
273  * \return int
274  *
275  * \note This function is similar to the genaNotifyAllExt. The only difference
276  *      is it takes event variable array instead of xml document.
277  */
278 #ifdef INCLUDE_DEVICE_APIS
279 EXTERN_C int genaNotifyAll(
280         /*! [in] Device handle. */
281         UpnpDevice_Handle device_handle,
282         /*! [in] Device udn. */
283         char *UDN,
284         /*! [in] Service ID. */
285         char *servId,
286         /*! [in] Array of varible names. */
287         char **VarNames,
288         /*! [in] Array of variable values. */
289         char **VarValues,
290         /*! [in] Number of variables. */
291         int var_count);
292 #endif /* INCLUDE_DEVICE_APIS */
293
294
295 /*!
296  * \brief Sends a notification to all the subscribed control points.
297  *
298  * \return int
299  *
300  * \note This function is similar to the genaNotifyAll. the only difference
301  *      is it takes the document instead of event variable array.
302  */
303 #ifdef INCLUDE_DEVICE_APIS
304 EXTERN_C int genaNotifyAllExt(
305         /*! [in] Device handle. */
306         UpnpDevice_Handle device_handle, 
307         /*! [in] Device udn. */
308         char *UDN,
309         /*! [in] Service ID. */
310         char *servId,
311         /*! [in] XML document Event varible property set. */
312         IXML_Document *PropSet);
313 #endif /* INCLUDE_DEVICE_APIS */
314
315
316 /*!
317  * \brief Sends the intial state table dump to newly subscribed control point.
318  *
319  * \return GENA_E_SUCCESS if successful, otherwise the appropriate error code.
320  * 
321  * \note  No other event will be sent to this control point before the 
322  *      intial state table dump.
323  */
324 #ifdef INCLUDE_DEVICE_APIS
325 EXTERN_C int genaInitNotify(
326         /*! [in] Device handle. */
327         UpnpDevice_Handle device_handle,
328         /*! [in] Device udn. */
329         char *UDN,
330         /*! [in] Service ID. */
331         char *servId,
332         /*! [in] Array of variable names. */
333         char **VarNames,
334         /*! [in] Array of variable values. */
335         char **VarValues,
336         /*! [in] Array size. */
337         int var_count,
338         /*! [in] Subscription ID. */
339         const Upnp_SID sid);
340 #endif /* INCLUDE_DEVICE_APIS */
341
342
343 /*!
344  * \brief Similar to the genaInitNofity. The only difference is that it
345  * takes the xml document for the state table and sends the intial state
346  * table dump to newly subscribed control point.
347  *
348  * \return GENA_E_SUCCESS if successful, otherwise the appropriate error code.
349  * 
350  * \note No other event will be sent to this control point before the 
351  *      intial state table dump.
352  */
353 #ifdef INCLUDE_DEVICE_APIS
354 EXTERN_C  int genaInitNotifyExt(
355         /*! [in] Device handle. */
356         UpnpDevice_Handle device_handle, 
357         /*! [in] Device udn. */
358         char *UDN, 
359         /*! [in] Service ID. */
360         char *servId,
361         /*! [in] Document of the state table. */
362         IXML_Document *PropSet, 
363         /*! [in] subscription ID. */
364         const Upnp_SID sid);
365 #endif /* INCLUDE_DEVICE_APIS */
366
367
368 /*!
369  * \brief Sends an error message to the control point in the case of incorrect
370  *      GENA requests.
371  *
372  * \return UPNP_E_SUCCESS if successful, otherwise appropriate error code.
373  */
374 void error_respond(
375         /*! [in] Structure containing information about the socket. */
376         SOCKINFO *info,
377         /*! [in] error code that will be in the GENA response. */
378         int error_code,
379         /*! [in] GENA request Packet. */
380         http_message_t* hmsg);
381
382
383 #endif /* GENA_H */
384