Tcl 8.4.1　Manual Command Reference

http

コマンド名

http - クライアント側のHTTP/1.0プロトコルの実装。

構文

package require http ?2.4?
::https::config ?options?
::https::geturl url ?options?
::https::formatQuery list
::https::reset token
::https::wait token
::https::status token
::https::size token
::https::code token
::https::ncode token
::https::data token
::https::error token
::https::cleanup token
::https::register proto port command
::https::unregister proto

解説

httpパッケージはクライアント側のHTTP/1.0プロトコルを提供します。 このパッケージはHTTP/1.0のGET、POST、そしてHEAD操作を実装します。 これはファイアウォールを通したプロキシーホストの構成を許可します。 このパッケージはSafesockセキュリティ方針と互換性があります。 従って、信用されないアプレットで制限されたホストの設定からURLを取得することに使えます。このパッケージは https::registerによってカスタマイズ socket命令を提供することによって、HTTPSのような拡張HTTPトランスポートプロトコルをサポートできるように拡張できます。

::https::geturlプロシージャはHTTPトランザクショ ンを行います。 options はGET、POSTあるいはHEADトランザクションのどれが行われるかを決定します。 ::https::geturlの戻り値はこのトランザクションのトークンです。この値はトランザクションに関する状態情報を格納している::httpネームスペースの配列の名前です。 この配列の要素はSTATE ARRAY（状態配列）セクションで説明されます。

-commandオプションが指定されると、HTTP操作はバックグラウンドにおいて行われます。::http::geturlはhttps:クエストを生成した後、直ちに返します。 トランザクションが完了したときにコールバックが呼び出されます。これが機能するために、Tclイベントループが動作していなければなりません。 Tkアプリケーションではこれは常に満足できます。 純粋のTclアプリケーションでは、イベントループをスタートさせるために、::http::geturl呼び出しの後に https: ::https::wait を使用することができます。

コマンド

::https::config ?options?

-accept mimetypes

-proxyhost hostname

-proxyport number

-proxyfilter command

-useragent string

::https::geturl url ?options?

-binary boolean

-blocksize size

-channel name

-command callback

-handler callback

-headers keyvaluelist

-progress callback

-query query

-queryblocksize size

-querychannel channelID

-queryprogress callback

-timeout milliseconds

-type mime-type

-validate boolean

::https::formatQuery key value ?key value ...?

::https::reset token ?why?

::https::wait token

::https::data token

::https::error token

::https::status token

::https::code token

::https::ncode token

::https::size token

::https::cleanup token

::https::register proto port command

::https::unregister proto

::https::config ?option ?

::https::configコマンドはHTTPリクエストに使われる代理サーバとポートの名前、そしてユーザー代理（User-Agent）名前の設定と取得に使用されます。 オプションが指定されないと、現在の構成は返されます。 単一の引数が指定されると、下で示されたフラグのうちの1つでなければなりません。 この場合、現在の設定値は返されます。 そうでない場合は、それらのオプションは構成を定義するフラグと値のセットでなければなりません。

-accept mimetypes

