Provided by: manpages-zh_1.5.1-1_all bug

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
_________________________________________________________________

yz DESCRIPTION
       http包提供 HTTP/1.0 協議的客戶端。這茈]實現了 HTTP/1.0 的 GET、POST、和
       HEAD  操作。它允陸t置一茈N理(proxy)主機來通過防火牆。這茈]與   Safesock
       安全策略相容,所以可以被不可信任的  applets  用來從一些受制的主機做 URL
       取回(fetching)。可以擴展這茈]來支持附加的      HTTP      傳輸協議,比如
       HTTPS,通過 http::register,提供一茤w制的 socket 命令。

       ::http::geturl    過程做一次   HTTP   事務(transaction)。它的   options
       (選項)確定完成 GET、POST、或 HEAD 事務中的那一荂C::http::geturl 的返回-
       O這茖漱@荌O號(token)。這蚧也是在::http              名字空間中一-
       蚍晡漲W字,這蚍掍]含關於這茖澈H息。這-
       蚍晡漱葛嬰b狀態數組章節中描z。

       如果指定了   -command   選項,則在I景做這   HTTP  操作。::http::geturl
       在生成一                                                          HTTP
       請求和在事務完成時調用的回調過程(callback)之後立即返回。n使它工作,Tcl
       事件循環必須是活躍的(active)。在    Tk    應用中總是真的。對於純    Tcl
       應用,調用者可以在調用     ::http::geturl     之後使用     ::http::wait
       來啟動事件循環。

