diff options
Diffstat (limited to 'doc/http.n')
-rw-r--r-- | doc/http.n | 362 |
1 files changed, 0 insertions, 362 deletions
diff --git a/doc/http.n b/doc/http.n deleted file mode 100644 index 7fd61ce..0000000 --- a/doc/http.n +++ /dev/null @@ -1,362 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: http.n,v 1.3 1999/04/16 00:46:35 stanton Exp $ -'\" -.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 -Once the data associated with the url is no longer needed, the state -array should be unset to free up storage. 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 - - |