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
}
- 使用這個選項來給 HTTP
請求增加額外的頭部。keyvaluelist
參數必須是有偶數個元素的一個列表,這些元素是交替的鍵(key)和值。這些鍵變成頭部的字段名字。從這些值中去除(strip)換行符,所以頭部不會被中斷(corrupt)。例如,如果
keyvaluelist 是 Pragma no-cache 則在 HTTP
請求中包含下列頭部:
- -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)來建立一個易用的數組變量:
一旦與某個 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
命令返回這個值。這個值的格式是:
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
《中國 Linux 論壇 man
手冊頁翻譯計劃》:
http://cmpp.linuxforum.net
跋
本頁面中文版由中文
man 手冊頁計劃提供。
中文 man
手冊頁計劃:https://github.com/man-pages-zh/manpages-zh