http

ReferenceTOPKeywords

コマンド名

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

構文

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

解説

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

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

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

コマンド

::http::config ?options?
-accept mimetypes
-proxyhost hostname
-proxyport number
-proxyfilter command
-useragent string
::http::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
::http::formatQuery key value ?key 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::cleanup token
::http::register proto port command
::http::unregister proto
::http::config ?option ?
::http::configコマンドはHTTPリクエストに使われる代理サーバとポートの名前、そしてユーザー代理(User-Agent)名前の設定と取得に使用されます。 オプションが指定されないと、現在の構成は返されます。 単一の引数が指定されると、下で示されたフラグのうちの1つでなければなりません。 この場合、現在の設定値は返されます。 そうでない場合は、それらのオプションは構成を定義するフラグと値のセットでなければなりません。
-accept mimetypes
リクエストの受け取りヘッダーで、デフォルトは*/*です。ドキュメントの全てのタイプが受け入れられることを意味します。 他の場合は、受け取りたいコンマで区切られたMIMEタイプパターンのリストを提供することができます。 例えば、"image/gif, image/jpeg, text/*"。
 
-proxyhost hostname
存在するなら代理ホストの名前です。 この値が空文字列ならば、URLホストが直接にコンタクトされます。
 
-proxyport number
代理ポート番号です。
 
-proxyfilter command 
command は与えられたホストに対して、代理が要求されるか判定するために ::http::geturlの間に作成されるコールバックです。 呼び出し時に、1つの引数(即ちホスト名)がcommandに付け加えられます。 代理が要求される場合、コールバックは代理サーバーと代理ポートを含む2つの要素のリストを返さなければなりません。そうでなければ、フィルタは空文字を返さなければなりません。デフォルトのフィルタは-proxyhost-proxyportが設定した値(もしそれらが空なければ)を返します。
 
-useragent string
HTTPリクエストのUser-Agentヘッダの値で、デフォルトは"Tcl http client package 2.0."です。
 
::http::geturl url ?option?
::http::geturlコマンドはこのパッケージの主なプロシージャです。 -queryオプションはPOST操作を実行させ、-validateオプションはHEAD操作を実行させます。 他の場合、GET操作が実行されます。 ::http::geturlコマンドは、このトランザクションに関する情報を取得するのに使用できるtoken 値を返します。詳細はSTATE ARRAY(状態配列)ERRORS(エラー)セクショ ンを参照します。 ::http::geturlコマンドは-commandオプションで、HTTPトランザクションが完了したときに呼び出されるコールバックを指定しないと、操作が完了するまでブロックを行います。 ::http::geturlはいくつかのオプションがあります。
 
-binary boolean
URLデータをバイナリと解釈することを強制するかどうかを指定します。通常、これは自動的に検出されます。 text コンテンツ型で始まらないもの、またはそのコンテンツエンコーディングがgzipcompressかであるものはバイナリデータと考えられます。
 
-blocksize size
URLを読み込むときに使用するブロックサイズです。 一度に最大でsizeバイト読み込みます。 各ブロックの後で、-progressコールバックの呼び出しが行われます。
 
-channel name
URLコンテンツをstate(body)に保存する代わりにチャンネルnameにコピーします。
 
-command callback
HTTPトランザクションが完了したときにcallback を呼び出します。このオプションは::http::geturlを直ちに制御を戻します。callback ::http::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::geturlから返された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 引数はキーと値が交互にある偶数の要素のリストでなければなりません。 キーはヘッダーのフィールド名になります。 ヘッダが破壊されないように、改行は値から取り除かれます。例えば、keyvaluelistPragma no-cacheなら、以下のヘッダーがHTTPリクエストに含まれます。
Pragma: no-cache
-progress callback
URLからの各データ転送の後でcallback が行われます。 callback は3つの追加的引数を受け取ります。 ::http::geturlからのtokenContent-Lengthメタデー タの内容の予想総サイズ、及び現在の転送されたバイ ト数です。予想総サイズは分からない場合は、コールバックに0が渡されます。 以下がコールバックのテンプレートです。
proc httpProgress {token total current} {
    upvar #0 $token state
}
-query query
このフラグは::http::geturlにPOSTリクエストを実行させます。 これでサーバーにquery を渡します。 query はx-url- encodingでフォーマットされたクエリーでなければなりません。 ::http::formatQuery プロシージャがこのフォーマットを作成するために使用できます。
 
-queryblocksize size
クエリーデータをURLにポストしているとき使用したブロックサイズです。一度に最大size バイトは書かれます。各ブロックの後で ( そのオプションが指定されるならば ) 、-queryprogressコールバックへの呼び出しは実行されます。
 
-querychannel channelID
このフラグは::http::geturlにPOSTリクエストを実行させます。 これでサーバへchannelID に含まれるデータを渡します。 下の-typeオプションが使われない限り、channelIDに含まれるデータはx-url-encodingにフォーマットされたクエリーでなければなりません。 Content-Lengthヘッダーが-headersオプションによって指定されないと、::http::geturlはそのヘッダーを作成するために、ポストデータのサイズを判断しようと試みます。 サイズを決定することができないとエラーを返します。
 
-queryprogress callback
URLからの各データ転送の後(即ちPOST)でcallback が行われ、-progressオプションと同様に動きます(コールバックのフォーマットが同じです)。
 
-timeout milliseconds
milliseconds が0でなければ、::http::geturlはタイムアウトを指定されたミリ秒後に起こるよう設定します。 指定されていれば、タイムアウトは::http::reset-commandコーバックの呼び出しを実行します。 ::http::status の戻り値はタイムアウトが起こっ た後ではtimeoutとなります。
 
-type mime-type
POST操作の間のデフォルト値 (application/x-www-form-urlencoded) の代わりにContent-Type値としてmime-type を使用します。
 
-validate boolean
boolean が0でなければ、::http::geturlはHTTPのHEADリクエストを行います。 このリクエストはURLに関するメタ情報を返しますが、その内容は返されません。 メタ情報はトランザクションの後にstate(meta) 変数の中に入れられます。詳細はSTATE ARRAYセクションを参照します。
 
::http::formatQuery key value ?key value ...?
本プロシージャはクエリーデータのx-url-encoding変換を行います。これはクエリーのキーと値の偶数の引数を受け取ります。 これはキーと値をエンコードし、そして適切な&と=の区切り記号を持つ1つの文字列を生成します。 その結果は::http::geturlに渡される-queryの値に適します。
 
::http::reset token ?why ?
このコマンドはtoken に識別されたHTTPトランザクション(もしあれば)をリセットします。 state(status)の値をwhyに設定します。 デフォルトはresetです。そして登録されている-commandコールバックを呼び出します。
 
::http::wait token
ブロックをしながら、トランザクションの完了を待つ便利なプロシージャです。 vwaitを使用するので信用できるコードでのみ動作します。::http::geturl-commandオプションなしで呼ばれている場合は使えません。 この場合、待つものがないにもかかわらず、HTTPトランザクションが完了するまで::http::geturlコールが戻りません。
 
::http::data token
これは状態配列のbody要素(すなわち、URLデータ)を返す便利なプロシージャです。
 
::http::error token
これは状態配列の error要素を返す便利なプロシージャです。
 
::http::status token
これは状態配列のstatus要素を返す便利なプロシージャです。
 
::http::code token
これは状態配列のhttp要素返す便利なプロシージャです。
 
::http::ncode token
これは状態配列のhttp要素の数値的なリターンコード ( 200、404等 )を返す便利なプロシージャです。
 
::http::size token
状態配列の::http::geturlコールにおけるURLから受け取られるバイトの数を表すcurrentsize要素を返す便利なプロ シージャです。
 
::http::cleanup token
本プロシージャは、token に識別された接続と関連していた状態をクリアします。 このコールの後で、::http::dataのようなプロシージャは操作に関する情報を得ることができません。 HTTPリクエストが終了した後で、この関数を呼ぶことを強く勧められます。 呼ばれなかった場合、メモリが解放されなくなるので、アプリが::http::geturlを繰り返し呼び出す場合、メモリ漏洩、パフォーマンスヒット、あるいはもっと悪い状況をもたらします。
 
::http::register proto port command
このプロシージャは、HTTPSのようなカストマイズHTTPトランスポートタイプを提供することを可能にします。 方法は、接頭辞とデフォルトポートを登録し、そしてTcl channelを作成するため実行するコマンドを登録します。
package require http
package require tls

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

set token [http::geturl https://my.secure.site/]
::http::unregister proto
このプロシージャはhttp::registerによって以前に登録されたプロトコルハンドラの登録を解除します。
 

エラー

::http::geturlプロシージャは次の場合にエラーを上げます。 無効のコマンドラインオプション、無効のURL、実際存在しないホスト上のURL、または現存するホスト上の不良ポート上のURLなどです。 これらのエラーは、ネットワークトランザクションを始動させることができないことを意味します。 HTTPリクエストヘッダーを書き込む間にI/Oエラーを得る場合もエラーを上げます。 同期::http::geturlの呼び出し (-commandが指定されない場合)に対して、HTTP応答ヘッダーやデータを読み込む間にI/Oエラーを得る場合もエラーを上げます。これらの場合には::http::geturlはトークンを生まないので、必要とされた全てのクリーンアップをしてくれますので、アプリで::http::cleanupを呼ぶ必要はありません。

非同期::http::geturの呼び出しに対して、HTTP応答ヘッダーやデータを読み込む間のあらゆるエラーには例外が投げかけられないということを除けば、前述のエラー状況の全ては適用されます。 これはHTTPヘッダーを書いた後で::http::geturlが戻り、そしてHTTPトランザクションの残りがバックグラウンドで動作するからです。 コマンドコールバックは状態をチェックする::http::statusを呼び出すことによって、エラーが読み込む間に発生したかどうかをチェックすることができます。 そして、エラーメッセージを得る::http::errorを呼び出すことによって、そのエラーをチェックできます。

代りに、メインプログラムフローが非同期HTTPリクエストの結果を知る必要があるポイントに達すると、コールバックのように、::http::waitを呼び出して状態とエラーをチェックすることができます。

いずれにせよ、操作が完了するときに、状態配列を削除するためにまだhttp::cleanupを呼ばなければなりません。

HTTPトランザクションの可能な結果が他にもあります。 http::statusから状態を検査することによって生み出されたものです。 以下で示されます。

ok
eof
error
ok
HTTPトランザクションが完全に完成すれば状態は ok です。しかし、HTTP状態を得るためにhttp::code値をまだチェックすべきです。 http::ncodeプロシージャは単に数値エラー (例えば、200、404 又は500 ) を提供します。一方、http::codeプロシージャが”HTTP 404 File not found”のような値を返します。
 
eof
サーバが返答せずにソケットを閉じる場合、エラーは上げられません。 しかし、トランザクションの状態はeofです。
 
error
エラーメッセージは::http::errorによってアクセス可能な error状態配列要素に格納されます。
 

もう1つの可能なエラーは、http::geturlが、サーバが応答しソケットを閉じる前に、ポストクエリーデータを全てサーバに書き込むことができない場合です。 エラーメッセージはposterror状態配列要素に保存された後、http::geturlはトランザクションを完了しようと試みます。 サーバの応答を読むことができれば、ok状態で終わります。そうでないと、 eof状態で終わります。

状態配列

::http::geturlプロシージャはTcl配列の形でHTTPトランザクションの状態を取得するために使われ得るtoken を返します。以下の構造は使い易い配列変数を作成するために使います。

upvar #0 $token state

いったんURLと関連していたデータが、もう必要とされない場合、メモリを解放するために、状態配列をアンセットすべきです。 http::cleanupプロシージャはこのために提供されます。以下の配列の要素がサポートされています。

body
charset
coding
currentsize
error
http
meta
Content-Type
Content-Length
Location
posterror
status
totalsize
type
url
body
URLの内容。-channelオプションが指定されたら、これは空です。この値は::http::dataコマンドによって返されます。
 
charset
Content-Typeメタデータ値からの文字コード表属性の値。何も指定されなかったら、デフォルトはRFCの標準のiso8859-1$::http::defaultCharsetの値です。 受け取るテキストデータはこの文字コード表からutf-8に自動的に変換されます。
 
coding
Content-Encodingメタデータ値のコピー。
 
currentsize
URLから取って来た現在のバイト数。この値は::http::sizeコマンドによって返されます。
 
error
定義されると、HTTPトランザクションが失敗したときに見られるエラー文字列。
 
http
サーバから返信されたHTTP状態。この値は::http::codeコマンドに返されます。 この値のフォーマットは以下です。
HTTP/1.0 code string

code はHTTP標準で定義されている3桁の数字です。  コード200 はOK、4か5から始まっているコードはエラーを表わす。 3で始まっているコードはリダイレクションエラーです。この場合はLocationメタデータは要求された情報を含んでいる新しいURLを指定します。

meta
HTTPプロトコルはURL内容を記述するメタデー タを返します。 状態配列のmeta要素はメタデータのキーと値のリストです。 これはメタデータのみを含む配列を初期化するのに便利なフォーマットになっています。
array set meta $state(meta)

いくつかのメタデータのキーは以下にリストされます。 これ以外にもHTTP標準は定義されてています。またサーバーは独自のものを自由に追加できます。

Content-Type
URL内容のタイプ。例、 text/html, image/gif, application/postscript and application/x-tcl。
 
Content-Length
内容の公表されているサイズです。 ::http::geturl で取得される実際のサイズは state(size)にあり、利用できます。
 
Location
要求されたデータを含むのURL。
posterror
存在すれば、ポストクエリーデータをサーバに書き込んでいる間に発生したエラーです。
 
status
成功に完了したときはok、ユーザーにリセットされたときはreset、トランザクションの前にタイムアウトが発生したときはtimeout、エラーerror状態のいずれかです。トランザクションの最中はこの値は空文字列です。
 
totalsize
Content-Lengthメタデータ値のコピー。
 
type
Content-Typeメタデータ値のコピー。
 
url
要求されたURL。
 

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

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

参照

safe, socket, safesock

キーワード

security policy, socket


Copyright © 1995-1997 Sun Microsystems, Inc. Copyright © 1998-2000 by Ajuba Solutions. Copyright © 1995-1997 Roger E. Critchlow Jr.