1 | '\" |
---|
2 | '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. |
---|
3 | '\" Copyright (c) 1998-2000 by Ajuba Solutions. |
---|
4 | '\" Copyright (c) 2004 ActiveState Corporation. |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: http.n,v 1.36 2008/03/12 10:01:02 hobbs Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH "http" n 2.7 http "Tcl Bundled Packages" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | http \- Client-side implementation of the HTTP/1.1 protocol |
---|
17 | .SH SYNOPSIS |
---|
18 | \fBpackage require http ?2.7?\fR |
---|
19 | .\" See Also -useragent option documentation in body! |
---|
20 | .sp |
---|
21 | \fB::http::config \fI?options?\fR |
---|
22 | .sp |
---|
23 | \fB::http::geturl \fIurl ?options?\fR |
---|
24 | .sp |
---|
25 | \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? |
---|
26 | .sp |
---|
27 | \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? |
---|
28 | .sp |
---|
29 | \fB::http::wait \fItoken\fR |
---|
30 | .sp |
---|
31 | \fB::http::status \fItoken\fR |
---|
32 | .sp |
---|
33 | \fB::http::size \fItoken\fR |
---|
34 | .sp |
---|
35 | \fB::http::code \fItoken\fR |
---|
36 | .sp |
---|
37 | \fB::http::ncode \fItoken\fR |
---|
38 | .sp |
---|
39 | \fB::http::meta \fItoken\fR |
---|
40 | .sp |
---|
41 | \fB::http::data \fItoken\fR |
---|
42 | .sp |
---|
43 | \fB::http::error \fItoken\fR |
---|
44 | .sp |
---|
45 | \fB::http::cleanup \fItoken\fR |
---|
46 | .sp |
---|
47 | \fB::http::register \fIproto port command\fR |
---|
48 | .sp |
---|
49 | \fB::http::unregister \fIproto\fR |
---|
50 | .BE |
---|
51 | .SH DESCRIPTION |
---|
52 | .PP |
---|
53 | The \fBhttp\fR package provides the client side of the HTTP/1.1 |
---|
54 | protocol. The package implements the GET, POST, and HEAD operations |
---|
55 | of HTTP/1.1. It allows configuration of a proxy host to get through |
---|
56 | firewalls. The package is compatible with the \fBSafesock\fR security |
---|
57 | policy, so it can be used by untrusted applets to do URL fetching from |
---|
58 | a restricted set of hosts. This package can be extended to support |
---|
59 | additional HTTP transport protocols, such as HTTPS, by providing |
---|
60 | a custom \fBsocket\fR command, via \fB::http::register\fR. |
---|
61 | .PP |
---|
62 | The \fB::http::geturl\fR procedure does a HTTP transaction. |
---|
63 | Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction |
---|
64 | is performed. |
---|
65 | The return value of \fB::http::geturl\fR is a token for the transaction. |
---|
66 | The value is also the name of an array in the ::http namespace |
---|
67 | that contains state information about the transaction. The elements |
---|
68 | of this array are described in the \fBSTATE ARRAY\fR section. |
---|
69 | .PP |
---|
70 | If the \fB\-command\fR option is specified, then |
---|
71 | the HTTP operation is done in the background. |
---|
72 | \fB::http::geturl\fR returns immediately after generating the |
---|
73 | HTTP request and the callback is invoked |
---|
74 | when the transaction completes. For this to work, the Tcl event loop |
---|
75 | must be active. In Tk applications this is always true. For pure-Tcl |
---|
76 | applications, the caller can use \fB::http::wait\fR after calling |
---|
77 | \fB::http::geturl\fR to start the event loop. |
---|
78 | .SH COMMANDS |
---|
79 | .TP |
---|
80 | \fB::http::config\fR ?\fIoptions\fR? |
---|
81 | The \fB::http::config\fR command is used to set and query the name of the |
---|
82 | proxy server and port, and the User-Agent name used in the HTTP |
---|
83 | requests. If no options are specified, then the current configuration |
---|
84 | is returned. If a single argument is specified, then it should be one |
---|
85 | of the flags described below. In this case the current value of |
---|
86 | that setting is returned. Otherwise, the options should be a set of |
---|
87 | flags and values that define the configuration: |
---|
88 | .RS |
---|
89 | .TP |
---|
90 | \fB\-accept\fR \fImimetypes\fR |
---|
91 | The Accept header of the request. The default is */*, which means that |
---|
92 | all types of documents are accepted. Otherwise you can supply a |
---|
93 | comma-separated list of mime type patterns that you are |
---|
94 | willing to receive. For example, |
---|
95 | .QW "image/gif, image/jpeg, text/*" . |
---|
96 | .TP |
---|
97 | \fB\-proxyhost\fR \fIhostname\fR |
---|
98 | The name of the proxy host, if any. If this value is the |
---|
99 | empty string, the URL host is contacted directly. |
---|
100 | .TP |
---|
101 | \fB\-proxyport\fR \fInumber\fR |
---|
102 | The proxy port number. |
---|
103 | .TP |
---|
104 | \fB\-proxyfilter\fR \fIcommand\fR |
---|
105 | The command is a callback that is made during |
---|
106 | \fB::http::geturl\fR |
---|
107 | to determine if a proxy is required for a given host. One argument, a |
---|
108 | host name, is added to \fIcommand\fR when it is invoked. If a proxy |
---|
109 | is required, the callback should return a two-element list containing |
---|
110 | the proxy server and proxy port. Otherwise the filter should return |
---|
111 | an empty list. The default filter returns the values of the |
---|
112 | \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are |
---|
113 | non-empty. |
---|
114 | .TP |
---|
115 | \fB\-urlencoding\fR \fIencoding\fR |
---|
116 | The \fIencoding\fR used for creating the x-url-encoded URLs with |
---|
117 | \fB::http::formatQuery\fR. The default is \fButf-8\fR, as specified by RFC |
---|
118 | 2718. Prior to http 2.5 this was unspecified, and that behavior can be |
---|
119 | returned by specifying the empty string (\fB{}\fR), although |
---|
120 | \fIiso8859-1\fR is recommended to restore similar behavior but without the |
---|
121 | \fB::http::formatQuery\fR throwing an error processing non-latin-1 |
---|
122 | characters. |
---|
123 | .TP |
---|
124 | \fB\-useragent\fR \fIstring\fR |
---|
125 | The value of the User-Agent header in the HTTP request. The default is |
---|
126 | .QW "\fBTcl http client package 2.7\fR" . |
---|
127 | .RE |
---|
128 | .TP |
---|
129 | \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? |
---|
130 | The \fB::http::geturl\fR command is the main procedure in the package. |
---|
131 | The \fB\-query\fR option causes a POST operation and |
---|
132 | the \fB\-validate\fR option causes a HEAD operation; |
---|
133 | otherwise, a GET operation is performed. The \fB::http::geturl\fR command |
---|
134 | returns a \fItoken\fR value that can be used to get |
---|
135 | information about the transaction. See the \fBSTATE ARRAY\fR and |
---|
136 | \fBERRORS\fR section for |
---|
137 | details. The \fB::http::geturl\fR command blocks until the operation |
---|
138 | completes, unless the \fB\-command\fR option specifies a callback |
---|
139 | that is invoked when the HTTP transaction completes. |
---|
140 | \fB::http::geturl\fR takes several options: |
---|
141 | .RS |
---|
142 | .TP |
---|
143 | \fB\-binary\fR \fIboolean\fR |
---|
144 | Specifies whether to force interpreting the URL data as binary. Normally |
---|
145 | this is auto-detected (anything not beginning with a \fBtext\fR content |
---|
146 | type or whose content encoding is \fBgzip\fR or \fBcompress\fR is |
---|
147 | considered binary data). |
---|
148 | .TP |
---|
149 | \fB\-blocksize\fR \fIsize\fR |
---|
150 | The block size used when reading the URL. |
---|
151 | At most \fIsize\fR bytes are read at once. After each block, a call to the |
---|
152 | \fB\-progress\fR callback is made (if that option is specified). |
---|
153 | .TP |
---|
154 | \fB\-channel\fR \fIname\fR |
---|
155 | Copy the URL contents to channel \fIname\fR instead of saving it in |
---|
156 | \fBstate(body)\fR. |
---|
157 | .TP |
---|
158 | \fB\-command\fR \fIcallback\fR |
---|
159 | Invoke \fIcallback\fR after the HTTP transaction completes. |
---|
160 | This option causes \fB::http::geturl\fR to return immediately. |
---|
161 | The \fIcallback\fR gets an additional argument that is the \fItoken\fR returned |
---|
162 | from \fB::http::geturl\fR. This token is the name of an array that is |
---|
163 | described in the \fBSTATE ARRAY\fR section. Here is a template for the |
---|
164 | callback: |
---|
165 | .RS |
---|
166 | .CS |
---|
167 | proc httpCallback {token} { |
---|
168 | upvar #0 $token state |
---|
169 | # Access state as a Tcl array |
---|
170 | } |
---|
171 | .CE |
---|
172 | .RE |
---|
173 | .TP |
---|
174 | \fB\-handler\fR \fIcallback\fR |
---|
175 | Invoke \fIcallback\fR whenever HTTP data is available; if present, nothing |
---|
176 | else will be done with the HTTP data. This procedure gets two additional |
---|
177 | arguments: the socket for the HTTP data and the \fItoken\fR returned from |
---|
178 | \fB::http::geturl\fR. The token is the name of a global array that is |
---|
179 | described in the \fBSTATE ARRAY\fR section. The procedure is expected |
---|
180 | to return the number of bytes read from the socket. Here is a |
---|
181 | template for the callback: |
---|
182 | .RS |
---|
183 | .CS |
---|
184 | proc httpHandlerCallback {socket token} { |
---|
185 | upvar #0 $token state |
---|
186 | # Access socket, and state as a Tcl array |
---|
187 | # For example... |
---|
188 | ... |
---|
189 | set data [read $socket 1000] |
---|
190 | set nbytes [string length $data] |
---|
191 | ... |
---|
192 | return $nbytes |
---|
193 | } |
---|
194 | .CE |
---|
195 | .RE |
---|
196 | .TP |
---|
197 | \fB\-headers\fR \fIkeyvaluelist\fR |
---|
198 | This option is used to add extra headers to the HTTP request. The |
---|
199 | \fIkeyvaluelist\fR argument must be a list with an even number of |
---|
200 | elements that alternate between keys and values. The keys become |
---|
201 | header field names. Newlines are stripped from the values so the |
---|
202 | header cannot be corrupted. For example, if \fIkeyvaluelist\fR is |
---|
203 | \fBPragma no-cache\fR then the following header is included in the |
---|
204 | HTTP request: |
---|
205 | .CS |
---|
206 | Pragma: no-cache |
---|
207 | .CE |
---|
208 | .TP |
---|
209 | \fB\-keepalive\fR \fIboolean\fR |
---|
210 | If true, attempt to keep the connection open for servicing |
---|
211 | multiple requests. Default is 0. |
---|
212 | .TP |
---|
213 | \fB\-method\fR \fItype\fR |
---|
214 | Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will |
---|
215 | auto-select GET, POST or HEAD based on other options, but this option |
---|
216 | enables choices like PUT and DELETE for webdav support. |
---|
217 | .TP |
---|
218 | \fB\-myaddr\fR \fIaddress\fR |
---|
219 | Pass an specific local address to the underlying \fBsocket\fR call in case |
---|
220 | multiple interfaces are available. |
---|
221 | .TP |
---|
222 | \fB\-progress\fR \fIcallback\fR |
---|
223 | The \fIcallback\fR is made after each transfer of data from the URL. |
---|
224 | The callback gets three additional arguments: the \fItoken\fR from |
---|
225 | \fB::http::geturl\fR, the expected total size of the contents from the |
---|
226 | \fBContent-Length\fR meta-data, and the current number of bytes |
---|
227 | transferred so far. The expected total size may be unknown, in which |
---|
228 | case zero is passed to the callback. Here is a template for the |
---|
229 | progress callback: |
---|
230 | .RS |
---|
231 | .CS |
---|
232 | proc httpProgress {token total current} { |
---|
233 | upvar #0 $token state |
---|
234 | } |
---|
235 | .CE |
---|
236 | .RE |
---|
237 | .TP |
---|
238 | \fB\-protocol\fR \fIversion\fR |
---|
239 | Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the |
---|
240 | default). Should only be necessary for servers that do not understand or |
---|
241 | otherwise complain about HTTP/1.1. |
---|
242 | .TP |
---|
243 | \fB\-query\fR \fIquery\fR |
---|
244 | This flag causes \fB::http::geturl\fR to do a POST request that passes the |
---|
245 | \fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding |
---|
246 | formatted query. The \fB::http::formatQuery\fR procedure can be used to |
---|
247 | do the formatting. |
---|
248 | .TP |
---|
249 | \fB\-queryblocksize\fR \fIsize\fR |
---|
250 | The block size used when posting query data to the URL. |
---|
251 | At most |
---|
252 | \fIsize\fR |
---|
253 | bytes are written at once. After each block, a call to the |
---|
254 | \fB\-queryprogress\fR |
---|
255 | callback is made (if that option is specified). |
---|
256 | .TP |
---|
257 | \fB\-querychannel\fR \fIchannelID\fR |
---|
258 | This flag causes \fB::http::geturl\fR to do a POST request that passes the |
---|
259 | data contained in \fIchannelID\fR to the server. The data contained in |
---|
260 | \fIchannelID\fR must be an x-url-encoding |
---|
261 | formatted query unless the \fB\-type\fR option below is used. |
---|
262 | If a Content-Length header is not specified via the \fB\-headers\fR options, |
---|
263 | \fB::http::geturl\fR attempts to determine the size of the post data |
---|
264 | in order to create that header. If it is |
---|
265 | unable to determine the size, it returns an error. |
---|
266 | .TP |
---|
267 | \fB\-queryprogress\fR \fIcallback\fR |
---|
268 | The \fIcallback\fR is made after each transfer of data to the URL |
---|
269 | (i.e. POST) and acts exactly like the \fB\-progress\fR option (the |
---|
270 | callback format is the same). |
---|
271 | .TP |
---|
272 | \fB\-strict\fR \fIboolean\fR |
---|
273 | Whether to enforce RFC 3986 URL validation on the request. Default is 1. |
---|
274 | .TP |
---|
275 | \fB\-timeout\fR \fImilliseconds\fR |
---|
276 | If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout |
---|
277 | to occur after the specified number of milliseconds. |
---|
278 | A timeout results in a call to \fB::http::reset\fR and to |
---|
279 | the \fB\-command\fR callback, if specified. |
---|
280 | The return value of \fB::http::status\fR is \fBtimeout\fR |
---|
281 | after a timeout has occurred. |
---|
282 | .TP |
---|
283 | \fB\-type\fR \fImime-type\fR |
---|
284 | Use \fImime-type\fR as the \fBContent-Type\fR value, instead of the |
---|
285 | default value (\fBapplication/x-www-form-urlencoded\fR) during a |
---|
286 | POST operation. |
---|
287 | .TP |
---|
288 | \fB\-validate\fR \fIboolean\fR |
---|
289 | If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD |
---|
290 | request. This request returns meta information about the URL, but the |
---|
291 | contents are not returned. The meta information is available in the |
---|
292 | \fBstate(meta) \fR variable after the transaction. See the |
---|
293 | \fBSTATE ARRAY\fR section for details. |
---|
294 | .RE |
---|
295 | .TP |
---|
296 | \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...? |
---|
297 | This procedure does x-url-encoding of query data. It takes an even |
---|
298 | number of arguments that are the keys and values of the query. It |
---|
299 | encodes the keys and values, and generates one string that has the |
---|
300 | proper & and = separators. The result is suitable for the |
---|
301 | \fB\-query\fR value passed to \fB::http::geturl\fR. |
---|
302 | .TP |
---|
303 | \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR? |
---|
304 | This command resets the HTTP transaction identified by \fItoken\fR, if |
---|
305 | any. This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback. |
---|
306 | .TP |
---|
307 | \fB::http::wait\fR \fItoken\fR |
---|
308 | This is a convenience procedure that blocks and waits for the |
---|
309 | transaction to complete. This only works in trusted code because it |
---|
310 | uses \fBvwait\fR. Also, it is not useful for the case where |
---|
311 | \fB::http::geturl\fR is called \fIwithout\fR the \fB\-command\fR option |
---|
312 | because in this case the \fB::http::geturl\fR call does not return |
---|
313 | until the HTTP transaction is complete, and thus there is nothing to |
---|
314 | wait for. |
---|
315 | .TP |
---|
316 | \fB::http::data\fR \fItoken\fR |
---|
317 | This is a convenience procedure that returns the \fBbody\fR element |
---|
318 | (i.e., the URL data) of the state array. |
---|
319 | .TP |
---|
320 | \fB::http::error\fR \fItoken\fR |
---|
321 | This is a convenience procedure that returns the \fBerror\fR element |
---|
322 | of the state array. |
---|
323 | .TP |
---|
324 | \fB::http::status\fR \fItoken\fR |
---|
325 | This is a convenience procedure that returns the \fBstatus\fR element of |
---|
326 | the state array. |
---|
327 | .TP |
---|
328 | \fB::http::code\fR \fItoken\fR |
---|
329 | This is a convenience procedure that returns the \fBhttp\fR element of the |
---|
330 | state array. |
---|
331 | .TP |
---|
332 | \fB::http::ncode\fR \fItoken\fR |
---|
333 | This is a convenience procedure that returns just the numeric return |
---|
334 | code (200, 404, etc.) from the \fBhttp\fR element of the state array. |
---|
335 | .TP |
---|
336 | \fB::http::size\fR \fItoken\fR |
---|
337 | This is a convenience procedure that returns the \fBcurrentsize\fR |
---|
338 | element of the state array, which represents the number of bytes |
---|
339 | received from the URL in the \fB::http::geturl\fR call. |
---|
340 | .TP |
---|
341 | \fB::http::meta\fR \fItoken\fR |
---|
342 | This is a convenience procedure that returns the \fBmeta\fR |
---|
343 | element of the state array which contains the HTTP response |
---|
344 | headers. See below for an explanation of this element. |
---|
345 | .TP |
---|
346 | \fB::http::cleanup\fR \fItoken\fR |
---|
347 | This procedure cleans up the state associated with the connection |
---|
348 | identified by \fItoken\fR. After this call, the procedures |
---|
349 | like \fB::http::data\fR cannot be used to get information |
---|
350 | about the operation. It is \fIstrongly\fR recommended that you call |
---|
351 | this function after you are done with a given HTTP request. Not doing |
---|
352 | so will result in memory not being freed, and if your app calls |
---|
353 | \fB::http::geturl\fR enough times, the memory leak could cause a |
---|
354 | performance hit...or worse. |
---|
355 | .TP |
---|
356 | \fB::http::register\fR \fIproto port command\fR |
---|
357 | This procedure allows one to provide custom HTTP transport types |
---|
358 | such as HTTPS, by registering a prefix, the default port, and the |
---|
359 | command to execute to create the Tcl \fBchannel\fR. E.g.: |
---|
360 | .RS |
---|
361 | .CS |
---|
362 | package require http |
---|
363 | package require tls |
---|
364 | |
---|
365 | ::http::register https 443 ::tls::socket |
---|
366 | |
---|
367 | set token [::http::geturl https://my.secure.site/] |
---|
368 | .CE |
---|
369 | .RE |
---|
370 | .TP |
---|
371 | \fB::http::unregister\fR \fIproto\fR |
---|
372 | This procedure unregisters a protocol handler that was previously |
---|
373 | registered via \fB::http::register\fR. |
---|
374 | .SH ERRORS |
---|
375 | The \fB::http::geturl\fR procedure will raise errors in the following cases: |
---|
376 | invalid command line options, |
---|
377 | an invalid URL, |
---|
378 | a URL on a non-existent host, |
---|
379 | or a URL at a bad port on an existing host. |
---|
380 | These errors mean that it |
---|
381 | cannot even start the network transaction. |
---|
382 | It will also raise an error if it gets an I/O error while |
---|
383 | writing out the HTTP request header. |
---|
384 | For synchronous \fB::http::geturl\fR calls (where \fB\-command\fR is |
---|
385 | not specified), it will raise an error if it gets an I/O error while |
---|
386 | reading the HTTP reply headers or data. Because \fB::http::geturl\fR |
---|
387 | does not return a token in these cases, it does all the required |
---|
388 | cleanup and there is no issue of your app having to call |
---|
389 | \fB::http::cleanup\fR. |
---|
390 | .PP |
---|
391 | For asynchronous \fB::http::geturl\fR calls, all of the above error |
---|
392 | situations apply, except that if there is any error while reading the |
---|
393 | HTTP reply headers or data, no exception is thrown. This is because |
---|
394 | after writing the HTTP headers, \fB::http::geturl\fR returns, and the |
---|
395 | rest of the HTTP transaction occurs in the background. The command |
---|
396 | callback can check if any error occurred during the read by calling |
---|
397 | \fB::http::status\fR to check the status and if its \fIerror\fR, |
---|
398 | calling \fB::http::error\fR to get the error message. |
---|
399 | .PP |
---|
400 | Alternatively, if the main program flow reaches a point where it needs |
---|
401 | to know the result of the asynchronous HTTP request, it can call |
---|
402 | \fB::http::wait\fR and then check status and error, just as the |
---|
403 | callback does. |
---|
404 | .PP |
---|
405 | In any case, you must still call |
---|
406 | \fB::http::cleanup\fR to delete the state array when you are done. |
---|
407 | .PP |
---|
408 | There are other possible results of the HTTP transaction |
---|
409 | determined by examining the status from \fB::http::status\fR. |
---|
410 | These are described below. |
---|
411 | .TP |
---|
412 | ok |
---|
413 | If the HTTP transaction completes entirely, then status will be \fBok\fR. |
---|
414 | However, you should still check the \fB::http::code\fR value to get |
---|
415 | the HTTP status. The \fB::http::ncode\fR procedure provides just |
---|
416 | the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR |
---|
417 | procedure returns a value like |
---|
418 | .QW "HTTP 404 File not found" . |
---|
419 | .TP |
---|
420 | eof |
---|
421 | If the server closes the socket without replying, then no error |
---|
422 | is raised, but the status of the transaction will be \fBeof\fR. |
---|
423 | .TP |
---|
424 | error |
---|
425 | The error message will also be stored in the \fBerror\fR status |
---|
426 | array element, accessible via \fB::http::error\fR. |
---|
427 | .PP |
---|
428 | Another error possibility is that \fB::http::geturl\fR is unable to |
---|
429 | write all the post query data to the server before the server |
---|
430 | responds and closes the socket. |
---|
431 | The error message is saved in the \fBposterror\fR status array |
---|
432 | element and then \fB::http::geturl\fR attempts to complete the |
---|
433 | transaction. |
---|
434 | If it can read the server's response |
---|
435 | it will end up with an \fBok\fR status, otherwise it will have |
---|
436 | an \fBeof\fR status. |
---|
437 | .SH "STATE ARRAY" |
---|
438 | The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to |
---|
439 | get to the state of the HTTP transaction in the form of a Tcl array. |
---|
440 | Use this construct to create an easy-to-use array variable: |
---|
441 | .CS |
---|
442 | upvar #0 $token state |
---|
443 | .CE |
---|
444 | Once the data associated with the URL is no longer needed, the state |
---|
445 | array should be unset to free up storage. |
---|
446 | The \fB::http::cleanup\fR procedure is provided for that purpose. |
---|
447 | The following elements of |
---|
448 | the array are supported: |
---|
449 | .RS |
---|
450 | .TP |
---|
451 | \fBbody\fR |
---|
452 | The contents of the URL. This will be empty if the \fB\-channel\fR |
---|
453 | option has been specified. This value is returned by the \fB::http::data\fR command. |
---|
454 | .TP |
---|
455 | \fBcharset\fR |
---|
456 | The value of the charset attribute from the \fBContent-Type\fR meta-data |
---|
457 | value. If none was specified, this defaults to the RFC standard |
---|
458 | \fBiso8859-1\fR, or the value of \fB$::http::defaultCharset\fR. Incoming |
---|
459 | text data will be automatically converted from this charset to utf-8. |
---|
460 | .TP |
---|
461 | \fBcoding\fR |
---|
462 | A copy of the \fBContent-Encoding\fR meta-data value. |
---|
463 | .TP |
---|
464 | \fBcurrentsize\fR |
---|
465 | The current number of bytes fetched from the URL. |
---|
466 | This value is returned by the \fB::http::size\fR command. |
---|
467 | .TP |
---|
468 | \fBerror\fR |
---|
469 | If defined, this is the error string seen when the HTTP transaction |
---|
470 | was aborted. |
---|
471 | .TP |
---|
472 | \fBhttp\fR |
---|
473 | The HTTP status reply from the server. This value |
---|
474 | is returned by the \fB::http::code\fR command. The format of this value is: |
---|
475 | .RS |
---|
476 | .CS |
---|
477 | \fIHTTP/1.1 code string\fR |
---|
478 | .CE |
---|
479 | The \fIcode\fR is a three-digit number defined in the HTTP standard. |
---|
480 | A code of 200 is OK. Codes beginning with 4 or 5 indicate errors. |
---|
481 | Codes beginning with 3 are redirection errors. In this case the |
---|
482 | \fBLocation\fR meta-data specifies a new URL that contains the |
---|
483 | requested information. |
---|
484 | .RE |
---|
485 | .TP |
---|
486 | \fBmeta\fR |
---|
487 | The HTTP protocol returns meta-data that describes the URL contents. |
---|
488 | The \fBmeta\fR element of the state array is a list of the keys and |
---|
489 | values of the meta-data. This is in a format useful for initializing |
---|
490 | an array that just contains the meta-data: |
---|
491 | .RS |
---|
492 | .CS |
---|
493 | array set meta $state(meta) |
---|
494 | .CE |
---|
495 | Some of the meta-data keys are listed below, but the HTTP standard defines |
---|
496 | more, and servers are free to add their own. |
---|
497 | .TP |
---|
498 | \fBContent-Type\fR |
---|
499 | The type of the URL contents. Examples include \fBtext/html\fR, |
---|
500 | \fBimage/gif,\fR \fBapplication/postscript\fR and |
---|
501 | \fBapplication/x-tcl\fR. |
---|
502 | .TP |
---|
503 | \fBContent-Length\fR |
---|
504 | The advertised size of the contents. The actual size obtained by |
---|
505 | \fB::http::geturl\fR is available as \fBstate(size)\fR. |
---|
506 | .TP |
---|
507 | \fBLocation\fR |
---|
508 | An alternate URL that contains the requested data. |
---|
509 | .RE |
---|
510 | .TP |
---|
511 | \fBposterror\fR |
---|
512 | The error, if any, that occurred while writing |
---|
513 | the post query data to the server. |
---|
514 | .TP |
---|
515 | \fBstatus\fR |
---|
516 | Either \fBok\fR, for successful completion, \fBreset\fR for |
---|
517 | user-reset, \fBtimeout\fR if a timeout occurred before the transaction |
---|
518 | could complete, or \fBerror\fR for an error condition. During the |
---|
519 | transaction this value is the empty string. |
---|
520 | .TP |
---|
521 | \fBtotalsize\fR |
---|
522 | A copy of the \fBContent-Length\fR meta-data value. |
---|
523 | .TP |
---|
524 | \fBtype\fR |
---|
525 | A copy of the \fBContent-Type\fR meta-data value. |
---|
526 | .TP |
---|
527 | \fBurl\fR |
---|
528 | The requested URL. |
---|
529 | .RE |
---|
530 | .SH EXAMPLE |
---|
531 | .CS |
---|
532 | # Copy a URL to a file and print meta-data |
---|
533 | proc httpcopy { url file {chunk 4096} } { |
---|
534 | set out [open $file w] |
---|
535 | set token [\fB::http::geturl\fR $url -channel $out \e |
---|
536 | -progress httpCopyProgress -blocksize $chunk] |
---|
537 | close $out |
---|
538 | |
---|
539 | # This ends the line started by httpCopyProgress |
---|
540 | puts stderr "" |
---|
541 | |
---|
542 | upvar #0 $token state |
---|
543 | set max 0 |
---|
544 | foreach {name value} $state(meta) { |
---|
545 | if {[string length $name] > $max} { |
---|
546 | set max [string length $name] |
---|
547 | } |
---|
548 | if {[regexp -nocase ^location$ $name]} { |
---|
549 | # Handle URL redirects |
---|
550 | puts stderr "Location:$value" |
---|
551 | return [httpcopy [string trim $value] $file $chunk] |
---|
552 | } |
---|
553 | } |
---|
554 | incr max |
---|
555 | foreach {name value} $state(meta) { |
---|
556 | puts [format "%-*s %s" $max $name: $value] |
---|
557 | } |
---|
558 | |
---|
559 | return $token |
---|
560 | } |
---|
561 | proc httpCopyProgress {args} { |
---|
562 | puts -nonewline stderr . |
---|
563 | flush stderr |
---|
564 | } |
---|
565 | .CE |
---|
566 | .SH "SEE ALSO" |
---|
567 | safe(n), socket(n), safesock(n) |
---|
568 | .SH KEYWORDS |
---|
569 | security policy, socket |
---|