361 lines
12 KiB
Plaintext
361 lines
12 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) http.n 1.11 97/08/07 16:45:02
|
|
'\"
|
|
.so man.macros
|
|
.TH "Http" n 8.0 Tcl "Tcl Built-In Commands"
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
Http \- Client-side implementation of the HTTP/1.0 protocol.
|
|
.SH SYNOPSIS
|
|
\fBpackage require http ?2.0?\fP
|
|
.sp
|
|
\fB::http::config \fI?options?\fR
|
|
.sp
|
|
\fB::http::geturl \fIurl ?options?\fR
|
|
.sp
|
|
\fB::http::formatQuery \fIlist\fR
|
|
.sp
|
|
\fB::http::reset \fItoken\fR
|
|
.sp
|
|
\fB::http::wait \fItoken\fR
|
|
.sp
|
|
\fB::http::status \fItoken\fR
|
|
.sp
|
|
\fB::http::size \fItoken\fR
|
|
.sp
|
|
\fB::http::code \fItoken\fR
|
|
.sp
|
|
\fB::http::data \fItoken\fR
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \fBhttp\fR package provides the client side of the HTTP/1.0
|
|
protocol. The package implements the GET, POST, and HEAD operations
|
|
of HTTP/1.0. It allows configuration of a proxy host to get through
|
|
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.
|
|
.PP
|
|
The \fB::http::geturl\fR procedure does a HTTP transaction.
|
|
Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
|
|
is performed.
|
|
The return value of \fB::http::geturl\fR is a token for the transaction.
|
|
The value is also the name of an array in the ::http namespace
|
|
that contains state
|
|
information about the transaction. The elements of this array are
|
|
described in the STATE ARRAY section.
|
|
.PP
|
|
If the \fB-command\fP option is specified, then
|
|
the HTTP operation is done in the background.
|
|
\fB::http::geturl\fR returns immediately after generating the
|
|
HTTP request and the callback is invoked
|
|
when the transaction completes. For this to work, the Tcl event loop
|
|
must be active. In Tk applications this is always true. For pure-Tcl
|
|
applications, the caller can use \fB::http::wait\fR after calling
|
|
\fB::http::geturl\fR to start the event loop.
|
|
.SH COMMANDS
|
|
.TP
|
|
\fB::http::config\fP ?\fIoptions\fR?
|
|
The \fB::http::config\fR command is used to set and query the name of the
|
|
proxy server and port, and the User-Agent name used in the HTTP
|
|
requests. If no options are specified, then the current configuration
|
|
is returned. If a single argument is specified, then it should be one
|
|
of the flags described below. In this case the current value of
|
|
that setting is returned. Otherwise, the options should be a set of
|
|
flags and values that define the configuration:
|
|
.RS
|
|
.TP
|
|
\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
|
|
willing to receive. For example, "image/gif, image/jpeg, text/*".
|
|
.TP
|
|
\fB\-proxyhost\fP \fIhostname\fP
|
|
The name of the proxy host, if any. If this value is the
|
|
empty string, the URL host is contacted directly.
|
|
.TP
|
|
\fB\-proxyport\fP \fInumber\fP
|
|
The proxy port number.
|
|
.TP
|
|
\fB\-proxyfilter\fP \fIcommand\fP
|
|
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
|
|
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
|
|
non-empty.
|
|
.TP
|
|
\fB\-useragent\fP \fIstring\fP
|
|
The value of the User-Agent header in the HTTP request. The default
|
|
is \fB"Tcl http client package 2.0."\fR
|
|
.RE
|
|
.TP
|
|
\fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP?
|
|
The \fB::http::geturl \fR command is the main procedure in the package.
|
|
The \fB\-query\fR option causes a POST operation and
|
|
the \fB\-validate\fR option causes a HEAD operation;
|
|
otherwise, a GET operation is performed. The \fB::http::geturl\fR command
|
|
returns a \fItoken\fR value that can be used to get
|
|
information about the transaction. See the STATE ARRAY section for
|
|
details. The \fB::http::geturl\fR command blocks until the operation
|
|
completes, unless the \fB\-command\fR option specifies a callback
|
|
that is invoked when the HTTP transaction completes.
|
|
\fB::http::geturl\fR takes several options:
|
|
.RS
|
|
.TP
|
|
\fB\-blocksize\fP \fIsize\fP
|
|
The blocksize 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.
|
|
.TP
|
|
\fB\-channel\fP \fIname\fP
|
|
Copy the URL contents to channel \fIname\fR instead of saving it in
|
|
\fBstate(body)\fR.
|
|
.TP
|
|
\fB\-command\fP \fIcallback\fP
|
|
Invoke \fIcallback\fP after the HTTP transaction completes.
|
|
This option causes \fB::http::geturl\fP to return immediately.
|
|
The \fIcallback\fP gets an additional argument that is the \fItoken\fR returned
|
|
from \fB::http::geturl\fR. This token is the name of an array that is
|
|
described in the STATE ARRAY section. Here is a template for the
|
|
callback:
|
|
.RS
|
|
.CS
|
|
proc httpCallback {token} {
|
|
upvar #0 $token state
|
|
# Access state as a Tcl array
|
|
}
|
|
.CE
|
|
.RE
|
|
.TP
|
|
\fB\-handler\fP \fIcallback\fP
|
|
Invoke \fIcallback\fP whenever HTTP data is available; if present, nothing
|
|
else will be done with the HTTP data. This procedure gets two additional
|
|
arguments: the socket for the HTTP data and the \fItoken\fR returned from
|
|
\fB::http::geturl\fR. The token is the name of a global array that is described
|
|
in the STATE ARRAY section. The procedure is expected to return the number
|
|
of bytes read from the socket. Here is a template for the callback:
|
|
.RS
|
|
.CS
|
|
proc httpHandlerCallback {socket token} {
|
|
upvar #0 $token state
|
|
# Access socket, and state as a Tcl array
|
|
...
|
|
(example: set data [read $socket 1000];set nbytes [string length $data])
|
|
...
|
|
return nbytes
|
|
}
|
|
.CE
|
|
.RE
|
|
.TP
|
|
\fB\-headers\fP \fIkeyvaluelist\fP
|
|
This option is used to add extra headers to the HTTP request. The
|
|
\fIkeyvaluelist\fR argument must be a list with an even number of
|
|
elements that alternate between keys and values. The keys become
|
|
header field names. Newlines are stripped from the values so the
|
|
header cannot be corrupted. For example, if \fIkeyvaluelist\fR is
|
|
\fBPragma no-cache\fR then the following header is included in the
|
|
HTTP request:
|
|
.CS
|
|
Pragma: no-cache
|
|
.CE
|
|
.TP
|
|
\fB\-progress\fP \fIcallback\fP
|
|
The \fIcallback\fR is made after each transfer of data from the URL.
|
|
The callback gets three additional arguments: the \fItoken\fR from
|
|
\fB::http::geturl\fR, the expected total size of the contents from the
|
|
\fBContent-Length\fR meta-data, and the current number of bytes
|
|
transferred so far. The expected total size may be unknown, in which
|
|
case zero is passed to the callback. Here is a template for the
|
|
progress callback:
|
|
.RS
|
|
.CS
|
|
proc httpProgress {token total current} {
|
|
upvar #0 $token state
|
|
}
|
|
.CE
|
|
.RE
|
|
.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
|
|
formatted query. The \fB::http::formatQuery\fR procedure can be used to
|
|
do the formatting.
|
|
.TP
|
|
\fB\-timeout\fP \fImilliseconds\fP
|
|
If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout
|
|
to occur after the specified number of milliseconds.
|
|
A timeout results in a call to \fB::http::reset\fP and to
|
|
the \fB-command\fP callback, if specified.
|
|
The return value of \fB::http::status\fP is \fBtimeout\fP
|
|
after a timeout has occurred.
|
|
.TP
|
|
\fB\-validate\fP \fIboolean\fP
|
|
If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD
|
|
request. This request returns meta information about the URL, but the
|
|
contents are not returned. The meta information is available in the
|
|
\fBstate(meta) \fR variable after the transaction. See the STATE
|
|
ARRAY section for details.
|
|
.RE
|
|
.TP
|
|
\fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
|
|
This procedure does x-url-encoding of query data. It takes an even
|
|
number of arguments that are the keys and values of the query. It
|
|
encodes the keys and values, and generates one string that has the
|
|
proper & and = separators. The result is suitable for the
|
|
\fB\-query\fR value passed to \fB::http::geturl\fR.
|
|
.TP
|
|
\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
|
|
This command resets the HTTP transaction identified by \fItoken\fR, if
|
|
any. This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
|
|
.TP
|
|
\fB::http::wait\fP \fItoken\fP
|
|
This is a convenience procedure that blocks and waits for the
|
|
transaction to complete. This only works in trusted code because it
|
|
uses \fBvwait\fR.
|
|
.TP
|
|
\fB::http::data\fP \fItoken\fP
|
|
This is a convenience procedure that returns the \fBbody\fP element
|
|
(i.e., the URL data) of the state array.
|
|
.TP
|
|
\fB::http::status\fP \fItoken\fP
|
|
This is a convenience procedure that returns the \fBstatus\fP element of
|
|
the state array.
|
|
.TP
|
|
\fB::http::code\fP \fItoken\fP
|
|
This is a convenience procedure that returns the \fBhttp\fP element of the
|
|
state array.
|
|
.TP
|
|
\fB::http::size\fP \fItoken\fP
|
|
This is a convenience procedure that returns the \fBcurrentsize\fP
|
|
element of the state array.
|
|
.SH "STATE ARRAY"
|
|
The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to
|
|
get to the state of the HTTP transaction in the form of a Tcl array.
|
|
Use this construct to create an easy-to-use array variable:
|
|
.CS
|
|
upvar #0 $token state
|
|
.CE
|
|
The following elements of the array are supported:
|
|
.RS
|
|
.TP
|
|
\fBbody\fR
|
|
The contents of the URL. This will be empty if the \fB\-channel\fR
|
|
option has been specified. This value is returned by the \fB::http::data\fP command.
|
|
.TP
|
|
\fBcurrentsize\fR
|
|
The current number of bytes fetched from the URL.
|
|
This value is returned by the \fB::http::size\fP command.
|
|
.TP
|
|
\fBerror\fR
|
|
If defined, this is the error string seen when the HTTP transaction
|
|
was aborted.
|
|
.TP
|
|
\fBhttp\fR
|
|
The HTTP status reply from the server. This value
|
|
is returned by the \fB::http::code\fP command. The format of this value is:
|
|
.RS
|
|
.CS
|
|
\fIcode string\fP
|
|
.CE
|
|
The \fIcode\fR is a three-digit number defined in the HTTP standard.
|
|
A code of 200 is OK. Codes beginning with 4 or 5 indicate errors.
|
|
Codes beginning with 3 are redirection errors. In this case the
|
|
\fBLocation\fR meta-data specifies a new URL that contains the
|
|
requested information.
|
|
.RE
|
|
.TP
|
|
\fBmeta\fR
|
|
The HTTP protocol returns meta-data that describes the URL contents.
|
|
The \fBmeta\fR element of the state array is a list of the keys and
|
|
values of the meta-data. This is in a format useful for initializing
|
|
an array that just contains the meta-data:
|
|
.RS
|
|
.CS
|
|
array set meta $state(meta)
|
|
.CE
|
|
Some of the meta-data keys are listed below, but the HTTP standard defines
|
|
more, and servers are free to add their own.
|
|
.TP
|
|
\fBContent-Type\fR
|
|
The type of the URL contents. Examples include \fBtext/html\fR,
|
|
\fBimage/gif,\fR \fBapplication/postscript\fR and
|
|
\fBapplication/x-tcl\fR.
|
|
.TP
|
|
\fBContent-Length\fR
|
|
The advertised size of the contents. The actual size obtained by
|
|
\fB::http::geturl\fR is available as \fBstate(size)\fR.
|
|
.TP
|
|
\fBLocation\fR
|
|
An alternate URL that contains the requested data.
|
|
.RE
|
|
.TP
|
|
\fBstatus\fR
|
|
Either \fBok\fR, for successful completion, \fBreset\fR for
|
|
user-reset, or \fBerror\fR for an error condition. During the
|
|
transaction this value is the empty string.
|
|
.TP
|
|
\fBtotalsize\fR
|
|
A copy of the \fBContent-Length\fR meta-data value.
|
|
.TP
|
|
\fBtype\fR
|
|
A copy of the \fBContent-Type\fR meta-data value.
|
|
.TP
|
|
\fBurl\fR
|
|
The requested URL.
|
|
.RE
|
|
.SH EXAMPLE
|
|
.DS
|
|
# 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]
|
|
}
|
|
|
|
return $token
|
|
}
|
|
proc ::http::Progress {args} {
|
|
puts -nonewline stderr . ; flush stderr
|
|
}
|
|
|
|
.DE
|
|
.SH "SEE ALSO"
|
|
safe(n), socket(n), safesock(n)
|
|
.SH KEYWORDS
|
|
security policy, socket
|
|
|
|
|