NAME
       Http  -  Client-side implementation of the HTTP/1.0 proto-
       col.

SYNOPSIS
       package require http ?2.0?

       ::http::config ?options?

       ::http::geturl url ?options?

       ::http::formatQuery list

       ::http::reset token

       ::http::wait token

       ::http::status token

       ::http::size token

       ::http::code token

       ::http::data token


DESCRIPTION
       The http 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 com-
       patible with the Safesock security policy, so  it  can  be
       used  by  untrusted  applets  to  do  URL  fetching from a
       restricted set of hosts.

       The ::http::geturl procedure does a HTTP transaction.  Its
       options   determine  whether a GET, POST, or HEAD transac-
       tion is performed.  The return value of ::http::geturl  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.

       If the -command option is specified, then the HTTP  opera-
       tion  is  done  in the background.  ::http::geturl 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 applica-
       tions, the  caller  can  use  ::http::wait  after  calling
       ::http::geturl to start the event loop.
COMMANDS
       ::http::config ?options?
              The ::http::config 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  configura-
              tion  is  returned.  If a single argument is speci-
              fied, then it should be one of the flags  described
              below.  In this case the current value of that set-
              ting is returned.  Otherwise, the options should be
              a  set of flags and values that define the configu-
              ration:

              -accept mimetypes
                     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/*".

              -proxyhost hostname
                     The name of the proxy host, if any.  If this
                     value  is  the empty string, the URL host is
                     contacted directly.

              -proxyport number
                     The proxy port number.

              -proxyfilter command
                     The command is a callback that is made  dur-
                     ing  ::http::geturl  to determine if a proxy
                     is required for a given host.  One argument,
                     a  host name, is added to command when it is
                     invoked.  If a proxy is required, the  call-
                     back  should  return a two element list con-
                     taining the proxy  server  and  proxy  port.
                     Otherwise  the filter should return an empty
                     list.  The default filter returns the values
                     of the -proxyhost and -proxyport settings if
                     they are non-empty.

              -useragent string
                     The value of the User-Agent  header  in  the
                     HTTP  request.   The  default  is  "Tcl http
                     client package 2.0."

       ::http::geturl url ?options?
              The ::http::geturl  command is the  main  procedure
              in  the  package.   The -query option causes a POST
              operation and the -validate option  causes  a  HEAD
              operation; otherwise, a GET operation is performed.
              The ::http::geturl command returns  a  token  value
              that  can  be  used  to  get  information about the
              transaction.   See  the  STATE  ARRAY  section  for
              details.   The  ::http::geturl command blocks until
              the operation completes, unless the -command option
              specifies  a callback that is invoked when the HTTP
              transaction completes.  ::http::geturl  takes  sev-
              eral options:

              -blocksize size
                     The blocksize used when reading the URL.  At
                     most size bytes are  read  at  once.   After
                     each block, a call to the -progress callback
                     is made.

              -channel name
                     Copy  the  URL  contents  to  channel   name
                     instead of saving it in state(body).

              -command callback
                     Invoke  callback  after the HTTP transaction
                     completes.      This      option      causes
                     ::http::geturl  to  return immediately.  The
                     callback gets an additional argument that is
                     the token returned from ::http::geturl. This
                     token is  the  name  of  an  array  that  is
                     described  in the STATE ARRAY section.  Here
                     is a template for the callback:
                             proc httpCallback {token} {
                                 upvar #0 $token state
                                 # Access state as a Tcl array
                             }

              -handler callback
                     Invoke callback whenever HTTP data is avail-
                     able;  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  token  returned   from
                     ::http::geturl.   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 call-
                     back:
                             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
                             }
              -headers keyvaluelist
                     This option is used to add extra headers  to
                     the HTTP request.  The keyvaluelist argument
                     must be a list with an even number  of  ele-
                     ments  that  alternate between keys and val-
                     ues.  The keys become  header  field  names.
                     Newlines are stripped from the values so the
                     header cannot be corrupted.  For example, if
                     keyvaluelist  is  Pragma  no-cache  then the
                     following header is  included  in  the  HTTP
                     request:
                     Pragma: no-cache

              -progress callback
                     The  callback is made after each transfer of
                     data from the URL.  The callback gets  three
                     additional   arguments:   the   token   from
                     ::http::geturl, the expected total  size  of
                     the  contents  from the Content-Length meta-
                     data, and the current number of bytes trans-
                     ferred  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:
                             proc httpProgress {token total current} {
                                 upvar #0 $token state
                             }

              -query query
                     This flag causes ::http::geturl to do a POST
                     request that passes the query to the server.
                     The query must be a x-url-encoding formatted
                     query.   The  ::http::formatQuery  procedure
                     can be used to do the formatting.

              -timeout milliseconds
                     If   milliseconds    is    non-zero,    then
                     ::http::geturl  sets  up  a timeout to occur
                     after the specified number of  milliseconds.
                     A timeout results in a call to ::http::reset
                     and to the -command callback, if  specified.
                     The  return value of ::http::status is time-
                     out after a timeout has occurred.

              -validate boolean
                     If boolean is non-zero, then  ::http::geturl
                     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  state(meta)
                     variable  after  the  transaction.   See the
                     STATE ARRAY section for details.
       ::http::formatQuery key value ?key value ...?
              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 -query value passed to ::http::geturl.

       ::http::reset token ?why?
              This command resets the HTTP transaction identified
              by token, if  any.   This  sets  the  state(status)
              value  to  why,  which  defaults to reset, and then
              calls the registered -command callback.

       ::http::wait token
              This is a convenience  procedure  that  blocks  and
              waits  for  the transaction to complete.  This only
              works in trusted code because it uses vwait.

       ::http::data token
              This is a convenience procedure  that  returns  the
              body  element  (i.e.,  the  URL  data) of the state
              array.

       ::http::status token
              This is a convenience procedure  that  returns  the
              status element of the state array.

       ::http::code token
              This  is  a  convenience procedure that returns the
              http element of the state array.

       ::http::size token
              This is a convenience procedure  that  returns  the
              currentsize element of the state array.

STATE ARRAY
       The  ::http::geturl  procedure returns a token 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:
              upvar #0 $token state
       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:

              body   The contents of the URL.  This will be empty
                     if  the  -channel option has been specified.
                     This value is returned by  the  ::http::data
                     command.

              currentsize
                     The current number of bytes fetched from the
                     URL.   This  value  is   returned   by   the
                     ::http::size command.

              error  If  defined,  this  is the error string seen
                     when the HTTP transaction was aborted.

              http   The HTTP status reply from the server.  This
                     value  is  returned by the ::http::code com-
                     mand.  The format of this value is:
                             code string
                     The code 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 Location meta-data
                     specifies   a  new  URL  that  contains  the
                     requested information.

              meta   The HTTP  protocol  returns  meta-data  that
                     describes  the  URL contents.  The meta ele-
                     ment 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:
                             array set meta $state(meta)
                     Some of the meta-data keys are listed below,
                     but the  HTTP  standard  defines  more,  and
                     servers are free to add their own.

                      Content-Type
                             The type of the URL contents.  Exam-
                             ples include  text/html,  image/gif,
                             application/postscript  and applica-
                             tion/x-tcl.

                      Content-Length
                             The advertised size of the contents.
                             The    actual   size   obtained   by
                             ::http::geturl   is   available   as
                             state(size).

                      Location
                             An  alternate  URL that contains the
                             requested data.

              status Either ok, for successful completion,  reset
                     for user-reset, or error for an error condi-
                     tion.  During the transaction this value  is
                     the empty string.

              totalsize
                     A   copy  of  the  Content-Length  meta-data
                     value.

              type   A copy of the Content-Type meta-data  value.
              url    The requested URL.

EXAMPLE
              # 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
              }



SEE ALSO
       safe(n), socket(n), safesock(n)

KEYWORDS
       security policy, socket
