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
_________________________________________________________________

 DESCRIPTION
       http包提供 HTTP/1.0 幸榈目突Ф恕U飧霭迪至 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)。例如,如果
                     keyvaluelistPragma    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/htmlimage/gifapplication/postscriptapplication/x-tclContent-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