## Tcl9.0.3/Tk9.0.3 Documentation > Tcl Commands > http

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    http — HTTP/1.1 通信規約の委託者側の実装　 Client-side implementation of the HTTP/1.1 protocol
  構文 SYNOPSIS
  移送される命令 EXPORTED COMMANDS
  説明 DESCRIPTION
  COMMANDS
    ::http::config ?options?
      -accept mimetypes
      -cookiejar command
      -pipeline boolean
      -postfresh boolean
      -proxyauth string
      -proxyfilter command
      -proxyhost hostname
      -proxynot list
      -proxyport number
      -repost boolean
      -threadlevel level
        0
        1
        2
      -urlencoding encoding
      -useragent string
      -zip boolean
    ::http::geturl url ?options?
      -binary boolean
      -blocksize size
      -channel name
      -command callback
      -guesstype boolean
      -handler callback
      -headers keyvaluelist
      -keepalive boolean
      -method type
      -myaddr address
      -progress callback
      -protocol version
      -query query
      -queryblocksize size
      -querychannel channelID
      -queryprogress callback
      -strict boolean
      -timeout milliseconds
      -type mime-type
      -validate boolean
    ::http::formatQuery key value ?key value ...?
    ::http::quoteString value
    ::http::reset token ?why?
    ::http::wait token
    ::http::status token
    ::http::size token
    ::http::error token
    ::http::postError token
    ::http::cleanup token
    ::http::requestLine token
    ::http::requestHeaders token ?headerName?
    ::http::requestHeaderValue token headerName
    ::http::responseLine token
    ::http::responseCode token
    ::http::reasonPhrase code
    ::http::responseHeaders token ?headerName?
    ::http::responseHeaderValue token headerName
    ::http::responseInfo token
    ::http::responseBody token
    ::http::register proto port command ?socketCmdVarName? ?useSockThread? ?endToEndProxy?
    ::http::registerError sock ?message?
    ::http::unregister proto
    ::http::code token
    ::http::data token
    ::http::meta token ?headerName?
    ::http::ncode token
  ERRORS
    ok
    eof
    error
    timeout
    reset
  METADATA
  MOST USEFUL METADATA
    stage
    status
    responseCode
    reasonPhrase
    contentType
    binary
    redirection
    upgrade
    error
    postError
    method
    charset
    compression
    httpRequest
    httpResponse
    url
    connectionRequest
    connectionResponse
    connectionActual
    transferEncoding
    totalPost
    currentPost
    totalSize
    currentSize
  MORE METADATA
    Content-Type
    Content-Length
    Content-Encoding
    Location
    Set-Cookie
    Connection
    Upgrade
  EVEN MORE METADATA
    1.
    2.
  STATE ARRAY
    binary
    body
    charset
    coding
    connection
    currentsize
    error
    http
    httpResponse
    meta
    method
    posterror
    postErrorFull
    -protocol
    querylength
    queryoffset
    reasonPhrase
    requestHeaders
    requestLine
    responseCode
    state
    status
    totalsize
    transfer
    type
    upgrade
    url
  永続的な接続　　PERSISTENT CONNECTIONS
  基本　　BASICS
  特別な場合　　SPECIAL CASES
  COOKIE JAR PROTOCOL
    cookieJar getCookies protocol host requestPath
    cookieJar storeCookie cookieDictionary
      domain
      expires
      hostonly
      httponly
      key
      origin
      path
      secure
      value
  PROTOCOL UPGRADES
  THREADS
  PURPOSE
  WITH TLS (HTTPS)
  WITH A CHILD INTERPRETER
  EXAMPLE
  SEE ALSO
  KEYWORDS

### NAME

http — HTTP/1.1 通信規約の委託者側の実装　 Client-side implementation of the HTTP/1.1 protocol

### 構文 SYNOPSIS

package require http ?2.10?
::http::config ?-option value ...?
::http::geturl url ?-option value ...?
::http::formatQuery key value ?key value ...?
::http::quoteString value
::http::reset token ?why?
::http::wait token
::http::status token
::http::size token
::http::error token
::http::postError token
::http::cleanup token
::http::requestLine token
::http::requestHeaders token ?headerName?
::http::requestHeaderValue token headerName
::http::responseLine token
::http::responseCode token
::http::reasonPhrase code
::http::responseHeaders token ?headerName?
::http::responseHeaderValue token headerName
::http::responseInfo token
::http::responseBody token
::http::register proto port command ?socketCmdVarName? ?useSockThread? ?endToEndProxy?
::http::registerError sock ?message?
::http::unregister proto
::http::code token
::http::data token
::http::meta token ?headerName?
::http::metaValue token headerName
::http::ncode token

### 移送される命令 EXPORTED COMMANDS

名前空間 http は config命令と formatQuery命令とgeturl命令とpostError命令とquoteString命令とreasonPhrase命令とregister命令とregisterError命令とrequestHeaders命令とrequestHeaderValue命令とrequestLine命令とresponseBody命令とresponseCode命令とresponseHeaders命令とresponseHeaderValue命令とresponseInfo命令とresponseLine命令とreset命令とunregister命令とwait命令を移送する｡ Namespace http exports the commands config, formatQuery, geturl, postError, quoteString, reasonPhrase, register, registerError, requestHeaders, requestHeaderValue, requestLine, responseBody, responseCode, responseHeaders, responseHeaderValue, responseInfo, responseLine, reset, unregister, and wait.

cleanup 命令や code 命令や data 命令や error 命令や meta 命令や metaValue 命令や ncode 命令や size命令 や status 命令は移送しない｡ It does not export the commands cleanup, code, data, error, meta, metaValue, ncode, size, or status.

### 説明 DESCRIPTION

この http 梱包は､RFC 9110 から 9112に定義された委託者側の HTTP/1.1 通信規約を提供する､RFC 9110 から 9112はRFC 7230 から 7235の代替わり､更にそれはRFC 2616の代替わりである｡ この梱包は､ HTTP/1.1 の GETと POST と HEAD 操作を実装する｡それは､代理の主人の構成設定に炎の防護壁を通り貫けることを許容する｡この梱包は Safesock 安全保障方針と互換性があり､故に信頼の置けない小応用譜によって規制された一群の主人からURL取得することに使われることがあり得る｡この梱包は､::http::register 経由の特別誂えの socket 命令を与えることにより､譬えば HTTPS の様な追加的な HTTP 輸送通信規約を適用する為の拡張が可能である｡ 　　　 The http package provides the client side of the HTTP/1.1 protocol, as defined in RFC 9110 to 9112, which supersede RFC 7230 to RFC 7235, which in turn supersede RFC 2616. The package implements the GET, POST, and HEAD operations of HTTP/1.1. It allows configuration of a proxy host to get through firewalls. The package is compatible with the Safesock security policy, so it can be used by untrusted applets to do URL fetching from a restricted set of hosts. This package can be extended to support additional HTTP transport protocols, such as HTTPS, by providing a custom socket command, via ::http::register.

::http::geturl 手続函数は HTTP 一括処理を行う｡その options は GET 又は POST 又は HEAD 一括処理のどれが遂行されるかを定める｡::http::geturl の返り値は一括処理の 解析字句 である｡その解析字句は､業務を管理しその結果を調査する為に､他の命令に引数として供給することが可能である｡ 　 The ::http::geturl procedure does a HTTP transaction. Its options determine whether a GET, POST, or HEAD transaction is performed. The return value of ::http::geturl is a token for the transaction. The token can be supplied as an argument to other commands, to manage the transaction and examine its results.

もし-command指示項目が指定されると､HTTP 操作は背景でなされる｡ HTTP要求の生成直後に::http::geturlが帰り､そして､処理が完了した時､-command呼戻しが起動される｡ この働きの為に､Tcl行事巡回は活動中でなければならない｡Tk応用譜内では､この条件は常に満たされている｡純粋-Tcl応用譜の為に､呼出側は､::http::geturl呼出しの後､行事巡回を開始する為に､::http::waitを使う事ができる｡ If the -command option is specified, then the HTTP operation is done in the background. ::http::geturl returns immediately after generating the HTTP request and the -command callback is invoked when the transaction completes. For this to work, the Tcl event loop must be active. In Tk applications this is always true. For pure-Tcl applications, the caller can use ::http::wait after calling ::http::geturl to start the event loop.

註意: 行事待ち行列は -command 指示項目無しでも使われる｡副作用として､ http::geturl の実行中に任意の命令が処理され得る｡ Note: The event queue is even used without the -command option. As a side effect, arbitrary commands may be processed while http::geturl is running.

HTTP 供給者が要求に答させた時､::http::responseInfoを呼出す､それは､成功裡の処理と応答の使用を識別する為の､本質的なdictの汎データを返す｡ 返される情報の詳細は､METADATA項目を参照されたい｡ 応答そのものは､::http::geturlの-channel指示項目によって再指定されない限り､::http::responseBody命令によって返される｡ When the HTTP server has replied to the request, call the command ::http::responseInfo, which returns a dict of metadata that is essential for identifying a successful transaction and making use of the response. See section METADATA for details of the information returned. The response itself is returned by command ::http::responseBody, unless it has been redirected to a file by the -channel option of ::http::geturl.

### COMMANDS