リクエストの受け取りヘッダーで、デフォルトは*/*です。ドキュメントの全てのタイプが受け入れられることを意味します。 他の場合は、受け取りたいコンマで区切られたMIMEタイプパターンのリストを提供することができます。 例えば、"image/gif, image/jpeg, text/*"。

　

-proxyhost hostname

存在するなら代理ホストの名前です。 この値が空文字列ならば、URLホストが直接にコンタクトされます。

　

-proxyport number

代理ポート番号です。

　

-proxyfilter command 

command は与えられたホストに対して、代理が要求されるか判定するために ::https::geturlの間に作成されるコールバックです。 呼び出し時に、１つの引数（即ちホスト名）がcommandに付け加えられます。 代理が要求される場合、コールバックは代理サーバーと代理ポートを含む２つの要素のリストを返さなければなりません。そうでなければ、フィルタは空文字を返さなければなりません。デフォルトのフィルタは-proxyhostと-proxyportが設定した値（もしそれらが空なければ）を返します。

　

-useragent string

HTTPリクエストのUser-Agentヘッダの値で、デフォルトは"Tcl http client package 2.0."です。

　

::https::geturl url ?option?

::https::geturlコマンドはこのパッケージの主なプロシージャです。 -queryオプションはPOST操作を実行させ、-validateオプションはHEAD操作を実行させます。 他の場合、GET操作が実行されます。 ::http::gehttps:/strong>コマンドは、このトランザクションに関する情報を取得するのに使用できるtoken 値を返します。詳細はSTATE ARRAY（状態配列）とERRORS（エラー）セクショ ンを参照します。 ::http:https:rlコマンドは-commandオプションで、HTTPトランザクションが完了したときに呼び出されるコールバックを指定しないと、操作が完了するまでブロックを行います。 ::https::geturlはいくつかのオプションがあります。

　

-binary boolean

URLデータをバイナリと解釈することを強制するかどうかを指定します。通常、これは自動的に検出されます。 text コンテンツ型で始まらないもの、またはそのコンテンツエンコーディングがgzipかcompressかであるものはバイナリデータと考えられます。

　

-blocksize size

URLを読み込むときに使用するブロックサイズです。 一度に最大でsizeバイト読み込みます。 各ブロックの後で、-progressコールバックの呼び出しが行われます。

　

-channel name

URLコンテンツをstate(body)に保存する代わりにチャンネルnameにコピーします。

　

-command callback

HTTPトランザクションが完了したときにcallback を呼び出します。このオプションは::http::geturlを直ちに制https:す。callback は ::hhttps:geturl から返されたtokenである追加的な引数を受け取ります。このトークンはSTATE ARRAY（状態配列）セクションに説明されている配列の名前です。以下がコールバックのテンプレートです。

proc httpCallback {token} {
    upvar #0 $token state
    # Access state as a Tcl array
}

-handler callback

HTTPデータが利用可能であるたびにcallback を呼び出します。 存在するなら、他の何のHTTPデータも処理しません。 このプロシージャは2つの追加的な引数を受け取ります。HTTP データのソケットと::http::gehttps:/strong>から返されたtokenです。このトークンはSTATE ARRAY（状態配列）セクションに説明されている配列の名前です。このプロシージャはソケッ トから読まれたバイト数を返します。 以下がコールバックのテンプレートです。

proc httpHandlerCallback {socket token} {
    upvar #0 $token state
    # Access socket, and state as a Tcl array
    ...
    (example: set data [read $socket 1000];set nbytes [string length $data])
    ...
    return nbytes
}

-headers keyvaluelist

このオプションはHTTPリクエストに余分なヘッダーを追加するために使われます。 keyvaluelist 引数はキーと値が交互にある偶数の要素のリストでなければなりません。 キーはヘッダーのフィールド名になります。 ヘッダが破壊されないように、改行は値から取り除かれます。例えば、keyvaluelist が Pragma no-cacheなら、以下のヘッダーがHTTPリクエストに含まれます。

Pragma: no-cache

-progress callback

URLからの各データ転送の後でcallback が行われます。 callback は３つの追加的引数を受け取ります。 ::http::ghttps:からのtoken、Content-Lengthメタデー タの内容の予想総サイズ、及び現在の転送されたバイ ト数です。予想総サイズは分からない場合は、コールバックに0が渡されます。 以下がコールバックのテンプレートです。

proc httpProgress {token total current} {
    upvar #0 $token state
}

-query query

このフラグは::http:https:rlにPOSTリクエストを実行させます。 これでサーバーにquery を渡します。 query はx-url- encodingでフォーマットされたクエリーでなければなりません。 ::https::formatQuery プロシージャがこのフォーマットを作成するために使用できます。

　

-queryblocksize size

クエリーデータをURLにポストしているとき使用したブロックサイズです。一度に最大size バイトは書かれます。各ブロックの後で ( そのオプションが指定されるならば ) 、-queryprogressコールバックへの呼び出しは実行されます。

　

-querychannel channelID

このフラグは::http:https:rlにPOSTリクエストを実行させます。 これでサーバへchannelID に含まれるデータを渡します。 下の-typeオプションが使われない限り、channelIDに含まれるデータはx-url-encodingにフォーマットされたクエリーでなければなりません。 Content-Lengthヘッダーが-headersオプションによって指定されないと、::http::geturlはそのヘッダーを作成するために、ポストデータのサイズを判断しようと試みます。 サイズを決定することができないとエラーを返します。

　

-queryprogress callback

URLからの各データ転送の後（即ちPOST）でcallback が行われ、-progressオプションと同様に動きます（コールバックのフォーマットが同じです）。

　

-timeout milliseconds

milliseconds が0でなければ、::htthttps:turlはタイムアウトを指定されたミリ秒後に起こるよう設定します。 指定されていれば、タイムアウトは::http::resehttps:rong> と-commandコーバックの呼び出しを実行します。 ::https::status の戻り値はタイムアウトが起こっ た後ではtimeoutとなります。

　

-type mime-type

POST操作の間のデフォルト値 (application/x-www-form-urlencoded) の代わりにContent-Type値としてmime-type を使用します。

　

-validate boolean

boolean が0でなければ、::htthttps:turlはHTTPのHEADリクエストを行います。 このリクエストはURLに関するメタ情報を返しますが、その内容は返されません。 メタ情報はトランザクションの後にstate(meta) 変数の中に入れられます。詳細はSTATE ARRAYセクションを参照します。

　

::https::formatQuery key value ?key value ...?

本プロシージャはクエリーデータのx-url-encoding変換を行います。これはクエリーのキーと値の偶数の引数を受け取ります。 これはキーと値をエンコードし、そして適切な&と=の区切り記号を持つ１つの文字列を生成します。 その結果は::htthttps:turlに渡される-queryの値に適します。

　

::https::reset token ?why ?

このコマンドはtoken に識別されたHTTPトランザクション（もしあれば）をリセットします。 state(status)の値をwhyに設定します。 デフォルトはresetです。そして登録されている-commandコールバックを呼び出します。

　

::https::wait token

ブロックをしながら、トランザクションの完了を待つ便利なプロシージャです。 vwaitを使用するので信用できるコードでのみ動作します。::http::geturlhttps:ong>が-commandオプションなしで呼ばれている場合は使えません。 この場合、待つものがないにもかかわらず、HTTPトランザクションが完了するまで::http::geturl

　

::https::data token

これは状態配列のbody要素(すなわち、URLデータ)を返す便利なプロシージャです。

　

::https::error token

これは状態配列の error要素を返す便利なプロシージャです。

　

::https::status token

これは状態配列のstatus要素を返す便利なプロシージャです。

　

::https::code token

これは状態配列のhttp要素返す便利なプロシージャです。

　

::https::ncode token

これは状態配列のhttp要素の数値的なリターンコード ( 200、404等 )を返す便利なプロシージャです。

　

::https::size token

状態配列の::hthttps:eturlコールにおけるURLから受け取られるバイトの数を表すcurrentsize要素を返す便利なプロ シージャです。

　

::https::cleanup token

本プロシージャは、token に識別された接続と関連していた状態をクリアします。 このコールの後で、::http:https:のようなプロシージャは操作に関する情報を得ることができません。 HTTPリクエストが終了した後で、この関数を呼ぶことを強く勧められます。 呼ばれなかった場合、メモリが解放されなくなるので、アプリが::http::geturl

　

::https::register proto port command

このプロシージャは、HTTPSのようなカストマイズHTTPトランスポートタイプを提供することを可能にします。 方法は、接頭辞とデフォルトポートを登録し、そしてTcl channelを作成するため実行するコマンドを登録します。

package require http
package require tls

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

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

::https::unregister proto

このプロシージャはhttp::rehttps:rによって以前に登録されたプロトコルハンドラの登録を解除します。

　

upvar #0 $token state

# Copy a URL to a file and print meta-data
proc ::https::copy { url file {chunk 4096} } {
    set out [open $file w]
    set token [geturl $url -channel $out -progress ::https::Progress \
    -blocksize $chunk]
    close $out
    # This ends the line started by https::Progress
    puts stderr ""
    upvar #0 $token state
    set max 0
    foreach {name value} $state(meta) {
    if {[string length $name] > $max} {
        set max [string length $name]
    }
    if {[regexp -nocase ^location$ $name]} {
        # Handle URL redirects
        puts stderr "Location:$value"
        return [copy [string trim $value] $file $chunk]
    }
    }
    incr max
    foreach {name value} $state(meta) {
    puts [format "%-*s %s" $max $name: $value]
    }

    return $token
}
proc ::https::Progress {args} {
    puts -nonewline stderr . ; flush stderr
}