523 lines
26 KiB
HTML
523 lines
26 KiB
HTML
|
<HTML><HEAD><TITLE>Tcl Built-In Commands - Http manual page</TITLE></HEAD><BODY>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="http.htm#M2" NAME="L469">NAME</A>
|
||
|
|
<DL><DD>Http - Client-side implementation of the HTTP/1.0 protocol.</DL>
|
||
|
|
<DD><A HREF="http.htm#M3" NAME="L470">SYNOPSIS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><B>package require http ?2.4?</B>
|
||
|
|
<DD><B>::http::config </B><I>?options?</I>
|
||
|
|
<DD><B>::http::geturl </B><I>url ?options?</I>
|
||
|
|
<DD><B>::http::formatQuery </B><I>list</I>
|
||
|
|
<DD><B>::http::reset </B><I>token</I>
|
||
|
|
<DD><B>::http::wait </B><I>token</I>
|
||
|
|
<DD><B>::http::status </B><I>token</I>
|
||
|
|
<DD><B>::http::size </B><I>token</I>
|
||
|
|
<DD><B>::http::code </B><I>token</I>
|
||
|
|
<DD><B>::http::ncode </B><I>token</I>
|
||
|
|
<DD><B>::http::data </B><I>token</I>
|
||
|
|
<DD><B>::http::error </B><I>token</I>
|
||
|
|
<DD><B>::http::cleanup </B><I>token</I>
|
||
|
|
<DD><B>::http::register </B><I>proto port command</I>
|
||
|
|
<DD><B>::http::unregister </B><I>proto</I>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="http.htm#M4" NAME="L471">DESCRIPTION</A>
|
||
|
|
<DD><A HREF="http.htm#M5" NAME="L472">COMMANDS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="http.htm#M6" NAME="L473"><B>::http::config</B> ?<I>options</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="http.htm#M7" NAME="L474"><B>-accept</B> <I>mimetypes</I></A>
|
||
|
|
<DD><A HREF="http.htm#M8" NAME="L475"><B>-proxyhost</B> <I>hostname</I></A>
|
||
|
|
<DD><A HREF="http.htm#M9" NAME="L476"><B>-proxyport</B> <I>number</I></A>
|
||
|
|
<DD><A HREF="http.htm#M10" NAME="L477"><B>-proxyfilter</B> <I>command</I></A>
|
||
|
|
<DD><A HREF="http.htm#M11" NAME="L478"><B>-useragent</B> <I>string</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="http.htm#M12" NAME="L479"><B>::http::geturl</B> <I>url</I> ?<I>options</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="http.htm#M13" NAME="L480"><B>-binary</B> <I>boolean</I></A>
|
||
|
|
<DD><A HREF="http.htm#M14" NAME="L481"><B>-blocksize</B> <I>size</I></A>
|
||
|
|
<DD><A HREF="http.htm#M15" NAME="L482"><B>-channel</B> <I>name</I></A>
|
||
|
|
<DD><A HREF="http.htm#M16" NAME="L483"><B>-command</B> <I>callback</I></A>
|
||
|
|
<DD><A HREF="http.htm#M17" NAME="L484"><B>-handler</B> <I>callback</I></A>
|
||
|
|
<DD><A HREF="http.htm#M18" NAME="L485"><B>-headers</B> <I>keyvaluelist</I></A>
|
||
|
|
<DD><A HREF="http.htm#M19" NAME="L486"><B>-progress</B> <I>callback</I></A>
|
||
|
|
<DD><A HREF="http.htm#M20" NAME="L487"><B>-query</B> <I>query</I></A>
|
||
|
|
<DD><A HREF="http.htm#M21" NAME="L488"><B>-queryblocksize</B> <I>size</I></A>
|
||
|
|
<DD><A HREF="http.htm#M22" NAME="L489"><B>-querychannel</B> <I>channelID</I></A>
|
||
|
|
<DD><A HREF="http.htm#M23" NAME="L490"><B>-queryprogress</B> <I>callback</I></A>
|
||
|
|
<DD><A HREF="http.htm#M24" NAME="L491"><B>-timeout</B> <I>milliseconds</I></A>
|
||
|
|
<DD><A HREF="http.htm#M25" NAME="L492"><B>-type</B> <I>mime-type</I></A>
|
||
|
|
<DD><A HREF="http.htm#M26" NAME="L493"><B>-validate</B> <I>boolean</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="http.htm#M27" NAME="L494"><B>::http::formatQuery</B> <I>key value</I> ?<I>key value</I> ...?</A>
|
||
|
|
<DD><A HREF="http.htm#M28" NAME="L495"><B>::http::reset</B> <I>token</I> ?<I>why</I>?</A>
|
||
|
|
<DD><A HREF="http.htm#M29" NAME="L496"><B>::http::wait</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M30" NAME="L497"><B>::http::data</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M31" NAME="L498"><B>::http::error</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M32" NAME="L499"><B>::http::status</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M33" NAME="L500"><B>::http::code</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M34" NAME="L501"><B>::http::ncode</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M35" NAME="L502"><B>::http::size</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M36" NAME="L503"><B>::http::cleanup</B> <I>token</I></A>
|
||
|
|
<DD><A HREF="http.htm#M37" NAME="L504"><B>::http::register</B> <I>proto port command</I></A>
|
||
|
|
<DD><A HREF="http.htm#M38" NAME="L505"><B>::http::unregister</B> <I>proto</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="http.htm#M39" NAME="L506">ERRORS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="http.htm#M40" NAME="L507">ok</A>
|
||
|
|
<DD><A HREF="http.htm#M41" NAME="L508">eof</A>
|
||
|
|
<DD><A HREF="http.htm#M42" NAME="L509">error</A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="http.htm#M43" NAME="L510">STATE ARRAY</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="http.htm#M44" NAME="L511"><B>body</B></A>
|
||
|
|
<DD><A HREF="http.htm#M45" NAME="L512"><B>charset</B></A>
|
||
|
|
<DD><A HREF="http.htm#M46" NAME="L513"><B>coding</B></A>
|
||
|
|
<DD><A HREF="http.htm#M47" NAME="L514"><B>currentsize</B></A>
|
||
|
|
<DD><A HREF="http.htm#M48" NAME="L515"><B>error</B></A>
|
||
|
|
<DD><A HREF="http.htm#M49" NAME="L516"><B>http</B></A>
|
||
|
|
<DD><A HREF="http.htm#M50" NAME="L517"><B>meta</B></A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="http.htm#M51" NAME="L518"><B>Content-Type</B></A>
|
||
|
|
<DD><A HREF="http.htm#M52" NAME="L519"><B>Content-Length</B></A>
|
||
|
|
<DD><A HREF="http.htm#M53" NAME="L520"><B>Location</B></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="http.htm#M54" NAME="L521"><B>posterror</B></A>
|
||
|
|
<DD><A HREF="http.htm#M55" NAME="L522"><B>status</B></A>
|
||
|
|
<DD><A HREF="http.htm#M56" NAME="L523"><B>totalsize</B></A>
|
||
|
|
<DD><A HREF="http.htm#M57" NAME="L524"><B>type</B></A>
|
||
|
|
<DD><A HREF="http.htm#M58" NAME="L525"><B>url</B></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="http.htm#M59" NAME="L526">EXAMPLE</A>
|
||
|
|
<DD><A HREF="http.htm#M60" NAME="L527">SEE ALSO</A>
|
||
|
|
<DD><A HREF="http.htm#M61" NAME="L528">KEYWORDS</A>
|
||
|
|
</DL><HR>
|
||
|
|
<H3><A NAME="M2">NAME</A></H3>
|
||
|
|
Http - Client-side implementation of the HTTP/1.0 protocol.
|
||
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||
|
|
<B>package require http ?2.4?</B><BR>
|
||
|
|
<B>::http::config </B><I>?options?</I><BR>
|
||
|
|
<B>::http::geturl </B><I>url ?options?</I><BR>
|
||
|
|
<B>::http::formatQuery </B><I>list</I><BR>
|
||
|
|
<B>::http::reset </B><I>token</I><BR>
|
||
|
|
<B>::http::wait </B><I>token</I><BR>
|
||
|
|
<B>::http::status </B><I>token</I><BR>
|
||
|
|
<B>::http::size </B><I>token</I><BR>
|
||
|
|
<B>::http::code </B><I>token</I><BR>
|
||
|
|
<B>::http::ncode </B><I>token</I><BR>
|
||
|
|
<B>::http::data </B><I>token</I><BR>
|
||
|
|
<B>::http::error </B><I>token</I><BR>
|
||
|
|
<B>::http::cleanup </B><I>token</I><BR>
|
||
|
|
<B>::http::register </B><I>proto port command</I><BR>
|
||
|
|
<B>::http::unregister </B><I>proto</I><BR>
|
||
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||
|
|
The <B>http</B> 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 <B>Safesock</B> security
|
||
|
|
policy, so it can be used by untrusted applets to do URL fetching from
|
||
|
|
a restricted set of hosts. This package can be extened to support
|
||
|
|
additional HTTP transport protocols, such as HTTPS, by providing
|
||
|
|
a custom <B><A HREF="../TkCmd/socket.htm">socket</A></B> command, via <B>http::register</B>.
|
||
|
|
<P>
|
||
|
|
The <B>::http::geturl</B> procedure does a HTTP transaction.
|
||
|
|
Its <I>options </I> determine whether a GET, POST, or HEAD transaction
|
||
|
|
is performed.
|
||
|
|
The return value of <B>::http::geturl</B> 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.
|
||
|
|
<P>
|
||
|
|
If the <B>-command</B> option is specified, then
|
||
|
|
the HTTP operation is done in the background.
|
||
|
|
<B>::http::geturl</B> 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 <B>::http::wait</B> after calling
|
||
|
|
<B>::http::geturl</B> to start the event loop.
|
||
|
|
<H3><A NAME="M5">COMMANDS</A></H3>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M6"><B>::http::config</B> ?<I>options</I>?</A><DD>
|
||
|
|
The <B>::http::config</B> 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:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M7"><B>-accept</B> <I>mimetypes</I></A><DD>
|
||
|
|
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/*".
|
||
|
|
<P><DT><A NAME="M8"><B>-proxyhost</B> <I>hostname</I></A><DD>
|
||
|
|
The name of the proxy host, if any. If this value is the
|
||
|
|
empty string, the URL host is contacted directly.
|
||
|
|
<P><DT><A NAME="M9"><B>-proxyport</B> <I>number</I></A><DD>
|
||
|
|
The proxy port number.
|
||
|
|
<P><DT><A NAME="M10"><B>-proxyfilter</B> <I>command</I></A><DD>
|
||
|
|
The command is a callback that is made during
|
||
|
|
<B>::http::geturl</B>
|
||
|
|
to determine if a proxy is required for a given host. One argument, a
|
||
|
|
host name, is added to <I>command</I> 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
|
||
|
|
<B>-proxyhost</B> and <B>-proxyport</B> settings if they are
|
||
|
|
non-empty.
|
||
|
|
<P><DT><A NAME="M11"><B>-useragent</B> <I>string</I></A><DD>
|
||
|
|
The value of the User-Agent header in the HTTP request. The default
|
||
|
|
is <B>"Tcl http client package 2.2."</B>
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M12"><B>::http::geturl</B> <I>url</I> ?<I>options</I>?</A><DD>
|
||
|
|
The <B>::http::geturl</B> command is the main procedure in the package.
|
||
|
|
The <B>-query</B> option causes a POST operation and
|
||
|
|
the <B>-validate</B> option causes a HEAD operation;
|
||
|
|
otherwise, a GET operation is performed. The <B>::http::geturl</B> command
|
||
|
|
returns a <I>token</I> value that can be used to get
|
||
|
|
information about the transaction. See the STATE ARRAY and ERRORS section for
|
||
|
|
details. The <B>::http::geturl</B> command blocks until the operation
|
||
|
|
completes, unless the <B>-command</B> option specifies a callback
|
||
|
|
that is invoked when the HTTP transaction completes.
|
||
|
|
<B>::http::geturl</B> takes several options:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M13"><B>-binary</B> <I>boolean</I></A><DD>
|
||
|
|
Specifies whether to force interpreting the url data as binary. Normally
|
||
|
|
this is auto-detected (anything not beginning with a <B><A HREF="../TclCmd/text.htm">text</A></B> content
|
||
|
|
type or whose content encoding is <B>gzip</B> or <B>compress</B> is
|
||
|
|
considered binary data).
|
||
|
|
<P><DT><A NAME="M14"><B>-blocksize</B> <I>size</I></A><DD>
|
||
|
|
The blocksize used when reading the URL.
|
||
|
|
At most <I>size</I> bytes are read at once. After each block, a call to the
|
||
|
|
<B>-progress</B> callback is made (if that option is specified).
|
||
|
|
<P><DT><A NAME="M15"><B>-channel</B> <I>name</I></A><DD>
|
||
|
|
Copy the URL contents to channel <I>name</I> instead of saving it in
|
||
|
|
<B>state(body)</B>.
|
||
|
|
<P><DT><A NAME="M16"><B>-command</B> <I>callback</I></A><DD>
|
||
|
|
Invoke <I>callback</I> after the HTTP transaction completes.
|
||
|
|
This option causes <B>::http::geturl</B> to return immediately.
|
||
|
|
The <I>callback</I> gets an additional argument that is the <I>token</I> returned
|
||
|
|
from <B>::http::geturl</B>. This token is the name of an array that is
|
||
|
|
described in the STATE ARRAY section. Here is a template for the
|
||
|
|
callback:
|
||
|
|
<PRE>proc httpCallback {token} {
|
||
|
|
upvar #0 $token state
|
||
|
|
# Access state as a Tcl array
|
||
|
|
}</PRE>
|
||
|
|
<P><DT><A NAME="M17"><B>-handler</B> <I>callback</I></A><DD>
|
||
|
|
Invoke <I>callback</I> 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 <I>token</I> returned from
|
||
|
|
<B>::http::geturl</B>. 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:
|
||
|
|
<PRE>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
|
||
|
|
}</PRE>
|
||
|
|
<P><DT><A NAME="M18"><B>-headers</B> <I>keyvaluelist</I></A><DD>
|
||
|
|
This option is used to add extra headers to the HTTP request. The
|
||
|
|
<I>keyvaluelist</I> 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 <I>keyvaluelist</I> is
|
||
|
|
<B>Pragma no-cache</B> then the following header is included in the
|
||
|
|
HTTP request:
|
||
|
|
<PRE>Pragma: no-cache</PRE>
|
||
|
|
<P><DT><A NAME="M19"><B>-progress</B> <I>callback</I></A><DD>
|
||
|
|
The <I>callback</I> is made after each transfer of data from the URL.
|
||
|
|
The callback gets three additional arguments: the <I>token</I> from
|
||
|
|
<B>::http::geturl</B>, the expected total size of the contents from the
|
||
|
|
<B>Content-Length</B> 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:
|
||
|
|
<PRE>proc httpProgress {token total current} {
|
||
|
|
upvar #0 $token state
|
||
|
|
}</PRE>
|
||
|
|
<P><DT><A NAME="M20"><B>-query</B> <I>query</I></A><DD>
|
||
|
|
This flag causes <B>::http::geturl</B> to do a POST request that passes the
|
||
|
|
<I>query</I> to the server. The <I>query</I> must be a x-url-encoding
|
||
|
|
formatted query. The <B>::http::formatQuery</B> procedure can be used to
|
||
|
|
do the formatting.
|
||
|
|
<P><DT><A NAME="M21"><B>-queryblocksize</B> <I>size</I></A><DD>
|
||
|
|
The blocksize used when posting query data to the URL.
|
||
|
|
At most
|
||
|
|
<I>size</I>
|
||
|
|
bytes are written at once. After each block, a call to the
|
||
|
|
<B>-queryprogress</B>
|
||
|
|
callback is made (if that option is specified).
|
||
|
|
<P><DT><A NAME="M22"><B>-querychannel</B> <I>channelID</I></A><DD>
|
||
|
|
This flag causes <B>::http::geturl</B> to do a POST request that passes the
|
||
|
|
data contained in <I>channelID</I> to the server. The data contained in <I>channelID</I> must be a x-url-encoding
|
||
|
|
formatted query unless the <B>-type</B> option below is used.
|
||
|
|
If a Content-Length header is not specified via the <B>-headers</B> options,
|
||
|
|
<B>::http::geturl</B> attempts to determine the size of the post data
|
||
|
|
in order to create that header. If it is
|
||
|
|
unable to determine the size, it returns an error.
|
||
|
|
<P><DT><A NAME="M23"><B>-queryprogress</B> <I>callback</I></A><DD>
|
||
|
|
The <I>callback</I> is made after each transfer of data to the URL
|
||
|
|
(i.e. POST) and acts exactly like the <B>-progress</B> option (the
|
||
|
|
callback format is the same).
|
||
|
|
<P><DT><A NAME="M24"><B>-timeout</B> <I>milliseconds</I></A><DD>
|
||
|
|
If <I>milliseconds</I> is non-zero, then <B>::http::geturl</B> sets up a timeout
|
||
|
|
to occur after the specified number of milliseconds.
|
||
|
|
A timeout results in a call to <B>::http::reset</B> and to
|
||
|
|
the <B>-command</B> callback, if specified.
|
||
|
|
The return value of <B>::http::status</B> is <B>timeout</B>
|
||
|
|
after a timeout has occurred.
|
||
|
|
<P><DT><A NAME="M25"><B>-type</B> <I>mime-type</I></A><DD>
|
||
|
|
Use <I>mime-type</I> as the <B>Content-Type</B> value, instead of the
|
||
|
|
default value (<B>application/x-www-form-urlencoded</B>) during a
|
||
|
|
POST operation.
|
||
|
|
<P><DT><A NAME="M26"><B>-validate</B> <I>boolean</I></A><DD>
|
||
|
|
If <I>boolean</I> is non-zero, then <B>::http::geturl</B> 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
|
||
|
|
<B>state(meta) </B> variable after the transaction. See the STATE
|
||
|
|
ARRAY section for details.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M27"><B>::http::formatQuery</B> <I>key value</I> ?<I>key value</I> ...?</A><DD>
|
||
|
|
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
|
||
|
|
<B>-query</B> value passed to <B>::http::geturl</B>.
|
||
|
|
<P><DT><A NAME="M28"><B>::http::reset</B> <I>token</I> ?<I>why</I>?</A><DD>
|
||
|
|
This command resets the HTTP transaction identified by <I>token</I>, if
|
||
|
|
any. This sets the <B>state(status)</B> value to <I>why</I>, which defaults to <B>reset</B>, and then calls the registered <B>-command</B> callback.
|
||
|
|
<P><DT><A NAME="M29"><B>::http::wait</B> <I>token</I></A><DD>
|
||
|
|
This is a convenience procedure that blocks and waits for the
|
||
|
|
transaction to complete. This only works in trusted code because it
|
||
|
|
uses <B><A HREF="../TkCmd/vwait.htm">vwait</A></B>. Also, it's not useful for the case where
|
||
|
|
<B>::http::geturl</B> is called <I>without</I> the <B>-command</B> option
|
||
|
|
because in this case the <B>::http::geturl</B> call doesn't return
|
||
|
|
until the HTTP transaction is complete, and thus there's nothing to
|
||
|
|
wait for.
|
||
|
|
<P><DT><A NAME="M30"><B>::http::data</B> <I>token</I></A><DD>
|
||
|
|
This is a convenience procedure that returns the <B>body</B> element
|
||
|
|
(i.e., the URL data) of the state array.
|
||
|
|
<P><DT><A NAME="M31"><B>::http::error</B> <I>token</I></A><DD>
|
||
|
|
This is a convenience procedure that returns the <B><A HREF="../TkCmd/error.htm">error</A></B> element
|
||
|
|
of the state array.
|
||
|
|
<P><DT><A NAME="M32"><B>::http::status</B> <I>token</I></A><DD>
|
||
|
|
This is a convenience procedure that returns the <B>status</B> element of
|
||
|
|
the state array.
|
||
|
|
<P><DT><A NAME="M33"><B>::http::code</B> <I>token</I></A><DD>
|
||
|
|
This is a convenience procedure that returns the <B>http</B> element of the
|
||
|
|
state array.
|
||
|
|
<P><DT><A NAME="M34"><B>::http::ncode</B> <I>token</I></A><DD>
|
||
|
|
This is a convenience procedure that returns just the numeric return
|
||
|
|
code (200, 404, etc.) from the <B>http</B> element of the state array.
|
||
|
|
<P><DT><A NAME="M35"><B>::http::size</B> <I>token</I></A><DD>
|
||
|
|
This is a convenience procedure that returns the <B>currentsize</B>
|
||
|
|
element of the state array, which represents the number of bytes
|
||
|
|
received from the URL in the <B>::http::geturl</B> call.
|
||
|
|
<P><DT><A NAME="M36"><B>::http::cleanup</B> <I>token</I></A><DD>
|
||
|
|
This procedure cleans up the state associated with the connection
|
||
|
|
identified by <I>token</I>. After this call, the procedures
|
||
|
|
like <B>::http::data</B> cannot be used to get information
|
||
|
|
about the operation. It is <I>strongly</I> recommended that you call
|
||
|
|
this function after you're done with a given HTTP request. Not doing
|
||
|
|
so will result in memory not being freed, and if your app calls
|
||
|
|
<B>::http::geturl</B> enough times, the memory leak could cause a
|
||
|
|
performance hit...or worse.
|
||
|
|
<P><DT><A NAME="M37"><B>::http::register</B> <I>proto port command</I></A><DD>
|
||
|
|
This procedure allows one to provide custom HTTP transport types
|
||
|
|
such as HTTPS, by registering a prefix, the default port, and the
|
||
|
|
command to execute to create the Tcl <B>channel</B>. E.g.:
|
||
|
|
<PRE>package require http
|
||
|
|
package require tls
|
||
|
|
|
||
|
|
http::register https 443 ::tls::socket
|
||
|
|
|
||
|
|
set token [http::geturl https://my.secure.site/]</PRE>
|
||
|
|
<P><DT><A NAME="M38"><B>::http::unregister</B> <I>proto</I></A><DD>
|
||
|
|
This procedure unregisters a protocol handler that was previously
|
||
|
|
registered via <B>http::register</B>.
|
||
|
|
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M39">ERRORS</A></H3>
|
||
|
|
The <B>http::geturl</B> procedure will raise errors in the following cases:
|
||
|
|
invalid command line options,
|
||
|
|
an invalid URL,
|
||
|
|
a URL on a non-existent host,
|
||
|
|
or a URL at a bad port on an existing host.
|
||
|
|
These errors mean that it
|
||
|
|
cannot even start the network transaction.
|
||
|
|
It will also raise an error if it gets an I/O error while
|
||
|
|
writing out the HTTP request header.
|
||
|
|
For synchronous <B>::http::geturl</B> calls (where <B>-command</B> is
|
||
|
|
not specified), it will raise an error if it gets an I/O error while
|
||
|
|
reading the HTTP reply headers or data. Because <B>::http::geturl</B>
|
||
|
|
doesn't return a token in these cases, it does all the required
|
||
|
|
cleanup and there's no issue of your app having to call
|
||
|
|
<B>::http::cleanup</B>.
|
||
|
|
<P>
|
||
|
|
For asynchronous <B>::http::geturl</B> calls, all of the above error
|
||
|
|
situations apply, except that if there's any error while
|
||
|
|
reading the
|
||
|
|
HTTP reply headers or data, no exception is thrown. This is because
|
||
|
|
after writing the HTTP headers, <B>::http::geturl</B> returns, and the
|
||
|
|
rest of the HTTP transaction occurs in the background. The command
|
||
|
|
callback can check if any error occurred during the read by calling
|
||
|
|
<B>::http::status</B> to check the status and if it's <I>error</I>,
|
||
|
|
calling <B>::http::error</B> to get the error message.
|
||
|
|
<P>
|
||
|
|
Alternatively, if the main program flow reaches a point where it needs
|
||
|
|
to know the result of the asynchronous HTTP request, it can call
|
||
|
|
<B>::http::wait</B> and then check status and error, just as the
|
||
|
|
callback does.
|
||
|
|
<P>
|
||
|
|
In any case, you must still call
|
||
|
|
<B>http::cleanup</B> to delete the state array when you're done.
|
||
|
|
<P>
|
||
|
|
There are other possible results of the HTTP transaction
|
||
|
|
determined by examining the status from <B>http::status</B>.
|
||
|
|
These are described below.
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M40">ok</A><DD>
|
||
|
|
If the HTTP transaction completes entirely, then status will be <B>ok</B>.
|
||
|
|
However, you should still check the <B>http::code</B> value to get
|
||
|
|
the HTTP status. The <B>http::ncode</B> procedure provides just
|
||
|
|
the numeric error (e.g., 200, 404 or 500) while the <B>http::code</B>
|
||
|
|
procedure returns a value like "HTTP 404 File not found".
|
||
|
|
<P><DT><A NAME="M41">eof</A><DD>
|
||
|
|
If the server closes the socket without replying, then no error
|
||
|
|
is raised, but the status of the transaction will be <B><A HREF="../TkCmd/eof.htm">eof</A></B>.
|
||
|
|
<P><DT><A NAME="M42">error</A><DD>
|
||
|
|
The error message will also be stored in the <B><A HREF="../TkCmd/error.htm">error</A></B> status
|
||
|
|
array element, accessible via <B>::http::error</B>.
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
Another error possibility is that <B>http::geturl</B> 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 <B>posterror</B> status array
|
||
|
|
element and then <B>http::geturl</B> attempts to complete the
|
||
|
|
transaction.
|
||
|
|
If it can read the server's response
|
||
|
|
it will end up with an <B>ok</B> status, otherwise it will have
|
||
|
|
an <B><A HREF="../TkCmd/eof.htm">eof</A></B> status.
|
||
|
|
|
||
|
|
<H3><A NAME="M43">STATE ARRAY</A></H3>
|
||
|
|
The <B>::http::geturl</B> procedure returns a <I>token</I> 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:
|
||
|
|
<PRE>upvar #0 $token state</PRE>
|
||
|
|
Once the data associated with the url is no longer needed, the state
|
||
|
|
array should be unset to free up storage.
|
||
|
|
The <B>http::cleanup</B> procedure is provided for that purpose.
|
||
|
|
The following elements of
|
||
|
|
the array are supported:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M44"><B>body</B></A><DD>
|
||
|
|
The contents of the URL. This will be empty if the <B>-channel</B>
|
||
|
|
option has been specified. This value is returned by the <B>::http::data</B> command.
|
||
|
|
<P><DT><A NAME="M45"><B>charset</B></A><DD>
|
||
|
|
The value of the charset attribute from the <B>Content-Type</B> meta-data
|
||
|
|
value. If none was specified, this defaults to the RFC standard
|
||
|
|
<B>iso8859-1</B>, or the value of <B>$::http::defaultCharset</B>. Incoming
|
||
|
|
text data will be automatically converted from this charset to utf-8.
|
||
|
|
<P><DT><A NAME="M46"><B>coding</B></A><DD>
|
||
|
|
A copy of the <B>Content-Encoding</B> meta-data value.
|
||
|
|
<P><DT><A NAME="M47"><B>currentsize</B></A><DD>
|
||
|
|
The current number of bytes fetched from the URL.
|
||
|
|
This value is returned by the <B>::http::size</B> command.
|
||
|
|
<P><DT><A NAME="M48"><B>error</B></A><DD>
|
||
|
|
If defined, this is the error string seen when the HTTP transaction
|
||
|
|
was aborted.
|
||
|
|
<P><DT><A NAME="M49"><B>http</B></A><DD>
|
||
|
|
The HTTP status reply from the server. This value
|
||
|
|
is returned by the <B>::http::code</B> command. The format of this value is:
|
||
|
|
<PRE><I>HTTP/1.0 code string</I></PRE>
|
||
|
|
The <I>code</I> 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
|
||
|
|
<B>Location</B> meta-data specifies a new URL that contains the
|
||
|
|
requested information.
|
||
|
|
<P><DT><A NAME="M50"><B>meta</B></A><DD>
|
||
|
|
The HTTP protocol returns meta-data that describes the URL contents.
|
||
|
|
The <B>meta</B> 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:
|
||
|
|
<PRE>array set meta $state(meta)</PRE>
|
||
|
|
Some of the meta-data keys are listed below, but the HTTP standard defines
|
||
|
|
more, and servers are free to add their own.
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M51"><B>Content-Type</B></A><DD>
|
||
|
|
The type of the URL contents. Examples include <B>text/html</B>,
|
||
|
|
<B>image/gif,</B> <B>application/postscript</B> and
|
||
|
|
<B>application/x-tcl</B>.
|
||
|
|
<P><DT><A NAME="M52"><B>Content-Length</B></A><DD>
|
||
|
|
The advertised size of the contents. The actual size obtained by
|
||
|
|
<B>::http::geturl</B> is available as <B>state(size)</B>.
|
||
|
|
<P><DT><A NAME="M53"><B>Location</B></A><DD>
|
||
|
|
An alternate URL that contains the requested data.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M54"><B>posterror</B></A><DD>
|
||
|
|
The error, if any, that occurred while writing
|
||
|
|
the post query data to the server.
|
||
|
|
<P><DT><A NAME="M55"><B>status</B></A><DD>
|
||
|
|
Either <B>ok</B>, for successful completion, <B>reset</B> for
|
||
|
|
user-reset, <B>timeout</B> if a timeout occurred before the transaction
|
||
|
|
could complete, or <B><A HREF="../TkCmd/error.htm">error</A></B> for an error condition. During the
|
||
|
|
transaction this value is the empty string.
|
||
|
|
<P><DT><A NAME="M56"><B>totalsize</B></A><DD>
|
||
|
|
A copy of the <B>Content-Length</B> meta-data value.
|
||
|
|
<P><DT><A NAME="M57"><B>type</B></A><DD>
|
||
|
|
A copy of the <B>Content-Type</B> meta-data value.
|
||
|
|
<P><DT><A NAME="M58"><B>url</B></A><DD>
|
||
|
|
The requested URL.
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M59">EXAMPLE</A></H3>
|
||
|
|
<PRE># 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
|
||
|
|
}</PRE>
|
||
|
|
<H3><A NAME="M60">SEE ALSO</A></H3>
|
||
|
|
<B>safe</B>, <B><A HREF="../TkCmd/socket.htm">socket</A></B>, <B>safesock</B>
|
||
|
|
<H3><A NAME="M61">KEYWORDS</A></H3>
|
||
|
|
<A href="../Keywords/S.htm#security policy">security policy</A>, <A href="../Keywords/S.htm#socket">socket</A>
|
||
|
|
<HR><PRE>
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Sun Microsystems, Inc.
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1998-2000 by Ajuba Solutions.
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||
|
|
</BODY></HTML>
|