1http(n) Tcl Bundled Packages http(n)
2______________________________________________________________________________
6
8 http - Client-side implementation of the HTTP/1.1 protocol
9
11 package require http ?2.7?
12 ::http::config ?-option value ...?
14 ::http::geturl url ?-option value ...?
16 ::http::formatQuery key value ?key value ...?
18 ::http::reset token ?why?
20 ::http::wait token
22 ::http::status token
24 ::http::size token
26 ::http::code token
28 ::http::ncode token
30 ::http::meta token
32 ::http::data token
34 ::http::error token
36 ::http::cleanup token
38 ::http::register proto port command
40 ::http::unregister proto
42______________________________________________________________________________
43
45 The http package provides the client side of the HTTP/1.1 protocol, as
46 defined in RFC 2616. The package implements the GET, POST, and HEAD
47 operations of HTTP/1.1. It allows configuration of a proxy host to get
48 through firewalls. The package is compatible with the Safesock secu‐
49 rity policy, so it can be used by untrusted applets to do URL fetching
50 from a restricted set of hosts. This package can be extended to support
51 additional HTTP transport protocols, such as HTTPS, by providing a cus‐
52 tom socket command, via ::http::register.
53 The ::http::geturl procedure does a HTTP transaction. Its options
55 determine whether a GET, POST, or HEAD transaction is performed. The
56 return value of ::http::geturl is a token for the transaction. The
57 value is also the name of an array in the ::http namespace that con‐
58 tains state information about the transaction. The elements of this
59 array are described in the STATE ARRAY section.
60 If the -command option is specified, then the HTTP operation is done in
62 the background. ::http::geturl returns immediately after generating
63 the HTTP request and the callback is invoked when the transaction com‐
64 pletes. For this to work, the Tcl event loop must be active. In Tk
65 applications this is always true. For pure-Tcl applications, the call‐
66 er can use ::http::wait after calling ::http::geturl to start the event
67 loop.
68
70 ::http::config ?options?
71 The ::http::config command is used to set and query the name of
72 the proxy server and port, and the User-Agent name used in the
73 HTTP requests. If no options are specified, then the current
74 configuration is returned. If a single argument is specified,
75 then it should be one of the flags described below. In this
76 case the current value of that setting is returned. Otherwise,
77 the options should be a set of flags and values that define the
78 configuration:
79 -accept mimetypes
81 The Accept header of the request. The default is */*,
82 which means that all types of documents are accepted.
83 Otherwise you can supply a comma-separated list of mime
84 type patterns that you are willing to receive. For exam‐
85 ple, “image/gif, image/jpeg, text/*”.
86 -proxyhost hostname
88 The name of the proxy host, if any. If this value is the
89 empty string, the URL host is contacted directly.
90 -proxyport number
92 The proxy port number.
93 -proxyfilter command
95 The command is a callback that is made during
96 ::http::geturl to determine if a proxy is required for a
97 given host. One argument, a host name, is added to com‐
98 mand when it is invoked. If a proxy is required, the
99 callback should return a two-element list containing the
100 proxy server and proxy port. Otherwise the filter should
101 return an empty list. The default filter returns the
102 values of the -proxyhost and -proxyport settings if they
103 are non-empty.
104 -urlencoding encoding
106 The encoding used for creating the x-url-encoded URLs
107 with ::http::formatQuery. The default is utf-8, as spec‐
108 ified by RFC 2718. Prior to http 2.5 this was unspeci‐
109 fied, and that behavior can be returned by specifying the
110 empty string ({}), although iso8859-1 is recommended to
111 restore similar behavior but without the ::http::format‐
112 Query throwing an error processing non-latin-1 charac‐
113 ters.
114 -useragent string
116 The value of the User-Agent header in the HTTP request.
117 The default is “Tcl http client package 2.7”.
118 ::http::geturl url ?options?
120 The ::http::geturl command is the main procedure in the package.
121 The -query option causes a POST operation and the -validate
122 option causes a HEAD operation; otherwise, a GET operation is
123 performed. The ::http::geturl command returns a token value
124 that can be used to get information about the transaction. See
125 the STATE ARRAY and ERRORS section for details. The
126 ::http::geturl command blocks until the operation completes,
127 unless the -command option specifies a callback that is invoked
128 when the HTTP transaction completes. ::http::geturl takes sev‐
129 eral options:
130 -binary boolean
132 Specifies whether to force interpreting the URL data as
133 binary. Normally this is auto-detected (anything not
134 beginning with a text content type or whose content
135 encoding is gzip or compress is considered binary data).
136 -blocksize size
138 The block size used when reading the URL. At most size
139 bytes are read at once. After each block, a call to the
140 -progress callback is made (if that option is specified).
141 -channel name
143 Copy the URL contents to channel name instead of saving
144 it in state(body).
145 -command callback
147 Invoke callback after the HTTP transaction completes.
148 This option causes ::http::geturl to return immediately.
149 The callback gets an additional argument that is the
150 token returned from ::http::geturl. This token is the
151 name of an array that is described in the STATE ARRAY
152 section. Here is a template for the callback:
153 proc httpCallback {token} {
155 upvar #0 $token state
156 # Access state as a Tcl array
157 }
158 -handler callback
160 Invoke callback whenever HTTP data is available; if
161 present, nothing else will be done with the HTTP data.
162 This procedure gets two additional arguments: the socket
163 for the HTTP data and the token returned from
164 ::http::geturl. The token is the name of a global array
165 that is described in the STATE ARRAY section. The proce‐
166 dure is expected to return the number of bytes read from
167 the socket. Here is a template for the callback:
168 proc httpHandlerCallback {socket token} {
170 upvar #0 $token state
171 # Access socket, and state as a Tcl array
172 # For example...
173 ...
174 set data [read $socket 1000]
175 set nbytes [string length $data]
176 ...
177 return $nbytes
178 }
179 -headers keyvaluelist
181 This option is used to add headers not already specified
182 by ::http::config to the HTTP request. The keyvaluelist
183 argument must be a list with an even number of elements
184 that alternate between keys and values. The keys become
185 header field names. Newlines are stripped from the val‐
186 ues so the header cannot be corrupted. For example, if
187 keyvaluelist is Pragma no-cache then the following header
188 is included in the HTTP request:
189 Pragma: no-cache
191 -keepalive boolean
193 If true, attempt to keep the connection open for servic‐
194 ing multiple requests. Default is 0.
195 -method type
197 Force the HTTP request method to type. ::http::geturl
198 will auto-select GET, POST or HEAD based on other
199 options, but this option enables choices like PUT and
200 DELETE for webdav support.
201 -myaddr address
203 Pass an specific local address to the underlying socket
204 call in case multiple interfaces are available.
205 -progress callback
207 The callback is made after each transfer of data from the
208 URL. The callback gets three additional arguments: the
209 token from ::http::geturl, the expected total size of the
210 contents from the Content-Length meta-data, and the cur‐
211 rent number of bytes transferred so far. The expected
212 total size may be unknown, in which case zero is passed
213 to the callback. Here is a template for the progress
214 callback:
215 proc httpProgress {token total current} {
217 upvar #0 $token state
218 }
219 -protocol version
221 Select the HTTP protocol version to use. This should be
222 1.0 or 1.1 (the default). Should only be necessary for
223 servers that do not understand or otherwise complain
224 about HTTP/1.1.
225 -query query
227 This flag causes ::http::geturl to do a POST request that
228 passes the query to the server. The query must be an x-
229 url-encoding formatted query. The ::http::formatQuery
230 procedure can be used to do the formatting.
231 -queryblocksize size
233 The block size used when posting query data to the URL.
234 At most size bytes are written at once. After each
235 block, a call to the -queryprogress callback is made (if
236 that option is specified).
237 -querychannel channelID
239 This flag causes ::http::geturl to do a POST request that
240 passes the data contained in channelID to the server. The
241 data contained in channelID must be an x-url-encoding
242 formatted query unless the -type option below is used.
243 If a Content-Length header is not specified via the
244 -headers options, ::http::geturl attempts to determine
245 the size of the post data in order to create that header.
246 If it is unable to determine the size, it returns an
247 error.
248 -queryprogress callback
250 The callback is made after each transfer of data to the
251 URL (i.e. POST) and acts exactly like the -progress
252 option (the callback format is the same).
253 -strict boolean
255 Whether to enforce RFC 3986 URL validation on the
256 request. Default is 1.
257 -timeout milliseconds
259 If milliseconds is non-zero, then ::http::geturl sets up
260 a timeout to occur after the specified number of mil‐
261 liseconds. A timeout results in a call to ::http::reset
262 and to the -command callback, if specified. The return
263 value of ::http::status is timeout after a timeout has
264 occurred.
265 -type mime-type
267 Use mime-type as the Content-Type value, instead of the
268 default value (application/x-www-form-urlencoded) during
269 a POST operation.
270 -validate boolean
272 If boolean is non-zero, then ::http::geturl does an HTTP
273 HEAD request. This request returns meta information
274 about the URL, but the contents are not returned. The
275 meta information is available in the state(meta) vari‐
276 able after the transaction. See the STATE ARRAY section
277 for details.
278 ::http::formatQuery key value ?key value ...?
280 This procedure does x-url-encoding of query data. It takes an
281 even number of arguments that are the keys and values of the
282 query. It encodes the keys and values, and generates one string
283 that has the proper & and = separators. The result is suitable
284 for the -query value passed to ::http::geturl.
285 ::http::reset token ?why?
287 This command resets the HTTP transaction identified by token, if
288 any. This sets the state(status) value to why, which defaults
289 to reset, and then calls the registered -command callback.
290 ::http::wait token
292 This is a convenience procedure that blocks and waits for the
293 transaction to complete. This only works in trusted code
294 because it uses vwait. Also, it is not useful for the case
295 where ::http::geturl is called without the -command option
296 because in this case the ::http::geturl call does not return
297 until the HTTP transaction is complete, and thus there is noth‐
298 ing to wait for.
299 ::http::data token
301 This is a convenience procedure that returns the body element
302 (i.e., the URL data) of the state array.
303 ::http::error token
305 This is a convenience procedure that returns the error element
306 of the state array.
307 ::http::status token
309 This is a convenience procedure that returns the status element
310 of the state array.
311 ::http::code token
313 This is a convenience procedure that returns the http element of
314 the state array.
315 ::http::ncode token
317 This is a convenience procedure that returns just the numeric
318 return code (200, 404, etc.) from the http element of the state
319 array.
320 ::http::size token
322 This is a convenience procedure that returns the currentsize
323 element of the state array, which represents the number of bytes
324 received from the URL in the ::http::geturl call.
325 ::http::meta token
327 This is a convenience procedure that returns the meta element of
328 the state array which contains the HTTP response headers. See
329 below for an explanation of this element.
330 ::http::cleanup token
332 This procedure cleans up the state associated with the connec‐
333 tion identified by token. After this call, the procedures like
334 ::http::data cannot be used to get information about the opera‐
335 tion. It is strongly recommended that you call this function
336 after you are done with a given HTTP request. Not doing so will
337 result in memory not being freed, and if your app calls
338 ::http::geturl enough times, the memory leak could cause a per‐
339 formance hit...or worse.
340 ::http::register proto port command
342 This procedure allows one to provide custom HTTP transport types
343 such as HTTPS, by registering a prefix, the default port, and
344 the command to execute to create the Tcl channel. E.g.:
345 package require http
347 package require tls
348 ::http::register https 443 ::tls::socket
350 set token [::http::geturl https://my.secure.site/]
352 ::http::unregister proto
354 This procedure unregisters a protocol handler that was previ‐
355 ously registered via ::http::register, returning a two-item list
356 of the default port and handler command that was previously
357 installed (via ::http::register) if there was such a handler,
358 and an error if there was no such handler.
359
361 The ::http::geturl procedure will raise errors in the following cases:
362 invalid command line options, an invalid URL, a URL on a non-existent
363 host, or a URL at a bad port on an existing host. These errors mean
364 that it cannot even start the network transaction. It will also raise
365 an error if it gets an I/O error while writing out the HTTP request
366 header. For synchronous ::http::geturl calls (where -command is not
367 specified), it will raise an error if it gets an I/O error while read‐
368 ing the HTTP reply headers or data. Because ::http::geturl does not
369 return a token in these cases, it does all the required cleanup and
370 there is no issue of your app having to call ::http::cleanup.
371 For asynchronous ::http::geturl calls, all of the above error situa‐
373 tions apply, except that if there is any error while reading the HTTP
374 reply headers or data, no exception is thrown. This is because after
375 writing the HTTP headers, ::http::geturl returns, and the rest of the
376 HTTP transaction occurs in the background. The command callback can
377 check if any error occurred during the read by calling ::http::status
378 to check the status and if its error, calling ::http::error to get the
379 error message.
380 Alternatively, if the main program flow reaches a point where it needs
382 to know the result of the asynchronous HTTP request, it can call
383 ::http::wait and then check status and error, just as the callback
384 does.
385 In any case, you must still call ::http::cleanup to delete the state
387 array when you are done.
388 There are other possible results of the HTTP transaction determined by
390 examining the status from ::http::status. These are described below.
391 ok If the HTTP transaction completes entirely, then status will be
393 ok. However, you should still check the ::http::code value to
394 get the HTTP status. The ::http::ncode procedure provides just
395 the numeric error (e.g., 200, 404 or 500) while the ::http::code
396 procedure returns a value like “HTTP 404 File not found”.
397 eof If the server closes the socket without replying, then no error
399 is raised, but the status of the transaction will be eof.
400 error The error message will also be stored in the error status array
402 element, accessible via ::http::error.
403 Another error possibility is that ::http::geturl is unable to write all
405 the post query data to the server before the server responds and closes
406 the socket. The error message is saved in the posterror status array
407 element and then ::http::geturl attempts to complete the transaction.
408 If it can read the server's response it will end up with an ok status,
409 otherwise it will have an eof status.
410
412 The ::http::geturl procedure returns a token that can be used to get to
413 the state of the HTTP transaction in the form of a Tcl array. Use this
414 construct to create an easy-to-use array variable:
415 upvar #0 $token state
417 Once the data associated with the URL is no longer needed, the state
419 array should be unset to free up storage. The ::http::cleanup proce‐
420 dure is provided for that purpose. The following elements of the array
421 are supported:
422 body The contents of the URL. This will be empty if the
424 -channel option has been specified. This value is
425 returned by the ::http::data command.
426 charset
428 The value of the charset attribute from the Content-Type
429 meta-data value. If none was specified, this defaults to
430 the RFC standard iso8859-1, or the value of
431 $::http::defaultCharset. Incoming text data will be
432 automatically converted from this charset to utf-8.
433 coding A copy of the Content-Encoding meta-data value.
435 currentsize
437 The current number of bytes fetched from the URL. This
438 value is returned by the ::http::size command.
439 error If defined, this is the error string seen when the HTTP
441 transaction was aborted.
442 http The HTTP status reply from the server. This value is
444 returned by the ::http::code command. The format of this
445 value is:
446 HTTP/1.1 code string
448 The code is a three-digit number defined in the HTTP
450 standard. A code of 200 is OK. Codes beginning with 4
451 or 5 indicate errors. Codes beginning with 3 are redi‐
452 rection errors. In this case the Location meta-data
453 specifies a new URL that contains the requested informa‐
454 tion.
455 meta The HTTP protocol returns meta-data that describes the
457 URL contents. The meta element of the state array is a
458 list of the keys and values of the meta-data. This is in
459 a format useful for initializing an array that just con‐
460 tains the meta-data:
461 array set meta $state(meta)
463 Some of the meta-data keys are listed below, but the HTTP
465 standard defines more, and servers are free to add their
466 own.
467 Content-Type
469 The type of the URL contents. Examples include
470 text/html, image/gif, application/postscript and
471 application/x-tcl.
472 Content-Length
474 The advertised size of the contents. The actual
475 size obtained by ::http::geturl is available as
476 state(currentsize).
477 Location
479 An alternate URL that contains the requested data.
480 posterror
482 The error, if any, that occurred while writing the post
483 query data to the server.
484 status Either ok, for successful completion, reset for user-
486 reset, timeout if a timeout occurred before the transac‐
487 tion could complete, or error for an error condition.
488 During the transaction this value is the empty string.
489 totalsize
491 A copy of the Content-Length meta-data value.
492 type A copy of the Content-Type meta-data value.
494 url The requested URL.
496
498 This example creates a procedure to copy a URL to a file while printing
499 a progress meter, and prints the meta-data associated with the URL.
500 proc httpcopy { url file {chunk 4096} } {
502 set out [open $file w]
503 set token [::http::geturl $url -channel $out \
504 -progress httpCopyProgress -blocksize $chunk]
505 close $out
506 # This ends the line started by httpCopyProgress
508 puts stderr ""
509 upvar #0 $token state
511 set max 0
512 foreach {name value} $state(meta) {
513 if {[string length $name] > $max} {
514 set max [string length $name]
515 }
516 if {[regexp -nocase ^location$ $name]} {
517 # Handle URL redirects
518 puts stderr "Location:$value"
519 return [httpcopy [string trim $value] $file $chunk]
520 }
521 }
522 incr max
523 foreach {name value} $state(meta) {
524 puts [format "%-*s %s" $max $name: $value]
525 }
526 return $token
528 }
529 proc httpCopyProgress {args} {
530 puts -nonewline stderr .
531 flush stderr
532 }
533
535 safe(n), socket(n), safesock(n)
536
538 internet, security policy, socket, www
539http 2.7 http(n)