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