raw/mann/Http.n

   1 '\"
   2 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
   3 '\" Copyright (c) 1998-2000 by Ajuba Solutions.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" The definitions below are for supplemental macros used in Tcl/Tk
   9 '\" manual entries.
  10 '\"
  11 '\" .AP type name in/out ?indent?
  12 '\"     Start paragraph describing an argument to a library procedure.
  13 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 '\"     needed;  use .AS below instead)
  17 '\"
  18 '\" .AS ?type? ?name?
  19 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 '\"     name are examples of largest possible arguments that will be passed
  21 '\"     to .AP later.  If args are omitted, default tab stops are used.
  22 '\"
  23 '\" .BS
  24 '\"     Start box enclosure.  From here until next .BE, everything will be
  25 '\"     enclosed in one large box.
  26 '\"
  27 '\" .BE
  28 '\"     End of box enclosure.
  29 '\"
  30 '\" .CS
  31 '\"     Begin code excerpt.
  32 '\"
  33 '\" .CE
  34 '\"     End code excerpt.
  35 '\"
  36 '\" .VS ?version? ?br?
  37 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 '\"     of man pages.  The first argument is ignored and used for recording
  39 '\"     the version when the .VS was added, so that the sidebars can be
  40 '\"     found and removed when they reach a certain age.  If another argument
  41 '\"     is present, then a line break is forced before starting the sidebar.
  42 '\"
  43 '\" .VE
  44 '\"     End of vertical sidebar.
  45 '\"
  46 '\" .DS
  47 '\"     Begin an indented unfilled display.
  48 '\"
  49 '\" .DE
  50 '\"     End of indented unfilled display.
  51 '\"
  52 '\" .SO
  53 '\"     Start of list of standard options for a Tk widget.  The
  54 '\"     options follow on successive lines, in four columns separated
  55 '\"     by tabs.
  56 '\"
  57 '\" .SE
  58 '\"     End of list of standard options for a Tk widget.
  59 '\"
  60 '\" .OP cmdName dbName dbClass
  61 '\"     Start of description of a specific option.  cmdName gives the
  62 '\"     option's name as specified in the class command, dbName gives
  63 '\"     the option's name in the option database, and dbClass gives
  64 '\"     the option's class in the option database.
  65 '\"
  66 '\" .UL arg1 arg2
  67 '\"     Print arg1 underlined, then print arg2 normally.
  68 '\"
  69 '\"
  70 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  71 .if t .wh -1.3i ^B
  72 .nr ^l \n(.l
  73 .ad b
  74 '\"     # Start an argument description
  75 .de AP
  76 .ie !"\\$4"" .TP \\$4
  77 .el \{\
  78 .   ie !"\\$2"" .TP \\n()Cu
  79 .   el          .TP 15
  80 .\}
  81 .ta \\n()Au \\n()Bu
  82 .ie !"\\$3"" \{\
  83 \&\\$1  \\fI\\$2\\fP    (\\$3)
  84 .\".b
  85 .\}
  86 .el \{\
  87 .br
  88 .ie !"\\$2"" \{\
  89 \&\\$1  \\fI\\$2\\fP
  90 .\}
  91 .el \{\
  92 \&\\fI\\$1\\fP
  93 .\}
  94 .\}
  95 ..
  96 '\"     # define tabbing values for .AP
  97 .de AS
  98 .nr )A 10n
  99 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 100 .nr )B \\n()Au+15n
 101 .\"
 102 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 103 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 104 ..
 105 .AS Tcl_Interp Tcl_CreateInterp in/out
 106 '\"     # BS - start boxed text
 107 '\"     # ^y = starting y location
 108 '\"     # ^b = 1
 109 .de BS
 110 .br
 111 .mk ^y
 112 .nr ^b 1u
 113 .if n .nf
 114 .if n .ti 0
 115 .if n \l'\\n(.lu\(ul'
 116 .if n .fi
 117 ..
 118 '\"     # BE - end boxed text (draw box now)
 119 .de BE
 120 .nf
 121 .ti 0
 122 .mk ^t
 123 .ie n \l'\\n(^lu\(ul'
 124 .el \{\
 125 .\"     Draw four-sided box normally, but don't draw top of
 126 .\"     box if the box started on an earlier page.
 127 .ie !\\n(^b-1 \{\
 128 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 129 .\}
 130 .el \}\
 131 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 132 .\}
 133 .\}
 134 .fi
 135 .br
 136 .nr ^b 0
 137 ..
 138 '\"     # VS - start vertical sidebar
 139 '\"     # ^Y = starting y location
 140 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 141 .de VS
 142 .if !"\\$2"" .br
 143 .mk ^Y
 144 .ie n 'mc \s12\(br\s0
 145 .el .nr ^v 1u
 146 ..
 147 '\"     # VE - end of vertical sidebar
 148 .de VE
 149 .ie n 'mc
 150 .el \{\
 151 .ev 2
 152 .nf
 153 .ti 0
 154 .mk ^t
 155 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 156 .sp -1
 157 .fi
 158 .ev
 159 .\}
 160 .nr ^v 0
 161 ..
 162 '\"     # Special macro to handle page bottom:  finish off current
 163 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 164 '\"     # page bottom macro.
 165 .de ^B
 166 .ev 2
 167 'ti 0
 168 'nf
 169 .mk ^t
 170 .if \\n(^b \{\
 171 .\"     Draw three-sided box if this is the box's first page,
 172 .\"     draw two sides but no top otherwise.
 173 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 174 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 175 .\}
 176 .if \\n(^v \{\
 177 .nr ^x \\n(^tu+1v-\\n(^Yu
 178 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 179 .\}
 180 .bp
 181 'fi
 182 .ev
 183 .if \\n(^b \{\
 184 .mk ^y
 185 .nr ^b 2
 186 .\}
 187 .if \\n(^v \{\
 188 .mk ^Y
 189 .\}
 190 ..
 191 '\"     # DS - begin display
 192 .de DS
 193 .RS
 194 .nf
 195 .sp
 196 ..
 197 '\"     # DE - end display
 198 .de DE
 199 .fi
 200 .RE
 201 .sp
 202 ..
 203 '\"     # SO - start of list of standard options
 204 .de SO
 205 .SH "STANDARD OPTIONS"
 206 .LP
 207 .nf
 208 .ta 5.5c 11c
 209 .ft B
 210 ..
 211 '\"     # SE - end of list of standard options
 212 .de SE
 213 .fi
 214 .ft R
 215 .LP
 216 See the \\fBoptions\\fR manual entry for details on the standard options.
 217 ..
 218 '\"     # OP - start of full description for a single option
 219 .de OP
 220 .LP
 221 .nf
 222 .ta 4c
 223 Command-Line Name:      \\fB\\$1\\fR
 224 Database Name:  \\fB\\$2\\fR
 225 Database Class: \\fB\\$3\\fR
 226 .fi
 227 .IP
 228 ..
 229 '\"     # CS - begin code excerpt
 230 .de CS
 231 .RS
 232 .nf
 233 .ta .25i .5i .75i 1i
 234 ..
 235 '\"     # CE - end code excerpt
 236 .de CE
 237 .fi
 238 .RE
 239 ..
 240 .de UL
 241 \\$1\l'|0\(ul'\\$2
 242 ..
 243 .TH "Http" n 8.3 Tcl "Tcl Built-In Commands"
 244 .BS
 245 '\" Note:  do not modify the .SH NAME line immediately below!
 246 .SH NAME
 247 Http \- Client-side implementation of the HTTP/1.0 protocol.
 248 .SH SYNOPSIS
 249 \fBpackage require http ?2.4?\fR
 250 .sp
 251 \fB::http::config \fI?options?\fR
 252 .sp
 253 \fB::http::geturl \fIurl ?options?\fR
 254 .sp
 255 \fB::http::formatQuery \fIlist\fR
 256 .sp
 257 \fB::http::reset \fItoken\fR
 258 .sp
 259 \fB::http::wait \fItoken\fR
 260 .sp
 261 \fB::http::status \fItoken\fR
 262 .sp
 263 \fB::http::size \fItoken\fR
 264 .sp
 265 \fB::http::code \fItoken\fR
 266 .sp
 267 \fB::http::ncode \fItoken\fR
 268 .sp
 269 \fB::http::data \fItoken\fR
 270 .sp
 271 \fB::http::error \fItoken\fR
 272 .sp
 273 \fB::http::cleanup \fItoken\fR
 274 .sp
 275 \fB::http::register \fIproto port command\fR
 276 .sp
 277 \fB::http::unregister \fIproto\fR
 278 .BE
 279
 280 .SH DESCRIPTION
 281 .PP
 282 The \fBhttp\fR package provides the client side of the HTTP/1.0
 283 protocol.  The package implements the GET, POST, and HEAD operations
 284 of HTTP/1.0.  It allows configuration of a proxy host to get through
 285 firewalls.  The package is compatible with the \fBSafesock\fR security
 286 policy, so it can be used by untrusted applets to do URL fetching from
 287 a restricted set of hosts. This package can be extened to support
 288 additional HTTP transport protocols, such as HTTPS, by providing
 289 a custom \fBsocket\fR command, via \fBhttp::register\fR.
 290 .PP
 291 The \fB::http::geturl\fR procedure does a HTTP transaction.
 292 Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
 293 is performed.
 294 The return value of \fB::http::geturl\fR is a token for the transaction.
 295 The value is also the name of an array in the ::http namespace
 296 that contains state information about the transaction.  The elements
 297 of this array are described in the STATE ARRAY section.
 298 .PP
 299 If the \fB-command\fP option is specified, then
 300 the HTTP operation is done in the background.
 301 \fB::http::geturl\fR returns immediately after generating the
 302 HTTP request and the callback is invoked
 303 when the transaction completes.  For this to work, the Tcl event loop
 304 must be active.  In Tk applications this is always true.  For pure-Tcl
 305 applications, the caller can use \fB::http::wait\fR after calling
 306 \fB::http::geturl\fR to start the event loop.
 307 .SH COMMANDS
 308 .TP
 309 \fB::http::config\fP ?\fIoptions\fR?
 310 The \fB::http::config\fR command is used to set and query the name of the
 311 proxy server and port, and the User-Agent name used in the HTTP
 312 requests.  If no options are specified, then the current configuration
 313 is returned.  If a single argument is specified, then it should be one
 314 of the flags described below.  In this case the current value of
 315 that setting is returned.  Otherwise, the options should be a set of
 316 flags and values that define the configuration:
 317 .RS
 318 .TP
 319 \fB\-accept\fP \fImimetypes\fP
 320 The Accept header of the request.  The default is */*, which means that
 321 all types of documents are accepted.  Otherwise you can supply a
 322 comma separated list of mime type patterns that you are
 323 willing to receive.  For example, "image/gif, image/jpeg, text/*".
 324 .TP
 325 \fB\-proxyhost\fP \fIhostname\fP
 326 The name of the proxy host, if any.  If this value is the
 327 empty string, the URL host is contacted directly.
 328 .TP
 329 \fB\-proxyport\fP \fInumber\fP
 330 The proxy port number.
 331 .TP
 332 \fB\-proxyfilter\fP \fIcommand\fP
 333 The command is a callback that is made during
 334 \fB::http::geturl\fR
 335 to determine if a proxy is required for a given host.  One argument, a
 336 host name, is added to \fIcommand\fR when it is invoked.  If a proxy
 337 is required, the callback should return a two element list containing
 338 the proxy server and proxy port.  Otherwise the filter should return
 339 an empty list.  The default filter returns the values of the
 340 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
 341 non-empty.
 342 .TP
 343 \fB\-useragent\fP \fIstring\fP
 344 The value of the User-Agent header in the HTTP request.  The default
 345 is \fB"Tcl http client package 2.2."\fR
 346 .RE
 347 .TP
 348 \fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP?
 349 The \fB::http::geturl\fR command is the main procedure in the package.
 350 The \fB\-query\fR option causes a POST operation and
 351 the \fB\-validate\fR option causes a HEAD operation;
 352 otherwise, a GET operation is performed.  The \fB::http::geturl\fR command
 353 returns a \fItoken\fR value that can be used to get
 354 information about the transaction.  See the STATE ARRAY and ERRORS section for
 355 details.  The \fB::http::geturl\fR command blocks until the operation
 356 completes, unless the \fB\-command\fR option specifies a callback
 357 that is invoked when the HTTP transaction completes.
 358 \fB::http::geturl\fR takes several options:
 359 .RS
 360 .TP
 361 \fB\-binary\fP \fIboolean\fP
 362 Specifies whether to force interpreting the url data as binary.  Normally
 363 this is auto-detected (anything not beginning with a \fBtext\fR content
 364 type or whose content encoding is \fBgzip\fR or \fBcompress\fR is
 365 considered binary data).
 366 .TP
 367 \fB\-blocksize\fP \fIsize\fP
 368 The blocksize used when reading the URL.
 369 At most \fIsize\fR bytes are read at once.  After each block, a call to the
 370 \fB\-progress\fR callback is made (if that option is specified).
 371 .TP
 372 \fB\-channel\fP \fIname\fP
 373 Copy the URL contents to channel \fIname\fR instead of saving it in
 374 \fBstate(body)\fR.
 375 .TP
 376 \fB\-command\fP \fIcallback\fP
 377 Invoke \fIcallback\fP after the HTTP transaction completes.
 378 This option causes \fB::http::geturl\fP to return immediately.
 379 The \fIcallback\fP gets an additional argument that is the \fItoken\fR returned
 380 from \fB::http::geturl\fR. This token is the name of an array that is
 381 described in the STATE ARRAY section.  Here is a template for the
 382 callback:
 383 .RS
 384 .CS
 385 proc httpCallback {token} {
 386     upvar #0 $token state
 387     # Access state as a Tcl array
 388 }
 389 .CE
 390 .RE
 391 .TP
 392 \fB\-handler\fP \fIcallback\fP
 393 Invoke \fIcallback\fP whenever HTTP data is available; if present, nothing
 394 else will be done with the HTTP data.  This procedure gets two additional
 395 arguments: the socket for the HTTP data and the \fItoken\fR returned from
 396 \fB::http::geturl\fR.  The token is the name of a global array that is described
 397 in the STATE ARRAY section.  The procedure is expected to return the number
 398 of bytes read from the socket.  Here is a template for the callback:
 399 .RS
 400 .CS
 401 proc httpHandlerCallback {socket token} {
 402     upvar #0 $token state
 403     # Access socket, and state as a Tcl array
 404     ...
 405     (example: set data [read $socket 1000];set nbytes [string length $data])
 406     ...
 407     return nbytes
 408 }
 409 .CE
 410 .RE
 411 .TP
 412 \fB\-headers\fP \fIkeyvaluelist\fP
 413 This option is used to add extra headers to the HTTP request.  The
 414 \fIkeyvaluelist\fR argument must be a list with an even number of
 415 elements that alternate between keys and values.  The keys become
 416 header field names.  Newlines are stripped from the values so the
 417 header cannot be corrupted.  For example, if \fIkeyvaluelist\fR is
 418 \fBPragma no-cache\fR then the following header is included in the
 419 HTTP request:
 420 .CS
 421 Pragma: no-cache
 422 .CE
 423 .TP
 424 \fB\-progress\fP \fIcallback\fP
 425 The \fIcallback\fR is made after each transfer of data from the URL.
 426 The callback gets three additional arguments: the \fItoken\fR from
 427 \fB::http::geturl\fR, the expected total size of the contents from the
 428 \fBContent-Length\fR meta-data, and the current number of bytes
 429 transferred so far.  The expected total size may be unknown, in which
 430 case zero is passed to the callback.  Here is a template for the
 431 progress callback:
 432 .RS
 433 .CS
 434 proc httpProgress {token total current} {
 435     upvar #0 $token state
 436 }
 437 .CE
 438 .RE
 439 .TP
 440 \fB\-query\fP \fIquery\fP
 441 This flag causes \fB::http::geturl\fR to do a POST request that passes the
 442 \fIquery\fR to the server. The \fIquery\fR must be a x-url-encoding
 443 formatted query.  The \fB::http::formatQuery\fR procedure can be used to
 444 do the formatting.
 445 .TP
 446 \fB\-queryblocksize\fP \fIsize\fP
 447 The blocksize used when posting query data to the URL.
 448 At most
 449 \fIsize\fR
 450 bytes are written at once.  After each block, a call to the
 451 \fB\-queryprogress\fR
 452 callback is made (if that option is specified).
 453 .TP
 454 \fB\-querychannel\fP \fIchannelID\fP
 455 This flag causes \fB::http::geturl\fR to do a POST request that passes the
 456 data contained in \fIchannelID\fR to the server. The data contained in \fIchannelID\fR must be a x-url-encoding
 457 formatted query unless the \fB\-type\fP option below is used.
 458 If a Content-Length header is not specified via the \fB\-headers\fR options,
 459 \fB::http::geturl\fR attempts to determine the size of the post data
 460 in order to create that header.  If it is
 461 unable to determine the size, it returns an error.
 462 .TP
 463 \fB\-queryprogress\fP \fIcallback\fP
 464 The \fIcallback\fR is made after each transfer of data to the URL
 465 (i.e. POST) and acts exactly like the \fB\-progress\fR option (the
 466 callback format is the same).
 467 .TP
 468 \fB\-timeout\fP \fImilliseconds\fP
 469 If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout
 470 to occur after the specified number of milliseconds.
 471 A timeout results in a call to \fB::http::reset\fP and to
 472 the \fB-command\fP callback, if specified.
 473 The return value of \fB::http::status\fP is \fBtimeout\fP
 474 after a timeout has occurred.
 475 .TP
 476 \fB\-type\fP \fImime-type\fP
 477 Use \fImime-type\fR as the \fBContent-Type\fR value, instead of the
 478 default value (\fBapplication/x-www-form-urlencoded\fR) during a
 479 POST operation.
 480 .TP
 481 \fB\-validate\fP \fIboolean\fP
 482 If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD
 483 request.  This request returns meta information about the URL, but the
 484 contents are not returned.  The meta information is available in the
 485 \fBstate(meta) \fR variable after the transaction.  See the STATE
 486 ARRAY section for details.
 487 .RE
 488 .TP
 489 \fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
 490 This procedure does x-url-encoding of query data.  It takes an even
 491 number of arguments that are the keys and values of the query.  It
 492 encodes the keys and values, and generates one string that has the
 493 proper & and = separators.  The result is suitable for the
 494 \fB\-query\fR value passed to \fB::http::geturl\fR.
 495 .TP
 496 \fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
 497 This command resets the HTTP transaction identified by \fItoken\fR, if
 498 any.  This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
 499 .TP
 500 \fB::http::wait\fP \fItoken\fP
 501 This is a convenience procedure that blocks and waits for the
 502 transaction to complete.  This only works in trusted code because it
 503 uses \fBvwait\fR.  Also, it's not useful for the case where
 504 \fB::http::geturl\fP is called \fIwithout\fP the \fB-command\fP option
 505 because in this case the \fB::http::geturl\fP call doesn't return
 506 until the HTTP transaction is complete, and thus there's nothing to
 507 wait for.
 508 .TP
 509 \fB::http::data\fP \fItoken\fP
 510 This is a convenience procedure that returns the \fBbody\fP element
 511 (i.e., the URL data) of the state array.
 512 .TP
 513 \fB::http::error\fP \fItoken\fP
 514 This is a convenience procedure that returns the \fBerror\fP element
 515 of the state array.
 516 .TP
 517 \fB::http::status\fP \fItoken\fP
 518 This is a convenience procedure that returns the \fBstatus\fP element of
 519 the state array.
 520 .TP
 521 \fB::http::code\fP \fItoken\fP
 522 This is a convenience procedure that returns the \fBhttp\fP element of the
 523 state array.
 524 .TP
 525 \fB::http::ncode\fP \fItoken\fP
 526 This is a convenience procedure that returns just the numeric return
 527 code (200, 404, etc.) from the \fBhttp\fP element of the state array.
 528 .TP
 529 \fB::http::size\fP \fItoken\fP
 530 This is a convenience procedure that returns the \fBcurrentsize\fP
 531 element of the state array, which represents the number of bytes
 532 received from the URL in the \fB::http::geturl\fP call.
 533 .TP
 534 \fB::http::cleanup\fP \fItoken\fP
 535 This procedure cleans up the state associated with the connection
 536 identified by \fItoken\fP.  After this call, the procedures
 537 like \fB::http::data\fP cannot be used to get information
 538 about the operation.  It is \fIstrongly\fP recommended that you call
 539 this function after you're done with a given HTTP request.  Not doing
 540 so will result in memory not being freed, and if your app calls
 541 \fB::http::geturl\fP enough times, the memory leak could cause a
 542 performance hit...or worse.
 543 .TP
 544 \fB::http::register\fP \fIproto port command\fP
 545 This procedure allows one to provide custom HTTP transport types
 546 such as HTTPS, by registering a prefix, the default port, and the
 547 command to execute to create the Tcl \fBchannel\fR. E.g.:
 548 .RS
 549 .CS
 550 package require http
 551 package require tls
 552
 553 http::register https 443 ::tls::socket
 554
 555 set token [http::geturl https://my.secure.site/]
 556 .CE
 557 .RE
 558 .TP
 559 \fB::http::unregister\fP \fIproto\fP
 560 This procedure unregisters a protocol handler that was previously
 561 registered via \fBhttp::register\fR.
 562
 563 .SH "ERRORS"
 564 The \fBhttp::geturl\fP procedure will raise errors in the following cases:
 565 invalid command line options,
 566 an invalid URL,
 567 a URL on a non-existent host,
 568 or a URL at a bad port on an existing host.
 569 These errors mean that it
 570 cannot even start the network transaction.
 571 It will also raise an error if it gets an I/O error while
 572 writing out the HTTP request header.
 573 For synchronous \fB::http::geturl\fP calls (where \fB-command\fP is
 574 not specified), it will raise an error if it gets an I/O error while
 575 reading the HTTP reply headers or data.  Because \fB::http::geturl\fP
 576 doesn't return a token in these cases, it does all the required
 577 cleanup and there's no issue of your app having to call
 578 \fB::http::cleanup\fP.
 579 .PP
 580 For asynchronous \fB::http::geturl\fP calls, all of the above error
 581 situations apply, except that if there's any error while
 582 reading the
 583 HTTP reply headers or data, no exception is thrown.  This is because
 584 after writing the HTTP headers, \fB::http::geturl\fP returns, and the
 585 rest of the HTTP transaction occurs in the background.  The command
 586 callback can check if any error occurred during the read by calling
 587 \fB::http::status\fP to check the status and if it's \fIerror\fP,
 588 calling \fB::http::error\fP to get the error message.
 589 .PP
 590 Alternatively, if the main program flow reaches a point where it needs
 591 to know the result of the asynchronous HTTP request, it can call
 592 \fB::http::wait\fP and then check status and error, just as the
 593 callback does.
 594 .PP
 595 In any case, you must still call
 596 \fBhttp::cleanup\fP to delete the state array when you're done.
 597 .PP
 598 There are other possible results of the HTTP transaction
 599 determined by examining the status from \fBhttp::status\fP.
 600 These are described below.
 601 .TP
 602 ok
 603 If the HTTP transaction completes entirely, then status will be \fBok\fP.
 604 However, you should still check the \fBhttp::code\fP value to get
 605 the HTTP status.  The \fBhttp::ncode\fP procedure provides just
 606 the numeric error (e.g., 200, 404 or 500) while the \fBhttp::code\fP
 607 procedure returns a value like "HTTP 404 File not found".
 608 .TP
 609 eof
 610 If the server closes the socket without replying, then no error
 611 is raised, but the status of the transaction will be \fBeof\fP.
 612 .TP
 613 error
 614 The error message will also be stored in the \fBerror\fP status
 615 array element, accessible via \fB::http::error\fP.
 616 .PP
 617 Another error possibility is that \fBhttp::geturl\fP is unable to
 618 write all the post query data to the server before the server
 619 responds and closes the socket.
 620 The error message is saved in the \fBposterror\fP status array
 621 element and then  \fBhttp::geturl\fP attempts to complete the
 622 transaction.
 623 If it can read the server's response
 624 it will end up with an \fBok\fP status, otherwise it will have
 625 an \fBeof\fP status.
 626
 627 .SH "STATE ARRAY"
 628 The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to
 629 get to the state of the HTTP transaction in the form of a Tcl array.
 630 Use this construct to create an easy-to-use array variable:
 631 .CS
 632 upvar #0 $token state
 633 .CE
 634 Once the data associated with the url is no longer needed, the state
 635 array should be unset to free up storage.
 636 The \fBhttp::cleanup\fP procedure is provided for that purpose.
 637 The following elements of
 638 the array are supported:
 639 .RS
 640 .TP
 641 \fBbody\fR
 642 The contents of the URL.  This will be empty if the \fB\-channel\fR
 643 option has been specified.  This value is returned by the \fB::http::data\fP command.
 644 .TP
 645 \fBcharset\fR
 646 The value of the charset attribute from the \fBContent-Type\fR meta-data
 647 value.  If none was specified, this defaults to the RFC standard
 648 \fBiso8859-1\fR, or the value of \fB$::http::defaultCharset\fR.  Incoming
 649 text data will be automatically converted from this charset to utf-8.
 650 .TP
 651 \fBcoding\fR
 652 A copy of the \fBContent-Encoding\fR meta-data value.
 653 .TP
 654 \fBcurrentsize\fR
 655 The current number of bytes fetched from the URL.
 656 This value is returned by the \fB::http::size\fP command.
 657 .TP
 658 \fBerror\fR
 659 If defined, this is the error string seen when the HTTP transaction
 660 was aborted.
 661 .TP
 662 \fBhttp\fR
 663 The HTTP status reply from the server.  This value
 664 is returned by the \fB::http::code\fP command.  The format of this value is:
 665 .RS
 666 .CS
 667 \fIHTTP/1.0 code string\fP
 668 .CE
 669 The \fIcode\fR is a three-digit number defined in the HTTP standard.
 670 A code of 200 is OK.  Codes beginning with 4 or 5 indicate errors.
 671 Codes beginning with 3 are redirection errors.  In this case the
 672 \fBLocation\fR meta-data specifies a new URL that contains the
 673 requested information.
 674 .RE
 675 .TP
 676 \fBmeta\fR
 677 The HTTP protocol returns meta-data that describes the URL contents.
 678 The \fBmeta\fR element of the state array is a list of the keys and
 679 values of the meta-data.  This is in a format useful for initializing
 680 an array that just contains the meta-data:
 681 .RS
 682 .CS
 683 array set meta $state(meta)
 684 .CE
 685 Some of the meta-data keys are listed below, but the HTTP standard defines
 686 more, and servers are free to add their own.
 687 .TP
 688 \fBContent-Type\fR
 689 The type of the URL contents.  Examples include \fBtext/html\fR,
 690 \fBimage/gif,\fR \fBapplication/postscript\fR and
 691 \fBapplication/x-tcl\fR.
 692 .TP
 693 \fBContent-Length\fR
 694 The advertised size of the contents.  The actual size obtained by
 695 \fB::http::geturl\fR is available as \fBstate(size)\fR.
 696 .TP
 697 \fBLocation\fR
 698 An alternate URL that contains the requested data.
 699 .RE
 700 .TP
 701 \fBposterror\fR
 702 The error, if any, that occurred while writing
 703 the post query data to the server.
 704 .TP
 705 \fBstatus\fR
 706 Either \fBok\fR, for successful completion, \fBreset\fR for
 707 user-reset, \fBtimeout\fP if a timeout occurred before the transaction
 708 could complete, or \fBerror\fR for an error condition.  During the
 709 transaction this value is the empty string.
 710 .TP
 711 \fBtotalsize\fR
 712 A copy of the \fBContent-Length\fR meta-data value.
 713 .TP
 714 \fBtype\fR
 715 A copy of the \fBContent-Type\fR meta-data value.
 716 .TP
 717 \fBurl\fR
 718 The requested URL.
 719 .RE
 720 .SH EXAMPLE
 721 .DS
 722 # Copy a URL to a file and print meta-data
 723 proc ::http::copy { url file {chunk 4096} } {
 724     set out [open $file w]
 725     set token [geturl $url -channel $out -progress ::http::Progress \\
 726         -blocksize $chunk]
 727     close $out
 728     # This ends the line started by http::Progress
 729     puts stderr ""
 730     upvar #0 $token state
 731     set max 0
 732     foreach {name value} $state(meta) {
 733         if {[string length $name] > $max} {
 734             set max [string length $name]
 735         }
 736         if {[regexp -nocase ^location$ $name]} {
 737             # Handle URL redirects
 738             puts stderr "Location:$value"
 739             return [copy [string trim $value] $file $chunk]
 740         }
 741     }
 742     incr max
 743     foreach {name value} $state(meta) {
 744         puts [format "%-*s %s" $max $name: $value]
 745     }
 746
 747     return $token
 748 }
 749 proc ::http::Progress {args} {
 750     puts -nonewline stderr . ; flush stderr
 751 }
 752 .DE
 753
 754 .SH "SEE ALSO"
 755 safe(n), socket(n), safesock(n)
 756
 757 .SH KEYWORDS
 758 security policy, socket