Annotation of embedaddon/libpdel/http/http_request.3, revision 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