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

SYNOPSIS
       package require http ?2.4?

       ::http::config ?options?

       ::http::geturl url ?options?

       ::http::formatQuery key value ?key value ...?

       ::http::reset token ?why?

       ::http::wait token

       ::http::status token

       ::http::size token

       ::http::code token

       ::http::ncode token

       ::http::data token

       ::http::error token

       ::http::cleanup token

       ::http::register proto port command

       ::http::unregister proto


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. This package can be  extended  to
       support  additional  HTTP  transport  protocols,  such  as
       HTTPS,  by  providing  a  custom   socket   command,   via
       http::register.

       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
       applications,  the caller can use ::http::wait after call-
       ing ::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.4."

       ::http::geturl url ?options?
              The ::http::geturl command is the main procedure in
              the package.  The -query option causes a POST oper-
              ation and the -validate option causes a HEAD opera-
              tion; otherwise, a GET operation is performed.  The
              ::http::geturl  command  returns a token value that
              can be used to get information about  the  transac-
              tion.   See  the STATE ARRAY and ERRORS 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:

              -binary boolean
                     Specifies whether to force interpreting  the
                     url  data as binary.  Normally this is auto-
                     detected (anything not beginning with a text
                     content  type  or  whose content encoding is
                     gzip or compress is considered binary data).

              -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 (if that option is specified).

              -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.

              -queryblocksize size
                     The blocksize used when posting  query  data
                     to  the URL.  At most size bytes are written
                     at once.  After each block, a  call  to  the
                     -queryprogress  callback  is  made  (if that
                     option is specified).

              -querychannel channelID
                     This flag causes ::http::geturl to do a POST
                     request  that  passes  the data contained in
                     channelID to the server. The data  contained
                     in  channelID  must be a x-url-encoding for-
                     matted query unless the -type  option  below
                     is  used.  If a Content-Length header is not
                     specified   via   the   -headers    options,
                     ::http::geturl  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.

              -queryprogress callback
                     The callback is made after each transfer  of
                     data to the URL (i.e. POST) and acts exactly
                     like the -progress option (the callback for-
                     mat is the same).

              -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.

              -type mime-type
                     Use  mime-type  as  the  Content-Type value,
                     instead of the default value (application/x-
                     www-form-urlencoded)  during  a  POST opera-
                     tion.

              -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.  Also,
              it's  not  useful for the case where ::http::geturl
              is called without the -command  option  because  in
              this  case  the  ::http::geturl call doesn't return
              until the HTTP transaction is  complete,  and  thus
              there's nothing to wait for.

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

       ::http::error token
              This  is  a  convenience procedure that returns the
              error element 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::ncode token
              This is a convenience procedure that  returns  just
              the  numeric  return code (200, 404, etc.) from the
              http element of the state array.

       ::http::size token
              This is a convenience procedure  that  returns  the
              currentsize  element of the state array, which rep-
              resents the number of bytes received from  the  URL
              in the ::http::geturl call.

       ::http::cleanup token
              This  procedure cleans up the state associated with
              the connection identified  by  token.   After  this
              call,  the  procedures  like ::http::data cannot be
              used to get information about the operation.  It is
              strongly  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 ::http::geturl enough times,  the
              memory  leak  could  cause  a  performance hit...or
              worse.

       ::http::register proto port command
              This procedure allows one to  provide  custom  HTTP
              transport  types  such  as  HTTPS, by registering a
              prefix, the default port, and the command  to  exe-
              cute to create the Tcl channel. E.g.:
                     package require http
                     package require tls

                     http::register https 443 ::tls::socket

                     set token [http::geturl https://my.secure.site/]

       ::http::unregister proto
              This  procedure unregisters a protocol handler that
              was previously registered via http::register.


ERRORS
       The http::geturl procedure will raise errors in  the  fol-
       lowing  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  ::http::geturl  calls
       (where  -command is not specified), it will raise an error
       if it gets an I/O error while reading the HTTP reply head-
       ers  or  data.   Because  ::http::geturl  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
       ::http::cleanup.

       For asynchronous ::http::geturl 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 head-
       ers, ::http::geturl returns, and  the  rest  of  the  HTTP
       transaction  occurs  in the background.  The command call-
       back can check if any error occurred during  the  read  by
       calling  ::http::status  to  check  the  status and if its
       error, calling ::http::error to get the error message.

       Alternatively, if the main program flow  reaches  a  point
       where it needs to know the result of the asynchronous HTTP
       request, it can call ::http::wait and  then  check  status
       and error, just as the callback does.

       In  any  case, you must still call http::cleanup to delete
       the state array when you're done.

       There are other possible results of the  HTTP  transaction
       determined  by  examining  the  status  from http::status.
       These are described below.

       ok     If the HTTP transaction  completes  entirely,  then
              status will be ok.  However, you should still check
              the http::code value to get the HTTP  status.   The
              http::ncode  procedure  provides  just  the numeric
              error (e.g., 200, 404 or 500) while the  http::code
              procedure  returns  a value like "HTTP 404 File not
              found".

       eof    If the server closes the socket  without  replying,
              then  no  error  is  raised,  but the status of the
              transaction will be eof.

       error  The error message will also be stored in the  error
              status array element, accessible via ::http::error.

       Another error possibility is that http::geturl  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 posterror status array element and then
       http::geturl attempts to complete the transaction.  If  it
       can  read  the server's response it will end up with an ok
       status, otherwise it will have an eof status.


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
       http::cleanup procedure is provided for that purpose.  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.

              charset
                     The  value of the charset attribute from the
                     Content-Type meta-data value.  If  none  was
                     specified, this defaults to the RFC standard
                     iso8859-1, or the value of $::http::default-
                     Charset.   Incoming  text data will be auto-
                     matically converted  from  this  charset  to
                     utf-8.

              coding A  copy  of  the  Content-Encoding meta-data
                     value.

              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:
                             HTTP/1.0 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.

              posterror
                     The error, if any, that occurred while writ-
                     ing the post query data to the server.

              status Either ok, for successful completion,  reset
                     for   user-reset,   timeout   if  a  timeout
                     occurred before the transaction  could  com-
                     plete,  or  error  for  an  error condition.
                     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
