'\"
'\" 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