libUPnP  1.8.0
httpreadwrite.h
1 //
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 //
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 
Represents a URI used in parse_uri and elsewhere.
Definition: uri.h:148
Definition: sock.h:55
Definition: httpparser.h:206
Definition: membuffer.h:52