Annotation of embedaddon/libpdel/http/http_request.3, revision 1.1.1.1
1.1 misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
2: .\" All rights reserved.
3: .\"
4: .\" Subject to the following obligations and disclaimer of warranty,
5: .\" use and redistribution of this software, in source or object code
6: .\" forms, with or without modifications are expressly permitted by
7: .\" Packet Design; provided, however, that:
8: .\"
9: .\" (i) Any and all reproductions of the source or object code
10: .\" must include the copyright notice above and the following
11: .\" disclaimer of warranties; and
12: .\" (ii) No rights are granted, in any manner or form, to use
13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
14: .\" on advertising, endorsements, or otherwise except as such
15: .\" appears in the above copyright notice or in the software.
16: .\"
17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
34: .\" THE POSSIBILITY OF SUCH DAMAGE.
35: .\"
36: .\" Author: Archie Cobbs <archie@freebsd.org>
37: .\"
38: .\" $Id: http_request.3,v 1.13 2004/06/02 17:24:36 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt HTTP_REQUEST 3
42: .Os
43: .Sh NAME
44: .Nm http_request
45: .Nd HTTP request object
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In stdio.h
51: .In netinet/in.h
52: .In openssl/ssl.h
53: .In pdel/http/http_defs.h
54: .In pdel/http/http_server.h
55: .\"
56: .Ss Accessors
57: .\"
58: .Ft "const char *"
59: .Fn http_request_get_method "struct http_request *req"
60: .Ft "int"
61: .Fn http_request_set_method "struct http_request *req" "const char *method"
62: .Ft "const char *"
63: .Fn http_request_get_uri "struct http_request *req"
64: .Ft "const char *"
65: .Fn http_request_get_path "struct http_request *req"
66: .Ft "int"
67: .Fn http_request_set_path "struct http_request *req" "const char *path"
68: .Ft "const char *"
69: .Fn http_request_get_version "struct http_request *req"
70: .Ft "const char *"
71: .Fn http_request_get_query_string "struct http_request *req"
72: .Ft "const char *"
73: .Fn http_request_get_host "struct http_request *req"
74: .Ft "struct in_addr"
75: .Fn http_request_get_remote_ip "struct http_request *req"
76: .Ft "u_int16_t"
77: .Fn http_request_get_remote_port "struct http_request *req"
78: .Ft "SSL_CTX *"
79: .Fn http_request_get_ssl "struct http_request *req"
80: .\"
81: .Ss "HTTP Headers"
82: .\"
83: .Ft "const char *"
84: .Fn http_request_get_header "struct http_request *req" "const char *name"
85: .Ft "int"
86: .Fn http_request_num_headers "struct http_request *req"
87: .Ft "int"
88: .Fn http_request_get_header_by_index "struct http_request *req" "u_int index" "const char **namep" "const char **valuep"
89: .Ft "int"
90: .Fn http_request_set_header "struct http_request *req" "int append" "const char *name" "const char *valfmt" "..."
91: .Ft "int"
92: .Fn http_request_remove_header "struct http_request *req" "const char *name"
93: .Ft "int"
94: .Fn http_request_send_headers "struct http_request *req"
95: .\"
96: .Ss "HTTP Body"
97: .\"
98: .Ft "FILE *"
99: .Fn http_request_get_input "struct http_request *req"
100: .Ft "FILE *"
101: .Fn http_request_get_output "struct http_request *req" "int buffer"
102: .\"
103: .Ss "HTTP Basic Authorization"
104: .\"
105: .Ft "const char *"
106: .Fn http_request_get_username "struct http_request *req"
107: .Ft "const char *"
108: .Fn http_request_get_password "struct http_request *req"
109: .Ft "char *"
110: .Fn http_request_encode_basic_auth "const char *mtype" "const char *username" "const char *password"
111: .\"
112: .Ss "Name/Value Pairs"
113: .\"
114: .Ft "const char *"
115: .Fn http_request_get_value "struct http_request *req" "const char *name" "int instance"
116: .Ft "int"
117: .Fn http_request_set_value "struct http_request *req" "const char *name" "const char *value"
118: .Ft int
119: .Fn http_request_get_num_values "struct http_request *req"
120: .Ft int
121: .Fn http_request_get_value_by_index "struct http_request *req" "int index" "const char **name" "const char **value"
122: .Ft "int"
123: .Fn http_request_set_query_from_values "struct http_request *req"
124: .Ft "int"
125: .Fn http_request_read_url_encoded_values "struct http_request *req"
126: .Ft "int"
127: .Fn http_request_write_url_encoded_values "struct http_request *req"
128: .\"
129: .Ss "MIME Multi-Part Support"
130: .\"
131: .Ft int
132: .Fn http_request_get_mime_multiparts "struct http_request *req" "http_mime_handler_t *handler" "void *arg"
133: .Ft "struct mime_multipart *"
134: .Fn http_request_read_mime_multipart "struct http_request *req"
135: .Ft "int"
136: .Fn http_request_file_upload "struct http_request *req" "const char *field" "FILE *fp" "size_t max"
137: .\"
138: .Ss Miscellaneous
139: .\"
140: .Ft "char *"
141: .Fn http_request_url_encode "const char *mtype" "const char *string"
142: .Ft "void"
143: .Fn http_request_url_decode "const char *s" "char *t"
144: .Ft "time_t"
145: .Fn http_request_parse_time "const char *string"
146: .Ft "void "
147: .Fn http_request_set_proxy "struct http_request *req" "int whether"
148: .Ft "int"
149: .Fn http_request_get_raw_socket "struct http_request *req"
150: .\"
151: .Sh DESCRIPTION
152: .\"
153: The
154: .Nm http_request
155: object is used by the PDEL HTTP library to represent an HTTP request.
156: An HTTP request may be associated with an HTTP client (the request is
157: generated locally) or an HTTP server (the request is generated remotely).
158: Some of the functions and values defined below only make sense in one
159: of these cases.
160: .Pp
161: .Nm http_request
162: objects are not created directly; rather, they are obtained from another
163: object which is associated with the HTTP connection.
164: They are freed automatically (and become invalid) when the corresponding
165: HTTP connection object is closed.
166: .\"
167: .Ss Accessors
168: .\"
169: .Fn http_request_get_method
170: returns the HTTP method, typically "GET" or "POST" but others are possible.
171: .Pp
172: .Fn http_request_set_method
173: sets the method for a request when the local side is the client.
174: .Pp
175: .Fn http_request_get_uri
176: gets the URI from the request.
177: This is the requested resource exactly as the client requested it,
178: before any URL-decoding.
179: The first character of this string will always be '/' for non-proxy requests.
180: .Pp
181: .Fn http_request_get_path
182: returns the path part of the URI, after URL-decoding has taken place.
183: This does not include the '?' and query string part, if any.
184: The first character of this string will always be '/'.
185: .Pp
186: .Fn http_request_set_path
187: sets the path for a request.
188: The first character must be '/'.
189: .Pp
190: .Fn http_request_get_version
191: returns the version string for this request.
192: Typically one of "HTTP/0.9", "HTTP/1.0", or "HTTP/1.1".
193: .Pp
194: .Fn http_request_get_query_string
195: returns the HTTP query string (which optionally appears at the end of
196: an URL after a '?' character), or the empty string if there is no query string.
197: The returned string is exactly as it was submitted by the client,
198: i.e., no URL-decoding has been performed on it.
199: .Pp
200: .Fn http_request_get_host
201: returns the hostname specified in the request.
202: This may be
203: .Dv NULL
204: for a non-proxy request if the client fails to send the "Host" header
205: (typically older browsers).
206: This value can be used to implement "virtual hosting".
207: .Pp
208: .Fn http_request_get_remote_ip
209: returns the IP address of the remote side.
210: .Pp
211: .Fn http_request_get_remote_port
212: returns the TCP port of the remote side.
213: .Pp
214: .Fn http_request_get_ssl
215: returns the SSL context for the HTTP connection, or
216: .Dv NULL
217: if the connection is not over SSL.
218: .\"
219: .Ss "HTTP Headers"
220: .\"
221: .Fn http_request_get_header
222: returns the value of the named header, or
223: .Dv NULL
224: if the header is not defined for the request.
225: HTTP header names are case-insensitive.
226: .Pp
227: .Fn http_request_num_headers
228: returns the number of headers in the request.
229: .Pp
230: .Fn http_request_get_header_by_index
231: points
232: .Fa "*namep"
233: at the name and
234: .Fa "*valuep"
235: at the value of the header with index
236: .Fa index ,
237: which must be less than the value returned by
238: .Fn http_request_num_headers .
239: .Pp
240: .Fn http_request_set_header
241: formats and sets a header value.
242: If
243: .Fa append
244: is non-zero, the value is appended to any existing value
245: (after adding a ",\ " separator) rather than replacing it.
246: .Pp
247: .Fn http_request_remove_header
248: removes a header from the request.
249: .Pp
250: .Fn http_request_send_headers
251: causes the client request headers to be sent to the server if they
252: haven't already been sent.
253: This causes the URI to be constructed from the request path (see
254: .Fn http_request_set_path
255: above) and the name/value pairs (see
256: .Fn http_request_set_value
257: below) added as the query string.
258: .\"
259: .Ss "HTTP Body"
260: .\"
261: .Fn http_request_get_input
262: returns the body of the request as an input stream.
263: The local side must be the server for this HTTP connection.
264: .Pp
265: .Fn http_request_get_output
266: returns an output stream that writes into the body of the request.
267: The local side must be the client for this HTTP connection.
268: .Fa buffer
269: determines whether the entire output should be buffered before sending, or
270: should writes to the stream translate immediately into writes to the server.
271: The latter option will force the headers to be sent (if they haven't been
272: sent already) when the first byte is written to the stream.
273: Setting
274: .Fa buffer
275: to zero is also incompatible with keep-alive, unless the user code manually
276: sets the "Content-Length" header (in which case it takes responsibility
277: for writing the correct number of bytes).
278: If
279: .Fa buffer
280: is non-zero, the output will be buffered entirely in memory until the output
281: stream is closed, at which point "Content-Length" is computed automatically.
282: .\"
283: .Ss "HTTP Basic Authorization"
284: .\"
285: .Fn http_request_get_username
286: returns the username from the "Authorization" header, or
287: .Dv NULL
288: if none was specified.
289: This works for "Basic" authentication only.
290: .Pp
291: .Fn http_request_get_password
292: returns the password from the "Authorization" header, or
293: .Dv NULL
294: if none was specified.
295: This works for "Basic" authentication only.
296: .Pp
297: .Fn http_request_encode_basic_auth
298: formats and base-64 encodes the
299: .Fa username
300: and
301: .Fa password
302: into a form suitable for the HTTP "Basic" authentication header.
303: The returned buffer is allocated with
304: .Xr typed_mem 3
305: type
306: .Fa mtype ;
307: the caller must eventually free it.
308: .\"
309: .Ss "Name/Value Pairs"
310: .\"
311: Requests have an internal list of name, value pairs.
312: The names need not be unique.
313: For servers, this list is automatically initialized from the request
314: by parsing the URI query string.
315: For clients, this list is used to automatically generate the URI query
316: string when the request headers are sent for "GET" queries only.
317: .Pp
318: .Fn http_request_get_value
319: returns the value associated with with
320: .Fa name .
321: Since the same name may exist multiple times,
322: .Fa instance
323: should be 0 to retrieve the first value, 1 for the second, etc.
324: .Dv NULL
325: is returned if the value is not found.
326: .Pp
327: .Fn http_request_set_value
328: adds a name, value pair to the internal database.
329: .Pp
330: .Fn http_request_get_num_values
331: returns the number of name, value pairs.
332: .Pp
333: .Fn http_request_get_value_by_index
334: retrieves name, value pair that is at position
335: .Fa index
336: in the list.
337: Note that the list is kept sorted by name.
338: .Pp
339: .Fn http_request_set_query_from_values
340: generates a query string for the request based on the
341: name, value pairs.
342: This is useful if a query string is desired with a non-GET request.
343: .Pp
344: .Fn http_request_read_url_encoded_values
345: reads the request body, interprets it as an URL-encoded query string,
346: and sets the request's name, value pairs from string.
347: This is typically used by a server to input HTML form data that
348: was submitted using the "POST" method.
349: .Pp
350: .Fn http_request_write_url_encoded_values
351: writes out the name, value pairs as URL-encoded query string data.
352: This is typically used by a client to output HTML form data using
353: the "POST" method.
354: .Pp
355: .\"
356: .Ss "MIME Multi-Part Support"
357: .\"
358: These functions operate on requests whose body contains multi-part MIME data.
359: The request must have content type "multipart/form-data" and
360: the body must be properly formatted for multi-part MIME or else these
361: functions will return an error.
362: .Pp
363: .Fn http_request_get_mime_multiparts
364: reads the request body as a multi-part MIME document and invokes the
365: .Fa handler
366: for each part:
367: .Pp
368: .Bd -literal -compact
369: typedef int http_mime_handler_t(void *arg,
370: struct mime_part *part, FILE *fp);
371: .Ed
372: .Pp
373: The
374: .Fa arg
375: is passed untouched to the handler.
376: .Fa fp
377: is an input stream that reads only the MIME part being processed.
378: The handler should read as much of the MIME part as desired and then return
379: 0 to continue with subsequent parts, or else
380: -1 (with
381: .Va errno
382: set) to abort processing.
383: In the latter case,
384: .Fn http_request_get_mime_multiparts
385: will return -1.
386: In no case should
387: the handler close the stream
388: .Fa fp
389: or free
390: .Fa part .
391: See
392: .Xr http_mime 3
393: for a description of how to use
394: .Fa part .
395: .Pp
396: .Fn http_request_read_mime_multipart
397: reads an entire multi-part MIME request body into memory and returns
398: the result, which the caller is responsible for eventually freeing.
399: See
400: .Xr http_mime 3
401: for a description of how to use the return value.
402: .Pp
403: .Fn http_request_file_upload
404: reads only the value of the field
405: .Fa field
406: from a multi-part MIME request body and writes it to the output stream
407: .Fa fp .
408: The data is transferred in an on-line fasion so that the entire value
409: does not need to fit in memory at once.
410: This is useful for HTML form file uploads of large files.
411: All MIME parts other than the first part with name
412: .Fa field
413: are discarded.
414: If
415: .Fa max
416: is non-zero and the length of the field is more than
417: .Fa max
418: bytes, an error is generated with
419: .Va errno
420: set to
421: .Er EFBIG.
422: This is useful for avoiding disk-filling attacks.
423: .\"
424: .Ss Miscellaneous
425: .\"
426: .Fn http_request_url_encode
427: URL-encodes the string
428: .Fa s
429: into a buffer allocated with
430: .Xr typed_mem 3
431: type
432: .Fa mtype
433: and returns the result, which the caller must eventually free.
434: .Pp
435: .Fn http_request_url_decode
436: URL-decodes the string
437: .Fa s
438: and puts the result in the buffer
439: .Fa t ,
440: which must have length at least
441: .Li "strlen(s) + 1" .
442: .Pp
443: .Fn http_request_parse_time
444: parses an HTTP time string and returns the result, or -1 on failure.
445: .Pp
446: .Fn http_request_set_proxy
447: sets or clears the proxy bit for a client request.
448: When this bit is set, the client will make a proxy HTTP request instead
449: of a normal HTTP request.
450: .Pp
451: .Fn http_request_get_raw_socket
452: returns the underlying file descriptor for the HTTP connection.
453: This is a huge layering violation fraught with danger, but necessary
454: for implementing a proxy server that supports the "CONNECT" method.
455: This function will fail for SSL connections.
456: The returned file descriptor should not be closed.
457: .Sh RETURN VALUES
458: All of the above routines that can return an error return
459: .Dv NULL
460: or -1 to indicate this and set
461: .Va errno
462: to an appropriate value.
463: Success is indicated by a normal return value or zero.
464: .Sh SEE ALSO
465: .Xr http_client 3 ,
466: .Xr http_mime 3 ,
467: .Xr http_response 3 ,
468: .Xr http_server 3 ,
469: .Xr http_servlet 3 ,
470: .Xr libpdel 3 ,
471: .Xr typed_mem 3
472: .Rs
473: .%A R. Fielding
474: .%A J. Gettys
475: .%A J. Mogul
476: .%A H. Frystyk
477: .%A L. Masinter
478: .%A P. Leach
479: .%A T. Berners-Lee
480: .%T "Hypertext Transfer Protocol -- HTTP/1.1"
481: .%O RFC 2616
482: .Re
483: .Rs
484: .%A N. Freed
485: .%A N. Borenstein
486: .%T "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
487: .%O RFC 2046
488: .Re
489: .Sh HISTORY
490: The PDEL library was developed at Packet Design, LLC.
491: .Dv "http://www.packetdesign.com/"
492: .Sh AUTHORS
493: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_request.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / http