'\"
'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
'\" Copyright (c) 1998-2000 by Ajuba Solutions.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.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
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "Http" 3tcl 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Http \- HTTP/1.0 協議客戶端的實現。
.SH 總覽 SYNOPSIS
\fBpackage require http ?2.4?\fR
.sp
\fB::http::config \fI?options?\fR
.sp
\fB::http::geturl \fIurl ?options?\fR
.sp
\fB::http::formatQuery \fIlist\fR
.sp
\fB::http::reset \fItoken\fR
.sp
\fB::http::wait \fItoken\fR
.sp
\fB::http::status \fItoken\fR
.sp
\fB::http::size \fItoken\fR
.sp
\fB::http::code \fItoken\fR
.sp
\fB::http::ncode \fItoken\fR
.sp
\fB::http::data \fItoken\fR
.sp
\fB::http::error \fItoken\fR
.sp
\fB::http::cleanup \fItoken\fR
.sp
\fB::http::register \fIproto port command\fR
.sp
\fB::http::unregister \fIproto\fR
.BE

.SH 描述 DESCRIPTION
.PP
\fBhttp\fR包提供 HTTP/1.0 協議的客戶端。這個包實現了 HTTP/1.0 的 GET、POST、和 HEAD 操作。它允許配置一個代理(proxy)主機來透過防火牆。這個包與 \fBSafesock\fR 安全策略相容，所以可以被不可信任的 applets 用來從一些受限制的主機做 URL 取回(fetching)。可以擴充套件這個包來支援附加的 HTTP 傳輸協議，比如 HTTPS，透過 \fBhttp::register\fR，提供一個定製的 \fBsocket\fR 命令。
.PP
\fB::http::geturl\fR 過程做一次 HTTP 事務(transaction)。它的 \fIoptions \fR (選項)確定完成 GET、POST、或 HEAD 事務中的那一個。\fB::http::geturl\fR 的返回值是這個事務的一個記號(token)。這個值也是在::http 名字空間中一個數組的名字，這個陣列包含關於這個事務的資訊。這個陣列的元素在狀態陣列章節中描述。
.PP
如果指定了 \fB-command\fP 選項，則在後臺做這個 HTTP 操作。\fB::http::geturl\fR 在生成一個 HTTP 請求和在事務完成時呼叫的回撥過程(callback)之後立即返回。要使它工作，Tcl 事件迴圈必須是活躍的(active)。在 Tk 應用中總是真的。對於純 Tcl 應用，呼叫者可以在呼叫 \fB::http::geturl\fR 之後使用 \fB::http::wait\fR 來啟動事件迴圈。
.SH 命令 COMMANDS
.TP
\fB::http::config\fP ?\fIoptions\fR?
使用 \fB::http::config\fR 命令來設定和查詢代理伺服器的和埠的名字，和在 HTTP 請求中使用的使用者代理(User-Agent)名字。如果未指定選項，則返回當前的配製。如果指定了一個單一的引數，則它應該是下面描述的標誌之一。在這種情況下返回設定的當前值。否則，選項應該是定義配置的一系列標誌和值:
.RS
.TP
\fB\-accept\fP \fImimetypes\fP
(指定)請求的接受(型別)頭部(header)。預設是 */*，這意味者接受所有型別的文件。否則你可以提供用逗號分隔的你想接收的 mime(多用途互連網郵件擴充套件)型別模式的一個列表。例如，"image/gif, image/jpeg, text/*"。
.TP
\fB\-proxyhost\fP \fIhostname\fP
如果有代理伺服器主機的話，它是代理伺服器主機的名字。如果這個值是空串，則直接聯絡 URL 主機。
.TP
\fB\-proxyport\fP \fInumber\fP
代理伺服器埠。
.TP
\fB\-proxyfilter\fP \fIcommand\fP
這個命令設定在 \fB::http::geturl\fR 期間的一個回撥過程，用來決定是否為一個給定主機而要求一個代理伺服器。在呼叫它的時候，向命令 \fIcommand\fR 新增的一個引數是主機名字。如果要求一個代理伺服器，則這個回撥過程應該返回一個有兩個元素的陣列，分別是代理伺服器和代理服務埠。否則這個過濾器應該返回一個空列表。在 \fB\-proxyhost\fR 和 \fB\-proxyport\fR 設定非空的時候，預設的過濾器返回它們的值。
.TP
\fB\-useragent\fP \fIstring\fP
在 HTTP 請求中客戶代理頭部的值。預設是 \fB"Tcl http client package 2.2."\fR
.RE
.TP
\fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP? 
\fB::http::geturl\fR 命令是包中的主過程。\fB\-query\fR 選項導致一個 POST 操作，而 \fB\-validate\fR 選項導致一個 HEAD 操作；否則，進行一個 GET 操作。\fB::http::geturl\fR 命令返回一個 \fItoken\fR (記號)值，可用它來獲得關於這次事務的資訊。詳情參見狀態陣列和錯誤章節。除非用 \fB\-command\fR 選項指定在 HTTP 事務完成時呼叫的一個回撥過程，否則 \fB::http::geturl\fR 命令在操作完成之前一直阻塞。 \fB::http::geturl\fR 接受一些選項:
.RS
.TP
\fB\-binary\fP \fIboolean\fP
Specifies whether to force interpreting the url data as binary.  Normally
this is auto-detected (anything not beginning with a \fBtext\fR content
type or whose content encoding is \fBgzip\fR or \fBcompress\fR is
considered binary data).
.TP
\fB\-blocksize\fP \fIsize\fP
在讀 URL 時使用塊大小。一次最多讀 \fIsize\fR 位元組。讀完每一塊之後，呼叫 \fB\-progress\fR 回撥過程(如果指定著這個選項的話)。
.TP
\fB\-channel\fP \fIname\fP
複製 URL 內容到叫 \fIname\fR 的通道中而不是儲存在 \fBstate(body)\fR 中。
.TP
\fB\-command\fP \fIcallback\fP
在這次 HTTP 事務完成之後呼叫 \fIcallback\fP。這個選項導致 \fB::http::geturl\fP 立即返回。\fIcallback\fP 得到一個增添的引數，它是從 \fB::http::geturl\fR 返回的 \fItoken\fR (記號)。這個記號是在狀態陣列章節中描述的一個數組的名字。下面是這個回撥過程的一個模版:
.RS
.CS
proc httpCallback {token} {
    upvar #0 $token state
    # Access state as a Tcl array
}
.CE
.RE
.TP
\fB\-handler\fP \fIcallback\fP
在可獲得 HTTP 資料的時候呼叫 \fIcallback\fP ；如果(這個回撥)存在，則不對 HTTP 資料做其他任何事情。這個過程得到兩個增添的引數: 給這些 HTTP 資料的套介面和從 \fB::http::geturl\fR 返回的 \fItoken\fR 。這個記號是在狀態陣列章節中描述的一個數組的名字。回撥過程應返回從這個套介面中讀到的位元組數目。下面是這個回撥過程的一個模版:
.RS
.CS
proc httpHandlerCallback {socket token} {
    upvar #0 $token state
    # Access socket, and state as a Tcl array
    ...
    (example: set data [read $socket 1000];set nbytes [string length $data])
    ...
    return nbytes
}
.CE
.RE
.TP
\fB\-headers\fP \fIkeyvaluelist\fP
使用這個選項來給 HTTP 請求增加額外的頭部。\fIkeyvaluelist\fR 引數必須是有偶數個元素的一個列表，這些元素是交替的鍵(key)和值。這些鍵變成頭部的欄位名字。從這些值中去除(strip)換行符，所以頭部不會被中斷(corrupt)。例如，如果 \fIkeyvaluelist\fR 是 \fBPragma no-cache\fR 則在 HTTP 請求中包含下列頭部:
.CS
Pragma: no-cache
.CE
.TP
\fB\-progress\fP \fIcallback\fP
每次從 URL 傳輸資料之後呼叫這個 \fIcallback\fR。這個呼叫得到三個增添的引數: 從 \fB::http::geturl\fR 得來的 \fItoken\fR，從 \fBContent-Length\fR 元(meta)資料得來的期望的內容總體大小，和迄今為止傳輸的位元組數。期望的總體大小可以是未知的，在這種情況下向這個回撥傳遞零。下面是這個回撥過程的一個模版:
.RS
.CS
proc httpProgress {token total current} {
    upvar #0 $token state
}
.CE
.RE
.TP
\fB\-query\fP \fIquery\fP
這個標誌導致 \fB::http::geturl\fR 去做向伺服器傳遞 \fIquery\fR 的一次 POST 請求。這個 \fIquery\fR 必須是 x-url-encoding 編碼格式的一個查詢。可以使用 \fB::http::formatQuery\fR 過程來做格式化。
.TP
\fB\-queryblocksize\fP \fIsize\fP
在向 URL 傳送(post)查詢資料的時候使用這個塊大小。一次最多寫 \fIsize\fR 位元組。 在每塊(被傳輸完畢)之後，呼叫 \fB\-queryprogress\fR 回撥過程(如果指定了這個選項的話)。
.TP
\fB\-querychannel\fP \fIchannelID\fP
這個標誌導致 \fB::http::geturl\fR 去做向伺服器傳遞在 \fIchannelID\fR 中包含的資料的一次 POST 請求。除非使用了下面的 \fB\-type\fP 選項，否則在 \fIchannelID\fR 中包含的資料必須是 x-url-encoding 編碼格式的一個查詢。如果沒有透過 \fB\-headers\fR 選項指定 Content-Length(內容長度)頭部，則 \fB::http::geturl\fR 嘗試確定傳送的資料的大小來建立這個頭部。如果不能確定這個大小，它返回一個錯誤。
.TP
\fB\-queryprogress\fP \fIcallback\fP
在每次到 URL 的資料傳輸之後呼叫這個 \fIcallback\fR (例如，POST)，並且表現(act)得與 \fB\-progress\fR 選項精確的相似(回撥過程的格式相同)。
.TP
\fB\-timeout\fP \fImilliseconds\fP
如果 \fImilliseconds\fR 是非零(的數)，則 \fB::http::geturl\fR 設定在這個數字指定的毫秒後發生一個超時(timeout)。如果指定了 \fB::http::reset\fP 和 \fB-command\fP 回撥過程，一個超時導致對它們的呼叫。在超時發生之後，\fB::http::status\fP 的返回值是 \fBtimeout\fP。
.TP
\fB\-type\fP \fImime-type\fP
使用 \fImime-type\fR 作為 \fBContent-Type\fR (內容型別)的值，在一次 POST 操作期間，替換預設值(\fBapplication/x-www-form-urlencoded\fR)。
.TP
\fB\-validate\fP \fIboolean\fP
如果 \fIboolean\fR 是非零，則 \fB::http::geturl\fR 做一次 HTTP HEAD 請求。這個請求返回關於這個 URL 的元(meta)資訊，而不返回(具體)內容。這個事務之後在 \fBstate(meta) \fR 變數中可獲得這些元資訊。詳情參見STATE ARRAY章節。
.RE
.TP
\fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
這個過程做查詢資料的 x-url 編碼。它接受偶數個引數，它們是這個查詢的鍵和值。它編碼這些鍵和值，並生成有正確的 & 和 = 分隔符的一個字串。 結果適合於傳遞給 \fB::http::geturl\fR 的 \fB\-query\fR 的值。
.TP
\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
這個命令重置用 \fItoken\fR 標識的 HTTP 事務。如果有的話，它設定 \fBstate(status)\fP 值為 \fIwhy\fP，它的預設值是 \fBreset\fR，並且接著呼叫註冊的 \fB\-command\fR 回撥。
.TP
\fB::http::wait\fP \fItoken\fP
這是阻塞並等待一個事務完成的一個方便函式。它使用了 \fBvwait\fR 所以只能在可信賴的程式碼中工作。還有，它對呼叫 \fB::http::geturl\fP 而不加 \fB-command\fP 選項的情況沒有用處，在這種情況下 \fB::http::geturl\fP 在 HTTP 事務完成之前不返回，所以不需等待。
.TP
\fB::http::data\fP \fItoken\fP
這是返回狀態陣列的 \fBbody\fP 元素(例如，URL 資料)的一個方便過程。
.TP
\fB::http::error\fP \fItoken\fP
這是返回狀態陣列的 \fBerror\fP 元素的一個方便過程。
.TP
\fB::http::status\fP \fItoken\fP
這是返回狀態陣列的 \fBstatus\fP 元素的一個方便過程。
.TP
\fB::http::code\fP \fItoken\fP
這是返回狀態陣列的 \fBhttp\fP 元素的一個方便過程。
.TP
\fB::http::ncode\fP \fItoken\fP
這是隻返回狀態陣列的 \fBhttp\fP 元素的數值返回碼(200、404 等)的一個方便過程。
.TP
\fB::http::size\fP \fItoken\fP
這是返回狀態陣列的 \fBcurrentsize\fP 元素的一個方便過程，它表示在 \fB::http::geturl\fP 呼叫中從 URL 接收的位元組數。
.TP
\fB::http::cleanup\fP \fItoken\fP
這個過程清除與由 \fItoken\fP 標識的連線相關的狀態。在這個呼叫之後，不能使用象 \fB::http::data\fP 這樣的過程得到關於這個操作的資訊。強烈建議你在做完一個特定的 HTTP 操作之後呼叫這個函式。不這樣做將導致記憶體不被釋放，如果你的應用呼叫 \fB::http::geturl\fP 次數足夠多，記憶體洩露(leak)將導致效能下降(hit)...或更糟。
.TP
\fB::http::register\fP \fIproto port command\fP
這個過程允許你透過註冊一個字首、預設埠、和建立 Tcl \fBchannel\fR (通道)的命令，提供定製的 HTTP 傳輸型別如 HTTPS。比如:
.RS
.CS
package require http
package require tls

http::register https 443 ::tls::socket

set token [http::geturl https://my.secure.site/]
.CE
.RE
.TP
\fB::http::unregister\fP \fIproto\fP
這個過程登出(unregister)以前透過 \fBhttp::register\fR註冊的一個協議處理器(handler)。

.SH "錯誤 ERRORS"
\fBhttp::geturl\fP 過程在下列情況下將引發(raise)錯誤: 無效的命令列選項、一個無效的 URL、在一個不存在的主機上的一個 URL、或在一個存在的主機的一個不良埠上的一個 URL。這些錯誤意味著它不能開始網路事務。如果它在寫出 HTTP 請求頭部期間得到了一個 I/O 錯誤，它也引發一個錯誤。對於同步 \fB::http::geturl\fP 呼叫(這個未指定 \fB-command\fP)，如果它在讀 HTTP 回應頭部或資料期間得到一個 I/O 錯誤，它將引發一個錯誤。因為在這種情況下 \fB::http::geturl\fP 不返回一個記號，它做所有需要的清除，你的應用沒有必要呼叫 \fB::http::cleanup\fP。
.PP
對於非同步 \fB::http::geturl\fP  呼叫，除了在讀 HTTP 回應頭部或資料期間出現 I/O 錯誤之外，所有上述錯誤情況不引起(throw)例外(異常)。這是因為在寫完 HTTP 頭部之後，\fB::http::geturl\fP 返回，而餘下的 HTTP 事務在後臺發生。命令的回撥過程可以透過呼叫 \fB::http::status\fP 來檢查狀態，檢視在讀的時候是否發生了 \fIerror\fP 錯誤，如果有錯誤，呼叫 \fB::http::error\fP 來得到錯誤的訊息。
.PP
另一個選擇，如果主程式流到達需要知道非同步 HTTP 請求的結果的某點(point)，它可以呼叫 \fB::http::wait\fP 並接著象上面的回撥過程做的那樣檢查狀態和錯誤。
.PP
在任何情況下，你必須在你做完(檢查)的時候呼叫 \fBhttp::cleanup\fP 來刪除狀態陣列。
.PP
下面描述的是用 \fBhttp::status\fP 檢查狀態能確定的 HTTP 事務的可能的結果。
.TP
ok
如果 HTTP 事務完整完成，則狀態將是 \fBok\fP。但是，你仍需檢查 \fBhttp::code\fP 的值來得到 HTTP 狀態。\fBhttp::ncode\fP 過程只提供數值的錯誤(程式碼)(例如，200，404 或 500) 而 \fBhttp::code\fP 過程返回象“HTTP 404 File not found”這樣的一個值。
.TP
eof
如果伺服器關閉了套介面而不回應，則不引發錯誤，但事務的狀態將是 \fBeof\fP。
.TP
error
錯誤訊息將被儲存在狀態陣列的 \fBerror\fP 元素中，可透過 \fB::http::error\fP 訪問。
.PP
另一個錯誤的可能是 \fBhttp::geturl\fP 在伺服器響應並關閉套介面之前不能向伺服器寫出所有的 post 查詢。錯誤訊息儲存在狀態陣列的 \fBposterror\fP 元素中，而 \fBhttp::geturl\fP 接著嘗試完成這個事務。如果它能讀到伺服器的響應，它將以一個 \fBok\fP 狀態結束，否則將有一個 \fBeof\fP 狀態。

.SH "狀態陣列 STATE ARRAY"
\fB::http::geturl\fR 過程返回一個 \fItoken\fR ，可以用它來得到一個 Tcl 陣列形式的 HTTP 事務狀態。使用下面這個構造(construct)來建立一個易用的陣列變數:
.CS
upvar #0 $token state
.CE
一旦與某個 url 有關的資料不再需要，應當清除這個陣列來釋放儲存(空間)。為此提供了 \fBhttp::cleanup\fP 過程。這個陣列支援下列元素:
.RS
.TP
\fBbody\fR
URL 的內容。如果指定了 \fB\-channel\fR 選項，則它將為空。用 \fB::http::data\fP 命令返回這個值。
.TP
\fBcharset\fR
The value of the charset attribute from the \fBContent-Type\fR meta-data
value.  If none was specified, this defaults to the RFC standard
\fBiso8859-1\fR, or the value of \fB$::http::defaultCharset\fR.  Incoming
text data will be automatically converted from this charset to utf-8.
.TP
\fBcoding\fR
A copy of the \fBContent-Encoding\fR meta-data value.
.TP
\fBcurrentsize\fR
當前從 URL 取回的位元組數。用 \fB::http::size\fP 命令返回這個值。
.TP
\fBerror\fR
如果定義了這個元素，這是終止 HTTP 事務時(描述)錯誤的字串。
.TP
\fBhttp\fR
從伺服器回應的 HTTP 狀態。用 \fB::http::code\fP 命令返回這個值。這個值的格式是:
.RS
.CS
\fIHTTP/1.0 code string\fP
.CE
\fIcode\fR 是在 HTTP 標準中定義的一個三位數。程式碼 200 是 OK。以4或5開始
的程式碼指示錯誤。以3開始的程式碼是重定向錯誤。在這種情況下，\fBLocation\fP 
元資料指定包含所需資訊的一個新 URL。
.RE
.TP
\fBmeta\fR
HTTP 協議返回描述 URL 內容的元資料。狀態陣列的 \fBmeta\fR 元素是元資料的鍵和值的一個列表。下面的格式對初始化只包含元資料的一個數組有用:
.RS
.CS
array set meta $state(meta)
.CE
下面列出一些元資料的鍵，HTTP 標準定義了更多，伺服器可自由的新增它們自己的鍵。
.TP
\fBContent-Type\fR
URL 內容的型別。例子包括 \fBtext/html\fR、\fBimage/gif\fR、\fBapplication/postscript\fR 和 \fBapplication/x-tcl\fR。
.TP
\fBContent-Length\fR
內容的通告(advertise)的大小。透過 \fB::http::geturl\fR 獲得的實際大小作為 \fBstate(size)\fR 來獲取。
.TP
\fBLocation\fR
包含所需的資料的一個可替代的 URL。
.RE
.TP
\fBposterror\fR
在向伺服器寫 post 查詢時發生的錯誤。如果有的話。
.TP
\fBstatus\fR
對於成功完成是 \fBok\fR，對於使用者重重置(user-reset)是 \fBreset\fR，如果在事務完成之前發生了超時則是\fBtimeout\fP。或在錯誤的情況下是 \fBerror\fR。在事務(進行)期間這個值是一個空串。
.TP
\fBtotalsize\fR
\fBContent-Length\fR 元資料值的一個複本。
.TP
\fBtype\fR
\fBContent-Type\fR 元資料值的一個複本。
.TP
\fBurl\fR
請求的 URL。
.RE
.SH 示例 EXAMPLE
.DS
# Copy a URL to a file and print meta-data
proc ::http::copy { url file {chunk 4096} } {
    set out [open $file w]
    set token [geturl $url -channel $out -progress ::http::Progress \\
	-blocksize $chunk]
    close $out
    # This ends the line started by http::Progress
    puts stderr ""
    upvar #0 $token state
    set max 0
    foreach {name value} $state(meta) {
	if {[string length $name] > $max} {
	    set max [string length $name]
	}
	if {[regexp -nocase ^location$ $name]} {
	    # Handle URL redirects
	    puts stderr "Location:$value"
	    return [copy [string trim $value] $file $chunk]
	}
    }
    incr max
    foreach {name value} $state(meta) {
	puts [format "%-*s %s" $max $name: $value]
    }

    return $token
}
proc ::http::Progress {args} {
    puts -nonewline stderr . ; flush stderr
}
.DE

.SH "參見 SEE ALSO"
safe(n), socket(n), safesock(n)

.SH 關鍵字 KEYWORDS
security policy, socket

.SH "[中文版維護人]"
.B 寒蟬退士
.SH "[中文版最新更新]"
.B 2001/09/20
.SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:"
.BI http://cmpp.linuxforum.net
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR