## Tcl8.6.17/Tk8.6.17 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
      -pipeline boolean
      -postfresh boolean
      -proxyhost hostname
      -proxyport number
      -proxyfilter command
      -repost boolean
      -urlencoding encoding
      -useragent string
      -zip boolean
    ::http::geturl url ?options?
      -binary boolean
      -blocksize size
      -channel name
      -command callback
      -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::data token
    ::http::error token
    ::http::status token
    ::http::code token
    ::http::ncode token
    ::http::size token
    ::http::meta token
    ::http::cleanup token
    ::http::register proto port command
    ::http::registerError port ?message?
    ::http::unregister proto
  ERRORS
    ok
    eof
    error
    timeout
    reset
  STATE ARRAY
    binary
    body
    charset
    coding
    currentsize
    error
    http
    meta
      Content-Type
      Content-Length
      Location
    posterror
    status
    totalsize
    type
    url
  永続的な接続　　PERSISTENT CONNECTIONS
  基本　　BASICS
  特別な場合　　SPECIAL CASES
  通信規約の昇格　　PROTOCOL UPGRADES
  用例 EXAMPLE
  SEE ALSO
  KEYWORDS

### NAME

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

### 構文 SYNOPSIS

package require http ?2.9?

::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::code token

::http::ncode token

::http::meta token

::http::data token

::http::error token

::http::cleanup token

::http::register proto port command

::http::registerError port ?message?

::http::unregister proto

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

名前空間 http は config命令と formatQuery命令と geturl命令と quoteString命令と register命令と registerError命令と reset命令と unregister命令と wait命令を移送する｡ Namespace http exports the commands config, formatQuery, geturl, quoteString, register, registerError, reset, unregister, and wait.

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

### 説明 DESCRIPTION

この http 梱包は､RFC 2616 から代替わりした RFC 7230 から RFC 7235 に定義された委託者側の HTTP/1.1 通信規約を提供する｡この梱包は､ 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 7230 to RFC 7235, which 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 の返り値は一括処理の token である｡この値は､一括処理に関する状態情報を含む ::http 名前空間の中の配列の名前でもある｡この配列の要素は STATE ARRAY 節の中に記述されている｡ 　　　　 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 value is also the name of an array in the ::http namespace that contains state information about the transaction. The elements of this array are described in the STATE ARRAY section.

もし -command 指示項目が指定されると､ HTTP 操作は背景処理で行われる｡ ::http::geturl は HTTP 要求を生成後直ちに制御を戻し､一括処理が完了すると､呼戻しが起動される｡これが作動する為には 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 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.

### 諸命令 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/*”.

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

  -proxyhost hostname
    指定する場合は､代理の主人の名前｡この値が空文字列であると､URL の主人は直接接続される｡　　　　　 The name of the proxy host, if any. If this value is the empty string, the URL host is contacted directly.

  -proxyport number
    代理の port 番号｡　　　 The proxy port number.

  -proxyfilter command
    command は ::http::geturl の間に､与えられた主人の為に代理が要求されるかを定める為になされる呼戻しである｡ 起動される時は一つの引数が､即ち主人の名前が､command に追加される｡もし､代理が要求される場合は､呼戻しは､代理の中央収集処理装置と代理の port 番号を含む２要素のリストを返す｡それ以外の場合は､空リストを返すことになる｡省略時設定では､ -proxyhost と -proxyport の値が非空であればその設定を返す｡ 　　　 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 should return an empty list. The default filter returns the values of the -proxyhost and -proxyport settings if they are non-empty.

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

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

  -urlencoding encoding
    ::http::formatQuery と ::http::quoteString による x-url-encoded 符号化 URL の生成に使用される符号系｡ 省略時設定は RFC 2718 の指定に従って utf-8 である｡http 2.5 版以前は､規定されていなかった､それで､その振舞いは､空文字列({})を指定して戻ることもあった､同様な振舞いを復元する為に iso8859-1 が推奨されたが､ ::http::formatQuery 又は ::http::quoteString なしでは非-ラテン文字ｰ1文字を処理の不都合が発生する｡ 　　　 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. Prior to http 2.5 this was unspecified, and that behavior can be returned by specifying the empty string ({}), although iso8859-1 is recommended to restore similar behavior but without the ::http::formatQuery or ::http::quoteString throwing an error processing non-latin-1 characters.

  -useragent string
    HTTP 要求の中の使用者-代理者項目の値である｡不安全な解釈実行機能の中では､省略時設定の値はOS 及び､ http と Tcl の版番号､及び(譬ば) “Mozilla/5.0 (Windows; U; Windows NT 10.0) http/2.9.0 Tcl/8.6.9” に依存する｡安全な解釈実行機能は､その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.9.0 Tcl/8.6.9”. 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,compress” を送る｡ 値が論理偽値であると､省略時設定によりこの冒頭部は送られない｡両方の場合､省略時設定は個別の要求により､誂えた受入れ-符号系冒頭部を http::geturl の -headers 指定項目内に供給して､上書きすることができる｡省略時設定は 1 である｡　　　　　　 If the value is boolean true, then by default requests will send a header “Accept-Encoding: gzip,deflate,compress”. If the value is boolean false, then by default this header will not be sent. 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 is 1.

