Provided by: manpages-zh_1.6.3.2-1_all 
NAME
Http - HTTP/1.0 協議客戶端的實現。
總覽 SYNOPSIS
package require http ?2.4?
::http::config ?options?
::http::geturl url ?options?
::http::formatQuery list
::http::reset token
::http::wait token
::http::status token
::http::size token
::http::code token
::http::ncode token
::http::data token
::http::error token
::http::cleanup token
::http::register proto port command
::http::unregister proto
_________________________________________________________________
描述 DESCRIPTION
http包提供 HTTP/1.0 協議的客戶端。這個包實現了 HTTP/1.0 的 GET、POST、和 HEAD 操作。它允許配置一個代
理(proxy)主機來通過防火牆。這個包與 Safesock 安全策略相容，所以可以被不可信任的 applets 用來從一些受限制
的主機做 URL 取回(fetching)。可以擴展這個包來支持附加的 HTTP 傳輸協議，比如 HTTPS，通過
http::register，提供一個定製的 socket 命令。
::http::geturl 過程做一次 HTTP 事務(transaction)。它的 options (選項)確定完成 GET、POST、或 HEAD 事務中
的那一個。::http::geturl 的返回值是這個事務的一個記號(token)。這個值也是在::http 名字空間中一個數組的名
字，這個數組包含關於這個事務的信息。這個數組的元素在狀態數組章節中描述。
如果指定了 -command 選項，則在後臺做這個 HTTP 操作。::http::geturl 在生成一個 HTTP 請求和在事務完成時調用
的回調過程(callback)之後立即返回。要使它工作，Tcl 事件循環必須是活躍的(active)。在 Tk 應用中總是真的。對
於純 Tcl 應用，調用者可以在調用 ::http::geturl 之後使用 ::http::wait 來啓動事件循環。
命令 COMMANDS
::http::config ?options?
使用 ::http::config 命令來設置和查詢代理服務器的和端口的名字，和在 HTTP 請求中使用的用戶代理(User-
Agent)名字。如果未指定選項，則返回當前的配製。如果指定了一個單一的參數，則它應該是下面描述的標誌之
一。在這種情況下返回設置的當前值。否則，選項應該是定義配置的一系列標誌和值:
-accept mimetypes
(指定)請求的接受(類型)頭部(header)。缺省是 */*，這意味者接受所有類型的文檔。否則你可以提供
用逗號分隔的你想接收的 mime(多用途互連網郵件擴展)類型模式的一個列表。例如，"image/gif,
image/jpeg, text/*"。
-proxyhost hostname
如果有代理服務器主機的話，它是代理服務器主機的名字。如果這個值是空串，則直接聯繫 URL 主機。
-proxyport number
代理服務器端口。
-proxyfilter command
這個命令設置在 ::http::geturl 期間的一個回調過程，用來決定是否爲一個給定主機而要求一個代理
服務器。在調用它的時候，向命令 command 添加的一個參數是主機名字。如果要求一個代理服務器，則
這個回調過程應該返回一個有兩個元素的數組，分別是代理服務器和代理服務端口。否則這個過濾器應
該返回一個空列表。在 -proxyhost 和 -proxyport 設置非空的時候，缺省的過濾器返回它們的值。
-useragent string
在 HTTP 請求中客戶代理頭部的值。缺省是 "Tcl http client package 2.2."
::http::geturl url ?options?
::http::geturl 命令是包中的主過程。-query 選項導致一個 POST 操作，而 -validate 選項導致一個 HEAD
操作；否則，進行一個 GET 操作。::http::geturl 命令返回一個 token (記號)值，可用它來獲得關於這次事
務的信息。詳情參見狀態數組和錯誤章節。除非用 -command 選項指定在 HTTP 事務完成時調用的一個回調過
程，否則 ::http::geturl 命令在操作完成之前一直阻塞。 ::http::geturl 接受一些選項:
-binary boolean
Specifies whether to force interpreting the url data as binary. Normally this is auto-
detected (anything not beginning with a text content type or whose content encoding is gzip
or compress is considered binary data).
-blocksize size
在讀 URL 時使用塊大小。一次最多讀 size 字節。讀完每一塊之後，調用 -progress 回調過程(如果指
定着這個選項的話)。
-channel name
複製 URL 內容到叫 name 的通道中而不是保存在 state(body) 中。
-command callback
在這次 HTTP 事務完成之後調用 callback。這個選項導致 ::http::geturl 立即返回。callback 得到
一個增添的參數，它是從 ::http::geturl 返回的 token (記號)。這個記號是在狀態數組章節中描述的
一個數組的名字。下面是這個回調過程的一個模版:
proc httpCallback {token} {
upvar #0 $token state
# Access state as a Tcl array
}
-handler callback
在可獲得 HTTP 數據的時候調用 callback ；如果(這個回調)存在，則不對 HTTP 數據做其他任何事
情。這個過程得到兩個增添的參數: 給這些 HTTP 數據的套接口和從 ::http::geturl 返回的 token
。這個記號是在狀態數組章節中描述的一個數組的名字。回調過程應返回從這個套接口中讀到的字節數
目。下面是這個回調過程的一個模版:
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
}
-headers keyvaluelist
使用這個選項來給 HTTP 請求增加額外的頭部。keyvaluelist 參數必須是有偶數個元素的一個列表，這
些元素是交替的鍵(key)和值。這些鍵變成頭部的字段名字。從這些值中去除(strip)換行符，所以頭部
不會被中斷(corrupt)。例如，如果 keyvaluelist 是 Pragma no-cache 則在 HTTP 請求中包含下列頭
部:
Pragma: no-cache
-progress callback
每次從 URL 傳輸數據之後調用這個 callback。這個調用得到三個增添的參數: 從 ::http::geturl 得
來的 token，從 Content-Length 元(meta)數據得來的期望的內容總體大小，和迄今爲止傳輸的字節
數。期望的總體大小可以是未知的，在這種情況下向這個回調傳遞零。下面是這個回調過程的一個模版:
proc httpProgress {token total current} {
upvar #0 $token state
}
-query query
這個標誌導致 ::http::geturl 去做向服務器傳遞 query 的一次 POST 請求。這個 query 必須是 x-
url-encoding 編碼格式的一個查詢。可以使用 ::http::formatQuery 過程來做格式化。
-queryblocksize size
在向 URL 傳送(post)查詢數據的時候使用這個塊大小。一次最多寫 size 字節。 在每塊(被傳輸完
畢)之後，調用 -queryprogress 回調過程(如果指定了這個選項的話)。
-querychannel channelID
這個標誌導致 ::http::geturl 去做向服務器傳遞在 channelID 中包含的數據的一次 POST 請求。除非
使用了下面的 -type 選項，否則在 channelID 中包含的數據必須是 x-url-encoding 編碼格式的一個
查詢。如果沒有通過 -headers 選項指定 Content-Length(內容長度)頭部，則 ::http::geturl 嘗試確
定傳送的數據的大小來建立這個頭部。如果不能確定這個大小，它返回一個錯誤。
-queryprogress callback
在每次到 URL 的數據傳輸之後調用這個 callback (例如，POST)，並且表現(act)得與 -progress 選項
精確的相似(回調過程的格式相同)。
-timeout milliseconds
如果 milliseconds 是非零(的數)，則 ::http::geturl 設置在這個數字指定的毫秒後發生一個超
時(timeout)。如果指定了 ::http::reset 和 -command 回調過程，一個超時導致對它們的調用。在超
時發生之後，::http::status 的返回值是 timeout。
-type mime-type
使用 mime-type 作爲 Content-Type (內容類型)的值，在一次 POST 操作期間，替換缺省
值(application/x-www-form-urlencoded)。
-validate boolean
如果 boolean 是非零，則 ::http::geturl 做一次 HTTP HEAD 請求。這個請求返回關於這個 URL 的
元(meta)信息，而不返回(具體)內容。這個事務之後在 state(meta) 變量中可獲得這些元信息。詳情
參見STATE ARRAY章節。
::http::formatQuery key value ?key value ...?
這個過程做查詢數據的 x-url 編碼。它接受偶數個參數，它們是這個查詢的鍵和值。它編碼這些鍵和值，並生
成有正確的 & 和 = 分隔符的一個字符串。 結果適合於傳遞給 ::http::geturl 的 -query 的值。
::http::reset token ?why?
這個命令重置用 token 標識的 HTTP 事務。如果有的話，它設置 state(status) 值爲 why，它的缺省值是
reset，並且接着調用註冊的 -command 回調。
::http::wait token
這是阻塞並等待一個事務完成的一個方便函數。它使用了 vwait 所以只能在可信賴的代碼中工作。還有，它對
調用 ::http::geturl 而不加 -command 選項的情況沒有用處，在這種情況下 ::http::geturl 在 HTTP 事務完
成之前不返回，所以不需等待。
::http::data token
這是返回狀態數組的 body 元素(例如，URL 數據)的一個方便過程。
::http::error token
這是返回狀態數組的 error 元素的一個方便過程。
::http::status token
這是返回狀態數組的 status 元素的一個方便過程。
::http::code token
這是返回狀態數組的 http 元素的一個方便過程。
::http::ncode token
這是隻返回狀態數組的 http 元素的數值返回碼(200、404 等)的一個方便過程。
::http::size token
這是返回狀態數組的 currentsize 元素的一個方便過程，它表示在 ::http::geturl 調用中從 URL 接收的字節
數。
::http::cleanup token
這個過程清除與由 token 標識的連接相關的狀態。在這個調用之後，不能使用象 ::http::data 這樣的過程得
到關於這個操作的信息。強烈建議你在做完一個特定的 HTTP 操作之後調用這個函數。不這樣做將導致內存不被
釋放，如果你的應用調用 ::http::geturl 次數足夠多，內存泄露(leak)將導致性能下降(hit)...或更糟。
::http::register proto port command
這個過程允許你通過註冊一個前綴、缺省端口、和建立 Tcl channel (通道)的命令，提供定製的 HTTP 傳輸類
型如 HTTPS。比如:
package require http
package require tls
http::register https 443 ::tls::socket
set token [http::geturl https://my.secure.site/]
::http::unregister proto
這個過程註銷(unregister)以前通過 http::register註冊的一個協議處理器(handler)。
錯誤 ERRORS
http::geturl 過程在下列情況下將引發(raise)錯誤: 無效的命令行選項、一個無效的 URL、在一個不存在的主機上的
一個 URL、或在一個存在的主機的一個不良端口上的一個 URL。這些錯誤意味着它不能開始網絡事務。如果它在寫出
HTTP 請求頭部期間得到了一個 I/O 錯誤，它也引發一個錯誤。對於同步 ::http::geturl 調用(這個未指定
-command)，如果它在讀 HTTP 迴應頭部或數據期間得到一個 I/O 錯誤，它將引發一個錯誤。因爲在這種情況下
::http::geturl 不返回一個記號，它做所有需要的清除，你的應用沒有必要調用 ::http::cleanup。
對於異步 ::http::geturl 調用，除了在讀 HTTP 迴應頭部或數據期間出現 I/O 錯誤之外，所有上述錯誤情況不引
起(throw)例外(異常)。這是因爲在寫完 HTTP 頭部之後，::http::geturl 返回，而餘下的 HTTP 事務在後臺發生。命
令的回調過程可以通過調用 ::http::status 來檢查狀態，查看在讀的時候是否發生了 error 錯誤，如果有錯誤，調用
::http::error 來得到錯誤的消息。
另一個選擇，如果主程序流到達需要知道異步 HTTP 請求的結果的某點(point)，它可以調用 ::http::wait 並接着象上
面的回調過程做的那樣檢查狀態和錯誤。
在任何情況下，你必須在你做完(檢查)的時候調用 http::cleanup 來刪除狀態數組。
下面描述的是用 http::status 檢查狀態能確定的 HTTP 事務的可能的結果。
ok 如果 HTTP 事務完整完成，則狀態將是 ok。但是，你仍需檢查 http::code 的值來得到 HTTP 狀
態。http::ncode 過程只提供數值的錯誤(代碼)(例如，200，404 或 500) 而 http::code 過程返回象“HTTP
404 File not found”這樣的一個值。
eof 如果服務器關閉了套接口而不迴應，則不引發錯誤，但事務的狀態將是 eof。
error 錯誤消息將被存儲在狀態數組的 error 元素中，可通過 ::http::error 訪問。
另一個錯誤的可能是 http::geturl 在服務器響應並關閉套接口之前不能向服務器寫出所有的 post 查詢。錯誤消息保
存在狀態數組的 posterror 元素中，而 http::geturl 接着嘗試完成這個事務。如果它能讀到服務器的響應，它將以一
個 ok 狀態結束，否則將有一個 eof 狀態。
狀態數組 STATE ARRAY
::http::geturl 過程返回一個 token ，可以用它來得到一個 Tcl 數組形式的 HTTP 事務狀態。使用下面這個構
造(construct)來建立一個易用的數組變量:
upvar #0 $token state
一旦與某個 url 有關的數據不再需要，應當清除這個數組來釋放存儲(空間)。爲此提供了 http::cleanup 過程。這個
數組支持下列元素:
body URL 的內容。如果指定了 -channel 選項，則它將爲空。用 ::http::data 命令返回這個值。
charset
The value of the charset attribute from the Content-Type meta-data value. If none was
specified, this defaults to the RFC standard iso8859-1, or the value of
$::http::defaultCharset. Incoming text data will be automatically converted from this
charset to utf-8.
coding A copy of the Content-Encoding meta-data value.
currentsize
當前從 URL 取回的字節數。用 ::http::size 命令返回這個值。
error 如果定義了這個元素，這是終止 HTTP 事務時(描述)錯誤的字符串。
http 從服務器迴應的 HTTP 狀態。用 ::http::code 命令返回這個值。這個值的格式是:
HTTP/1.0 code string
code 是在 HTTP 標準中定義的一個三位數。代碼 200 是 OK。以4或5開始 的代碼指示錯誤。以3開始的
代碼是重定向錯誤。在這種情況下，Location 元數據指定包含所需信息的一個新 URL。
meta HTTP 協議返回描述 URL 內容的元數據。狀態數組的 meta 元素是元數據的鍵和值的一個列表。下面的
格式對初始化只包含元數據的一個數組有用:
array set meta $state(meta)
下面列出一些元數據的鍵，HTTP 標準定義了更多，服務器可自由的添加它們自己的鍵。
Content-Type
URL 內容的類型。例子包括 text/html、image/gif、application/postscript 和
application/x-tcl。
Content-Length
內容的通告(advertise)的大小。通過 ::http::geturl 獲得的實際大小作爲 state(size) 來獲
取。
Location
包含所需的數據的一個可替代的 URL。
posterror
在向服務器寫 post 查詢時發生的錯誤。如果有的話。
status 對於成功完成是 ok，對於用戶重重置(user-reset)是 reset，如果在事務完成之前發生了超時則
是timeout。或在錯誤的情況下是 error。在事務(進行)期間這個值是一個空串。
totalsize
Content-Length 元數據值的一個複本。
type Content-Type 元數據值的一個複本。
url 請求的 URL。
示例 EXAMPLE
# 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 }
參見 SEE ALSO
safe(n), socket(n), safesock(n)
關鍵字 KEYWORDS
security policy, socket
[中文版維護人]
寒蟬退士
[中文版最新更新]
2001/09/20
《中國 Linux 論壇 man 手冊頁翻譯計劃》:
http://cmpp.linuxforum.net
跋
本頁面中文版由中文 man 手冊頁計劃提供。
中文 man 手冊頁計劃：https://github.com/man-pages-zh/manpages-zh