| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
rfc.http - HTTP このモジュールは、RFC2616 "Hypertext Transfer Protocol – HTTP/1.1" で定義されているHTTP/1.1に対する簡単なクライアントAPIを提供します。 (RFC2616).
現在のAPIは、プロトコルの一部のみ実装されています。 HTTP/1.0のサーバーとはうまく通信できません。 また、HTTP/1.1の先進的機能、例えば永続的接続などはサポートしていません。 これらの機能は、将来のバージョンで追加されるでしょう。
サーバから接続が切られた場合や、サーバの返したHTTPレスポンスのフォーマットが
正しくない場合に投げられるコンディションです。<error>を継承します。
serverに、それぞれHTTPのGET、HEAD、POST、PUT、DELETEリクエストを送り、 サーバの応答を返します。
サーバが "3xx" のリダイレクトを指示する応答を返した場合、これらの手続きは デフォルトで、応答のメッセージヘッダの "location" で返されるURIに従うよう 試みます。リダイレクションを抑制するには、下の"キーワード引数"を参照してください。
必須の引数:
server引数では、文字列でHTTPサーバ名を指定します。
サーバ名は、オプションでコロンに続いてポート番号を付加できます。
Examples: "w3c.org", "mycompany.com:8080".
request-uri引数は文字列かリストです。 文字列の場合、RFC2616で規定されているリクエストURIと解釈されます。 通常これはHTTP URLのパス部分です。 文字列はそのままサーバに渡されるので、呼び出し側で必要な 文字コード変換やurlエンコーディングを行う必要があります。
request-uriがリストの場合は、次の形式でなければなりません。
(path (name value) ...) |
ここでpathはリクエストURIのパスコンポーネントまでを指定する
文字列です。与えられたnameとvalueのalistから、
httpリクエスト手続きはHTML4で定められた
application/x-www-form-urlencoded形式の
クエリ文字列を構成し、pathにアペンドします。
例えば次のふたつのリクエストは同じ効果を持ちます。
二番目の呼び出しではurlエスケープが自動的に行われることに注目してください。
(http-get "example.com" "/search?q=foo%20bar&n=20")
(http-get "example.com" '("/search" (q "foo bar") (n 20)))
|
request-encodingキーワード引数が与えられた場合、 nameとvalueはまずその文字エンコーディングに変換されたのちに urlエスケープされます。そうでない場合はgaucheの内部 エンコーディングがそのまま使われます。
いくつかの手続きは、リクエストメッセージのボディを指定するbodyを第3引数として
取ります。bodyは文字列かリストで、文字列の場合はそのまま送られ、
リストの場合はmultipart/form-data形式にエンコードされて送られます。
bodyがリストの場合、それはパラメータ指定のリストです。
各パラメータ指定は、("submit" "OK")のような名前と値のリスト、
もしくは("upload" :file "logo.png" :content-type "image/png")
のように名前の後にキーワード-値リストを付加したものです。
最初の形式は使うのが簡単で、またrequest-uriのクエリパラメータリストと
同じ形式なのでGETとPOSTでルーチンを共有したい場合にも便利でしょう。
この形式では、各値はMIMEパーとにtext/plainとして置かれます。
文字コードは下に述べるrequest-encodingキーワード引数により変換されます。
二番目の形式では、MIMEパートの属性についてより細かな指定を行うことができます。 以下のキーワードが特別に扱われます。
:valueパラメータの値を指定します。簡潔な(name val)形式は
(name :value val)の省略形です。
:file指定された名前のファイルの中身をパラメータの値として挿入します。
ファイルのアップロードに便利です。このオプションは:valueより
優先されます。MIMEタイプは、指定が無ければ
application/octet-streamとなります。
:content-typeMIMEタイプをオーバライドします。与えられた値にcharsetパラメータが ついていない場合は自動的に付加されます。
:content-transfer-encodingcontent-transfer-encodingを
7bit、binary、quoted-printable、base64の
いずれかで指定します。指定が無ければbinaryが使われます。
残りのキーワードはMIMEパートのヘッダにそのまま使われます。
戻り値: 全ての手続きは3つの値を返します。
1つ目は、RFC2616で定義されているステータスコードの文字列値(例えば、成功時の 200、"Not found"の404など)です。
2つ目は、パーズされたヘッダのリストで、リストの要素は(header-name
value …)です。header-nameはヘッダの文字列名(例えば、
"content-type"や"location"など)で、valueは対応する値の文字列値です。
ヘッダ名は小文字に変換されます。値は、RFC2822で定義されている無指定行区切
(ソフト・ライン・ブレイク)が除かれる以外はそのままです。
サーバが同じ名前のヘッダを1つ以上返した場合は、
1つのリストに統合されます。それ以外では、2つ目の戻り値に
おけるヘッダのリストの順番は、サーバの応答での順番と同じです。
3つ目の戻り値は、サーバの応答におけるメッセージボディです。
デフォルトでは、文字列で表現されたメッセージボディそのものです。
サーバの応答がボディを持たない場合、3つ目の戻り値は#fです。
キーワード引数によって、メッセージボディがどのように扱われるかを制御できます。
例えば、中間的な文字列を作らずに、返されたメッセージボディを直接ファイルに
格納することが出来ます。詳細は以下で説明しています。
キーワード引数:
デフォルトで、これらの手続きはリクエストメッセージに"Host"ヘッダ・フィールドを
追加するだけです。他のヘッダ・フィールドを追加するためにキーワード引数を
与えることができます。
(http-get "foo.bar.com" "/index.html" :accept-language "ja" :user-agent "My Scheme Program/1.0") |
以下のキーワード引数は手続きによって解釈され、リクエストヘッダには現れません。
request-uriやbodyがリストで与えられた場合、パラメータの
名前や値はまずこの引数で指定される文字エンコーディングへと変換され、
その後、application/x-www-form-urlencodedや
multipart/form-data MIME形式にしたがったエンコーディングが行われます。
この引数が省略された場合はGaucheの内部文字エンコーディングが使われます。
multipart/form-dataについては、パラメータにcontent-typeヘッダを
与えることでパラメータごとに文字エンコーディングの設定をオーバライドできます。
詳しくは上のbody引数の説明を参照してください。
request-uriやbodyに文字列を与えた場合は、文字エンコーディング変換は 行われません。呼び出し側で望みの文字コードにあらかじめ変換しておいてください。
httpプロキシサーバを、hostnameまたはhostname:port形式の
文字列で指定します。
真の値が与えられた場合、リダイレクションには従わなくなります。すなわち、 手続きは"3xx"のメッセージをそのまま返します。
これらのキーワード引数によりリプライメッセージ・ボディがどのように扱われるかを カスタマイズできます。sinkには出力ポートを、flusherには2引数を 取る手続きを渡さなければなりません。
手続きがメッセージ・ボディを受信し始めると、sinkへ受け取った データ片をフィードします。手続きがメッセージ・ボディを受信し終わると、 flusherに与えられた手続きが、sinkと(手続きからの2つ目の 戻り値と同じフォーマットの)メッセージ・ヘッダ・フィールドのリストとともに 呼び出されます。flusherの戻り値が、手続きからの3つ目の戻り値と なります。
したがって、sinkのデフォルト値は、新しく開かれた文字列ポートで、
flusherのデフォルト値は(lambda (sink headers) (get-output-string sink))
とも言えます。
以下のサンプルは、(とても大きい可能性のある)文字列バッファを作らずに、 メッセージ・ボディを直接ファイルに保存します。
(call-with-output-file "page.html"
(lambda (out)
(http-get "www.schemers.org" "/"
:sink out :flusher (lambda _ #t))))
|
The module also provides some utility procedures.
user-agentヘッダに渡される値のデフォルト値を指定するパラメータです。
デフォルトの値はgauche.http/* (*部分はGaucheのバージョン)
になっています。
各アプリケーションは適切な値を設定するようにしてください。
A helper procedure to create a request-uri from a list of query parameters. Encoding specifies the character encodings to be used.
(http-compose-query "/search" '((q "$foo") (n 20))) ⇒ "/search?q=%24foo&n=20" |
A helper procedure to create multipart/form-data
from a list of parameters. The format of params argument
is the same as the list format of body argument of
http request procedures. The result is written to an output
port port, and the boundary string used to compose
MIME message is returned. Alternatively you can pass #f
to the port to get the result in a string.
In that case, two values are returned, the MIME message string
and the boundary string.
Encoding specifies the character encodings to be used.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated by Shiro Kawai on November, 22 2009 using texi2html 1.78.