RO COMMANDS
       ::http::config ?options?
              使用                                              ::http::config
              命令來設置和查詢代理伺服器的和端口的名字,和在              HTTP
              請求中使用的使用者代理(User-Agent)名字。如果未指定選項,則返回當前的配制。如果指定了一-
              茬璊@的參數,則它應該是下探y-
              z的標誌之一。在這種情況下返回設置的當前-
              C否則,選項應該是定義配置的一系列標誌和:

              -accept mimetypes
                     (指定)請求的接受(類型)頭部(header)。預設是
                     */*,這意味者接受所有類型的文件。否則你可以提供用逗號分隔的你想接收的
                     mime(多用途互連網郵件擴展)類型模式的一-
                     茼C表。例如,"image/gif, image/jpeg, text/*"。

              -proxyhost hostname
                     如果有代理伺服器主機的話,它是代理伺服器主機的名字。如果這-
                     蚧是空串,則直接聯系 URL 主機。

              -proxyport number
                     代理伺服器端口。

              -proxyfilter command
                     這茤R令設置在           ::http::geturl          期間的一-
                     茼^調過程,用來決定是否為一茧鼎w主機而n求一-
                     茈N理伺服器。在調用它的時唌A向命令    command   添加的一-
                     荌捊O主機名字。如果n求一茈N理伺服器,則這-
                     茼^調過程應該返回一茼釣-
                     茪葛尷獐捸A分別是代理伺服器和代理服務端口。否則這-
                     蚢L濾器應該返回一茠臟C表。在   -proxyhost-proxyport
                     設置非空的時唌A預設的過濾器返回它怐瘓。

              -useragent string
                     在 HTTP 請求中客戶代理頭部的C預設是  "Tcl  http  client
                     package 2.2."

       ::http::geturl url ?options?
              ::http::geturl    命令是包中的主過程。-query   選項導P一   POST
              操作,而  -validate  選項導P一  HEAD  操作;否則,進行一   GET
              操作。::http::geturl       命令返回一       token       (記號)-
              A可用它來獲得關於這次事務的信息。詳情參見狀態數組和錯誤章節。除非用
              -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         得到一-
                     蚍W添的參數,它是從    ::http::geturl    返回的     token
                     (記號)。這荌O號是在狀態數組章節中描z的一蚍晡漲W字。下-
                     惇O這茼^調過程的一蚍猁:
                             proc httpCallback {token} {
                                 upvar #0 $token state
                                 # Access state as a Tcl array
                             }

              -handler callback
                     在可獲得   HTTP   數據的時埣掍    callback    ;如果(這-
                     茼^調)存在,則不對      HTTP      數據做其他任何事情。這-
                     蚢L程得到兩蚍W添的參數:  給這些   HTTP   數據的套接口和從
                     ::http::geturl         返回的         token         。這-
                     荌O號是在狀態數組章節中描z的一-
                     蚍晡漲W字。回調過程應返回從這-
                     荇M接口中讀到的字節數目。下惇O這茼^調過程的一蚍猁:
                             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
                     參數必須是有偶數茪葛尷漱@-
                     茼C表,這些元素是交替的鍵(key)和-
                     C這些鍵變成頭部的字段名字。從這些-
                     丰h除(strip)換行符,所以頭部不會被中斷(corrupt)。例如,如果
                     keyvaluelistPragma    no-cache    則在    HTTP
                     請求中包含下列頭部:
                     Pragma: no-cache

              -progress callback
                     每次從 URL  傳輸數據之後調用這  callback。這蚑掍帢o到三-
                     蚍W添的參數:  從 ::http::geturl 得來的 token,從 Content-
                     Length
                     元(meta)數據得來的期望的內容總體大小,和迄今為止傳輸的字節數。期望的總體大小可以是未知的,在這種情況下向這-
                     茼^調傳遞零。下惇O這茼^調過程的一蚍猁:
                             proc httpProgress {token total current} {
                                 upvar #0 $token state
                             }

              -query query
                     這蚍郅x導P ::http::geturl 去做向伺服器傳遞  query  的一次
                     POST  請求。這 query 必須是 x-url-encoding 編碼格式的一-
                     茯d詢。可以使用 ::http::formatQuery 過程來做格式化。

              -queryblocksize size
                     在向 URL 傳送(post)查詢數據的時唻洏帠o荈穭j小。一次最多寫
                     size  字節。  在每塊(被傳輸完畢)之後,調用 -queryprogress
                     回調過程(如果指定了這蚇龠答爾)。

              -querychannel channelID
                     這蚍郅x導P  ::http::geturl  去做向伺服器傳遞在  channelID
                     中包含的數據的一次   POST   請求。除非使用了下悸   -type
                     選項,否則在 channelID 中包含的數據必須是  x-url-encoding
                     編碼格式的一茯d詢。如果沒有通過     -headers     選項指定
                     Content-Length(內容長度)頭部,則           ::http::geturl
                     嘗試確定傳送的數據的大小來建立這蚗Y部。如果不能確定這-
                     茪j小,它返回一蚇欞~。

              -queryprogress callback
                     在每次到     URL      的數據傳輸之後調用這      callback
                     (例如,POST),並且表現(act)得與                 -progress
                     選項精確的相似(回調過程的格式相同)。

              -timeout milliseconds
                     如果   milliseconds    是非零(的數),則    ::http::geturl
                     設置在這蚍r指定的毫秒後發生一荈W時(timeout)。如果指定了
                     ::http::reset-command   回調過程,一荈W時導P對它-
                     怐瑤掍峞C在超時發生之後,::http::status         的返回O
                     timeout-type mime-type
                     使用 mime-type  作為  Content-Type  (內容類型)的A在一次
                     POST                                  操作期間,替換預設-
                     (application/x-www-form-urlencoded)。

              -validate boolean
                     如果 boolean 是非零,則 ::http::geturl 做一次  HTTP  HEAD
                     請求。這蚑虼D返回關於這                              URL
                     的元(meta)信息,而不返回(具體)內容。這茖妨嶆b
                     state(meta)         變量中可獲得這些元信息。詳情參見STATE
                     ARRAY章節。

       ::http::formatQuery key value ?key value ...?
              這蚢L程做查詢數據的    x-url     編碼。它接受偶數荌捊A它怓O這-
              茯d詢的鍵和C它編碼這些鍵和A並生成有正確的 & 和 = 分隔符的一-
              茼r符串。 結果適合於傳遞給 ::http::geturl-query 的C

       ::http::reset token ?why?
              這茤R令姜m用   token   標識的   HTTP    事務。如果有的話,它設置
              state(status)why,它的預設O  reset,並且接著調用注冊的
              -command 回調。

       ::http::wait token
              這是阻塞並等待一茖髡赤漱@茪隢K函數。它使用了           vwait
              所以只能在可信賴的代碼中工作。還有,它對調用      ::http::geturl
              而不加 -command 選項的情況沒有用處,在這種情況下  ::http::geturl
              在 HTTP 事務完成之前不返回,所以不需等待。

       ::http::data token
              這是返回狀態數組的 body 元素(例如,URL 數據)的一茪隢K過程。

       ::http::error token
              這是返回狀態數組的 error 元素的一茪隢K過程。

       ::http::status token
              這是返回狀態數組的 status 元素的一茪隢K過程。

       ::http::code token
              這是返回狀態數組的 http 元素的一茪隢K過程。

       ::http::ncode token
              這是只返回狀態數組的   http   元素的數藀^碼(200、404  等)的一-
              茪隢K過程。

       ::http::size token
              這是返回狀態數組的    currentsize    元素的一茪隢K過程,它表示在
              ::http::geturl 調用中從 URL 接收的字節數。

       ::http::cleanup token
              這蚢L程清除與由         token        標識的連接相關的狀態。在這-
              蚑掍峇妨寣A不能使用像     ::http::data     這樣的過程得到關於這-
              蚞犑@的信息。強烈建議你在做完一荅S定的    HTTP   操作之後調用這-
              茖蝻C不這樣做將導P記憶體不被釋放,如果你的應用調用
              ::http::geturl          次數足夠多,記憶體泄露(leak)將導P性能下-
              (hit)...或更糟。

       ::http::register proto port command
              這蚢L程允釦A通過注冊一茷e綴、預設端口、和建立    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
              這蚢L程注銷(unregister)以前通過          http::register注冊的一-
              茖鬎陶B理器(handler)。

~ ERRORS
       http::geturl  過程在下列情況下將引發(raise)錯誤:  無效的命令行選項、一-
       茧L效的    URL、在一茪ㄕs在的主機上的一    URL、或在一茼s在的主機的一-
       茪ㄗ}端口上的一    URL。這些錯誤意味著它不能開始網路事務。如果它在寫出
       HTTP    請求頭部期間得到了一    I/O    錯誤,它也引發一蚇欞~。對於同步
       ::http::geturl      調用(這茈憤定      -command),如果它在讀      HTTP
       回應頭部或數據期間得到一  I/O  錯誤,它將引發一蚇欞~。因為在這種情況下
       ::http::geturl    不返回一荌O號,它做所有需n的清除,你的應用沒有必n調用
       ::http::cleanup。

       對於異步 ::http::geturl  調用,除了在讀 HTTP 回應頭部或數據期間出現 I/O
       錯誤之外,所有上z錯誤情況不引起(throw)例外(異常)。這是因為在寫完   HTTP
       頭部之後,::http::geturl        返回,而餘下的       HTTP       事務在-
       I景發生。命令的回調過程可以通過調用                      ::http::status
       來檢查狀態,查看在讀的時圇O否發生了     error    錯誤,如果有錯誤,調用
       ::http::error 來得到錯誤的消息。

       另一蚇嚝隉A如果主程式流到達需n知道異步                             HTTP
       請求的結果的某點(point),它可以調用       ::http::wait      並接著像上-
       悸漲^調過程做的那樣檢查狀態和錯誤。

       在任何情況下,你必須在你做完(檢查)的時埣掍               http::cleanup
       來刪除狀態數組。

       下探yz的是用 http::status 檢查狀態能確定的 HTTP 事務的可能的結果。

       ok     如果    HTTP    事務完整完成,則狀態將是    ok。但是,你仍需檢查
              http::code  的荓o到   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
       接著嘗試完成這茖C如果它能讀到伺服器的響應,它將以一             ok
       狀態結束,否則將有一 eof 狀態。

A STATE ARRAY
       ::http::geturl 過程返回一  token  ,可以用它來得到一  Tcl  數組形式的
       HTTP 事務狀態。使用下掖o蚨c造(construct)來建立一茤鬘峈獐桲僆q:
              upvar #0 $token state
       一旦與某               url              有關的數據不再需n,應當清除這-
       蚍旍蚅孺韘s儲(空間)。為此提供了        http::cleanup        過程。這-
       蚍掑銕糷U列元素:

              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  如果定義了這茪葛嚏A這是終止        HTTP        事務時(描-
                     z)錯誤的字符串。

              http   從伺服器回應的  HTTP  狀態。用  ::http::code 命令返回這-
                     C這蚧的格式是:
                             HTTP/1.0 code string
                     code  是在  HTTP   標準中定義的一茪T位數。代碼   200   是
                     OK。以4或5開始           的代碼指示錯誤。以3開始的代碼是-
                     咿w向錯誤。在這種情況下,Location
                     元數據指定包含所需信息的一虓s URL。

              meta   HTTP   協議返回描z   URL   內容的元數據。狀態數組的  meta
                     元素是元數據的鍵和漱@茼C表。下-
                     悸漁璁★麊鴝l化只包含元數據的一蚍捰野:
                             array set meta $state(meta)
                     下惘C出一些元數據的鍵,HTTP
                     標準定義了更多,伺服器可自由的添加它怞菑v的鍵。

                     Content-Type
                             URL                          內容的類型。例子包括
                             text/htmlimage/gifapplication/postscriptapplication/x-tclContent-Length
                             內容的通告(advertise)的大小。通過  ::http::geturl
                             獲得的實際大小作為 state(size) 來獲取。

                     Location
                             包含所需的數據的一茈i替代的 URL。

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

              status 對於成尼髡足O            ok,對於使用者垂置(user-reset)是
                     reset,如果在事務完成之前發生了超時則是timeout。或在錯誤的情況下是
                     error。在事務(進行)期間這蚧是一茠臟瞗C

              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)

r KEYWORDS
       security policy, socket

[]
      Hhh

[]
       2001/09/20

m Linux manUpn:
       http://cmpp.linuxforum.net