argra****@users*****
argra****@users*****
2010年 7月 2日 (金) 03:41:17 JST
Index: docs/modules/libwww-perl-5.813/HTTP/Request/Common.pod diff -u /dev/null docs/modules/libwww-perl-5.813/HTTP/Request/Common.pod:1.1 --- /dev/null Fri Jul 2 03:41:17 2010 +++ docs/modules/libwww-perl-5.813/HTTP/Request/Common.pod Fri Jul 2 03:41:17 2010 @@ -0,0 +1,401 @@ + +=encoding euc-jp + +=head1 NAME + +=begin original + +HTTP::Request::Common - Construct common HTTP::Request objects + +=end original + +HTTP::Request::Common - 汎用のHTTP::Request オブジェクトの組み立て + +=head1 SYNOPSIS + + use HTTP::Request::Common; + $ua = LWP::UserAgent->new; + $ua->request(GET 'http://www.sn.no/'); + $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]); + +=head1 DESCRIPTION + +=begin original + +This module provide functions that return newly created C<HTTP::Request> +objects. These functions are usually more convenient to use than the +standard C<HTTP::Request> constructor for the most common requests. The +following functions are provided: + +=end original + +このモジュールは新しく作成された C<HTTP::Request> オブジェクトを +返す関数を提供します。 +これらの関数はこれらの一般的なリクエストのための標準の C<HTTP::Request> +コンストラクタよりも、通常より使いやすいものです。 +以下の関数が提供されます: + +=over 4 + +=item GET $url + +=item GET $url, Header => Value,... + +=begin original + +The GET() function returns an C<HTTP::Request> object initialized with +the "GET" method and the specified URL. It is roughly equivalent to the +following call + +=end original + +GET() 関数は GET メソッドと指定された URL で初期化された C<HTTP::Request> +オブジェクトを返します。 +それはおおざっぱには以下の呼び出しと同じです: + + HTTP::Request->new( + GET => $url, + HTTP::Headers->new(Header => Value,...), + ) + +=begin original + +but is less cluttered. What is different is that a header named +C<Content> will initialize the content part of the request instead of +setting a header field. Note that GET requests should normally not +have a content, so this hack makes more sense for the PUT() and POST() +functions described below. + +=end original + +しかし散らかりは少ないです。 +What is different is that a header named +C<Content> will initialize the content part of the request instead of +setting a header field. Note that GET requests should normally not +have a content, so this hack makes more sense for the PUT() and POST() +functions described below. +(TBT) + +=begin original + +The get(...) method of C<LWP::UserAgent> exists as a shortcut for +$ua->request(GET ...). + +=end original + + +=item HEAD $url + +=item HEAD $url, Header => Value,... + +=begin original + +Like GET() but the method in the request is "HEAD". + +=end original + +Like GET() but the method in the request is "HEAD". +(TBT) + +=begin original + +The head(...) method of "LWP::UserAgent" exists as a shortcut for +$ua->request(HEAD ...). + +=end original + +The head(...) method of "LWP::UserAgent" exists as a shortcut for +$ua->request(HEAD ...). +(TBT) + +=item PUT $url + +=item PUT $url, Header => Value,... + +=item PUT $url, Header => Value,..., Content => $content + +=begin original + +Like GET() but the method in the request is "PUT". + +=end original + +Like GET() but the method in the request is "PUT". +(TBT) + +=begin original + +The content of the request can be specified using the "Content" +pseudo-header. This steals a bit of the header field namespace as +there is no way to directly specify a header that is actually called +"Content". If you really need this you must update the request +returned in a separate statement. + +=end original + +The content of the request can be specified using the "Content" +pseudo-header. This steals a bit of the header field namespace as +there is no way to directly specify a header that is actually called +"Content". If you really need this you must update the request +returned in a separate statement. +(TBT) + +=item POST $url + +=item POST $url, Header => Value,... + +=item POST $url, $form_ref, Header => Value,... + +=item POST $url, Header => Value,..., Content => $form_ref + +=item POST $url, Header => Value,..., Content => $content + +=begin original + +This works mostly like PUT() with "POST" as the method, but this +function also takes a second optional array or hash reference +parameter $form_ref. As for PUT() the content can also be specified +directly using the "Content" pseudo-header, and you may also provide +the $form_ref this way. + +=end original + +これは "POST" をメソッドとしてほとんど PUT() のように機能します。 +しかしこの関数は 2 番目のオプションの配列またはハッシュリファレンスの +パラメータ $form_ref を取ります。 +As for PUT() the content can also be specified +directly using the "Content" pseudo-header, and you may also provide +the $form_ref this way. +(TBT) + +=begin original + +The $form_ref argument can be used to pass key/value pairs for the +form content. By default we will initialize a request using the +C<application/x-www-form-urlencoded> content type. This means that +you can emulate a HTML E<lt>form> POSTing like this: + +=end original + +$form_ref 引数はフォームコンテントのためのキー/値の組を渡すために +使うことが出来ます。 +デフォルトでは C<application/x-www-form-urlencoded> コンテントタイプを +使ってリクエストを初期化します。 +つまり以下のようにして HTML E<lt>form> POSTすることを +エミュレートできます： + + + POST 'http://www.perl.org/survey.cgi', + [ name => 'Gisle Aas', + email => 'gisle****@aas*****', + gender => 'M', + born => '1964', + perc => '3%', + ]; + +=begin original + +This will create a HTTP::Request object that looks like this: + +=end original + +これは以下のような HTTP::Request オブジェクトを作成します： + + POST http://www.perl.org/survey.cgi + Content-Length: 66 + Content-Type: application/x-www-form-urlencoded + + name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25 + +=begin original + +Multivalued form fields can be specified by either repeating the field +name or by passing the value as an array reference. + +=end original + +Multivalued form fields can be specified by either repeating the field +name or by passing the value as an array reference. +(TBT) + +=begin original + +The POST method also supports the C<multipart/form-data> content used +for I<Form-based File Upload> as specified in RFC 1867. You trigger +this content format by specifying a content type of C<'form-data'> as +one of the request headers. If one of the values in the $form_ref is +an array reference, then it is treated as a file part specification +with the following interpretation: + +=end original + +POST メソッドはRFC1867 で示された Form-based File Upload のために使われる +C<multipart/form-data> コンテントもサポートします。 +リクエストヘッダの一つとして C<'form-data'> のコンテントタイプを +指定することにより、このコンテントフォーマットを利用することが出来ます。 +もし $form_ref の中の値の1つが配列リファレンスであれば、それは以下の解釈で +ファイル部分の指定であるように扱われます: + + [ $file, $filename, Header => Value... ] + [ undef, $filename, Header => Value,..., Content => $content ] + +=begin original + +The first value in the array ($file) is the name of a file to open. +This file will be read and its content placed in the request. The +routine will croak if the file can't be opened. Use an C<undef> as +$file value if you want to specify the content directly with a +C<Content> header. The $filename is the filename to report in the +request. If this value is undefined, then the basename of the $file +will be used. You can specify an empty string as $filename if you +want to suppress sending the filename when you provide a $file value. + +=end original + +配列での先頭の値 ($file) はオープンするファイルの名前です。 +このファイルは読みこまれ、その内容がリクエストに入れられます。 +もしファイルをオープンできなければルーチンは croak します。 +コンテントを直接 C<Content> ヘッダで指定したければ $file の値を C<undef> に +してください。 +$filename はリクエストで報告されるファイル名です。 +この値が未定義であれば、$file の基本名が使われます。 +$file の値を提供したとき、ファイル名の送信をよくせいしたいなら、 +$filename に空文字列を指定することができます。 + +=begin original + +If a $file is provided by no C<Content-Type> header, then C<Content-Type> +and C<Content-Encoding> will be filled in automatically with the values +returned by LWP::MediaTypes::guess_media_type() + +=end original + +If a $file is provided by no C<Content-Type> header, then C<Content-Type> +and C<Content-Encoding> will be filled in automatically with the values +returned by LWP::MediaTypes::guess_media_type() +(TBT) + +=begin original + +Sending my F<~/.profile> to the survey used as example above can be +achieved by this: + +=end original + +上記の例として F<~/.profile> を survey に送信することが以下のようにして +実現できます: + + POST 'http://www.perl.org/survey.cgi', + Content_Type => 'form-data', + Content => [ name => 'Gisle Aas', + email => 'gisle****@aas*****', + gender => 'M', + born => '1964', + init => ["$ENV{HOME}/.profile"], + ] + +=begin original + +This will create a HTTP::Request object that almost looks this (the +boundary and the content of your F<~/.profile> is likely to be +different): + +=end original + +これはおおむね以下のような HTTP::Request オブジェクトを作成します +(バウンダリと F<~/.profile> の中身は違っていることでしょう): + + POST http://www.perl.org/survey.cgi + Content-Length: 388 + Content-Type: multipart/form-data; boundary="6G+f" + + --6G+f + Content-Disposition: form-data; name="name" + + Gisle Aas + --6G+f + Content-Disposition: form-data; name="email" + + gisle****@aas***** + --6G+f + Content-Disposition: form-data; name="gender" + + M + --6G+f + Content-Disposition: form-data; name="born" + + 1964 + --6G+f + Content-Disposition: form-data; name="init"; filename=".profile" + Content-Type: text/plain + + PATH=/local/perl/bin:$PATH + export PATH + + --6G+f-- + +=begin original + +If you set the $DYNAMIC_FILE_UPLOAD variable (exportable) to some TRUE +value, then you get back a request object with a subroutine closure as +the content attribute. This subroutine will read the content of any +files on demand and return it in suitable chunks. This allow you to +upload arbitrary big files without using lots of memory. You can even +upload infinite files like F</dev/audio> if you wish; however, if +the file is not a plain file, there will be no Content-Length header +defined for the request. Not all servers (or server +applications) like this. Also, if the file(s) change in size between +the time the Content-Length is calculated and the time that the last +chunk is delivered, the subroutine will C<Croak>. + +=end original + +(エクスポート可能な) $DYNAMIC_FILE 変数を TRUE に設定すると、content 属性として +サブルーチンクロージャでリクエストオブジェクトを取得します。 +このサブルーチンは命令のなかのすべてのファイルの内容を読みこみ、それを +適切なチャンクにいれて返します。 +これにより大量のメモリを使わずに任意の大きなファイルを +アップロードすることができます。 +お望みであれば F</dev/audio> のような無限大のファイルを +アップロードすることすら可能です; しかし、ファイルが普通のファイルでない場合、 +リクエストのために定義された Content-Length ヘッダがありません。 +すべてのサーバ(またはサーバアプリケーション)が +そのようであるというわけではありません。 +Also, if the file(s) change in size between +the time the Content-Length is calculated and the time that the last +chunk is delivered, the subroutine will C<Croak>. +(TBT) + +=begin original + +The post(...) method of "LWP::UserAgent" exists as a shortcut for +$ua->request(POST ...). + +=end original + +The post(...) method of "LWP::UserAgent" exists as a shortcut for +$ua->request(POST ...). +(TBT) + +=back + +=head1 SEE ALSO + +L<HTTP::Request>, L<LWP::UserAgent> + +=head1 COPYRIGHT + +Copyright 1997-2004, Gisle Aas + +This library is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + +=begin meta + +Translated: Hippo2000 <GCD00****@nifty*****> (5.48) +Updated: Kentaro SHIRAKATA <argra****@ub32*****> (5.813) + +=end meta + +=cut +
