Http

-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."

-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章節。

upvar #0 $token state

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

meta

HTTP 協議返回描述 URL 內容的元資料。狀態陣列的 meta 元素是元資料的鍵和值的一個列表。下面的格式對初始化只包含元資料的一個數組有用:

array set meta $state(meta)

posterror

在向伺服器寫 post 查詢時發生的錯誤。如果有的話。

status

對於成功完成是 ok，對於使用者重重置(user-reset)是 reset，如果在事務完成之前發生了超時則是timeout。或在錯誤的情況下是 error。在事務(進行)期間這個值是一個空串。

totalsize

Content-Length 元資料值的一個複本。

type

Content-Type 元資料值的一個複本。

url

請求的 URL。

 
# 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
}