::http::config ?options?
  この ::http::config 命令は中央集中処理装置の代理と受け口の名前､及び､ HTTP 要求中で使用される使用者-代理者の名前､の設定と問合せに使用する｡もし､何も指示項目が指定されないと､現在の構成設定が返って来る｡もし､一つの引数が指定されていると､下に記述した旗標の内の１つのはずである｡この場合､現在の設定値が返って来る｡それ以外の場合､指示項目は構成設定を定義する旗標と値の組合せになる筈である: 　　 The ::http::config command is used to set and query the name of the proxy server and port, and the User-Agent name used in the HTTP requests. If no options are specified, then the current configuration is returned. If a single argument is specified, then it should be one of the flags described below. In this case the current value of that setting is returned. Otherwise, the options should be a set of flags and values that define the configuration:

  -accept mimetypes
    受取り可能な型の指定｡省略時設定は */* で､これは文書の全ての型が受取られることを意味する｡それ以外の場合､受取る意思がある型を､ mime 型模様のコンマ区切りリストで与えることができる｡譬えば､画像や､文章の型を指定して､ “image/gif, image/jpeg, text/*” とか｡ 　　　　 The Accept header of the request. The default is */*, which means that all types of documents are accepted. Otherwise you can supply a comma-separated list of mime type patterns that you are willing to receive. For example, “image/gif, image/jpeg, text/*”.

  -cookiejar command
    HTTP cookieを管理する為に使う梱包の為のcookie貯蔵｡ commandは命令の前置辞; もし､空リスト(無為設定の値)が使われると､ 要求や応答からの貯蔵によってはcookieが送られなくなる｡ もし､供給されると､commandによって示された本命令は､下に述べられたCOOKIE JAR PROTOCOLを遵守しなければならない｡ The cookie store for the package to use to manage HTTP cookies. command is a command prefix list; if the empty list (the default value) is used, no cookies will be sent by requests or stored from responses. The command indicated by command, if supplied, must obey the COOKIE JAR PROTOCOL described below.

  -pipeline boolean
    永続的な socket 上の HTTP/1.1 一括処理はパイプライン化されるか否かを指し示す｡詳細は PERSISTENT SOCKETS の節を参照されたい｡省略時設定は 1 である｡　　　　　 Specifies whether HTTP/1.1 transactions on a persistent socket will be pipelined. See the PERSISTENT SOCKETS section for details. The default is 1.

  -postfresh boolean
    http::geturl 命令の -keepalive 指示項目を上書きして､ POST 手段の使用が常に新鮮な socket を使うことを要求するか否かを指し示す｡詳細は PERSISTENT SOCKETS の節を参照されたい｡省略時設定は 0 である｡　　　　 Specifies whether requests that use the POST method will always use a fresh socket, overriding the -keepalive option of command http::geturl. See the PERSISTENT SOCKETS section for details. The default is 0.

  -proxyauth string
    もし､非-空文字列の場合､文字列は､要求冒頭句､代理-認可の値として代理従事者に供給される｡この指示項目は､HTTP基本認証の為に使用できる｡ もし､代理従事者が､他の技術､譬えば縮約認証､により､認証を要求すると､-proxyauth指示項目は便利ではない｡ その様な場合､呼出側は､代理からの407応答を待ち､且つ､供給される為の認証値を計算し､且つ､それを､代理-認可の冒頭句の値として供給せねばならない｡ If non-empty, the string is supplied to the proxy server as the value of the request header Proxy-Authorization. This option can be used for HTTP Basic Authentication. If the proxy server requires authentication by another technique, e.g. Digest Authentication, the -proxyauth option is not useful. In that case the caller must expect a 407 response from the proxy, compute the authentication value to be supplied, and use the -headers option to supply it as the value of the Proxy-Authorization header.

  -proxyfilter command
    本命令は､代理が､与えられた亭主から要求されたのかを定める為に::http::geturlの間に作成された､追随函数である｡ 一個の引数､即ち､亭主の名前が､起動される時にcommandに追加される｡ もし代理が要求されると､追随函数は､代理従事者と代理接合口を含む二要素リストを返すべき｡それ以外の場合､濾過命令は空リストを返すべき｡ The command is a callback that is made during ::http::geturl to determine if a proxy is required for a given host. One argument, a host name, is added to command when it is invoked. If a proxy is required, the callback should return a two-element list containing the proxy server and proxy port. Otherwise the filter command should return an empty list.

    無為設定の-proxyfilterの値はhttp::ProxyRequiredであり､ この命令は､設定が非-空であれば-proxyhostと-proxyportの設定値を返す｡ 指示項目-proxyhostと-proxyportと-proxynotは､http::ProxyRequiredと､::http::geturl以外では使われない｡ 使用者供給の-proxyfilter命令はこの様な指示項目を使い得る､若しくは､代りに､呼出し記述譜から値を得るかもしれない｡後者の場合､-proxyhostと-proxyportと-proxynotとの為に提供されたどの様な値も使われない｡[訳註:??] The default value of -proxyfilter is http::ProxyRequired, and this command returns the values of the -proxyhost and -proxyport settings if they are non-empty. The options -proxyhost, -proxyport, and -proxynot are used only by http::ProxyRequired, and nowhere else in ::http::geturl. A user-supplied -proxyfilter command may use these options, or alternatively it may obtain values from elsewhere in the calling script. In the latter case, any values provided for -proxyhost, -proxyport, and -proxynot are unused.

    ::http::geturl 命令は catch 命令の内部で -proxyfilter 呼戻しを実行する｡従って callback 命令内の不都合は bgerror 把持子を呼出さない｡詳細は ERRORS を参照されたい｡ The ::http::geturl command runs the -proxyfilter callback inside a catch command. Therefore an error in the callback command does not call the bgerror handler. See the ERRORS section for details.

  -proxyhost hostname
    もしあれば､亭主の名前又は代理従事者のIP番地｡もし､この値が空文字列の場合､ 統一資源位置指定子(URL)亭主が直接接続される｡この値が如何に使わるかは-proxyfilterを参照されたい｡ The host name or IP address of the proxy server, if any. If this value is the empty string, the URL host is contacted directly. See -proxyfilter for how the value is used.

  -proxynot list
    直接利用可能な筈の領域内名称とIP番地のＴｃｌリスト､代理従事者を経由しない｡ 目的亭主名は大文字小文字を区別するstring matchを使うリスト要素と較べられる｡ 領域内名称の先頭(譬えば *.example.com)､又は､ IP番地の末尾(譬えば 192.168.0.*)に､万能符号"*"を使う事は､屡々便利である｡ この値を如何が如何に使われるかは-proxyfilterを参照されたい｡ A Tcl list of domain names and IP addresses that should be accessed directly, not through the proxy server. The target hostname is compared with each list element using a case-insensitive string match. It is often convenient to use the wildcard "*" at the start of a domain name (e.g. *.example.com) or at the end of an IP address (e.g. 192.168.0.*). See -proxyfilter for how the value is used.

  -proxyport number
    代理従事者の接続口番号｡値が如何に使用されるかは-proxyfilterを参照されたい｡ The port number of the proxy server. See -proxyfilter for how the value is used.

  -repost boolean
    中央集中処理機能が半閉じ接続を有している為に永続的接続を覆う POST 要求が失敗した時に何をすべきかを指し示す｡もし論理値が真値であると､その要求は自動的に再試用される；もし論理値が偽値であると､そうならず､ POST を再試用する前に使用者の再確認の捜索するために､ http::geturl の使用が期待される｡値の真値は特定の条件下でのみ使われるべきである｡詳細については PERSISTENT SOCKETS を参照されたい｡省略時設定は 0 である｡　　　　　　 Specifies what to do if a POST request over a persistent connection fails because the server has half-closed the connection. If boolean true, the request will be automatically retried; if boolean false it will not, and the application that uses http::geturl is expected to seek user confirmation before retrying the POST. The value true should be used only under certain conditions. See the PERSISTENT SOCKETS section for details. The default is 0.

  -threadlevel level
    Thread梱包を使うか否か､どう使うかを指定する｡levelの可能な値は0か1か2｡ Specifies whether and how to use the Thread package. Possible values of level are 0, 1 or 2.

    0
      Threadを(無為設定)使用しない (the default) do not use Thread

    1
      利用可能ならThreadを使用する､利用できないなら使わない use Thread if it is available, do not use it if it is unavailable

    2
      利用可能ならThreadを使用する､利用できないなら不都合を発する use Thread if it is available, raise an error if it is unavailable

    socket -async命令は､反対の場合に遮断できる(譬えば､DNS緩行を捜されたい)｡ Thread梱包の使用が､この問題等の､HTTP と HTTPS処理の両方に関して､働く｡ 0以外のlevelの値は､それぞれの時分割片内の､主解釈実行機能 のみに利用可能である｡ 更なる情報はTHREADS項目を参照されたい｡ The Tcl socket -async command can block in adverse cases (e.g. a slow DNS lookup). Using the Thread package works around this problem, for both HTTP and HTTPS transactions. Values of level other than 0 are available only to the main interpreter in each thread. See section THREADS for more information.

  -urlencoding encoding
    ::http::formatQuery と ::http::quoteString による x-url-encoded 符号化 URL の生成に使用される符号系｡ 省略時設定は RFC 2718 の指定に従って utf-8 である｡ The encoding used for creating the x-url-encoded URLs with ::http::formatQuery and ::http::quoteString. The default is utf-8, as specified by RFC 2718.

  -useragent string
    HTTP 要求の中の使用者-代理者項目の値である｡不安全な解釈実行機能の中では､省略時設定の値はOS 及び､ http と Tcl の版番号､及び(譬ば) “Mozilla/5.0 (Windows; U; Windows NT 10.0) http/2.10.1 Tcl/9.0.0” に依存する｡安全な解釈実行機能は､そのOSを定めることができない､又､安全な解釈実行機能内の省略時設定は http と Tcl の現在の版番号を伴う Windows 10 値の使用である｡　　　　　　 The value of the User-Agent header in the HTTP request. In an unsafe interpreter, the default value depends upon the operating system, and the version numbers of http and Tcl, and is (for example) “Mozilla/5.0 (Windows; U; Windows NT 10.0) http/2.10.1 Tcl/9.0.0”. A safe interpreter cannot determine its operating system, and so the default in a safe interpreter is to use a Windows 10 value with the current version numbers of http and Tcl.

  -zip boolean
    値が論理真値であると､無為設定の要求により､冒頭部 “受入れる-符号系:gzip,deflate” を送る｡ 値が論理偽値であると､無為設定の要求により､冒頭部 “受入れる-符号系:identity” を送る｡ 両方の場合､無為設定は個別の要求により､誂えた受入れ-符号系冒頭部を http::geturl の -headers 指定項目内に供給して､上書きすることができる｡無為設定は 1 である｡　　　　　　 If the value is boolean true, then by default requests will send a header “Accept-Encoding: gzip,deflate”. If the value is boolean false, then by default requests will send a header “Accept-Encoding: identity”. In either case the default can be overridden for an individual request by supplying a custom Accept-Encoding header in the -headers option of http::geturl. The default value is 1.

::http::geturl url ?options?
  この ::http::geturl 命令はこの梱包の主たる手続函数である｡ -query 指定項目又は-querychannel指定項目は､ POST 操作を､ -validate 指定項目は､ HEAD 操作を惹き起し; それ以外は､ GET 操作が遂行される｡ 本::http::geturl命令は､token値を返し､これは､業務に関する情報を得る為､他の命令に引数として渡すことができる｡詳細は STATE ARRAY と ERRORS の項を参照されたい｡ この ::http::geturl 命令は､ -command 指定項目が HTTP一括処理が完了した時に起動される 呼戻しを指定しない限り､操作が完了するまで抑止をおこす｡::http::geturl は次の幾つかの指定項目をとる: 　　　　　 The ::http::geturl command is the main procedure in the package. The -query or -querychannel option causes a POST operation and the -validate option causes a HEAD operation; otherwise, a GET operation is performed. The ::http::geturl command returns a token value that can be passed as an argument to other commands to get information about the transaction. See the METADATA and ERRORS section for details. The ::http::geturl command blocks until the operation completes, unless the -command option specifies a callback that is invoked when the HTTP transaction completes. ::http::geturl takes several options:

  -binary boolean
    URL データを二進列として解釈することを強制するか否かを指定する｡ URL データを二進列として解釈することを強制するか否かを指定する｡ 通常､これは､自動検出である( text 含有型で始まらないものや､その内容の文字符号系が gzip や deflate のものは､なんであれ二進データと看做す)｡　 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 deflate is considered binary data).

  -blocksize size
    URL を読む時に使われる一区切りの長さ｡最大 size バイトが一度に読まれる｡それぞれの区切りの後に､ -progress の呼戻しがなされる(もし､指示項目が指定されていると)｡[訳註:8.6版の文に字句が挿入され意味??] 　　 The block size used when reading the URL. At most size bytes are read at once. After each block, a call to the -progress callback is made (if that option is specified).

  -channel name
    URL の内容を､ ::http::responseBodyによる取出しの為に､ Tcl変数 の中に保存する代りに通信路 name に複写する｡[訳註:8.6版の文に字句が挿入され意味??] Copy the URL contents to channel name instead of saving it in a Tcl variable for retrieval by ::http::responseBody.

  -command callback
    この指示項目の存在は::http::geturlに即時の戻りを引き起こす｡ HTTP一括処理が完了した後､callbackの値が拡張され､そして､追加引数が加えられ､そして､結果の命令が評価される｡ 追加された引数は返されたtokenである｡ この token は STATE ARRAY の節に記載された配列の名前である｡次に示すのが呼戻しの為の雛形である: 　　　　 The presence of this option causes ::http::geturl to return immediately. After the HTTP transaction completes, the value of callback is expanded, an additional argument is added, and the resulting command is evaluated. The additional argument is the token returned from ::http::geturl. This token is the name of an array that is described in the STATE ARRAY section. Here is a template for the callback:

        proc httpCallback {token} {
            upvar 0 $token state
            # state をこの手続函数内で宣言された Tcl 配列として利用する
            # Access state as a Tcl array defined in this proc
            ...
            return
        }

    ::http::geturl 命令は catch 命令の内部で -command 呼戻しを実行する｡従って callback 命令内の不都合は bgerror 把持子を呼出さない｡詳細は ERRORS を参照されたい｡ The ::http::geturl command runs the -command callback inside a catch command. Therefore an error in the callback command does not call the bgerror handler. See the ERRORS section for details.

  -guesstype boolean
    構成設定不良の中央集中処理譜が情報を提供しない時､内容-型と文字揃いの推測を試みる｡無為値は偽値(何もしない)｡もし､論理真値であれば､もし､中央集中処理装置が内容-型冒頭部を送らないなら､又は､もし､"応用譜/八個単位-系"値を送るなら､http::geturlは適切な値を推測する事になる｡ これは､一般目的道具になる事を意図していない､又､現在の処､XML宣言で始まるXML説明譜の検出に限定している｡ この場合､内容-型は"応用譜/xml"に変化され､二進旗印状態(二進)は0に変化され､文字揃いは XML行の"符号化"貼札により指定されるモノか符号化が指定されない場合はutf-8 に､変えられる｡もし-channelが指定されると使われない｡ Attempt to guess the Content-Type and character set when a misconfigured server provides no information. The default value is false (do nothing). If boolean true then, if the server does not send a Content-Type header, or if it sends the value "application/octet-stream", http::geturl will attempt to guess appropriate values. This is not intended to become a general-purpose tool, and currently it is limited to detecting XML documents that begin with an XML declaration. In this case the Content-Type is changed to "application/xml", the binary flag state(binary) is changed to 0, and the character set is changed to the one specified by the "encoding" tag of the XML line, or to utf-8 if no encoding is specified. Not used if a -channel is specified.

  -handler callback
    この指示項目が無いと､http::geturlは､入ってくるデータそのものを､state(body)変数に追加するか､-channelに記入して､処理する｡ しかし､-handler指示項目があると､http::geturlは､その処理を行わず､且つ､callbackを呼出す｡ 何時であれ､HTTPデータが利用できると､callbackの値は拡張され､そして､更に二つの引数が追加され､そして､結果の命令が評価される｡ 二つの引数は: HTTPデータの為の接続口と､::http::geturlから返されたtokenである｡ token は大域配列の名前であり､それは STATE ARRAY の節に記載されている｡この手続函数は受け口から読んだバイトの個数を返すよう期待されている｡これが呼戻しの為の雛形である: 　　 If this option is absent, http::geturl processes incoming data itself, either appending it to the state(body) variable or writing it to the -channel. But if the -handler option is present, http::geturl does not do this processing and instead calls callback. Whenever HTTP data is available, the value of callback is expanded, an additional two arguments are added, and the resulting command is evaluated. The two additional arguments are: the socket for the HTTP data and the token returned from ::http::geturl. The token is the name of a global array that is described in the STATE ARRAY section. The procedure is expected to return the number of bytes read from the socket. Here is a template for the callback:

        proc httpHandlerCallback {socket token} {
            upvar 0 $token state
            # socketを使い､この手続き函数内に定義されたTcl配列として宣言する
            # 譬えば､...
            # Access socket, and state as a Tcl array defined in this proc
            # For example...
            ...
            set data [read $socket 1000]
            set nbytes [string length $data]
            ...
            return $nbytes
        }

    -handler 指示項目の為の http::geturl 符号系は､圧縮とも分割送信方式とも両立しない｡もし､ -handler が指定されると､ これらの問題を回避する為に､ http::geturl は HTTP 通信規約を 1.0 に減退し､且つ -zip 指示項目を上書きすることになる(即ち､冒頭句"Accept-Encoding: gzip,deflate"の代りに"Accept-Encoding: identity"を送る) The http::geturl code for the -handler option is not compatible with either compression or chunked transfer-encoding. If -handler is specified, then to work around these issues http::geturl will reduce the HTTP protocol to 1.0, and override the -zip option (i.e. it will send the header Accept-Encoding: identity instead of Accept-Encoding: gzip,deflate).

    もし指示項目 -handler と -channel が一緒に使われると､処理子は､ HTTP 受け口からのデータを､指定された通信路に､複写することを担当する｡通信路の名前は処理子には､解析配列の要素 -channel として利用できる｡ If options -handler and -channel are used together, the handler is responsible for copying the data from the HTTP socket to the specified channel. The name of the channel is available to the handler as element -channel of the token array.

    ::http::geturl 命令は catch 命令の内部で -handler 呼戻しを実行する｡従って callback 命令内の不都合は bgerror 把持子を呼出さない｡詳細は ERRORS を参照されたい｡ The ::http::geturl command runs the -handler callback inside a catch command. Therefore an error in the callback command does not call the bgerror handler. See the ERRORS section for details.

  -headers keyvaluelist
    この指示項目は ::http::config によって未だ指定されていない見出しを HTTP 要求に加えるために使用される｡keyvaluelist 引数は要素が鍵と値が交互に並ぶ偶数個数の要素のリストでなければならない｡鍵は見出しの名前になる｡改行は値から取除かれ､見出しが壊れないようになる｡譬えば､もし keyvaluelist が Pragma no-cache であれば､次の見出しが､HTTP 要求の中に含まれている: 　　 This option is used to add headers not already specified by ::http::config to the HTTP request. The keyvaluelist argument must be a list with an even number of elements that alternate between keys and values. The keys become header field names. Newlines are stripped from the values so the header cannot be corrupted. For example, if keyvaluelist is Pragma no-cache then the following header is included in the HTTP request:

        Pragma: no-cache

  -keepalive boolean
    もし論理真値なら､複数の要求の役務処理の為に接続を開いて保持するよう試みる｡省略時設定は 0｡ 　　 If boolean true, attempt to keep the connection open for servicing multiple requests. Default is 0.

  -method type
    HTTP 要求手段を type に強制する｡::http::geturl は他の指示項目に従って GET か POST か HEAD を自動的に選択するようになる､しかし､この指示項目は､その選択を上書きし､且つ WebDAV を適用する為の PUT や DELETE の様な選択を可能にする｡ 　　　 Force the HTTP request method to type. ::http::geturl will auto-select GET, POST or HEAD based on other options, but this option overrides that selection and enables choices like PUT and DELETE for WebDAV support.

    冒頭部と(もしあれば)要求本体が要求手段の要求事項に適合することを確認するのは呼出者の責務である｡譬えば､ -method POST を使用して､要求本体が空の POST を送ると､呼出者は指示項目 “-headers {Content-Length 0}” をも提供せねばならない｡ It is the caller's responsibility to ensure that the headers and request body (if any) conform to the requirements of the request method. For example, if using -method POST to send a POST with an empty request body, the caller must also supply the option

        -headers {Content-Length 0}

  -myaddr address
    複数の対話機能が利用可能である場合には､基になる socket 呼出しに特定の局所番地を渡す｡ 　　　 Pass an specific local address to the underlying socket call in case multiple interfaces are available.

  -progress callback
    -progress指示項目が存すると､URLからのデータのそれぞれの移転の後にcallbackが作成される｡ callbackは拡張され､そして､更なる三つの引数が追加され､そして､結果の命令が評価される｡ 更なる三つの引数は: ::http::geturlから返されたtokenと､Content-Length回答冒頭句からの内容の予測沿う寸法と､転送等された現在のバイト個数である｡ tokenは､STATE ARRAY項目に記述された大域配列の名前である｡ 予想される総数は不明のこともあり､その場合は呼戻しに零が渡される｡次に示すのが呼戻しの為の雛形である: 　　 If the -progress option is present, then the callback is made after each transfer of data from the URL. The value of callback is expanded, an additional three arguments are added, and the resulting command is evaluated. The three additional arguments are: the token returned from ::http::geturl, the expected total size of the contents from the Content-Length response header, and the current number of bytes transferred so far. The token is the name of a global array that is described in the STATE ARRAY section. The expected total size may be unknown, in which case zero is passed to the callback. Here is a template for the progress callback:

        proc httpProgress {token total current} {
            upvar 0 $token state
            # state をこの手続函数内で宣言された Tcl 配列として利用する
            # Access state as a Tcl array defined in this proc
            ...
            return
        }

  -protocol version
    使用する HTTP 通信規約の版番号を選択する｡それは 1.0 か 1.1(こちらが省略時設定)でなければならない｡中央集中処理装置が理解できないか HTTP/1.1 について不満がある場合にのみ必要になる｡ Select the HTTP protocol version to use. This should be 1.0 or 1.1 (the default). Should only be necessary for servers that do not understand or otherwise complain about HTTP/1.1.

  -query query
    この旗標は(値が空値でなければ) ::http::geturl に対し､中央集中処理装置に要求有効負荷として､文字列の 問合せ を言葉通りに渡す POST 要求を実行することを惹き起こさせる｡ 問合せ の内容の書式(と符号系)は､指示項目 -type により設定された要求冒頭部の内容型によって宣言される｡どの様な -type の値も許容され､且つ､正しい書式で問合せを提供することは､呼出側の責務である｡ This flag (if the value is non-empty) causes ::http::geturl to do a POST request that passes the string query verbatim to the server as the request payload. The content format (and encoding) of query is announced by the request header Content-Type which is set by the option -type. Any value of -type is permitted, and it is the responsibility of the caller to supply query in the correct format.

    もし -type が指定されていないと､ application/x-www-form-urlencoded が省略時設定になり､それは query に対して x-url-encoding 書式(この -type と問合せ書式は html 書式から寄託された POST 内で使用される)された問合せ文字列であることを要求する｡ ::http::formatQuery 手続き函数は書式化に使用できる｡ If -type is not specified, it defaults to application/x-www-form-urlencoded, which requires query to be an x-url-encoding formatted query-string (this -type and query format are used in a POST submitted from an html form). The ::http::formatQuery procedure can be used to do the formatting.

  -queryblocksize size
    URL への問合せデータの表示に使用する区切りの長さ｡一回では精々その size のバイトが書かれる｡それぞれの区切りの度毎にその後に -queryprogress 呼び出しがなされる(もし､この指示項目が指定されていると)｡ 　 The block size used when posting query data to the URL. At most size bytes are written at once. After each block, a call to the -queryprogress callback is made (if that option is specified).

  -querychannel channelID
    この旗標は ::http::geturl に対して channelID の中のデータを中央集中処理装置に渡すPOST 要求を実行させる｡ channelID の中に含まれるデータは下の -type 項目が指定されない限り x-url-encoding 書式の問合せでなければならない｡もし､内容の長さの見出しが -headers 指示項目経由で指定されていないと､ ::http::geturl は見出しを生成する為に表示データの寸法を決定しようと試みる｡もし､寸法が決定できないと不都合を返す｡ 　 This flag causes ::http::geturl to do a POST request that passes the data contained in channelID to the server. The data contained in channelID must be an x-url-encoding formatted query unless the -type option below is used. If a Content-Length header is not specified via the -headers options, ::http::geturl attempts to determine the size of the post data in order to create that header. If it is unable to determine the size, it returns an error.

  -queryprogress callback
    もし-queryprogressがあると､callbackは､ URL へのPOST要求内(即ち-queryか-querychannelを伴う::http::geturl呼出し)の データの輸送の後毎に callback がなされ､ 正確に -progress 指示項目(呼戻し書式と同一)と同じに動作する｡ If the -queryprogress option is present, then the callback is made after each transfer of data to the URL in a POST request (i.e. a call to ::http::geturl with option -query or -querychannel) and acts exactly like the -progress option (the callback format is the same).

  -strict boolean
    もし､真値なら本命令は､URLはRFC 3986に準拠する事を試験する､ 即ち､"x-url-encoded"である様な文字がない事(即ち､空白は"%20"に符号化されている筈)｡省略時設定は1｡ If true then the command will test that the URL complies with RFC 3986, i.e. that it has no characters that should be "x-url-encoded" (e.g. a space should be encoded to "%20"). Default value is 1.

  -timeout milliseconds
    もし milliseconds が非零であると､::http::geturl は指定された数の厘秒後に起る期限切れを設定する｡期限切れの結果は ::http::reset 呼び出しと､更にもし設定されていると -command 呼戻しになる｡期限切れが生じた後には､::http::status の返り値(及び､::http::responseInfoに返された辞書内のstatusの値)は timeout になる｡ 　　　 If milliseconds is non-zero, then ::http::geturl sets up a timeout to occur after the specified number of milliseconds. A timeout results in a call to ::http::reset and to the -command callback, if specified. The return value of ::http::status (and the value of the status key in the dictionary returned by ::http::responseInfo) is timeout after a timeout has occurred.

  -type mime-type
    Content-Type の値として､ POST 操作の間は省略時設定(application/x-www-form-urlencoded)の代りに mime-type を使う｡ 　　 Use mime-type as the Content-Type value, instead of the default value (application/x-www-form-urlencoded) during a POST operation.

  -validate boolean
    もし､ boolean が非零であれば､::http::geturl は HTTP HEAD 要求を行う｡ この中央集中処理装置は､ 同じ状態表示行と応答冒頭句を､ HTTP GETに関する要求として､ 返す､但し､応答実体(URL"内容")を略す｡ 応答冒頭句は､命令::http::responseHeaders又は､選択された情報の::http::responseInfoを使った処理の後､利用できる｡ If boolean is non-zero, then ::http::geturl does an HTTP HEAD request. This server returns the same status line and response headers as it would for a HTTP GET request, but omits the response entity (the URL "contents"). The response headers are available after the transaction using command ::http::responseHeaders or, for selected information, ::http::responseInfo.

::http::formatQuery key value ?key value ...?
  この手続函数は問合せデータの x-url-encoding 符号化を行う｡問合せの鍵と値の偶数の要員の引数を採る｡鍵と値を符号化し､適切な & と = の区切りを有する一つの文字列を生成する｡結果は ::http::geturl に渡す -query 値として適している｡ 　　 This procedure does x-url-encoding of query data. It takes an even number of arguments that are the keys and values of the query. It encodes the keys and values, and generates one string that has the proper & and = separators. The result is suitable for the -query value passed to ::http::geturl.

::http::quoteString value
  この手続函数は文字列の x-番地-符号化 x-url-encoding を行う｡これは引数を一つとりそれを符号化する｡　　　　　　　 This procedure does x-url-encoding of string. It takes a single argument and encodes it.

::http::reset token ?why?
  この命令は token により識別される HTTP 一括処理があれば解除する｡この命令は state(status) 値を why に設定する､その省略時設定は 解除 reset であり､登録してある -command 呼戻しを呼出す｡ 　　　 This command resets the HTTP transaction identified by token, if any. This sets the state(status) value to why, which defaults to reset, and then calls the registered -command callback.

::http::wait token
  この命令は､一括処理を完了する為に､抑止して待つ｡ これは､信頼できる命令のみで稼動する､理由は vwait を使用するから｡又､::http::geturl が -command 指示項目なしで呼ばれている時は便利ではない､理由は､この場合､ ::http::geturl 呼出しは HTTP 一括処理が完了して､待つべきものがなくなる迄制御が返らないから｡ 　　 This command blocks and waits for the transaction to complete. This only works in trusted code because it uses vwait. Also, it is not useful for the case where ::http::geturl is called without the -command option because in this case the ::http::geturl call does not return until the HTTP transaction is complete, and thus there is nothing to wait for.

::http::status token
  この命令は､HTTP処理の状況を記述する｡ HTTP処理化完了する迄は､返る値は空文字列である; 完了後に返る値は次の内の一つである､ okか eofか errorか timeoutか reset｡ これ等の値の意味は(下の)ERRORS に記述されている｡ This command returns a description of the status of the HTTP transaction. The return value is the empty string until the HTTP transaction is completed; after completion it has one of the values ok, eof, error, timeout, and reset. The meaning of these values is described in the section ERRORS (below).

  "状況"の名前は､HTTP応答に定義された用語"status line"や"status code"とは関係ない｡ The name "status" is not related to the terms "status line" and "status code" that are defined for a HTTP response.

::http::size token
  本命令は､::http::geturl呼出しの中のURLからこれ迄に受取ったバイトの個数を返す｡ This command returns the number of bytes received so far from the URL in the ::http::geturl call.

::http::error token
  本命令はHTTP処理が失敗していると不都合情報を返す､不都合が無ければ､空文字列を返す｡情報は､不都合伝言文と､棚追跡と､不都合番号のTclリストである｡ This command returns the error information if the HTTP transaction failed, or the empty string if there was no error. The information is a Tcl list of the error message, stack trace, and error code.

::http::postError token
  POST要求は-queryか-querychannel指示項目を伴った::http::geturlへの呼出しである｡ ::http::postError命令は､ HTTP POSTがその要求-本体を中央集中処理に送った時に生成された不都合情報を返す; 不都合がない場合は空文字列｡ 情報は､不都合伝言文と､棚追跡と､不都合番号のTclリストである｡ この型の不都合が起った時､::http::geturl命令は､処理を続け､そして､中央集中処理から応答を受取ろうと試みる｡ A POST request is a call to ::http::geturl with either the -query or -querychannel option. The ::http::postError command returns the error information generated when a HTTP POST request sends its request-body to the server; or the empty string if there was no error. The information is a Tcl list of the error message, stack trace, and error code. When this type of error occurs, the ::http::geturl command continues the transaction and attempts to receive a response from the server.

::http::cleanup token
  この手続函数は token で識別される接続に関する状態を刷新する｡この呼び出しの後は､ ::http::responseBody のような手続函数はこの操作に関する情報の取得に使用できない｡与えられた HTTP 要求を済まして後にこの函数を呼ぶ様に強く推奨する｡そうしないと､記憶領域が解放されない結果になり､もし応用譜が::http::geturl を十分な回数呼ぶと､記憶領域の漏洩が性能を直撃するかもしれない更に悪い事態も...｡ This procedure cleans up the state associated with the connection identified by token. After this call, the procedures like ::http::responseBody cannot be used to get information about the operation. It is strongly recommended that you call this function after you are done with a given HTTP request. Not doing so will result in memory not being freed, and if your app calls ::http::geturl enough times, the memory leak could cause a performance hit...or worse.

::http::requestLine token
  本命令は中央集中処理に送った"要求行"を返す｡ "要求行"はHTTP顧客要求の第一行であり､且つ､空白で区切られた三要素を有す: HTTP手段と､中央集中処理相対URLと､HTTP版番号である｡譬えば､ This command returns the "request line" sent to the server. The "request line" is the first line of a HTTP client request, and has three elements separated by spaces: the HTTP method, the URL relative to the server, and the HTTP version. Examples:

  GET / HTTP/1.1 GET /introduction.html?subject=plumbing HTTP/1.1 POST /forms/order.html HTTP/1.1

::http::requestHeaders token ?headerName?
  本命令は､HTTP 要求冒頭句名称と値とを､中央集中処理に送られた順に､Tcl リスト形式に従って､?名称 値 ...? ､を返す｡ 冒頭句名称は､大文字小文字を区別せず､且つ､小文字に変換される｡ 戻り値は､dictではない､理由は､幾つかの冒頭句名称は一度以上起こるから｡ 若し一つの引数が供給されると､全ての要求冒頭句が返される｡ 要求された名称を伴う冒頭句のみ(小文字に変換され)が返される｡ もし､その様な冒頭句が見付らない場合､空リストが返される｡ This command returns the HTTP request header names and values, in the order that they were sent to the server, as a Tcl list of the form ?name value ...? Header names are case-insensitive and are converted to lower case. The return value is not a dict because some header names may occur more than once. If one argument is supplied, all request headers are returned. If two arguments are supplied, the second provides the value of a header name. Only headers with the requested name (converted to lower case) are returned. If no such headers are found, an empty list is returned.

::http::requestHeaderValue token headerName
  本命令は､headerNameと名付けられたHTTP要求冒頭句を返す｡ 冒頭句の名称は､大文字小文字を区別せず､且つ､小文字に変換される｡ その様な冒頭句がない場合､返り値は空文字列である｡ headerNameと名付けられた複数の冒頭句が存在する場合､結果は､ 個別の値を文字列", " (コンマと空白)で結合し､順序を保存して､結合して得られる｡ This command returns the value of the HTTP request header named headerName. Header names are case-insensitive and are converted to lower case. If no such header exists, the return value is the empty string. If there are multiple headers named headerName, the result is obtained by joining the individual values with the string ", " (comma and space), preserving their order.

::http::responseLine token
  本命令は､中央集中処理の応答の第一行を返す: HTTP "宣言行"｡ "宣言行"は空白で区切られた三つの要素を有す: HTTP版番号と､三つの数字の"宣言行番号"と､"理由句"である｡ "理由句"のみが空白を含む｡譬えば: This command returns the first line of the server response: the HTTP "status line". The "status line" has three elements separated by spaces: the HTTP version, a three-digit numerical "status code", and a "reason phrase". Only the reason phrase may contain spaces. Examples:

  HTTP/1.1 200 OK HTTP/1.0 404 Not Found

  "宣言行番号"は100から599の範囲の三桁の数字である｡ 値200は､GET要求からの正常な戻りで､且つ､その合致した"理由句"は"OK"である｡ 4か5で始まる番号は､不都合を示す｡ 4で始まる番号は､出力先の切換え不都合である｡ この場合､Location応答冒頭句は､要求された情報を含む､新しいURLを指定する｡ The "status code" is a three-digit number in the range 100 to 599. A value of 200 is the normal return from a GET request, and its matching "reason phrase" is "OK". Codes beginning with 4 or 5 indicate errors. Codes beginning with 3 are redirection errors. In this case the Location response header specifies a new URL that contains the requested information.

  "理由句"は､"状況番号"の文書記述である: それは中央集中処理から中央集中処理へで変化すし得る､且つ､ HTTP 議定書の影響なしに変化し得る｡ それぞれの番号の為の推奨値(RFC7231とIANA割当て)は命令::http::reasonPhraseによって与えらえる｡ The "reason phrase" is a textual description of the "status code": it may vary from server to server, and can be changed without affecting the HTTP protocol. The recommended values (RFC 7231 and IANA assignments) for each code are provided by the command ::http::reasonPhrase.

::http::responseCode token
  本命令は中央集中処理"状況行"の"状況番号"(200, 404,等)を返す｡ もし､三桁番号が見付らない場合は､完全状況行が返される｡ "状況行"の更なる情報は::http::responseLineを参照されたい｡ This command returns the "status code" (200, 404, etc.) of the server "status line". If a three-digit code cannot be found, the full status line is returned. See command ::http::responseLine for more information on the "status line".

::http::reasonPhrase code
  この命令は､ HTTP中央集中処理によって返された､特定の"状況番号"の為の､ IANAに推奨された"理由句"を返す｡ 引数code は､種々の状況番号であり､且つ､従って､100 から 599迄の両端を含む範囲内の整数である｡ この範囲の符号なし数に関する意味は､本命令が値"符号無し"を返す｡ 幾つかの状況番号は､HEADや､GETや､POST要求手段への応答ではなく､ HTTP拡張によって定義された手段への応答､譬えばWebDAVとして､のみに使われる｡ This command returns the IANA recommended "reason phrase" for a particular "status code" returned by a HTTP server. The argument code is a valid status code, and therefore is an integer in the range 100 to 599 inclusive. For numbers in this range with no assigned meaning, the command returns the value "Unassigned". Several status codes are used only in response to the methods defined by HTTP extensions such as WebDAV, and not in response to a HEAD, GET, or POST request method.

  HTTP中央集中処理によって返された"理由句"は､HTTP協定の影響なしでは､推奨された値とは異るかもしれない｡ ::http::geturlに返された値は､ ::http::responseLine命令呼出(これは全状況行)又は､ ::http::responseInfo命令呼出(これはreasonPhrase鍵内に保存された"理由句"を伴う辞書を返す)の孰れかによって得られる｡ The "reason phrase" returned by a HTTP server may differ from the recommended value, without affecting the HTTP protocol. The value returned by ::http::geturl can be obtained by calling either command ::http::responseLine (which returns the full status line) or command ::http::responseInfo (which returns a dictionary, with the "reason phrase" stored in key reasonPhrase).

  種々の状況番号の登録は､ https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml になされる｡ A registry of valid status codes is maintained at https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

::http::responseHeaders token ?headerName?
  HTTP中央集中処理空の応答は､応答本体と処置そのものを記述する汎データの冒頭句を含む｡ 本命令は､HTTP 応答冒頭句名称と値とを､中央集中処理に送られた順に､Tcl リスト形式に従って､?名称 値 ...? ､を返す｡ 冒頭句名称は､大文字小文字を区別せず､且つ､小文字に変換される｡ 戻り値は､dictではない､理由は､幾つかの冒頭句名称は一度以上､特に､Set-Cookieでは､起こるから｡ もし､第二引数が供給されないと､全ての応答冒頭句が返される｡ もし､第二引数が供給されると､それは冒頭句名称の値を提供する｡ 要求された名前(小文字に変換されて)の冒頭句のみが返される｡ もしこの様な冒頭句が見付らないと､空リストが返される｡更なる情報はMETADATA節を参照されたい｡ The response from a HTTP server includes metadata headers that describe the response body and the transaction itself. This command returns the HTTP response header names and values, in the order that they were received from the server, as a Tcl list of the form ?name value ...? Header names are case-insensitive and are converted to lower case. The return value is not a dict because some header names may occur more than once, notably Set-Cookie. If the second argument is not supplied, all response headers are returned. If the second argument is supplied, it provides the value of a header name. Only headers with the requested name (converted to lower case) are returned. If no such headers are found, an empty list is returned. See section METADATA for more information.

::http::responseHeaderValue token headerName
  この命令は､headerNameと名付けられたHTTP応答冒頭句の値を返す｡ 冒頭句名称は大文字小文字を区別せず､且つ､小文字に変換される｡ もしその様な冒頭句が存在しないと､返る値は空文字列である｡ もし､headerNameと名付けられた冒頭句が複数あると､結果は､ 個別の値を文字列", " (コンマと空白)で結合し､順序を保存して､結合して得られる｡ この方法では､同じ名前の複数の冒頭句が処理され得るが､ 例外として､Set-Cookieはコンマ区切りリストの形式を満足せず､且つ､一個の値に組入れる事は出来ない｡ それぞれのSet-Cookie冒頭句は､個別に扱われなければならない､譬えば､ ::http::responseHeaders token Set-Cookieの返り値の処理によって｡ This command returns the value of the HTTP response header named headerName. Header names are case-insensitive and are converted to lower case. If no such header exists, the return value is the empty string. If there are multiple headers named headerName, the result is obtained by joining the individual values with the string ", " (comma and space), preserving their order. Multiple headers with the same name may be processed in this manner, except Set-Cookie which does not conform to the comma-separated-list syntax and cannot be combined into a single value. Each Set-Cookie header must be treated individually, e.g. by processing the return value of ::http::responseHeaders token Set-Cookie.

::http::responseInfo token
  この命令は､選択された汎データのdictを返す､それは､成功裡の処理の確認に不可欠であり､且つ､他の非公式な汎データと共に､応答を使用させる｡ dictの鍵は､ stageと status, responseCodeと reasonPhraseと contentTypeと binaryと redirectionと upgradeと errorと postErrorと method, charsetと compression, httpRequestと httpResponseと urlと connectionRequestと connectionResponseと connectionActualと transferEncodingと totalPostと currentPostと totalSizeと currentSizeと､である｡ これはの鍵の意味は､下のMETADATA項を参照されたい｡ This command returns a dict of selected response metadata that are essential for identifying a successful transaction and making use of the response, along with other metadata that are informational. The keys of the dict are stage, status, responseCode, reasonPhrase, contentType, binary, redirection, upgrade, error, postError, method, charset, compression, httpRequest, httpResponse, url, connectionRequest, connectionResponse, connectionActual, transferEncoding, totalPost, currentPost, totalSize, and currentSize. The meaning of these keys is described in the section METADATA below.

  HTTP処理の後にbinaryの値を確認する事は､ 構成設定不良の中央集中処理譜が､httpに､二進数として文書原資を解釈することを惹き起ししていないか､その他､を定める為に､ 常に価値がある｡ It is always worth checking the value of binary after a HTTP transaction, to determine whether a misconfigured server has caused http to interpret a text resource as a binary, or vice versa.

  POST処理の後に､ 要求本体が不都合無しに移送されたかを確かめる為に､ postErrorの値を確認されたい｡ After a POST transaction, check the value of postError to verify that the request body was uploaded without error.

::http::responseBody token
  この命令は､HTTP中央集中処理譜によって送られた実体を返す(-channelが使われない限り､ その場合､実体は通信路に配送され､且つ､命令は空文字列を返す)｡ This command returns the entity sent by the HTTP server (unless -channel was used, in which case the entity was delivered to the channel, and the command returns the empty string).

  "representation of resource"と resource"と "response body after decoding"と "payload"と "message body after decoding"と "content(s)"と "file"とを､含む､ 種々の精度を伴う､他の用語｡ Other terms for "entity", with varying precision, include "representation of resource", "resource", "response body after decoding", "payload", "message body after decoding", "content(s)", and "file".

::http::register proto port command ?socketCmdVarName? ?useSockThread? ?endToEndProxy?
  この手続函数は､接尾辞を登録して､ HTTPSの様な誂えたHTTP移送型を､無為設定の接続口に､提供すること､ 及び､本命令がTcl通信路の生成を実行すること､を許容する｡ 任意追加の指示項目は､ httpが誂えた移送口を如何に使うか､及び､ 任意追加の引数がない::http::register内の旧版httpと両立する 無為設定の値を有すること､ を構成設定する｡ This procedure allows one to provide custom HTTP transport types such as HTTPS, by registering a prefix, the default port, and the command to execute to create the Tcl channel. The optional arguments configure how http uses the custom transport, and have default values that are compatible with older versions of http in which ::http::register has no optional arguments.

  socketCmdVarName引数は､移送口によって提供された変数の名前であり､ その値は､移送口に､ソケットを開ける為に使われた命令である｡ その無為設定の値は､移送口によって設定され､且つ､"::socket"であるが､ 変数の名前が::http::registerに供給されると､httpは､追加設備を利用可能にするために､ 新しい名前を設定する｡ これらの設備は､追加引数useSockThread, endToEndProxy によって可能であり､ この引数は､論理値を採るが､無為設定ではfalse.である｡ Argument socketCmdVarName is the name of a variable provided by the transport, whose value is the command used by the transport to open a socket. Its default value is set by the transport and is "::socket", but if the name of the variable is supplied to ::http::register, then http will set a new value in order to make optional facilities available. These facilities are enabled by the optional arguments useSockThread, endToEndProxy, which take boolean values with default value false.

  もし引数useSockThreadが供給され､且つ､論理値trueであると､ すると､もし､値[http::config -threadlevel]によって許容され､且つ､梱包Threadによって､利用可能であると､ 移送の為に作成されたソケットは､異なる時分割細片内で開かれ､ その為､遅いDNS捜索は記述譜の阻止を惹き起さない｡[訳註:if<--iif ???] Iff argument useSockThread is supplied and is boolean true, then iff permitted by the value [http::config -threadlevel] and by the availability of package Thread, sockets created for the transport will be opened in a different thread so that a slow DNS lookup will not cause the script to block.

  引数endToEndProxyが供給され､且つ､論理真値であると､ http::geturlは代理経由で中央集中処理を利用する時､ 代理にCONNECT要求を送り､通信路を開ける､ 次に､仔の通信路を越えて要求をさせる｡ これは､代理経由でなされたHTTPS要求の為に､ 末尾-末尾暗号を許容する｡[訳註:if<--iif ???] Iff argument endToEndProxy is supplied and is boolean true, then when http::geturl accesses a server via a proxy, it will open a channel by sending a CONNECT request to the proxy, and it will then make its request over this channel. This allows end-to-end encryption for HTTPS requests made through a proxy.

  譬えば､ For example,

      package require http
      package require tls

      ::http::register https 443 ::tls::socket ::tls::socketCmd 1 1

      set token [::http::geturl https://my.secure.site/]

::http::registerError sock ?message?
  この手続函数は登録された通信規約操作子に http の使用により不都合伝言文を配送することを許容する｡この命令の呼出しが不都合を生じることはない｡ 登録された通信規約が､ httpR に伝搬すべき不都合を惹き起こす問題(譬ば､不正な TLS 認証)を検出する時この命令は便利である｡本命令は http に一般のものより正確な不都合伝達文を提供する事を許容する｡本命令は引数伝言文 message を伴う最後の呼出しにより提供された値を持ち帰るか､そのような呼出しが作られて無いときは空文字列を持ち帰る｡　　　　　　 This procedure allows a registered protocol handler to deliver an error message for use by http. Calling this command does not raise an error. The command is useful when a registered protocol detects an problem (for example, an invalid TLS certificate) that will cause an error to propagate to http. The command allows http to provide a precise error message rather than a general one. The command returns the value provided by the last call with argument message, or the empty string if no such call has been made.

::http::unregister proto
  この手続函数は､以前に::http::register経由で登録された､通信規格取扱子を登録せずに､ 値の六-項目リストを返す､それは､ もし､その様な取扱子があれば以前に::http::registerに供給したものである､ そして､その様な取扱子が無ければ不都合である｡[訳註:???] This procedure unregisters a protocol handler that was previously registered via ::http::register, returning a six-item list of the values that were previously supplied to ::http::register if there was such a handler, and an error if there was no such handler.

::http::code token
  命令::http::responseLineの別名｡ An alternative name for the command ::http::responseLine

::http::data token
  命令::http::responseBodyの別名｡ An alternative name for the command ::http::responseBody.

::http::meta token ?headerName?
  命令::http::responseHeadersの別名｡ An alternative name for the command ::http::responseHeaders

::http::ncode token
  命令::http::responseCodeの別名｡ An alternative name for the command ::http::responseCode

### ERRORS

次の場合::http::geturlは不都合を惹き起す: 不適正な命令行指示項目､又は､不適正なURL｡ この様な不都合は､ 電網処理開始さえも不可能を意味する｡ 同期した::http::geturl呼出し(ここで -commandは指定されない場合)に関して､ もし､URLが､ 非-存在亭主であるか､ 既存の亭主上の悪しき接続口の場合､ 不都合が生じる｡ HTTP要求行と冒頭句を書出しているいるか､ HTTP応答冒頭句かデータを読込んでいるかの間の､ どの様な入/出力不都合に関しても､ 又､不都合が起こる｡ 理由は､::http::geturlはこの様な場合に解析字句を返さない､ それは､要求された全ての解消を行い､且つ､ ::http::cleanup呼出しを有する使用者の応用譜に問題はない｡ The ::http::geturl procedure will raise errors in the following cases: invalid command line options, or an invalid URL. These errors mean that it cannot even start the network transaction. For synchronous ::http::geturl calls (where -command is not specified), it will raise an error if the URL is on a non-existent host or at a bad port on an existing host. It will also raise an error for any I/O errors while writing out the HTTP request line and headers, or reading the HTTP reply headers or data. Because ::http::geturl does not return a token in these cases, it does all the required cleanup and there is no issue of your app having to call ::http::cleanup.

非同期の ::http::geturl 呼び出しに､全ての上述の不都合状態が適用されるが､例外として､もし､HTTP 返答見出しかデータを読んでいる間に入出力不都合を得ると､例外は発信されない｡理由は､HTTP 見出しを書いた後に ::http::geturl が戻り､残りの HTTP一括処理は背景処理で行われるから｡ 命令の呼戻しは､状態を確認する為に呼出した::http::responseInfo による読出しの間に不都合が生じていたかを確認することができる｡ For asynchronous ::http::geturl calls, all of the above error situations apply, except that if there is any error while reading the HTTP reply headers or data, no exception is thrown. This is because after writing the HTTP headers, ::http::geturl returns, and the rest of the HTTP transaction occurs in the background. The command callback can check if any error occurred during the read by calling ::http::responseInfo to check the transaction status.

反対にもし､主算譜の処理流れが非同期のHTTP 要求の結果を知る必要がある箇所に達したら､ 丁度同期呼出しが行っている様に､ ::http::wait を呼び､状態と不都合を確認してもよい｡ 　　　 Alternatively, if the main program flow reaches a point where it needs to know the result of the asynchronous HTTP request, it can call ::http::wait and then check status and error, just as the synchronous call does.

::http::geturl 命令は catch 命令内部で -command と -handler と -proxyfilter 呼戻しを実行する｡従って､ callback 命令内の不都合は bgerror 把持子を呼出さない｡これ等の callback の内の一つを修繕する時､ callback 命令自身の内部の catch 命令に使われる不都合を報告することは便利かもしれない､譬えば､不都合報告を標準出力に書きだすとか｡ The ::http::geturl command runs the -command, -handler, and -proxyfilter callbacks inside a catch command. Therefore an error in the callback command does not call the bgerror handler. When debugging one of these callbacks, it may be convenient to report errors by using a catch command within the callback command itself, e.g. to write an error message to stdout.

いかなる場合も､最後に､状態配列を刷新する為に ::http::cleanup を呼び出す必要がある｡ In any case, you must still call ::http::cleanup to delete the state array when you are done.

HTTP一括処理の結果の可能性として､他にも ::http::status (又は､::http::responseInfoに返された辞書の中のstatus鍵語の値) の状態の調査によって定められるものがある｡これらは次に述べる｡ 　　　 There are other possible results of the HTTP transaction determined by examining the status from ::http::status (or the value of the status key in the dictionary returned by ::http::responseInfo). These are described below.

ok
  HTTP一括処理が完全に完了すると､状態が ok になる｡ しかし､それでもHTTP一括処理の結果を得る為に ::http::responseLine の値を試験しておく方が好い｡ ::http::responseCode手続函数が “HTTP 404 File not found” の様な値を返した時に ::http::responseLine 手続函数は数値不都合(譬えば､200 や 404 や 500)を提供する｡ If the HTTP transaction completes entirely, then status will be ok. However, you should still check the ::http::responseLine value to get the HTTP status. The ::http::responseCode procedure provides just the numeric error (e.g., 200, 404 or 500) while the ::http::responseLine procedure returns a value like “HTTP 404 File not found”.

eof
  もし､中央集中処理装置が受け口を回答なしに閉じた場合､不都合は生じないが､一括処理の状態はファイル終末状態 eof になる｡ 　　　 If the server closes the socket without replying, then no error is raised, but the status of the transaction will be eof.

error
  不都合伝言文､棚追跡､不都合番号が::http::error経由で､利用できる｡ 不都合電郷分は､又､::http::responseInfoに返された辞書内のerror鍵語の値によって提供される｡ The error message, stack trace, and error code are accessible via ::http::error. The error message is also provided by the value of the error key in the dictionary returned by ::http::responseInfo.

timeout
  処理が完了できる前に時間切れが生じる｡ A timeout occurred before the transaction could complete.

reset
  使用者は::http::resetを呼んだ｡ The user has called ::http::reset.

  (空文字列)処理は未だ終了してない｡ (empty string) The transaction has not yet finished.

起りうる他の不都合は､ POST要求本体(-query又は-querychannel)の全体を中央集中処理に書くことに::http::geturlが失敗することである｡ ::http::geturlは､::http::postError命令や::http::responseInfo命令による後の取得の為の不都合伝言文を保存する､そして､次に､業務処理の完遂を試みる｡ 中央集中処理の応答を読むことができる場合､状況はokになる､但し､全てのPOSTの後に､データが全部送られたかを確認する為に､::http::postErrorか::http::responseInfoを呼ぶことが､重要である｡ もし､中央集中処理が接続を閉じていたら､状況はeofになる｡ Another error possibility is that ::http::geturl failed to write the whole of the POST request body (-query or -querychannel data) to the server. ::http::geturl stores the error message for later retrieval by the ::http::postError or ::http::responseInfo commands, and then attempts to complete the transaction. If it can read the server's response the status will be ok, but it is important to call ::http::postError or ::http::responseInfo after every POST to check that the data was sent in full. If the server has closed the connection the status will be eof.

### METADATA

#### MOST USEFUL METADATA

HTTP中央集中処理が要求に応答する時､要求された実体のみでなく､汎データも供給する｡これは､応答の第一行("状況行")､及び､沢山のHTTP冒頭句によって提供される｡ 更なる汎データは､中央集中処理からの応答を如何に::http::geturlが処理するかに関わる｡ When a HTTP server responds to a request, it supplies not only the entity requested, but also metadata. This is provided by the first line (the "status line") of the response, and by a number of HTTP headers. Further metadata relates to how ::http::geturl has processed the response from the server.

最も重要な汎データが､命令::http::responseInfoにより利用可能である｡ この命令は､ 情報となる他の汎データに沿って､成功裡の一括処理の識別の為､ 及び､応答の使用をなす為､ 汎データのdictを返す｡ dictの鍵語は: The most important metadata can be accessed with the command ::http::responseInfo. This command returns a dict of metadata that are essential for identifying a successful transaction and making use of the response, along with other metadata that are informational. The keys of the dict are:

    ===== 不可欠な値 Essential Values =====

stage
  この値は::http::geturlによって制定され､一括処理が到達した段階を記述する｡ 値は､一括処理の寿命巡回の順に､"生成"と "接続"と "冒頭句"と"本体"と "完了"｡ 他の辞書dict鍵語は段階の値が"本体"か"完了"になる迄は利用できない｡鍵語､現寸法currentSizeは段階が"完了"の時のみその最終値を有す｡ This value, set by ::http::geturl, describes the stage that the transaction has reached. Values, in order of the transaction lifecycle, are: "created", "connecting", "header", "body", and "complete". The other dict keys will not be available until the value of stage is "body" or "complete". The key currentSize has its final value only when stage is "complete".

status
  この値は::http::geturlにより設定され､成功裡の一括処理に関しては"ok"; 成功しない一括処理には､"eof"か "error"か "timeout"か "reset"; 一括処理が未だ進行中の場合､""である｡ 値は､命令::http::statusによって返されるのと同じである｡これ等の値の意味は､ERRORS節(上述)に記述されている｡ This value, set by ::http::geturl, is "ok" for a successful transaction; "eof", "error", "timeout", or "reset" for an unsuccessful transaction; or "" if the transaction is still in progress. The value is the same as that returned by command ::http::status. The meaning of these values is described in the section ERRORS (above).

responseCode
  中央集中処理によって､応答の第一行("状況行")内に送られた"HTTP status code"｡ もし､値が､状況行から拡張できないと､全状況行が返される｡ The "HTTP status code" sent by the server in the first line (the "status line") of the response. If the value cannot be extracted from the status line, the full status line is returned.

reasonPhrase
  HTTP状況行の記述として中央集中処理によって送られた"理由句"｡ もし､値が､状況行から拡張できないと､全状況行が返される｡ The "reason phrase" sent by the server as a description of the HTTP status code. If the value cannot be extracted from the status line, the full status line is returned.

contentType
  Content-Type応答冒頭句の値か､冒頭句が供給されない場合､無為設定の値は､"応用譜/八区切り-羅列"である｡ 　 The value of the Content-Type response header or, if the header was not supplied, the default value "application/octet-stream".

binary
  この論理値は､::http::geturlによって設定され､ 本命令が､ 中央集中処理によって返された実体を､ (Content-Encoding応答冒頭句によって指定された､どのような圧縮をも復号した後に) 如何に解釈したかを記述する｡ This boolean value, set by ::http::geturl, describes how the command has interpreted the entity returned by the server (after decoding any compression specified by the Content-Encoding response header). This decoded entity is accessible as the return value of the command ::http::responseBody.

  もし､httpが二進数として符号化実態を解釈した場合､値は論理真値である｡ ::http::responseBodyに返される値は､Tcl二進数文字列である｡ これは､影像データ､zipファイル､等の為の好ましい形式である｡ もし､ 仕様側が､本命令に指示項目-binaryを渡すことにより､二進数解釈を要求した場合､ 又は､もし､ 中央集中処理が､Content-Type応答冒頭句内で､二進数内容を伝えた場合､ 又は､もし､ 中央集中処理が､どの様なContent-Type応答冒頭句も供給しなかった場合､ ::http::geturlはこの値を選択する｡ The value is true if http has interpreted the decoded entity as binary. The value returned by ::http::responseBody is a Tcl binary string. This is a suitable format for image data, zip files, etc. ::http::geturl chooses this value if the user has requested a binary interpretation by passing the option -binary to the command, or if the server has supplied a binary content type in a Content-Type response header, or if the server has not supplied any Content-Type header.

  その他の場合､値は論理偽値であり､その意味は､httpは文書として実態を復号した｡ その文書は､中央集中処理によって通知された文字揃いから､ユニコード形式に､変換された; ::http::responseBodyによって返される値は､通常Tcl文字列である｡ The value is false in other cases, and this means that http has interpreted the decoded entity as text. The text has been converted, from the character set notified by the server, into Tcl's internal Unicode format; the value returned by ::http::responseBody is an ordinary Tcl string.

  HTTP処理の後に"binary"の値を確認する事は､ 構成設定不良の中央集中処理譜が､httpに､二進数として文書原資を解釈することを惹き起ししていないか､その他､を定める為に､ 常に価値がある｡ It is always worth checking the value of "binary" after a HTTP transaction, to determine whether a misconfigured server has caused http to interpret a text resource as a binary, or vice versa.

redirection
  回送目的のURLである｡ 値は､そのLocation応答冒頭句である｡ 本冒頭句は､応答が状況番号3XX (回送)を有する時に送られる｡ The URL that is the redirection target. The value is that of the Location response header. This header is sent when a response has status code 3XX (redirection).

upgrade
  もし､空でない場合､値は､ 同じ接続を使用する為に接続している間に､ そこに中央集中処理がこの一括処理の完遂後に切替える､ 通信規約を示す｡ 中央集中処理は､通信規約の切換えを意図している時､ それは､また､状況符号として､値"101"(responseCode鍵語)を､及び､ 接続応答冒頭部の要素として､単語"昇格upgrade"を､送り､ そして､それは､応答本体は送らない｡ 更なる情報はPROTOCOL UPGRADES項を参照されたい｡ If not empty, the value indicates the protocol(s) to which the server will switch after completion of this transaction, while continuing to use the same connection. When the server intends to switch protocols, it will also send the value "101" as the status code (the responseCode key), and the word "upgrade" as an element of the Connection response header (the connectionResponse key), and it will not send a response body. See the section PROTOCOL UPGRADES for more information.

error
  もし､一つなら､不都合伝言文｡ 棚追跡と不都合符号を含む､更なる情報､は命令::http::errorから利用できる｡ The error message, if there is one. Further information, including a stack trace and error code, are available from command ::http::error.

postError
  (幾つかあれば) HTTP POST要求がその要求-本体を中央集中処理に送った時に生成された不都合伝言文｡ 棚追跡､不都合番号を含む更なる情報は､::http::postError命令から利用できる｡ POST一括処理は､ 鍵stageと鍵statusと鍵responseCodeとに沿って､完全である様に見えるかもしれない､ 但し､要求-本体の昇格の時､不都合が起こる場合は､このpostError鍵語を確認する事は重要である｡ The error message (if any) generated when a HTTP POST request sends its request-body to the server. Further information, including a stack trace and error code, are available from command ::http::postError. A POST transaction may appear complete, according to the keys stage, status, and responseCode, but it is important to check this postError key in case an error occurred when uploading the request-body.

    ===== 情報提供の値 Informational Values =====

method
  要求内で使われるHTTP手段｡ The HTTP method used in the request.

charset
  Content-Type応答冒頭部の文字揃い属性の値｡ 文字揃いの値は文書原資の為のみに使われる｡ もし､中央集中処理が文字揃いを指定しない場合､変数::http::defaultCharsetになるが､ 呼出側から故意に修正されてない限りiso8859-1である｡ 入って来る文書データは自動的にcharsetによって定められた文字揃いから Tclの内部ユニコード表現即ちTcl文字列に変換される｡ The value of the charset attribute of the Content-Type response header. The charset value is used only for a text resource. If the server did not specify a charset, the value defaults to that of the variable ::http::defaultCharset, which unless it has been deliberately modified by the caller is iso8859-1. Incoming text data is automatically converted from the character set defined by charset to Tcl's internal Unicode representation, i.e. to a Tcl string.

compression
  Content-Encoding応答冒頭句値の複写である｡ A copy of the Content-Encoding response-header value.

httpRequest
  要求内(即ち､要求行内に送られた)で指定されたHTTPの版である｡ 本命令が値を"1.0"に減らさない限り､ 値は､::http::geturlに供給された指示項目-protocolのものである(無為設定値"1.1") 理由は､それは渡された-handler指示項目だから ｡ The version of HTTP specified in the request (i.e. sent in the request line). The value is that of the option -protocol supplied to ::http::geturl (default value "1.1"), unless the command reduced the value to "1.0" because it was passed the -handler option.

httpResponse
  中央集中処理によって使われるHTTPの版である(応答"状況行"から得られた)｡ 中央集中処理はその応答内のHTTPの版を使うが､ この応答は､顧客の要求内に指定されたHTTP版と両立することを確認する｡ もし､値が､状況行から抜取れない場合､全状況行が返される｡ The version of HTTP used by the server (obtained from the response "status line"). The server uses this version of HTTP in its response, but ensures that this response is compatible with the HTTP version specified in the client's request. If the value cannot be extracted from the status line, the full status line is returned.

url
  要求されたURL､典型的には､ ::http::geturlへの引数として供給されたたURL 但し､その"断片"はなし ("#"で始まるURLの最終部分) ｡ The requested URL, typically the URL supplied as an argument to ::http::geturl but without its "fragment" (the final part of the URL beginning with "#").

connectionRequest
  幾つかあれば､ Connection要求冒頭句内の処理装置に送られた､値｡ The value, if any, sent to the server in Connection request header(s).

connectionResponse
  幾つかあれば､ Connection応答冒頭句内の処理装置から受取った値｡ The value, if any, received from the server in Connection response header(s).

connectionActual
  ::http::geturlによって設定された､この値は､ 一括処理の後､接続が､閉じられた(値"閉塞")か､開いて残存(値"活動保持")か､を報告する｡ This value, set by ::http::geturl, reports whether the connection was closed after the transaction (value "close"), or left open (value "keep-alive").

transferEncoding
  存する場合は､ Transfer-Encoding応答冒頭句の値｡ 値は､"chunked"(HTTP/1.1"塊符号化"を指す)か空文字列｡ The value of the Transfer-Encoding response header, if it is present. The value is either "chunked" (indicating HTTP/1.1 "chunked encoding") or the empty string.

totalPost
  POST要求内の要求本体の総長｡ The total length of the request body in a POST request.

currentPost
  これ迄中央集中処理に送ったPOST要求本体のバイト個数｡ 値は､::http::size命令に返されるものと同じ値である｡ 　 The number of bytes of the POST request body sent to the server so far. The value is the same as that returned by command ::http::size.

totalSize
  Content-Length応答冒頭句値の複写｡ もし､送られた場合､Content-Length冒頭句内に指定されたバイトの個数｡ もし､何も送られない場合､値は0｡ 正しく構成設定された中央集中処理は､ もし､移行-符号化が"集塊"か､又は､ (古い中央集中処理に関して)中央集中処理が原資の末尾に到達した時に中央集中処理が接続を閉じるか､の場合､ この冒頭句を､省略する｡ A copy of the Content-Length response-header value. The number of bytes specified in a Content-Length header, if one was sent. If none was sent, the value is 0. A correctly configured server omits this header if the transfer-encoding is "chunked", or (for older servers) if the server closes the connection when it reaches the end of the resource.

currentSize
  これまでに､中央集中処理から取出したバイトの個数｡ The number of bytes fetched from the server so far.

#### MORE METADATA

::http::responseInfoによって返された辞書は､汎データ利用の最も便利な小部分である｡ 他の､汎データはこれを含む: 　 The dictionary returned by ::http::responseInfo is the most useful subset of the available metadata. Other metadata include:

1. 応答の､完全な"状況行"､命令::http::responseLineの返り値として利用できる｡ The full "status line" of the response, available as the return value of command ::http::responseLine.

2. 応答冒頭句の､完全な"状況行"､命令::http::responseHeadersの返り値として利用できる｡ この返り値は､応答-冒頭句名称と値の､返り値のリスト で､中央集中処理から受取った順番である｡ The full response headers, available as the return value of command ::http::responseHeaders. This return value is a list of the response-header names and values, in the order that they were received from the server.

返り値はdictではない､理由は 幾つかの冒頭句名称は一回以上起こり得るから､特に､Set-Cookieは｡ もし､値がdictか配列(array set命令を使って)に読込まれると､ それぞれの名称の最後の冒頭句のみが保存される｡ The return value is not a dict because some header names may occur more than once, notably Set-Cookie. If the value is read into a dict or into an array (using array set), only the last header with each name will be preserved.

  幾つかの冒頭句の名称(汎データ鍵語)が下に列挙されている､ 但し､HTTP標準は更に幾つかを定義している､ 又､中央集中処理はそれ自身への追加は自由である｡ 辞書鍵が下に述べられるる時､これは::http::responseInfo命令によって返された dict値を参照する｡ Some of the header names (metadata keys) are listed below, but the HTTP standard defines several more, and servers are free to add their own. When a dictionary key is mentioned below, this refers to the dict value returned by command ::http::responseInfo.

  Content-Type
    URL内容の､内容型｡用例は､ text/htmlとimage/gif,とapplication/postscriptとapplication/x-tcl を含む｡ 文書値は典型的には文字揃いを指定する､譬えば､image/gifやapplication/postscriptやapplication/x-tcl ｡辞書の鍵語はcontentType｡ The content type of the URL contents. Examples include text/html, image/gif, application/postscript and application/x-tcl. Text values typically specify a character set, e.g. text/html; charset=UTF-8. Dictionary key contentType.

  Content-Length
    内容のバイト単位の喧伝されている寸法､利用できる辞書鍵語はtotalSize｡ これ迄に､::http::geturlによって読み出された実際のバイトの個数は､辞書鍵語currentSizeとして利用できる｡ The advertised size in bytes of the contents, available as dictionary key totalSize. The actual number of bytes read by ::http::geturl so far is available as dictionary key currentSize.

  Content-Encoding
    内容に使われた圧縮算法｡用例はgzipやdeflateを含む｡辞書鍵語はcontentである ｡ The compression algorithm used for the contents. Examples include gzip, deflate. Dictionary key content.

  Location
    この冒頭句は 応答が情況符号3XX(回送)のとき､送られる｡ 回送目的のURLを提供する｡辞書鍵語はredirectionである｡ This header is sent when a response has status code 3XX (redirection). It provides the URL that is the redirection target. Dictionary key redirection.

  Set-Cookie
    この冒頭句は､顧客にcookieを提供する為に送られる｡ cookie管理は､::http::config指示項目の::http::configによって為される､ 従って､Set-Cookie冒頭句は､使用者記述譜に解析される必要はない｡ COOKIE JAR PROTOCOL節を参照されたい｡ This header is sent to offer a cookie to the client. Cookie management is done by the ::http::config option -cookiejar, and so the Set-Cookie headers need not be parsed by user scripts. See section COOKIE JAR PROTOCOL.

  Connection
    値はコンマ区切りリストとしてか､多重冒頭句によって､供給できる｡ リストは､しばしば､"閉鎖"か"継続"の孰れかに一つの要素のみを有す｡ 値"機能昇格"は成功裡の機能昇格を示し､且つ､典型的には､状況符号101と､ Upgrade応答冒頭句と､無応答本体と､組合す｡ 辞書鍵語はconnectionResponseである｡ The value can be supplied as a comma-separated list, or by multiple headers. The list often has only one element, either "close" or "keep-alive". The value "upgrade" indicates a successful upgrade request and is typically combined with the status code 101, an Upgrade response header, and no response body. Dictionary key connectionResponse.

  Upgrade
    この値は､ 中央集中処理が､ 101応答冒頭句を終結する空行の直後に､其処に切替える通信規約を指し示す｡ 辞書鍵語はupgradeである｡ The value indicates the protocol(s) to which the server will switch immediately after the empty line that terminates the 101 response headers. Dictionary key upgrade.

#### EVEN MORE METADATA

1.
  HTTP要求の詳細｡ 要求は::http::geturlと::http::configに供給された指示項目によって定められる｡ しかし､::http::geturlが実際に中央集中処理に送ったことを調べる事は時には役立つ､ そして､この情報は命令::http::requestHeadersと::http::requestLineを通して利用できる｡ Details of the HTTP request. The request is determined by the options supplied to ::http::geturl and ::http::config. However, it is sometimes helpful to examine what ::http::geturl actually sent to the server, and this information is available through commands ::http::requestHeaders and ::http::requestLine.

2.
  状況配列: ::http::geturlの内部変数｡ それは､この配列を調査する為に､時に役立つ｡ 詳細は次の説で与えらえる｡ The state array: the internal variables of ::http::geturl. It may sometimes be helpful to examine this array. Details are given in the next section.

### STATE ARRAY

::http::geturl手続函数はtokenを返す､それは他の､HTTP一括処理の状況を調べ且つ管理する､::http::*命令への引数として使用可能である｡ 殆どの目的の為に､これ等の命令は充分である｡ tokenは､ Tcl 配列内に保存されている､一括処理の内部状態を利用する為に使う事ができる｡ この施設は､ 指示項目-commandや-handlerや-progressや-queryprogressに関する 呼戻し命令の書込みの時に最も便利である｡ 手続き函数内部の局所変数として､簡易使用配列stateを定義する為の手続き函数内の､次の命令を使われたい｡ The ::http::geturl procedure returns a token that can be used as an argument to other ::http::* commands, which examine and manage the state of the HTTP transaction. For most purposes these commands are sufficient. The token can also be used to access the internal state of the transaction, which is stored in a Tcl array. This facility is most useful when writing callback commands for the options -command, -handler, -progress, or -queryprogress. Use the following command inside the proc to define an easy-to-use array state as a local variable within the proc

    upvar 0 $token state

URL に関するデータが一たび､最早必要でなくなると､状態配列は保存域から解放することが望ましい｡ ::http::cleanup 手続函数はこの目的を提供してくれる｡ Once the data associated with the URL is no longer needed, the state array should be unset to free up storage. The ::http::cleanup procedure is provided for that purpose.

次の配列の要素が供給され､そして､それは､ 下に記述された命令から返された値の起源である｡ 辞書鍵語が下に述べられた時､これは 命令::http::responseInfoによって返された辞書値を参照する｡ The following elements of the array are supported, and are the origin of the values returned by commands as described below. When a dictionary key is mentioned below, this refers to the dict value returned by command ::http::responseInfo.

binary
  辞書鍵語binaryに関わる｡ For dictionary key binary.

body
  命令::http::responseBodyに関わる｡ For command ::http::responseBody.

charset
  辞書鍵語charsetに関わる｡ For dictionary key charset.

coding
  辞書鍵語compressionに関わる｡ For dictionary key compression.

connection
  辞書鍵語connectionActualに関わる｡ For dictionary key connectionActual.

currentsize
  命令::http::sizeに関わり､辞書鍵語currentSizeに関わる｡ For command ::http::size; and for dictionary key currentSize.

error
  命令::http::errorに関わり､部分が辞書鍵語errorに使われる｡ For command ::http::error; part is used in dictionary key error.

http
  命令::http::responseLineに関わる｡ For command ::http::responseLine.

httpResponse
  辞書鍵語httpResponseに関わる｡ For dictionary key httpResponse.

meta
  命令::http::responseHeadersに関わる｡更なる論議は上述のMORE METADATA項｡ For command ::http::responseHeaders. Further discussion above in the section MORE METADATA.

method
  辞書鍵語methodに関わる｡ For dictionary key method.

posterror
  辞書鍵語postErrorに関わる｡ For dictionary key postError.

postErrorFull
  命令::http::postErrorに関わる｡ For command ::http::postError.

-protocol
  辞書鍵語httpRequestに関わる｡ For dictionary key httpRequest.

querylength
  辞書鍵語totalPostに関わる｡ For dictionary key totalPost.

queryoffset
  辞書鍵語currentPostに関わる｡ For dictionary key currentPost.

reasonPhrase
  辞書鍵語reasonPhraseに関わる｡ For dictionary key reasonPhrase.

requestHeaders
  命令::http::requestHeadersに関わる｡ For command ::http::requestHeaders.

requestLine
  命令::http::requestLineに関わる｡ For command ::http::requestLine.

responseCode
  辞書鍵語responseCodeに関わる｡ For dictionary key responseCode.

state
  辞書鍵語stageに関わる｡ For dictionary key stage.

status
  命令::http::statusに関わる;且つ､辞書鍵語statusに関わる｡ For command ::http::status; and for dictionary key status.

totalsize
  辞書鍵語totalSizeに関わる｡ For dictionary key totalSize.

transfer
  辞書鍵語transferEncodingに関わる｡ For dictionary key transferEncoding.

type
  辞書鍵語contentTypeに関わる｡ For dictionary key contentType.

upgrade
  辞書鍵語upgradeに関わる｡ For dictionary key upgrade.

url
  辞書鍵語urlに関わる｡ For dictionary key url.

### 永続的な接続　　PERSISTENT CONNECTIONS

#### 基本　　BASICS

RFC 2616 Sec 8.1 の後継のRFC 7230 Sec 6 を参照されたい｡　　　　　 See RFC 7230 Sec 6, which supersedes RFC 2616 Sec 8.1.

永続的接続は､同じ TCP 接続に持越されるべき多重 HTTP/1.1 一括処理を許容する｡パイプライン化は依頼者にそれぞれの応答を待つことなく永続的接続の多重要求させることを許容する｡中央集中処理機能は要求が受付けられた順番に応答を送る｡　　　 A persistent connection allows multiple HTTP/1.1 transactions to be carried over the same TCP connection. Pipelining allows a client to make multiple requests over a persistent connection without waiting for each response. The server sends responses in the same order that the requests were received.

POST 要求が遂行に失敗すると､典型的には要求を再度送る前に使用者の確認が必要である｡使用者は同じ要求を再度送る前に失敗した POST 要求によって中央集中処理機能が修正されたか否かを検証することを望むかもしれない｡　　　　　　 If a POST request fails to complete, typically user confirmation is needed before sending the request again. The user may wish to verify whether the server was modified by the failed POST request, before sending the same request again.

http::geturl への呼出しが指示項目 -keepalive に真値を有している場合､HTTP 要求は永続的 socket を使用することになる｡ http::config の指示項目 -pipeline が論理真値(その省略時設定値)である場合､許可されている処でパイプライン化を使用する｡　　　　 A HTTP request will use a persistent socket if the call to http::geturl has the option -keepalive true. It will use pipelining where permitted if the http::config option -pipeline is boolean true (its default value).

http 梱包は最早やそれぞれの中央集中処理機能(即ち､それぞれの “domain:port” 値)毎に一つ以上の永続的接続を維持しない｡もし http::geturl が､他の要求により接続が繁忙である間､永続的接続を通して要求をさせる為に呼出されると､新しい要求は接続が自由になる迄待ち行列内に保持されることになる｡　　　　　　 The http package maintains no more than one persistent connection to each server (i.e. each value of “domain:port”). If http::geturl is called to make a request over a persistent connection while the connection is busy with another request, the new request will be held in a queue until the connection is free.

http は､継続使用の 冒頭部により管理される HTTP/1.0 永続接続に対応していない｡　　　　 The http package does not support HTTP/1.0 persistent connections controlled by the Keep-Alive header.

#### 特別な場合　　SPECIAL CASES

この小節では中央集中処理機能による永続的接続の閉鎖と､失敗した要求の自動的再試用と､ POST 要求の為に必要な特別の扱いと､このような場合を取扱う為の指示項目とに関連する事柄を議論する｡　　　　　　　 This subsection discusses issues related to closure of the persistent connection by the server, automatic retry of failed requests, the special treatment necessary for POST requests, and the options for dealing with these cases.

RFC 7230 に従って､ http::geturl は POST 手段が使用するパイプライン化要求を行わない｡もし､POST が永続的接続を使用し且つその接続の最初の要求でない場合､ http::geturl は先行の要求の応答が受付けられる迄待つか； 又は､(もし､http::config の -postfresh 指示項目が論理真値の場合)それぞれの POST に新しい接続を使う｡　　　　　 In accordance with RFC 7230, http::geturl does not pipeline requests that use the POST method. If a POST uses a persistent connection and is not the first request on that connection, http::geturl waits until it has received the response for the previous request; or (if http::config option -postfresh is boolean true) it uses a new connection for each POST.

もし中央集中処理機能が多数のパイプライン化要求を処理していて､且つ､その内のひとつが “接続: 閉鎖” 冒頭の応答を送ると(最後のものを除き)､引続く応答は実現されない｡http::geturl は新しい接続を通して実現されない要求を送ることになる｡　 If the server is processing a number of pipelined requests, and sends a response header “Connection: close” with one of the responses (other than the last), then subsequent responses are unfulfilled. http::geturl will send the unfulfilled requests again over a new connection.

HTTP 依頼者が､暫くの間､暇であった永続的接続を通して要求を送るとき困難が生じる｡ HTTP 中央集中処理機能は依頼者が要求を送っているが要求が中央集中処理機能に届く前に､明らかに暇な接続を半分閉じているかもしれない；この場合( “非同期閉鎖行事” )その要求は失敗する｡困難が生じる原因は､ POST が中央集中処理機能の状態を修正しているか否かを依頼者が確認できないことによる｡ HEAD や GET 要求では､http::geturl は他の接続を開き､失敗した要求を保持する｡しかしながら､もし要求が POST の場合､ RFC 7230 は省略時設定で自動再試用を許可していて､使用者による確認､若しくは､応用譜の意味論的理解を有している使用者-代理ソフトによる確認のいずれかを示唆している｡ http::config の -repost 指示項目は両方の可能性を許容している｡　　　　　 A difficulty arises when a HTTP client sends a request over a persistent connection that has been idle for a while. The HTTP server may half-close an apparently idle connection while the client is sending a request, but before the request arrives at the server: in this case (an “asynchronous close event”) the request will fail. The difficulty arises because the client cannot be certain whether the POST modified the state of the server. For HEAD or GET requests, http::geturl opens another connection and retransmits the failed request. However, if the request was a POST, RFC 7230 forbids automatic retry by default, suggesting either user confirmation, or confirmation by user-agent software that has semantic understanding of the application. The http::config option -repost allows for either possibility.

非同期閉鎖は短い期間の間のみ生じる可能性がある｡この http 梱包は中央集中処理機能によるそれぞれの永続的接続の閉鎖について監視している｡検知すると､依頼の終わりで接続も閉鎖され､引続く要求は新しい接続を使う｡　　　　　 Asynchronous close events can occur only in a short interval of time. The http package monitors each persistent connection for closure by the server. Upon detection, the connection is also closed at the client end, and subsequent requests will use a fresh connection.

http::geturl 命令が -keepalive 指示項目に真値を伴って呼出されると､既存の永続的接続を使う試み(それが利用できれば)と､将来の要求の為の接続の保持を要請する “接続: 活動的に保持” 冒頭部を中央集中処理機能に送る試みの両方が起こる｡　　　　 If the http::geturl command is called with option -keepalive true, then it will both try to use an existing persistent connection (if one is available), and it will send the server a “Connection: keep-alive” request header asking to keep the connection open for future requests.

http::config の指示項目の -pipeline と -postfresh と -repost は持続的な接続に関連する｡ 　 The http::config options -pipeline, -postfresh, and -repost relate to persistent connections.

指示項目 -pipeline が論理真値の場合､パイプライン GET と HEAD の要求は永続的接続を通して為される｡POST 要求は､ POST が､その接続上の最初の一括処理でなければパイプライン化されない､その要求は先行する応答が終るまで送られない｡POST の後でなされた GET と HEAD 要求は､ POST 応答が配賦される迄送られることはなく､もし POST が失敗すると送られることはない｡　　　　　 Option -pipeline, if boolean true, will pipeline GET and HEAD requests made over a persistent connection. POST requests will not be pipelined - if the POST is not the first transaction on the connection, its request will not be sent until the previous response has finished. GET and HEAD requests made after a POST will not be sent until the POST response has been delivered, and will not be sent if the POST fails.

指示項目 -postfresh が論理真値の場合､ http::geturl の -keepalive 指示項目を上書きすることになる､又､常に POST 要求の為の新しい接続を開く｡　　　　 Option -postfresh, if boolean true, will override the http::geturl option -keepalive, and always open a fresh connection for a POST request.

指示項目 -repost が論理真値の場合､中央集中処理機能が半閉じにした( “非同期的閉鎖行事” )永続接続を使う為に失敗した POST 要求を自動的に再試用することを許容する｡失敗したパイプライン内の､引続く GET と HEAD 要求も同じく再試用される｡ -repost 指示項目は応用譜が再試用が適切であることを理解している時のみ使用すべきである - 特に､その応用譜は POST が失敗した場合は成功裡に中央集中処理機能の状態を修正し､ POST の繰返しが悪影響を生じないことを知っていなければならない｡　　　　　 Option -repost, if true, permits automatic retry of a POST request that fails because it uses a persistent connection that the server has half-closed (an “asynchronous close event”). Subsequent GET and HEAD requests in a failed pipeline will also be retried. The -repost option should be used only if the application understands that the retry is appropriate - specifically, the application must know that if the failed POST successfully modified the state of the server, a repeat POST would have no adverse effect.

### COOKIE JAR PROTOCOL

cookieは短い鍵語-値 対であり､その他-状況無しHTTP通信規約の内部の講習会を実施する為に使われる｡ (詳細はRFC 6265を参照されたい;TclはCookie2通信規約は実装してない､それが世界でも 珍しいから｡)[訳註:wild-->world] Cookies are short key-value pairs used to implement sessions within the otherwise-stateless HTTP protocol. (See RFC 6265 for details; Tcl does not implement the Cookie2 protocol as that is rarely seen in the wild.)

cookie貯蔵管理命令 — “cookie 瓶” — はこれらの副命令を支援せねばならず､それは､HTTPcookie貯蔵管理通信規約を形成する｡註意すべきは､下記のcookieJarは命令名称である必要はない; それは､命令前置辞(その場で拡張される単語のTclリスト)が適切で､多くの可能な実装を認可している｡ Cookie storage management commands — “cookie jars” — must support these subcommands which form the HTTP cookie storage management protocol. Note that cookieJar below does not have to be a command name; it is properly a command prefix (a Tcl list of words that will be expanded in place) and admits many possible implementations.

通信規約の公式な部分でなくとも､cookie瓶の特定の値が講習に相当する事が期待されている; 講習が何に適用されるか､及び､ それが最早望まれない時(現在のcookie瓶として構成設定されない時である筈)に所謂講習の削除を管理すること､とは､ ::http::configの呼出し者次第である｡ Though not formally part of the protocol, it is expected that particular values of cookieJar will correspond to sessions; it is up to the caller of ::http::config to decide what session applies and to manage the deletion of said sessions when they are no longer desired (which should be when they not configured as the current cookie jar).

cookieJar getCookies protocol host requestPath
  この命令は､cookie瓶に､特定の要求の為に､どの様なcookieが供給されるべきかを問う｡ それは､protocol(典型的にはhttpかhttps)とhost名称とrequestPathとを採るべきで､そして､ cookie鍵語と､離れた亭主に供給する為のcookieを記述する値と､ を返す｡ リストは偶数個の要素がなければならない｡ This command asks the cookie jar what cookies should be supplied for a particular request. It should take the protocol (typically http or https), host name and requestPath (parsed from the url argument to ::http::geturl) and return a list of cookie keys and values that describe the cookies to supply to the remote host. The list must have an even number of elements.

  常に､任意の要求の為の特定の鍵(典型的には､最も特定の 亭主/領域合致､且つ､最も特定の 要求路/経路 合致)を伴い､ 最大限一個のみのcookieがあるべきであるが､ どの様な要求にも､異なる名前の多くのcookieが在るかも知れない ｡ There should only ever be at most one cookie with a particular key for any request (typically the one with the most specific host/domain match and most specific requestPath/path match), but there may be many cookies with different names in any request.

cookieJar storeCookie cookieDictionary
  この命令は､ 要求によって返された特定のcookieを保存する事をcookie瓶に要請する; この命令の結果は無視される｡ cookie(それは､http梱包によって解析された)は､辞書cookieDictionaryによって記述され､それは次の鍵語があり得る: This command asks the cookie jar to store a particular cookie that was returned by a request; the result of this command is ignored. The cookie (which will have been parsed by the http package) is described by a dictionary, cookieDictionary, that may have the following keys:

  domain
    これは､いつもある｡その値は､cookieがそこに返される筈の､領域亭主名か､ 前置辞を記述する｡ 元の箇所(下の)に対する領域の確認は注意を要す､理由は､issueを発行する基地は､ それ自身に関係する領域に関してのみそれをしてるから｡ 関連する起源に合致する規則に沿わないcookieは無視される筈である｡ This is always present. Its value describes the domain hostname or prefix that the cookie should be returned for. The checking of the domain against the origin (below) should be careful since sites that issue cookies should only do so for domains related to themselves. Cookies that do not obey a relevant origin matching rule should be ignored.

  expires
    これは任意追加である｡ もし､存する場合は､ cookieは､持続的cookieであり､且つ､指示項目の値は､ cookieが満了する時の(過去の場合もあり得る､その時は､cookieは即刻削除される) Tcl 時刻印(秒単位､clock secondsと同一基準の)､である｡ もし､ない場合､cookieは､ cookie瓶の寿命を超えて存続するべきでない講習のcookieが意図されている｡ This is optional. If present, the cookie is intended to be a persistent cookie and the value of the option is the Tcl timestamp (in seconds from the same base as clock seconds) of when the cookie expires (which may be in the past, which should result in the cookie being deleted immediately). If absent, the cookie is intended to be a session cookie that should be not persisted beyond the lifetime of the cookie jar.

  hostonly
    これは常にある｡ cookieが単一亭主cookie(真値)か､領域-水準cookie(偽値)､のどちらかである｡ This is always present. Its value is a boolean that describes whether the cookie is a single host cookie (true) or a domain-level cookie (false).

  httponly
    これは常にある｡ その値は､論理値であって､ 基地が､cookieに､HTTP(又はHTTPS)交換のみを常に使用することを望む時は真値である｡ This is always present. Its value is a boolean that is true when the site wishes the cookie to only ever be used with HTTP (or HTTPS) traffic.

  key
    これは常にある｡ その値は､cookieの鍵語であり､ それは､ 将来の要求にこのcookieを送る時に､戻さねばならない情報の部分である｡ This is always present. Its value is the key of the cookie, which is part of the information that must be return when sending this cookie back in a future request.

  origin
    これは常にある｡ その値は､ http梱包が､cookieを受取ったと信じている箇所を記述する､ cookieの領域が適性かを確認するには便利かも知れない｡ This is always present. Its value describes where the http package believes it received the cookie from, which may be useful for checking whether the cookie's domain is valid.

  path
    これは常にある｡ その値は､ cookieが返される筈のcookie領域への要求の経路前置辞を記述する｡ This is always present. Its value describes the path prefix of requests to the cookie domain where the cookie should be returned.

  secure
    これは常にある｡ その値は論理値であって､ cookieが､要求送付に安全な通信経路(典型的には､HTTPS)のみを使用するべき時､真値である｡ This is always present. Its value is a boolean that is true when the cookie should only used on requests sent over secure channels (typically HTTPS).

  value
    これは常にある｡ その値は､cookieの値であって､ それは､ 将来の要求にこのcookieを送る時に､戻さねばならない情報の部分である｡ This is always present. Its value is the value of the cookie, which is part of the information that must be return when sending this cookie back in a future request.

  他の鍵語は常に無視され､この通信規約内では意味がない｡ Other keys may always be ignored; they have no meaning in this protocol.

### PROTOCOL UPGRADES

HTTP/1.1 接続と機能昇格の要求の冒頭部は中央集中処理装置に依頼者が､使われている既存の接続 (RFC 7230)全体の通信規約の変更を望んでいる事を伝える｡ この機構は WebSocket (RFC 6455)､即ち HTTP 通信規約の上位版 (HTTP 2) や TLS 暗号化の要求に使う事ができる｡もし中央集中処理装置が機能昇格要求を受理すると､その応答符号は 101 になる｡ The HTTP/1.1 Connection and Upgrade request headers inform the server that the client wishes to change the protocol used over the existing connection (RFC 7230). This mechanism can be used to request a WebSocket (RFC 6455), a higher version of the HTTP protocol (HTTP 2), or TLS encryption. If the server accepts the upgrade request, its response code will be 101.

http::geturl を呼んでいる時に通信規約の昇格を要求する為には､ -headers 指示項目が､接続と昇格についての適切な値を提供せねばならず､且つ､ -command 指示項目は要求された通信規約を実装する命令を提供せねばならず､且つ又､もし中央集中処理装置が通信規約の昇格を拒絶した場合に中処理装置の応答を処理できねばならない｡昇格要求の為に､ http::geturl は指示項目 -keepalive の値を無視し､且つ常に､値 0 を使用する､従って､昇格要求は､多重 HTTP の為に意図された接続に渡されてはない｡ To request a protocol upgrade when calling http::geturl, the -headers option must supply appropriate values for Connection and Upgrade, and the -command option must supply a command that implements the requested protocol and can also handle the server response if the server refuses the protocol upgrade. For upgrade requests http::geturl ignores the value of option -keepalive, and always uses the value 0 so that the upgrade request is not made over a connection that is intended for multiple HTTP requests.

Tcllib外部函数websocketはWebSocketsを実装する､且つ､ http梱包内の命令への必要な呼出しを為す｡ The Tcllib library websocket implements WebSockets, and makes the necessary calls to commands in the http package.

HTTP/2 の為の固有のｔｃｌ 依頼者用の外部函数は今は未だない｡ There is currently no native Tcl client library for HTTP/2.

昇格用の機構は電網閲覧譜内の TLS を要求する為には使われない､理由は､ http と https は異なる入力番号(port)に奉仕する｡それは､ http(s) の最上位に組込まれて高低両方の信頼性の情報交換の為の同じ TCP ポート番号に使われている電網印刷通信規約 (IPP) の様な､通信規約に使用される｡ The Upgrade mechanism is not used to request TLS in web browsers, because http and https are served over different ports. It is used by protocols such as Internet Printing Protocol (IPP) that are built on top of http(s) and use the same TCP port number for both secure and insecure traffic.

閲覧譜内では､依頼者の冒頭部の 低信頼度-昇格-要求 によって代わりに日和見的な暗号化が実装される｡もし､高信頼の奉仕が利用可能であれば､中央集中処理装置の対応番号は 307 redirect であり､且つ､対応冒頭部の Location は目的の電網番地を指定する｡閲覧譜はこの電網番地を得る為に再度 http::geturl を呼出さねばならない｡https://w3c.github.io/webappsec-upgrade-insecure-requests/ を参照されたい｡ In browsers, opportunistic encryption is instead implemented by the Upgrade-Insecure-Requests client header. If a secure service is available, the server response code is a 307 redirect, and the response header Location specifies the target URL. The browser must call http::geturl again in order to fetch this URL. See https://w3c.github.io/webappsec-upgrade-insecure-requests/

### THREADS

#### PURPOSE

命令::http::geturlは､離れた中央集中処理に接続する為に､ -async指示項目を伴ってTcl ::socket 命令を使う､ 但し､この命令からの戻りは､不利な場合(譬えば､遅いDNS観察)は､ 他の行事処理からの行事巡回を阻んで､遅らせられる｡ この遅延は､ もし､::socket命令が他の分割実行細片内で評価されていると､回避される｡ 分割実行細片の梱包は､Tclの一部ではないが､"Batteries Included"配布内で提供される｡ ::socket命令の代りに､http梱包は､ -threadlevelの値と､Thread梱包の可用性と､によって指定される方法で接続を形成する､ ::http::socketを使う｡ Command ::http::geturl uses the Tcl ::socket command with the -async option to connect to a remote server, but the return from this command can be delayed in adverse cases (e.g. a slow DNS lookup), preventing the event loop from processing other events. This delay is avoided if the ::socket command is evaluated in another thread. The Thread package is not part of Tcl but is provided in "Batteries Included" distributions. Instead of the ::socket command, the http package uses ::http::socket which makes connections in the manner specified by the value of -threadlevel and the availability of package Thread.

#### WITH TLS (HTTPS)

同じ-threadlevel構成設定をHTTP接続とHTTPS接続の両方に適用する｡ HTTPSは､ http::register命令を､ 典型的には､ TLS暗号を扱う為の､tls梱包の::tls::socket命令を､ 使用して有効になる｡ ::tls::socket命令は､ その値が"::socket"になっている変数::tls::socketCmdの値によって指定される命令を使って､ 離れた中央集中処理に接続する｡ もし､ ::tls::socketCmdがこの値を有する事を､http::geturlが見付けると､それを､値"::http::socket"で置換える｡ もし､::tls::socketCmdが"::socket"以外の値を有すると､即ち､もし､記述譜又はTcl 設備が異なる命令の名前で値"::socket"を置換えると､httpは値を変更しない｡ ::tls::socketCmdを修正した記述譜や設備は､::http::socketを自己の置換命令内に統合する責務がある｡ The same -threadlevel configuration applies to both HTTP and HTTPS connections. HTTPS is enabled by using the http::register command, typically by specifying the ::tls::socket command of the tls package to handle TLS cryptography. The ::tls::socket command connects to the remote server by using the command specified by the value of variable ::tls::socketCmd, and this value defaults to "::socket". If http::geturl finds that ::tls::socketCmd has this value, it replaces it with the value "::http::socket". If ::tls::socketCmd has a value other than "::socket", i.e. if the script or the Tcl installation has replaced the value "::socket" with the name of a different command, then http does not change the value. The script or installation that modified ::tls::socketCmd is responsible for integrating ::http::socket into its own replacement command.

#### WITH A CHILD INTERPRETER

時分割実行細片の片割れは接続口のみ､記述譜の時分割実行細片の主解釈実行機能に 転送できる｡ 従って､もし､記述譜が主解釈実行機能内で走っていると､実行細片-基準の::http::socketは､ 非-零-threadlevel値のみで働く｡ 子供の解釈実行機能は､ 親の解釈実行機能が代りの設備を提供しない限り､-threadlevel 0を使わねばならない｡ 主親の解釈実行機能は､子供の解釈実行機能に､ 全-threadlevel設備を賦与するかもしれない､ 譬えば別名によって､子供の中の::http::socketに､ 親の中でhttp::socketが走る命令､及び､接続口を子供に転送する命令､とで｡ 　 The peer thread can transfer the socket only to the main interpreter of the script's thread. Therefore the thread-based ::http::socket works with non-zero -threadlevel values only if the script runs in the main interpreter. A child interpreter must use -threadlevel 0 unless the parent interpreter has provided alternative facilities. The main parent interpreter may grant full -threadlevel facilities to a child interpreter, for example by aliasing, to ::http::socket in the child, a command that runs http::socket in the parent, and then transfers the socket to the child.

### EXAMPLE

経過帯を印刷する間に､ URL からファイルに複写する為の手続き函数を創生し､URL に結合した 応答の追加情報 を印刷する｡ This example creates a procedure to copy a URL to a file while printing a progress meter, and prints the response headers associated with the URL.

    proc httpcopy { url file {chunk 4096} } {
        set out [open $file w]
        set token [::http::geturl $url -channel $out \
                -progress httpCopyProgress -blocksize $chunk]
        close $out

        # httpCopyProgress に始められた行を終らせる.
        # This ends the line started by httpCopyProgress
        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 [httpcopy [string trim $value] $file $chunk]
            }
        }
        incr max
        foreach {name value} $state(meta) {
            puts [format "%-*s %s" $max $name: $value]
        }

        return $token
    }
    proc httpCopyProgress {args} {
        puts -nonewline stderr .
        flush stderr
    }

### SEE ALSO

safe, socket, safesock

### KEYWORDS

internet, security policy, socket, www
Copyright © 1995-1997 Sun Microsystems, Inc.
Copyright © 1998-2000 Ajuba Solutions.
Copyright © 2004 ActiveState Corporation.