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 / httpreadwrite.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 #ifndef GENLIB_NET_HTTP_HTTPREADWRITE_H
33 #define GENLIB_NET_HTTP_HTTPREADWRITE_H
34
35 #include "config.h"
36 #include "util.h"
37 #include "sock.h"
38 #include "httpparser.h"
39
40 // timeout in secs
41 #define HTTP_DEFAULT_TIMEOUT    30
42
43
44
45 #ifdef __cplusplus
46 #extern "C" {
47 #endif
48
49 int
50 http_CancelHttpGet( IN void *Handle );
51
52 /************************************************************************
53  * Function: http_FixUrl
54  *
55  * Parameters:
56  *      IN uri_type* url;               URL to be validated and fixed
57  *      OUT uri_type* fixed_url;        URL after being fixed.
58  *
59  * Description:
60  *      Validates URL
61  *
62  * Returns:
63  *       UPNP_E_INVALID_URL
64  *       UPNP_E_SUCCESS
65  ************************************************************************/
66 int http_FixUrl( IN uri_type* url, OUT uri_type* fixed_url );
67
68
69 /************************************************************************
70  * Function: http_FixStrUrl
71  *
72  * Parameters:
73  *      IN char* urlstr ;               Character string as a URL
74  *      IN int urlstrlen ;              Length of the character string
75  *      OUT uri_type* fixed_url ;       Fixed and corrected URL
76  *
77  * Description:
78  *      Parses URL and then validates URL
79  *
80  * Returns:
81  *       UPNP_E_INVALID_URL
82  *       UPNP_E_SUCCESS
83  ************************************************************************/
84 int http_FixStrUrl( IN const char* urlstr, IN int urlstrlen, OUT uri_type* fixed_url );
85
86
87 /************************************************************************
88  * Function: http_Connect
89  *
90  * Parameters:
91  *      IN uri_type* destination_url;   URL containing destination information
92  *      OUT uri_type *url;              Fixed and corrected URL
93  *
94  * Description:
95  *      Gets destination address from URL and then connects to the remote end
96  *
97  *  Returns:
98  *      socket descriptor on sucess
99  *      UPNP_E_OUTOF_SOCKET
100  *      UPNP_E_SOCKET_CONNECT on error
101  ************************************************************************/
102 int http_Connect( IN uri_type* destination_url, OUT uri_type *url );
103
104
105 /************************************************************************
106  * Function: http_RecvMessage
107  *
108  * Parameters:
109  *      IN SOCKINFO *info;                      Socket information object
110  *      OUT http_parser_t* parser;              HTTP parser object
111  *      IN http_method_t request_method;        HTTP request method
112  *      IN OUT int* timeout_secs;               time out
113  *      OUT int* http_error_code;               HTTP error code returned
114  *
115  * Description:
116  *      Get the data on the socket and take actions based on the read data
117  *      to modify the parser objects buffer. If an error is reported while
118  *      parsing the data, the error code is passed in the http_errr_code
119  *      parameter
120  *
121  * Returns:
122  *       UPNP_E_BAD_HTTPMSG
123  *       UPNP_E_SUCCESS
124  ************************************************************************/
125 int http_RecvMessage( IN SOCKINFO *info, OUT http_parser_t* parser,
126                 IN http_method_t request_method, 
127                 IN OUT int* timeout_secs,
128                 OUT int* http_error_code );
129
130
131 /************************************************************************
132  * Function: http_SendMessage
133  *
134  * Parameters:
135  *      IN SOCKINFO *info ;             Socket information object
136  *      IN OUT int * TimeOut ;          time out value
137  *      IN const char* fmt, ...  Pattern format to take actions upon
138  *
139  * Description:
140  *      Sends a message to the destination based on the
141  *      IN const char* fmt parameter
142  *      fmt types:
143  *              'f':    arg = const char * file name
144  *              'm':    arg1 = const char * mem_buffer; arg2= size_t buf_length
145  *      E.g.:
146  *              char *buf = "POST /xyz.cgi http/1.1\r\n\r\n";
147  *              char *filename = "foo.dat";
148  *              int status = http_SendMessage( tcpsock, "mf",
149  *                      buf, strlen(buf),       // args for memory buffer
150  *                      filename );             // arg for file
151  *
152  * Returns:
153  *      UPNP_E_OUTOF_MEMORY
154  *      UPNP_E_FILE_READ_ERROR
155  *      UPNP_E_SUCCESS
156  ************************************************************************/
157 int http_SendMessage(
158         IN SOCKINFO *info,
159         IN OUT int* timeout_secs, 
160         IN const char* fmt, ... );
161
162
163 /************************************************************************
164  * Function: http_RequestAndResponse
165  *
166  * Parameters:
167  *      IN uri_type* destination;       Destination URI object which contains
168  *                                      remote IP address among other elements
169  *      IN const char* request;         Request to be sent
170  *      IN size_t request_length;       Length of the request
171  *      IN http_method_t req_method;    HTTP Request method
172  *      IN int timeout_secs;            time out value
173  *      OUT http_parser_t* response;    Parser object to receive the repsonse
174  *
175  * Description:
176  *      Initiates socket, connects to the destination, sends a
177  *      request and waits for the response from the remote end
178  *
179  * Returns:
180  *      UPNP_E_SOCKET_ERROR
181  *      UPNP_E_SOCKET_CONNECT
182  *      Error Codes returned by http_SendMessage
183  *      Error Codes returned by http_RecvMessage
184  ************************************************************************/
185 int http_RequestAndResponse(
186         IN uri_type* destination,
187         IN const char* request,
188         IN size_t request_length,
189         IN http_method_t req_method,
190         IN int timeout_secs, 
191         OUT http_parser_t* response );
192
193
194 /************************************************************************
195  * return codes:
196  *      0 -- success
197  *      UPNP_E_OUTOF_MEMORY
198  *      UPNP_E_TIMEDOUT
199  *      UPNP_E_BAD_REQUEST
200  *      UPNP_E_BAD_RESPONSE
201  *      UPNP_E_INVALID_URL
202  *      UPNP_E_SOCKET_READ
203  *      UPNP_E_SOCKET_WRITE
204  ************************************************************************/
205
206
207 /************************************************************************
208  * Function: http_Download
209  *
210  * Parameters:
211  *      IN const char* url_str; String as a URL
212  *      IN int timeout_secs;    time out value
213  *      OUT char** document;    buffer to store the document extracted
214  *                              from the donloaded message.
215  *      OUT int* doc_length;    length of the extracted document
216  *      OUT char* content_type; Type of content
217  *
218  * Description:
219  *      Download the document message and extract the document 
220  *      from the message.
221  *
222  * Return: int
223  *      UPNP_E_SUCCESS
224  *      UPNP_E_INVALID_URL
225  ************************************************************************/
226 int http_Download(
227         IN const char* url, 
228         IN int timeout_secs,
229         OUT char** document,
230         OUT int* doc_length,
231         OUT char* content_type );
232
233
234 /************************************************************************
235  * Function: http_WriteHttpPost
236  *
237  * Parameters:
238  *      IN void *Handle:        Handle to the http post object
239  *      IN char *buf:           Buffer to send to peer, if format used
240  *                              is not UPNP_USING_CHUNKED, 
241  *      IN unsigned int *size:  Size of the data to be sent.
242  *      IN int timeout:         time out value
243  *
244  * Description:
245  *      Formats data if format used is UPNP_USING_CHUNKED.
246  *      Writes data on the socket connected to the peer.
247  *
248  * Return: int
249  *      UPNP_E_SUCCESS - On Success
250  *      UPNP_E_INVALID_PARAM - Invalid Parameter
251  *      -1 - On Socket Error.
252  ************************************************************************/
253 int http_WriteHttpPost(IN void *Handle,
254                        IN char *buf,
255                        IN unsigned int *size,
256                        IN int timeout);
257
258
259 /************************************************************************
260  * Function: http_CloseHttpPost
261  *
262  * Parameters:
263  *      IN void *Handle;        Handle to the http post object
264  *      IN OUT int *httpStatus; HTTP status returned on receiving a
265  *                              response message
266  *      IN int timeout;         time out value
267  *
268  * Description:
269  *      Sends remaining data if using  UPNP_USING_CHUNKED 
270  *      format. Receives any more messages. Destroys socket and any socket
271  *      associated memory. Frees handle associated with the HTTP POST msg.
272  *
273  * Return: int
274  *      UPNP_E_SUCCESS          - On Sucess
275  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
276  ************************************************************************/
277 int http_CloseHttpPost(IN void *Handle, 
278                        IN OUT int *httpStatus,
279                        IN int timeout);
280
281
282 /************************************************************************
283  * Function: http_OpenHttpPost
284  *
285  * Parameters:
286  *      IN const char *url_str;         String as a URL 
287  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
288  *                                      post handle
289  *      IN const char *contentType;     Type of content
290  *      IN int contentLength;           length of content
291  *      IN int timeout;                 time out value
292  *
293  * Description:
294  *      Makes the HTTP POST message, connects to the peer, 
295  *      sends the HTTP POST request. Adds the post handle to buffer of 
296  *      such handles
297  *
298  * Return : int;
299  *      UPNP_E_SUCCESS          - On Sucess
300  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
301  *      UPNP_E_OUTOF_MEMORY
302  *      UPNP_E_SOCKET_ERROR
303  *      UPNP_E_SOCKET_CONNECT
304  ************************************************************************/
305 int http_OpenHttpPost(IN const char *url_str,
306                       IN OUT void **Handle,
307                       IN const char *contentType,
308                       IN int contentLength,
309                       IN int timeout);
310
311
312 /************************************************************************
313  * Function: http_ReadHttpGet
314  *
315  * Parameters:
316  *      IN void *Handle;                Handle to the HTTP get object
317  *      IN OUT char *buf;               Buffer to get the read and parsed data
318  *      IN OUT unsigned int *size;      Size of the buffer passed
319  *      IN int timeout;                 time out value
320  *
321  * Description:
322  *      Parses already existing data, then gets new data.
323  *      Parses and extracts information from the new data.
324  *
325  * Return: int
326  *      UPNP_E_SUCCESS          - On Sucess
327  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
328  *      UPNP_E_BAD_RESPONSE
329  *      UPNP_E_BAD_HTTPMSG
330  *      UPNP_E_CANCELED
331  ************************************************************************/
332 int http_ReadHttpGet(
333         IN void *Handle,
334         IN OUT char *buf,
335         IN OUT unsigned int *size,
336         IN int timeout);
337
338
339 /************************************************************************
340  * Function: http_HttpGetProgress
341  *
342  * Parameters:
343  *      IN void *Handle;                Handle to the HTTP get object
344  *      OUT unsigned int *length;       Buffer to get the read and parsed data
345  *      OUT unsigned int *total;        Size of tge buffer passed
346  *
347  * Description:
348  *      Extracts information from the Handle to the HTTP get object.
349  *
350  * Return: int
351  *      UPNP_E_SUCCESS          - On Sucess
352  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
353  ************************************************************************/
354 int http_HttpGetProgress(
355         IN void *Handle,
356         OUT unsigned int *length,
357         OUT unsigned int *total );
358
359
360 /************************************************************************
361  * Function: http_CloseHttpGet
362  *
363  * Parameters:
364  *      IN void *Handle;        Handle to HTTP get object
365  *
366  * Description:
367  *      Clears the handle allocated for the HTTP GET operation
368  *      Clears socket states and memory allocated for socket operations. 
369  *
370  * Return: int
371  *      UPNP_E_SUCCESS          - On Success
372  *      UPNP_E_INVALID_PARAM    - Invalid Parameter
373  ************************************************************************/
374 int http_CloseHttpGet(IN void *Handle);
375
376
377 /************************************************************************
378  * Function: http_OpenHttpGet
379  *
380  * Parameters:
381  *      IN const char *url_str:         String as a URL
382  *      IN OUT void **Handle:           Pointer to buffer to store HTTP
383  *                                      post handle
384  *      IN OUT char **contentType:      Type of content
385  *      OUT int *contentLength:         length of content
386  *      OUT int *httpStatus:            HTTP status returned on receiving a
387  *                                      response message
388  *      IN int timeout:                 time out value
389  *
390  * Description:
391  *      Makes the HTTP GET message, connects to the peer, 
392  *      sends the HTTP GET request, gets the response and parses the 
393  *      response.
394  *
395  * Return: int
396  *      UPNP_E_SUCCESS          - On Success
397  *      UPNP_E_INVALID_PARAM    - Invalid Paramters
398  *      UPNP_E_OUTOF_MEMORY
399  *      UPNP_E_SOCKET_ERROR
400  *      UPNP_E_BAD_RESPONSE
401  ************************************************************************/
402 int http_OpenHttpGet(
403         IN const char *url_str,
404         IN OUT void **Handle,
405         IN OUT char **contentType,
406         OUT int *contentLength,
407         OUT int *httpStatus,
408         IN int timeout);
409
410
411 /************************************************************************
412  * Function: http_OpenHttpGetProxy
413  *
414  * Parameters:
415  *      IN const char *url_str;         String as a URL
416  *      IN const char *proxy_str;       String as a URL
417  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
418  *                                      post handle
419  *      IN OUT char **contentType;      Type of content
420  *      OUT int *contentLength;         length of content
421  *      OUT int *httpStatus;            HTTP status returned on receiving a
422  *                                      response message
423  *      IN int timeout:                 time out value
424  *
425  * Description:
426  *      Makes the HTTP GET message, connects to the peer, 
427  *      sends the HTTP GET request, gets the response and parses the response.
428  *      If a proxy URL is defined then the connection is made there.
429  *
430  * Return: int
431  *      UPNP_E_SUCCESS          - On Success
432  *      UPNP_E_INVALID_PARAM    - Invalid Paramters
433  *      UPNP_E_OUTOF_MEMORY
434  *      UPNP_E_SOCKET_ERROR
435  *      UPNP_E_BAD_RESPONSE
436  ************************************************************************/
437 int http_OpenHttpGetProxy(IN const char *url_str,
438                                         IN const char *proxy_str,
439                                         IN OUT void **Handle,
440                                         IN OUT char **contentType,
441                                         OUT int *contentLength,
442                                         OUT int *httpStatus,
443                                         IN int timeout);
444
445
446 /************************************************************************
447  * Function: http_SendStatusResponse
448  *
449  * Parameters:
450  *      IN SOCKINFO *info;              Socket information object
451  *      IN int http_status_code;        error code returned while making 
452  *                                      or sending the response message
453  *      IN int request_major_version;   request major version
454  *      IN int request_minor_version;   request minor version
455  *
456  * Description:
457  *      Generate a response message for the status query and send the
458  *      status response.
459  *
460  * Return: int
461  *      0 -- success
462  *      UPNP_E_OUTOF_MEMORY
463  *      UPNP_E_SOCKET_WRITE
464  *      UPNP_E_TIMEDOUT
465  ************************************************************************/
466 int http_SendStatusResponse(
467         IN SOCKINFO *info,
468         IN int http_status_code,
469         IN int request_major_version,
470         IN int request_minor_version );
471
472
473 /************************************************************************
474  * Function: http_MakeMessage
475  *
476  * Parameters:
477  *      INOUT membuffer* buf;           buffer with the contents of the 
478  *                                      message
479  *      IN int http_major_version;      HTTP major version
480  *      IN int http_minor_version;      HTTP minor version
481  *      IN const char* fmt;             Pattern format 
482  *      ...;    
483  *
484  * Description:
485  *      Generate an HTTP message based on the format that is specified
486  *      in the input parameters.
487  *
488  * fmt types:
489  *      'B':    arg = int status_code 
490  *              appends content-length, content-type and HTML body
491  *              for given code
492  *      'b':    arg1 = const char* buf;
493  *              arg2 = size_t buf_length memory ptr
494  *      'C':    (no args) appends a HTTP CONNECTION: close header 
495  *                      depending on major,minor version
496  *      'c':    (no args) appends CRLF "\r\n"
497  *      'D':    (no args) appends HTTP DATE: header
498  *      'd':    arg = int number            // appends decimal number
499  *      'G':    arg = range information     // add range header
500  *      'h':    arg = off_t number          // appends off_t number
501  *      'K':    (no args)                   // add chunky header
502  *      'N':    arg1 = off_t content_length // content-length header
503  *      'q':    arg1 = http_method_t        // request start line and HOST header
504  *              arg2 = (uri_type *)
505  *      'Q':    arg1 = http_method_t;       // start line of request
506  *              arg2 = char* url; 
507  *              arg3 = size_t url_length 
508  *      'R':    arg = int status_code       // adds a response start line
509  *      'S':    (no args) appends HTTP SERVER: header
510  *      's':    arg = const char* C_string
511  *      'T':    arg = char * content_type; format
512  *              e.g: "text/html"; content-type header
513  *      't':    arg = time_t * gmt_time     // appends time in RFC 1123 fmt
514  *      'U':    (no args) appends HTTP USER-AGENT: header
515  *      'X':    arg = const char useragent; "redsonic" HTTP X-User-Agent: useragent
516  *
517  * Return: int
518  *      0 - On Success
519  *      UPNP_E_OUTOF_MEMORY
520  *      UPNP_E_INVALID_URL
521  ************************************************************************/
522 int http_MakeMessage(
523         INOUT membuffer* buf, 
524         IN int http_major_version,
525         IN int http_minor_version,
526         IN const char* fmt, ... );
527
528
529 /************************************************************************
530  * Function: http_CalcResponseVersion
531  *
532  * Parameters:
533  *      IN int request_major_vers;      Request major version
534  *      IN int request_minor_vers;      Request minor version
535  *      OUT int* response_major_vers;   Response mojor version
536  *      OUT int* response_minor_vers;   Response minor version
537  *
538  * Description:
539  *      Calculate HTTP response versions based on the request versions.
540  *
541  * Return: void
542  ************************************************************************/
543 void http_CalcResponseVersion( 
544         IN int request_major_vers,
545         IN int request_minor_vers,
546         OUT int* response_major_vers,
547         OUT int* response_minor_vers );
548
549
550 /************************************************************************
551  * Function: http_OpenHttpGetEx
552  *
553  * Parameters:
554  *      IN const char *url_str;         String as a URL
555  *      IN OUT void **Handle;           Pointer to buffer to store HTTP
556  *                                      post handle
557  *      IN OUT char **contentType;      Type of content
558  *      OUT int *contentLength;         length of content
559  *      OUT int *httpStatus;            HTTP status returned on receiving a
560  *                                      response message
561  *      IN int timeout;                 time out value
562  *
563  * Description:
564  *      Makes the HTTP GET message, connects to the peer, 
565  *      sends the HTTP GET request, gets the response and parses the 
566  *      response.
567  *
568  * Return: int
569  *      UPNP_E_SUCCESS          - On Success
570  *      UPNP_E_INVALID_PARAM    - Invalid Paramters
571  *      UPNP_E_OUTOF_MEMORY
572  *      UPNP_E_SOCKET_ERROR
573  *      UPNP_E_BAD_RESPONSE
574  ************************************************************************/
575 int http_OpenHttpGetEx(IN const char *url_str,
576                      IN OUT void **Handle,
577                      IN OUT char **contentType,
578                      OUT int *contentLength,
579                      OUT int *httpStatus,
580                          IN int lowRange,
581                          IN int highRange,
582                      IN int timeout);
583
584
585 /************************************************************************
586  * Function: get_sdk_info
587  *
588  * Parameters:
589  *      OUT char *info; buffer to store the operating system information
590  *
591  * Description:
592  *      Returns the server information for the operating system
593  *
594  * Return:
595  *      UPNP_INLINE void
596  ************************************************************************/
597 void get_sdk_info( OUT char *info );
598
599 #ifdef __cplusplus
600 }       // #extern "C"
601 #endif
602
603
604 #endif // GENLIB_NET_HTTP_HTTPREADWRITE_H
605