summaryrefslogtreecommitdiffstats
path: root/doc/http.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/http.n')
-rw-r--r--doc/http.n104
1 files changed, 54 insertions, 50 deletions
diff --git a/doc/http.n b/doc/http.n
index a76e6ff..95efcd6 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -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)