::http::geturl url ?options?
  この ::http::geturl 命令はこの梱包の主たる手続函数である｡ -query 指定項目は､ 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 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 used to get information about the transaction. See the STATE ARRAY 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 データを二進列として解釈することを強制するか否かを指定する｡通常､これは､自動検出である( text 含有型で始まらないものや､その内容の文字符号系が gzip や compress のものは､なんであれ二進データと看做す)｡　　　　　　 Specifies whether to force interpreting the URL data as binary. Normally this is auto-detected (anything not beginning with a text content type or whose content encoding is gzip or compress is considered binary data).

  -blocksize size
    URL を読む時に使われる一区切りの長さ｡最大 size バイトが一度に読まれる｡それぞれの区切りの後に､ -progress の呼戻しがなされる(もし､指示項目が指定されていると)｡ 　　 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 の内容を state(body) の中に保存する代りに通信路 name に複写する｡ 　　 Copy the URL contents to channel name instead of saving it in state(body).

  -command callback
    HTTP一括処理が完了した後に callback を起動する｡この指示項目は ::http::geturl に直ちに戻るようにさせる｡ callback は ::http::geturl から返された token を追加的な引数として取る｡この token は STATE ARRAY の節に記載された配列の名前である｡次に示すのが呼戻しの為の雛形である: 　　　　 Invoke callback after the HTTP transaction completes. This option causes ::http::geturl to return immediately. The callback gets an additional argument that 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
            # Tcl 配列としての宣言を利用する
            # Access state as a Tcl array
        }

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

  -handler callback
    この設定があると､HTTP データが利用できる時は何時でも callback を起動する; ないと､HTTP データにはそれ以上何もしない｡次に示す手続函数は二つの追加的引数をとる: HTTP データの為の受け口と､ ::http::geturl から返された token である｡ token は大域配列の名前であり､それは STATE ARRAY の節に記載されている｡この手続函数は受け口から読んだバイトの個数を返すよう期待されている｡これが呼戻しの為の雛形である: 　　 Invoke callback whenever HTTP data is available; if present, nothing else will be done with the HTTP data. This procedure gets two additional arguments: 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
            # 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,compress" を送らなくなる)｡ 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 not send the header "Accept-Encoding: gzip,deflate,compress").

    もし指示項目 -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
    callback は､URLからのデータの各転送後に行われる｡呼戻しは三つの追加的引数を取得する:即ち ::http::geturl からの token と､ Content-Length 擬似データの予想される総容量と､これまでに転送されたバイトの現在数である｡予想される総数は不明のこともあり､その場合は呼戻しに零が渡される｡次に示すのが呼戻しの為の雛形である: 　　 The callback is made after each transfer of data from the URL. The callback gets three additional arguments: the token from ::http::geturl, the expected total size of the contents from the Content-Length meta-data, and the current number of bytes transferred so far. 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
        }

  -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
    URL へのデータの輸送(即ち POST)の後毎に callback がなされ､正確に -progress 指示項目と同じに動作する(呼戻し書式は同一)｡ 　　 The callback is made after each transfer of data to the URL (i.e. POST) and acts exactly like the -progress option (the callback format is the same).

  -strict boolean
    要求に応じてRFC 3986 URL の検証を強制するかどうかを指定する｡省略時設定は 1｡ 　　 Whether to enforce RFC 3986 URL validation on the request. Default is 1.

  -timeout milliseconds
    もし milliseconds が非零であると､::http::geturl は指定された数の厘秒後に起る期限切れを設定する｡期限切れの結果は ::http::reset 呼び出しと､更にもし設定されていると -command 呼戻しになる｡期限切れが生じた後には､::http::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 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 要求を行う｡この要求は URLに関わる汎情報を返すが､内容は返されない｡この汎情報は､一括処理の後に state(meta) 変数の中で利用できる｡詳細は STATE ARRAY の節を参照されたい｡ 　　 If boolean is non-zero, then ::http::geturl does an HTTP HEAD request. This request returns meta information about the URL, but the contents are not returned. The meta information is available in the state(meta) variable after the transaction. See the STATE ARRAY section for details.

::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 is a convenience procedure that 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::data token
  これは状態配列の body 要素（即ち､URLデータ）を返す便利な手続函数である｡ 　　 This is a convenience procedure that returns the body element (i.e., the URL data) of the state array.

::http::error token
  これは状態配列の不都合要素errorを返す便利な手続函数である｡ 　　 This is a convenience procedure that returns the error element of the state array.

::http::status token
  状態配列の要素を返す為の便利な手続き函数である｡ This is a convenience procedure that returns the status element of the state array.

::http::code token
  これは状態配列の http 要素を返す便利な手続函数である｡ 　　 This is a convenience procedure that returns the http element of the state array.

::http::ncode token
  これは状態配列の http 要素から､終了符号数値(200, 404, etc.)を返す便利な手続函数である｡ 　　 This is a convenience procedure that returns just the numeric return code (200, 404, etc.) from the http element of the state array.

::http::size token
  これは状態配列の currentsize 要素を返す便利な手続函数である､それは､ ::http::geturl 呼出しの中の URL から受取ったバイトの個数である｡ 　　 This is a convenience procedure that returns the currentsize element of the state array, which represents the number of bytes received from the URL in the ::http::geturl call.

::http::meta token
  これは状態配列の meta 要素を返す便利な手続函数である｡それは､HTTP 回答見出しを含む｡その要素の説明については下を参照されたい｡ 　　 This is a convenience procedure that returns the meta element of the state array which contains the HTTP response headers. See below for an explanation of this element.

::http::cleanup token
  この手続函数は token で識別される接続に関する状態を刷新する｡この呼び出しの後は､ ::http::data のような手続函数はこの操作に関する情報の取得に使用できない｡与えられた HTTP 要求を済まして後にこの函数を呼ぶ様に強く推奨する｡そうしないと､記憶領域が解放されない結果になり､もし応用譜が::http::geturl を十分な回数呼ぶと､記憶領域の漏洩が性能を直撃するかもしれない更に悪い事態も...｡ 　　 This procedure cleans up the state associated with the connection identified by token. After this call, the procedures like ::http::data 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::register proto port command
  この手続函数はHTTPS の如き特別誂えの HTTP一括処理の型の提供を許容する｡接頭辞と､省略時設定の受け口と､Tcl 通信路を生成する為に実行する命令とを登録する｡譬えば: 　　　 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. E.g.:

      package require http
      package require tls

      ::http::register https 443 ::tls::socket

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

::http::registerError port ?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 two-item list of the default port and handler command that was previously installed (via ::http::register) if there was such a handler, and an error if there was no such handler.

### ERRORS

::http::geturl 手続函数は､次の場合に不都合を発信する: 不適切な命令指示項目や､不適切な URL や､実在しない主人上の URLや､実在する主人上の不正な port の URL ｡これらの不都合は電網の一括処理を始めることさえもできないことを意味している｡もし､HTTP 要求見出しを書き出している間に入出力不都合を得ると､その場合にも不都合を発生する｡同期した ::http::geturl 呼び出し(ここでは -command は指定されていない)では､もし､HTTP 返答見出しかデータを読んでいる間に入出力不都合を得ると､不都合を発生する｡この様な場合に ::http::geturl は token を返さずに､要求された全ての刷新を実行するので､応用譜が ::http::cleanup を呼ぶべきとの問題は生じない｡ 　　 　　 The ::http::geturl procedure will raise errors in the following cases: invalid command line options, an invalid URL, a URL on a non-existent host, or a URL at a bad port on an existing host. These errors mean that it cannot even start the network transaction. It will also raise an error if it gets an I/O error while writing out the HTTP request header. For synchronous ::http::geturl calls (where -command is not specified), it will raise an error if it gets an I/O error while 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::status による読出しの間に不都合が生じていたかを確認することができ､もし不都合が起こると､不都合伝言文を得る為に ::http::error を呼ぶ｡ 　　　　 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::status to check the status and if its error, calling ::http::error to get the error message.

反対にもし､主算譜の処理流れが非同期の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 callback 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 の状態の調査によって定められるものがある｡これらは次に述べる｡ 　　　 There are other possible results of the HTTP transaction determined by examining the status from ::http::status. These are described below.

ok
  HTTP一括処理が完全に完了すると､状態が ok になる｡しかし､それでもHTTP一括処理の結果を得る為に ::http::code の値を試験しておく方が好い｡ ::http::code 手続函数が “HTTP 404 File not found” の様な値を返した時に ::http::ncode 手続函数は数値不都合(譬えば､200 や 404 や 500)を提供する｡ If the HTTP transaction completes entirely, then status will be ok. However, you should still check the ::http::code value to get the HTTP status. The ::http::ncode procedure provides just the numeric error (e.g., 200, 404 or 500) while the ::http::code 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 経由で利用できる｡ 　　　 The error message will also be stored in the error status array element, accessible via ::http::error.

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

reset
  手作業での中止 user-reset

起りうる他の不都合は､中央集中処理装置が応答して受け口が閉じる迄､::http::geturl が､中央集中処理装置に全ての表示問合せデータの書込みに利用できない｡不都合伝達文は状態配列の posterror 要素に保存され､ ::http::geturl は一括処理を完了しようと試みる｡もし､中央集中処理装置の応答を読むことができれば､ ok 状態により終了するが､それ以外では､ファイル終末状態eofにさせる｡ 　　　　 Another error possibility is that ::http::geturl is unable to write all the post query data to the server before the server responds and closes the socket. The error message is saved in the posterror status array element and then ::http::geturl attempts to complete the transaction. If it can read the server's response it will end up with an ok status, otherwise it will have an eof status.

### STATE ARRAY

::http::geturl 手続函数は token を返し､それは Tcl 配列の形式の HTTP 一括処理の状態を得る為に使える｡次の構文を､使用し易い配列変数を生成する為に､使われたい: 　　　 The ::http::geturl procedure returns a token that can be used to get to the state of the HTTP transaction in the form of a Tcl array. Use this construct to create an easy-to-use array variable:

    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. The following elements of the array are supported:

binary
  HTTP 応答が( “内容-符号化” の応答冒頭で指定されたどの圧縮方法の後ででも)二進数であれば､これは論理真値である｡ HTTP 応答が文書であれば論理偽値である｡　　　　　 This is boolean true if (after decoding any compression specified by the “Content-Encoding” response header) the HTTP response is binary. It is boolean false if the HTTP response is text.

body
  URL の内容｡もし､ -channel 指示項目が指定されているとこれは空になる｡この値は ::http::data 命令から返って来る｡ 　　　　 The contents of the URL. This will be empty if the -channel option has been specified. This value is returned by the ::http::data command.

charset
  Content-Type 汎データ値の文字揃いの属性の値｡もし､何も指定されないと､省略時設定の RFC 標準 iso8859-1 か､$::http::defaultCharset の値かになる｡入力される文章は自動的にその文字揃いから utf-8 に変換される｡ 　　　　　 The value of the charset attribute from the Content-Type meta-data value. If none was specified, this defaults to the RFC standard iso8859-1, or the value of $::http::defaultCharset. Incoming text data will be automatically converted from this charset to utf-8.

coding
  Content-Encoding 汎データ値の複写｡ 　　　　 A copy of the Content-Encoding meta-data value.

currentsize
  URL から持帰った現在のバイトの数｡この値は ::http::size 命令から返ってくる｡ 　　　　 The current number of bytes fetched from the URL. This value is returned by the ::http::size command.

error
  もし定義されると､これが､HTTP 一括処理が中断された時に見える不都合伝達文字列になる｡ 　　 If defined, this is the error string seen when the HTTP transaction was aborted.

http
  中央集中処理装置からのHTTP 状態応答｡この値は ::http::code 命令から返って来る｡この値の書式は次の通り:　　 The HTTP status reply from the server. This value is returned by the ::http::code command. The format of this value is:

      HTTP/1.1 code string

  この code は HTTP 標準で定義された３桁の数字である｡番号 200 は良好 に相当する｡ 4 か 5 で始まる番号は不都合を指し示す｡ 3 で始まる番号は入出力先変更不都合である｡この場合､meta-data の Location が要求された情報を含んでいる新しい URL を指し示す｡　　　　　 The code is a three-digit number defined in the HTTP standard. A code of 200 is OK. Codes beginning with 4 or 5 indicate errors. Codes beginning with 3 are redirection errors. In this case the Location meta-data specifies a new URL that contains the requested information.

meta
  HTTP 通信規約は URL の内容を記述した汎データを返す｡状態配列の meta 要素は汎データの鍵と値のリストである｡これは､汎データを保有する配列の初期化に便利な書式である: 　　　 The HTTP protocol returns meta-data that describes the URL contents. The meta element of the state array is a list of the keys and values of the meta-data. This is in a format useful for initializing an array that just contains the meta-data:

      array set meta $state(meta)

  幾つかの汎データの鍵は下に列挙した､しかし､HTTP 標準には更に多くの定義があり､中央集中処理装置は自由に自身に追加し得る｡ 　　　 Some of the meta-data keys are listed below, but the HTTP standard defines more, and servers are free to add their own.

  Content-Type
    URL の内容の型｡例として text/html や image/gif や application/postscript や application/x-tcl がある｡　　　　 The type of the URL contents. Examples include text/html, image/gif, application/postscript and application/x-tcl.

  Content-Length
    内容の寸法の知らせ｡::http::geturl により得られた実際の寸法は state(currentsize) として利用できる｡ The advertised size of the contents. The actual size obtained by ::http::geturl is available as state(currentsize).

  Location
    要求されたデータを含む別のURL｡ 　　　 An alternate URL that contains the requested data.

posterror
  存在する場合は､中央集中処理装置に post 問合せを書いているときに生じた不都合｡ The error, if any, that occurred while writing the post query data to the server.

status
  状態 status のリストと記述については､上の ERRORS の章の記述を参照されたい｡一括処理の最中はこの値は空文字列である｡ See description in the chapter ERRORS above for a list and description of status. During the transaction this value is the empty string.

totalsize
  Content-Length 汎データ内容値の複写｡　　　 A copy of the Content-Length meta-data value.

type
  Content-Type 汎データ内容値の複写｡　　　 A copy of the Content-Type meta-data value.

url
  要求されたURL｡ 　　 The requested 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.

### 通信規約の昇格　　PROTOCOL UPGRADES

HTTP/1.1 接続と機能昇格の依頼者の冒頭部は中央集中処理装置に依頼者が､使われている既存の接続 (RFC 7230)全体の通信規約の変更を望んでいる事を伝える｡この機構は WebSocket (RFC 6455)､即ち HTTP 通信規約の上位版 (HTTP 2) や TLS 暗号化の要求に使う事ができる｡もし中央集中処理装置が機能昇格要求を受理すると､その応答符号は 101 になる｡ The HTTP/1.1 Connection and Upgrade client 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/

### 用例 EXAMPLE

この例は､ 進捗表示帯を印刷している間に､ URL をファイルに複写する為の手続き函数を創生し､URL に結合した汎データを印刷する｡ This example creates a procedure to copy a URL to a file while printing a progress meter, and prints the meta-data 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]} {
                # URL 配達先変更 の処理
                # 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.