diff options
Diffstat (limited to 'doc/http.n')
| -rw-r--r-- | doc/http.n | 104 |
1 files changed, 54 insertions, 50 deletions
@@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: http.n,v 1.18.2.2 2004/05/25 22:50:46 hobbs Exp $ +'\" RCS: @(#) $Id: http.n,v 1.18.2.3 2004/10/27 12:52:40 dkf Exp $ '\" .so man.macros .TH "http" n 2.5 http "Tcl Bundled Packages" @@ -55,7 +55,7 @@ firewalls. The package is compatible with the \fBSafesock\fR security policy, so it can be used by untrusted applets to do URL fetching from a restricted set of hosts. This package can be extended to support additional HTTP transport protocols, such as HTTPS, by providing -a custom \fBsocket\fR command, via \fBhttp::register\fR. +a custom \fBsocket\fR command, via \fB::http::register\fR. .PP The \fB::http::geturl\fR procedure does a HTTP transaction. Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction @@ -88,7 +88,7 @@ flags and values that define the configuration: \fB\-accept\fP \fImimetypes\fP The Accept header of the request. The default is */*, which means that all types of documents are accepted. Otherwise you can supply a -comma separated list of mime type patterns that you are +comma-separated list of mime type patterns that you are willing to receive. For example, "image/gif, image/jpeg, text/*". .TP \fB\-proxyhost\fP \fIhostname\fP @@ -103,7 +103,7 @@ The command is a callback that is made during \fB::http::geturl\fR to determine if a proxy is required for a given host. One argument, a host name, is added to \fIcommand\fR when it is invoked. If a proxy -is required, the callback should return a two element list containing +is required, the callback should return a two-element list containing the proxy server and proxy port. Otherwise the filter should return an empty list. The default filter returns the values of the \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are @@ -137,13 +137,13 @@ that is invoked when the HTTP transaction completes. .RS .TP \fB\-binary\fP \fIboolean\fP -Specifies whether to force interpreting the url data as binary. Normally +Specifies whether to force interpreting the URL data as binary. Normally this is auto-detected (anything not beginning with a \fBtext\fR content type or whose content encoding is \fBgzip\fR or \fBcompress\fR is considered binary data). .TP \fB\-blocksize\fP \fIsize\fP -The blocksize used when reading the URL. +The block size used when reading the URL. At most \fIsize\fR bytes are read at once. After each block, a call to the \fB\-progress\fR callback is made (if that option is specified). .TP @@ -217,12 +217,12 @@ proc httpProgress {token total current} { .TP \fB\-query\fP \fIquery\fP This flag causes \fB::http::geturl\fR to do a POST request that passes the -\fIquery\fR to the server. The \fIquery\fR must be a x-url-encoding +\fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding formatted query. The \fB::http::formatQuery\fR procedure can be used to do the formatting. .TP \fB\-queryblocksize\fP \fIsize\fP -The blocksize used when posting query data to the URL. +The block size used when posting query data to the URL. At most \fIsize\fR bytes are written at once. After each block, a call to the @@ -231,7 +231,8 @@ callback is made (if that option is specified). .TP \fB\-querychannel\fP \fIchannelID\fP This flag causes \fB::http::geturl\fR to do a POST request that passes the -data contained in \fIchannelID\fR to the server. The data contained in \fIchannelID\fR must be a x-url-encoding +data contained in \fIchannelID\fR to the server. The data contained in +\fIchannelID\fR must be an x-url-encoding formatted query unless the \fB\-type\fP option below is used. If a Content-Length header is not specified via the \fB\-headers\fR options, \fB::http::geturl\fR attempts to determine the size of the post data @@ -328,18 +329,18 @@ command to execute to create the Tcl \fBchannel\fR. E.g.: package require http package require tls -http::register https 443 ::tls::socket +::http::register https 443 ::tls::socket -set token [http::geturl https://my.secure.site/] +set token [::http::geturl https://my.secure.site/] .CE .RE .TP \fB::http::unregister\fP \fIproto\fP This procedure unregisters a protocol handler that was previously -registered via \fBhttp::register\fR. +registered via \fB::http::register\fR. .SH "ERRORS" -The \fBhttp::geturl\fP procedure will raise errors in the following cases: +The \fB::http::geturl\fP procedure will raise errors in the following cases: invalid command line options, an invalid URL, a URL on a non-existent host, @@ -371,17 +372,17 @@ to know the result of the asynchronous HTTP request, it can call callback does. .PP In any case, you must still call -\fBhttp::cleanup\fP to delete the state array when you're done. +\fB::http::cleanup\fP to delete the state array when you're done. .PP There are other possible results of the HTTP transaction -determined by examining the status from \fBhttp::status\fP. +determined by examining the status from \fB::http::status\fP. These are described below. .TP ok If the HTTP transaction completes entirely, then status will be \fBok\fP. -However, you should still check the \fBhttp::code\fP value to get -the HTTP status. The \fBhttp::ncode\fP procedure provides just -the numeric error (e.g., 200, 404 or 500) while the \fBhttp::code\fP +However, you should still check the \fB::http::code\fP value to get +the HTTP status. The \fB::http::ncode\fP procedure provides just +the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fP procedure returns a value like "HTTP 404 File not found". .TP eof @@ -392,11 +393,11 @@ error The error message will also be stored in the \fBerror\fP status array element, accessible via \fB::http::error\fP. .PP -Another error possibility is that \fBhttp::geturl\fP is unable to +Another error possibility is that \fB::http::geturl\fP is unable to write all the post query data to the server before the server responds and closes the socket. The error message is saved in the \fBposterror\fP status array -element and then \fBhttp::geturl\fP attempts to complete the +element and then \fB::http::geturl\fP attempts to complete the transaction. If it can read the server's response it will end up with an \fBok\fP status, otherwise it will have @@ -409,9 +410,9 @@ Use this construct to create an easy-to-use array variable: .CS upvar #0 $token state .CE -Once the data associated with the url is no longer needed, the state +Once the data associated with the URL is no longer needed, the state array should be unset to free up storage. -The \fBhttp::cleanup\fP procedure is provided for that purpose. +The \fB::http::cleanup\fP procedure is provided for that purpose. The following elements of the array are supported: .RS @@ -496,38 +497,41 @@ A copy of the \fBContent-Type\fR meta-data value. The requested URL. .RE .SH EXAMPLE -.DS +.CS # Copy a URL to a file and print meta-data -proc ::http::copy { url file {chunk 4096} } { - set out [open $file w] - set token [geturl $url -channel $out -progress ::http::Progress \\ - -blocksize $chunk] - close $out - # This ends the line started by http::Progress - puts stderr "" - upvar #0 $token state - set max 0 - foreach {name value} $state(meta) { - if {[string length $name] > $max} { - set max [string length $name] - } - if {[regexp -nocase ^location$ $name]} { - # Handle URL redirects - puts stderr "Location:$value" - return [copy [string trim $value] $file $chunk] - } - } - incr max - foreach {name value} $state(meta) { - puts [format "%-*s %s" $max $name: $value] - } +proc httpcopy { url file {chunk 4096} } { + set out [open $file w] + set token [\fB::http::geturl\fR $url -channel $out \\ + -progress httpCopyProgress -blocksize $chunk] + close $out + + # This ends the line started by httpCopyProgress + puts stderr "" - return $token + upvar #0 $token state + set max 0 + foreach {name value} $state(meta) { + if {[string length $name] > $max} { + set max [string length $name] + } + if {[regexp -nocase ^location$ $name]} { + # Handle URL redirects + puts stderr "Location:$value" + return [httpcopy [string trim $value] $file $chunk] + } + } + incr max + foreach {name value} $state(meta) { + puts [format "%-*s %s" $max $name: $value] + } + + return $token } -proc ::http::Progress {args} { - puts -nonewline stderr . ; flush stderr +proc httpCopyProgress {args} { + puts -nonewline stderr . + flush stderr } -.DE +.CE .SH "SEE ALSO" safe(n), socket(n), safesock(n) |