1http(n)                      Tcl Bundled Packages                      http(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       http - Client-side implementation of the HTTP/1.1 protocol
9

SYNOPSIS

11       package require http ?2.8?
12
13       ::http::config ?-option value ...?
14
15       ::http::geturl url ?-option value ...?
16
17       ::http::formatQuery key value ?key value ...?
18
19       ::http::quoteString value
20
21       ::http::reset token ?why?
22
23       ::http::wait token
24
25       ::http::status token
26
27       ::http::size token
28
29       ::http::code token
30
31       ::http::ncode token
32
33       ::http::meta token
34
35       ::http::data token
36
37       ::http::error token
38
39       ::http::cleanup token
40
41       ::http::register proto port command
42
43       ::http::registerError port ?message?
44
45       ::http::unregister proto
46______________________________________________________________________________
47

DESCRIPTION

49       The  http package provides the client side of the HTTP/1.1 protocol, as
50       defined in RFC 7230 to RFC 7235, which supersede RFC 2616.  The package
51       implements  the  GET, POST, and HEAD operations of HTTP/1.1.  It allows
52       configuration of a proxy host to get through firewalls.  The package is
53       compatible  with  the  Safesock  security  policy, so it can be used by
54       untrusted applets to do URL fetching from a restricted  set  of  hosts.
55       This  package can be extended to support additional HTTP transport pro‐
56       tocols, such as HTTPS,  by  providing  a  custom  socket  command,  via
57       ::http::register.
58
59       The  ::http::geturl  procedure  does  a  HTTP transaction.  Its options
60       determine whether a GET, POST, or HEAD transaction is  performed.   The
61       return  value  of  ::http::geturl  is a token for the transaction.  The
62       value is also the name of an array in the ::http  namespace  that  con‐
63       tains  state  information  about the transaction.  The elements of this
64       array are described in the STATE ARRAY section.
65
66       If the -command option is specified, then the HTTP operation is done in
67       the  background.   ::http::geturl  returns immediately after generating
68       the HTTP request and the callback is invoked when the transaction  com‐
69       pletes.   For  this  to work, the Tcl event loop must be active.  In Tk
70       applications this is always true.  For pure-Tcl applications, the call‐
71       er can use ::http::wait after calling ::http::geturl to start the event
72       loop.
73

COMMANDS

75       ::http::config ?options?
76              The ::http::config command is used to set and query the name  of
77              the  proxy  server and port, and the User-Agent name used in the
78              HTTP requests.  If no options are specified,  then  the  current
79              configuration  is  returned.  If a single argument is specified,
80              then it should be one of the flags  described  below.   In  this
81              case  the current value of that setting is returned.  Otherwise,
82              the options should be a set of flags and values that define  the
83              configuration:
84
85              -accept mimetypes
86                     The  Accept  header  of the request.  The default is */*,
87                     which means that all types  of  documents  are  accepted.
88                     Otherwise  you  can supply a comma-separated list of mime
89                     type patterns that you are willing to receive.  For exam‐
90                     ple, “image/gif, image/jpeg, text/*”.
91
92              -pipeline boolean
93                     Specifies  whether  HTTP/1.1 transactions on a persistent
94                     socket will be pipelined.   See  the  PERSISTENT  SOCKETS
95                     section for details. The default is 1.
96
97              -postfresh boolean
98                     Specifies  whether requests that use the POST method will
99                     always use a  fresh  socket,  overriding  the  -keepalive
100                     option of command http::geturl.  See the PERSISTENT SOCK‐
101                     ETS section for details.  The default is 0.
102
103              -proxyhost hostname
104                     The name of the proxy host, if any.  If this value is the
105                     empty string, the URL host is contacted directly.
106
107              -proxyport number
108                     The proxy port number.
109
110              -proxyfilter command
111                     The   command   is   a   callback  that  is  made  during
112                     ::http::geturl to determine if a proxy is required for  a
113                     given  host.  One argument, a host name, is added to com‐
114                     mand when it is invoked.  If a  proxy  is  required,  the
115                     callback  should return a two-element list containing the
116                     proxy server and proxy port.  Otherwise the filter should
117                     return  an  empty  list.   The default filter returns the
118                     values of the -proxyhost and -proxyport settings if  they
119                     are non-empty.
120
121              -repost boolean
122                     Specifies  what to do if a POST request over a persistent
123                     connection fails because the server has  half-closed  the
124                     connection.   If  boolean true, the request will be auto‐
125                     matically retried; if boolean false it will not, and  the
126                     application  that  uses  http::geturl is expected to seek
127                     user confirmation before retrying the  POST.   The  value
128                     true  should  be  used only under certain conditions. See
129                     the PERSISTENT SOCKETS section for details.  The  default
130                     is 0.
131
132              -urlencoding encoding
133                     The  encoding  used  for  creating the x-url-encoded URLs
134                     with ::http::formatQuery  and  ::http::quoteString.   The
135                     default  is  utf-8,  as  specified by RFC 2718.  Prior to
136                     http 2.5 this was unspecified, and that behavior  can  be
137                     returned  by  specifying  the empty string ({}), although
138                     iso8859-1 is recommended to restore similar behavior  but
139                     without  the  ::http::formatQuery  or ::http::quoteString
140                     throwing an error processing non-latin-1 characters.
141
142              -useragent string
143                     The value of the User-Agent header in the  HTTP  request.
144                     In  an unsafe interpreter, the default value depends upon
145                     the operating system, and the version numbers of http and
146                     Tcl,  and is (for example) “Mozilla/5.0 (Windows; U; Win‐
147                     dows NT 10.0) http/2.8.12 Tcl/8.6.8”.  A safe interpreter
148                     cannot determine its operating system, and so the default
149                     in a safe interpreter is to use a Windows 10  value  with
150                     the current version numbers of http and Tcl.
151
152              -zip boolean
153                     If  the  value  is boolean true, then by default requests
154                     will send a  header  “Accept-Encoding:  gzip,deflate,com‐
155                     press”.   If  the value is boolean false, then by default
156                     this header will not be sent.  In either case the default
157                     can  be overridden for an individual request by supplying
158                     a custom Accept-Encoding header in the -headers option of
159                     http::geturl. The default is 1.
160
161       ::http::geturl url ?options?
162              The ::http::geturl command is the main procedure in the package.
163              The -query option causes a  POST  operation  and  the  -validate
164              option  causes  a  HEAD operation; otherwise, a GET operation is
165              performed.  The ::http::geturl command  returns  a  token  value
166              that  can be used to get information about the transaction.  See
167              the  STATE  ARRAY  and  ERRORS   section   for   details.    The
168              ::http::geturl  command  blocks  until  the operation completes,
169              unless the -command option specifies a callback that is  invoked
170              when  the HTTP transaction completes.  ::http::geturl takes sev‐
171              eral options:
172
173              -binary boolean
174                     Specifies whether to force interpreting the URL  data  as
175                     binary.   Normally  this  is  auto-detected (anything not
176                     beginning with a  text  content  type  or  whose  content
177                     encoding is gzip or compress is considered binary data).
178
179              -blocksize size
180                     The  block  size used when reading the URL.  At most size
181                     bytes are read at once.  After each block, a call to  the
182                     -progress callback is made (if that option is specified).
183
184              -channel name
185                     Copy  the  URL contents to channel name instead of saving
186                     it in state(body).
187
188              -command callback
189                     Invoke callback after  the  HTTP  transaction  completes.
190                     This  option causes ::http::geturl to return immediately.
191                     The callback gets an  additional  argument  that  is  the
192                     token  returned  from  ::http::geturl.  This token is the
193                     name of an array that is described  in  the  STATE  ARRAY
194                     section.  Here is a template for the callback:
195
196                            proc httpCallback {token} {
197                                upvar #0 $token state
198                                # Access state as a Tcl array
199                            }
200
201              -handler callback
202                     Invoke  callback  whenever  HTTP  data  is  available; if
203                     present, nothing else will be done with  the  HTTP  data.
204                     This  procedure gets two additional arguments: the socket
205                     for  the  HTTP  data  and   the   token   returned   from
206                     ::http::geturl.   The token is the name of a global array
207                     that is described in the STATE ARRAY section.  The proce‐
208                     dure  is expected to return the number of bytes read from
209                     the socket.  Here is a template for the callback:
210
211                            proc httpHandlerCallback {socket token} {
212                                upvar #0 $token state
213                                # Access socket, and state as a Tcl array
214                                # For example...
215                                ...
216                                set data [read $socket 1000]
217                                set nbytes [string length $data]
218                                ...
219                                return $nbytes
220                            }
221
222              -headers keyvaluelist
223                     This option is used to add headers not already  specified
224                     by  ::http::config to the HTTP request.  The keyvaluelist
225                     argument must be a list with an even number  of  elements
226                     that  alternate between keys and values.  The keys become
227                     header field names.  Newlines are stripped from the  val‐
228                     ues  so  the header cannot be corrupted.  For example, if
229                     keyvaluelist is Pragma no-cache then the following header
230                     is included in the HTTP request:
231
232                            Pragma: no-cache
233
234              -keepalive boolean
235                     If  boolean true, attempt to keep the connection open for
236                     servicing multiple requests.  Default is 0.
237
238              -method type
239                     Force the HTTP request  method  to  type.  ::http::geturl
240                     will  auto-select  GET,  POST  or  HEAD  based  on  other
241                     options, but this option enables  choices  like  PUT  and
242                     DELETE for webdav support.
243
244              -myaddr address
245                     Pass  an  specific local address to the underlying socket
246                     call in case multiple interfaces are available.
247
248              -progress callback
249                     The callback is made after each transfer of data from the
250                     URL.   The  callback gets three additional arguments: the
251                     token from ::http::geturl, the expected total size of the
252                     contents  from the Content-Length meta-data, and the cur‐
253                     rent number of bytes transferred so  far.   The  expected
254                     total  size  may be unknown, in which case zero is passed
255                     to the callback.  Here is a  template  for  the  progress
256                     callback:
257
258                            proc httpProgress {token total current} {
259                                upvar #0 $token state
260                            }
261
262              -protocol version
263                     Select  the  HTTP protocol version to use. This should be
264                     1.0 or 1.1 (the default). Should only  be  necessary  for
265                     servers  that  do  not  understand  or otherwise complain
266                     about HTTP/1.1.
267
268              -query query
269                     This flag causes ::http::geturl to do a POST request that
270                     passes  the  query to the server. The query must be an x-
271                     url-encoding formatted  query.   The  ::http::formatQuery
272                     procedure can be used to do the formatting.
273
274              -queryblocksize size
275                     The  block  size used when posting query data to the URL.
276                     At most size bytes  are  written  at  once.   After  each
277                     block,  a call to the -queryprogress callback is made (if
278                     that option is specified).
279
280              -querychannel channelID
281                     This flag causes ::http::geturl to do a POST request that
282                     passes the data contained in channelID to the server. The
283                     data contained in channelID  must  be  an  x-url-encoding
284                     formatted  query  unless  the -type option below is used.
285                     If a Content-Length  header  is  not  specified  via  the
286                     -headers  options,  ::http::geturl  attempts to determine
287                     the size of the post data in order to create that header.
288                     If  it  is  unable  to  determine the size, it returns an
289                     error.
290
291              -queryprogress callback
292                     The callback is made after each transfer of data  to  the
293                     URL  (i.e.  POST)  and  acts  exactly  like the -progress
294                     option (the callback format is the same).
295
296              -strict boolean
297                     Whether  to  enforce  RFC  3986  URL  validation  on  the
298                     request.  Default is 1.
299
300              -timeout milliseconds
301                     If  milliseconds is non-zero, then ::http::geturl sets up
302                     a timeout to occur after the  specified  number  of  mil‐
303                     liseconds.   A timeout results in a call to ::http::reset
304                     and to the -command callback, if specified.   The  return
305                     value  of  ::http::status  is timeout after a timeout has
306                     occurred.
307
308              -type mime-type
309                     Use mime-type as the Content-Type value, instead  of  the
310                     default  value (application/x-www-form-urlencoded) during
311                     a POST operation.
312
313              -validate boolean
314                     If boolean is non-zero, then ::http::geturl does an  HTTP
315                     HEAD  request.   This  request  returns  meta information
316                     about the URL, but the contents are  not  returned.   The
317                     meta  information  is available in the state(meta)  vari‐
318                     able after the transaction.  See the STATE ARRAY  section
319                     for details.
320
321       ::http::formatQuery key value ?key value ...?
322              This  procedure  does x-url-encoding of query data.  It takes an
323              even number of arguments that are the keys  and  values  of  the
324              query.  It encodes the keys and values, and generates one string
325              that has the proper & and = separators.  The result is  suitable
326              for the -query value passed to ::http::geturl.
327
328       ::http::quoteString value
329              This procedure does x-url-encoding of string.  It takes a single
330              argument and encodes it.
331
332       ::http::reset token ?why?
333              This command resets the HTTP transaction identified by token, if
334              any.   This  sets the state(status) value to why, which defaults
335              to reset, and then calls the registered -command callback.
336
337       ::http::wait token
338              This is a convenience procedure that blocks and  waits  for  the
339              transaction  to  complete.   This  only  works  in  trusted code
340              because it uses vwait.  Also, it is  not  useful  for  the  case
341              where  ::http::geturl  is  called  without  the  -command option
342              because in this case the ::http::geturl  call  does  not  return
343              until  the HTTP transaction is complete, and thus there is noth‐
344              ing to wait for.
345
346       ::http::data token
347              This is a convenience procedure that returns  the  body  element
348              (i.e., the URL data) of the state array.
349
350       ::http::error token
351              This  is  a convenience procedure that returns the error element
352              of the state array.
353
354       ::http::status token
355              This is a convenience procedure that returns the status  element
356              of the state array.
357
358       ::http::code token
359              This is a convenience procedure that returns the http element of
360              the state array.
361
362       ::http::ncode token
363              This is a convenience procedure that returns  just  the  numeric
364              return  code (200, 404, etc.) from the http element of the state
365              array.
366
367       ::http::size token
368              This is a convenience procedure  that  returns  the  currentsize
369              element of the state array, which represents the number of bytes
370              received from the URL in the ::http::geturl call.
371
372       ::http::meta token
373              This is a convenience procedure that returns the meta element of
374              the  state  array  which contains the HTTP response headers. See
375              below for an explanation of this element.
376
377       ::http::cleanup token
378              This procedure cleans up the state associated with  the  connec‐
379              tion  identified by token.  After this call, the procedures like
380              ::http::data cannot be used to get information about the  opera‐
381              tion.   It  is  strongly recommended that you call this function
382              after you are done with a given HTTP request.  Not doing so will
383              result  in  memory  not  being  freed,  and  if  your  app calls
384              ::http::geturl enough times, the memory leak could cause a  per‐
385              formance hit...or worse.
386
387       ::http::register proto port command
388              This procedure allows one to provide custom HTTP transport types
389              such as HTTPS, by registering a prefix, the  default  port,  and
390              the command to execute to create the Tcl channel. E.g.:
391
392                     package require http
393                     package require tls
394
395                     ::http::register https 443 ::tls::socket
396
397                     set token [::http::geturl https://my.secure.site/]
398
399       ::http::registerError port ?message?
400              This  procedure  allows a registered protocol handler to deliver
401              an error message for use by http.  Calling this command does not
402              raise an error. The command is useful when a registered protocol
403              detects an problem (for example,  an  invalid  TLS  certificate)
404              that  will  cause  an  error  to propagate to http.  The command
405              allows http to provide a precise error  message  rather  than  a
406              general one.  The command returns the value provided by the last
407              call with argument message, or the empty string if no such  call
408              has been made.
409
410       ::http::unregister proto
411              This  procedure  unregisters  a protocol handler that was previ‐
412              ously registered via ::http::register, returning a two-item list
413              of  the  default  port  and  handler command that was previously
414              installed (via ::http::register) if there was  such  a  handler,
415              and an error if there was no such handler.
416

ERRORS

418       The  ::http::geturl procedure will raise errors in the following cases:
419       invalid command line options, an invalid URL, a URL on  a  non-existent
420       host,  or  a  URL at a bad port on an existing host.  These errors mean
421       that it cannot even start the network transaction.  It will also  raise
422       an  error  if  it  gets an I/O error while writing out the HTTP request
423       header.  For synchronous ::http::geturl calls (where  -command  is  not
424       specified),  it will raise an error if it gets an I/O error while read‐
425       ing the HTTP reply headers or data.  Because  ::http::geturl  does  not
426       return  a  token  in  these cases, it does all the required cleanup and
427       there is no issue of your app having to call ::http::cleanup.
428
429       For asynchronous ::http::geturl calls, all of the  above  error  situa‐
430       tions  apply,  except that if there is any error while reading the HTTP
431       reply headers or data, no exception is thrown.  This is  because  after
432       writing  the  HTTP headers, ::http::geturl returns, and the rest of the
433       HTTP transaction occurs in the background.  The  command  callback  can
434       check  if  any error occurred during the read by calling ::http::status
435       to check the status and if its error, calling ::http::error to get  the
436       error message.
437
438       Alternatively,  if the main program flow reaches a point where it needs
439       to know the result of  the  asynchronous  HTTP  request,  it  can  call
440       ::http::wait  and  then  check  status  and error, just as the callback
441       does.
442
443       In any case, you must still call ::http::cleanup to  delete  the  state
444       array when you are done.
445
446       There  are other possible results of the HTTP transaction determined by
447       examining the status from ::http::status.  These are described below.
448
449       ok     If the HTTP transaction completes entirely, then status will  be
450              ok.   However,  you should still check the ::http::code value to
451              get the HTTP status.  The ::http::ncode procedure provides  just
452              the numeric error (e.g., 200, 404 or 500) while the ::http::code
453              procedure returns a value like “HTTP 404 File not found”.
454
455       eof    If the server closes the socket without replying, then no  error
456              is raised, but the status of the transaction will be eof.
457
458       error  The  error message will also be stored in the error status array
459              element, accessible via ::http::error.
460
461       Another error possibility is that ::http::geturl is unable to write all
462       the post query data to the server before the server responds and closes
463       the socket.  The error message is saved in the posterror  status  array
464       element  and then  ::http::geturl attempts to complete the transaction.
465       If it can read the server's response it will end up with an ok  status,
466       otherwise it will have an eof status.
467

STATE ARRAY

469       The ::http::geturl procedure returns a token that can be used to get to
470       the state of the HTTP transaction in the form of a Tcl array.  Use this
471       construct to create an easy-to-use array variable:
472
473              upvar #0 $token state
474
475       Once  the  data  associated with the URL is no longer needed, the state
476       array should be unset to free up storage.  The  ::http::cleanup  proce‐
477       dure is provided for that purpose.  The following elements of the array
478       are supported:
479
480              binary This is boolean true if (after decoding  any  compression
481                     specified  by the “Content-Encoding” response header) the
482                     HTTP response is binary.  It is boolean false if the HTTP
483                     response is text.
484
485              body   The  contents  of  the  URL.   This  will be empty if the
486                     -channel  option  has  been  specified.   This  value  is
487                     returned by the ::http::data command.
488
489              charset
490                     The  value of the charset attribute from the Content-Type
491                     meta-data value.  If none was specified, this defaults to
492                     the   RFC   standard   iso8859-1,   or   the   value   of
493                     $::http::defaultCharset.   Incoming  text  data  will  be
494                     automatically converted from this charset to utf-8.
495
496              coding A copy of the Content-Encoding meta-data value.
497
498              currentsize
499                     The  current  number of bytes fetched from the URL.  This
500                     value is returned by the ::http::size command.
501
502              error  If defined, this is the error string seen when  the  HTTP
503                     transaction was aborted.
504
505              http   The  HTTP  status  reply  from the server.  This value is
506                     returned by the ::http::code command.  The format of this
507                     value is:
508
509                            HTTP/1.1 code string
510
511                     The  code  is  a  three-digit  number defined in the HTTP
512                     standard.  A code of 200 is OK.  Codes beginning  with  4
513                     or  5  indicate errors.  Codes beginning with 3 are redi‐
514                     rection errors.  In  this  case  the  Location  meta-data
515                     specifies  a new URL that contains the requested informa‐
516                     tion.
517
518              meta   The HTTP protocol returns meta-data  that  describes  the
519                     URL  contents.   The meta element of the state array is a
520                     list of the keys and values of the meta-data.  This is in
521                     a  format useful for initializing an array that just con‐
522                     tains the meta-data:
523
524                            array set meta $state(meta)
525
526                     Some of the meta-data keys are listed below, but the HTTP
527                     standard  defines more, and servers are free to add their
528                     own.
529
530                     Content-Type
531                            The type of the URL  contents.   Examples  include
532                            text/html,  image/gif,  application/postscript and
533                            application/x-tcl.
534
535                     Content-Length
536                            The advertised size of the contents.   The  actual
537                            size  obtained  by  ::http::geturl is available as
538                            state(currentsize).
539
540                     Location
541                            An alternate URL that contains the requested data.
542
543              posterror
544                     The error, if any, that occurred while writing  the  post
545                     query data to the server.
546
547              status Either  ok,  for  successful  completion, reset for user-
548                     reset, timeout if a timeout occurred before the  transac‐
549                     tion  could  complete,  or  error for an error condition.
550                     During the transaction this value is the empty string.
551
552              totalsize
553                     A copy of the Content-Length meta-data value.
554
555              type   A copy of the Content-Type meta-data value.
556
557              url    The requested URL.
558

PERSISTENT CONNECTIONS

560   BASICS
561       See RFC 7230 Sec 6, which supersedes RFC 2616 Sec 8.1.
562
563       A persistent connection allows multiple  HTTP/1.1  transactions  to  be
564       carried  over  the  same TCP connection.  Pipelining allows a client to
565       make multiple requests over a persistent connection without waiting for
566       each  response.   The server sends responses in the same order that the
567       requests were received.
568
569       If a POST request fails to complete,  typically  user  confirmation  is
570       needed  before  sending the request again.  The user may wish to verify
571       whether the server was modified by  the  failed  POST  request,  before
572       sending the same request again.
573
574       A HTTP request will use a persistent socket if the call to http::geturl
575       has the option -keepalive true. It will use pipelining where  permitted
576       if  the  http::config  option  -pipeline  is  boolean true (its default
577       value).
578
579       The http package maintains no more than one  persistent  connection  to
580       each  server  (i.e.  each  value of “domain:port”).  If http::geturl is
581       called to make a request over a persistent connection while the connec‐
582       tion  is  busy  with another request, the new request will be held in a
583       queue until the connection is free.
584
585       The http package does not support HTTP/1.0 persistent connections  con‐
586       trolled by the Keep-Alive header.
587
588   SPECIAL CASES
589       This  subsection  discusses issues related to closure of the persistent
590       connection by the server, automatic retry of failed requests, the  spe‐
591       cial treatment necessary for POST requests, and the options for dealing
592       with these cases.
593
594       In accordance with RFC 7230, http::geturl does  not  pipeline  requests
595       that  use  the POST method.  If a POST uses a persistent connection and
596       is not the first request on that connection, http::geturl  waits  until
597       it  has  received  the  response  for  the  previous  request;  or  (if
598       http::config option -postfresh is boolean true) it uses a  new  connec‐
599       tion for each POST.
600
601       If the server is processing a number of pipelined requests, and sends a
602       response header “Connection: close” with one of  the  responses  (other
603       than the last), then subsequent responses are unfulfilled. http::geturl
604       will send the unfulfilled requests again over a new connection.
605
606       A difficulty arises when a HTTP client sends a request over  a  persis‐
607       tent  connection  that  has been idle for a while.  The HTTP server may
608       half-close an apparently idle connection while the client is sending  a
609       request, but before the request arrives at the server: in this case (an
610       “asynchronous close event”) the  request  will  fail.   The  difficulty
611       arises  because  the client cannot be certain whether the POST modified
612       the state of the server.  For HEAD or GET requests, http::geturl  opens
613       another  connection and retransmits the failed request. However, if the
614       request was a POST, RFC 7230 forbids automatic retry by  default,  sug‐
615       gesting  either  user confirmation, or confirmation by user-agent soft‐
616       ware  that  has  semantic  understanding  of  the   application.    The
617       http::config option -repost allows for either possibility.
618
619       Asynchronous  close  events can occur only in a short interval of time.
620       The http package monitors each persistent connection for closure by the
621       server.   Upon  detection,  the connection is also closed at the client
622       end, and subsequent requests will use a fresh connection.
623
624       If the http::geturl command is called with option -keepalive true, then
625       it  will  both  try to use an existing persistent connection (if one is
626       available), and it will send  the  server  a  “Connection:  keep-alive
627       request header asking to keep the connection open for future requests.
628
629       The  http::config  options -pipeline, -postfresh, and -repost relate to
630       persistent connections.
631
632       Option -pipeline, if boolean true, will pipeline GET and HEAD  requests
633       made over a persistent connection.  POST requests will not be pipelined
634       - if the POST is not the  first  transaction  on  the  connection,  its
635       request will not be sent until the previous response has finished.  GET
636       and HEAD requests made after a POST will not be  sent  until  the  POST
637       response has been delivered, and will not be sent if the POST fails.
638
639       Option  -postfresh,  if  boolean  true,  will override the http::geturl
640       option -keepalive, and always  open  a  fresh  connection  for  a  POST
641       request.
642
643       Option -repost, if true, permits automatic retry of a POST request that
644       fails because it uses a persistent connection that the server has half-
645       closed  (an  “asynchronous  close  event”).   Subsequent  GET  and HEAD
646       requests in a failed pipeline will also be retried.  The -repost option
647       should  be  used  only if the application understands that the retry is
648       appropriate - specifically, the  application  must  know  that  if  the
649       failed  POST  successfully  modified  the state of the server, a repeat
650       POST would have no adverse effect.
651

EXAMPLE

653       This example creates a procedure to copy a URL to a file while printing
654       a progress meter, and prints the meta-data associated with the URL.
655
656              proc httpcopy { url file {chunk 4096} } {
657                  set out [open $file w]
658                  set token [::http::geturl $url -channel $out \
659                          -progress httpCopyProgress -blocksize $chunk]
660                  close $out
661
662                  # This ends the line started by httpCopyProgress
663                  puts stderr ""
664
665                  upvar #0 $token state
666                  set max 0
667                  foreach {name value} $state(meta) {
668                      if {[string length $name] > $max} {
669                          set max [string length $name]
670                      }
671                      if {[regexp -nocase ^location$ $name]} {
672                          # Handle URL redirects
673                          puts stderr "Location:$value"
674                          return [httpcopy [string trim $value] $file $chunk]
675                      }
676                  }
677                  incr max
678                  foreach {name value} $state(meta) {
679                      puts [format "%-*s %s" $max $name: $value]
680                  }
681
682                  return $token
683              }
684              proc httpCopyProgress {args} {
685                  puts -nonewline stderr .
686                  flush stderr
687              }
688

SEE ALSO

690       safe(n), socket(n), safesock(n)
691

KEYWORDS

693       internet, security policy, socket, www
694
695
696
697http                                  2.9                              http(n)
Impressum