536 lines
12 KiB
HTML
536 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of HTTP::Request::Common</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>HTTP::Request::Common</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2020-02-29<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
HTTP::Request::Common - Construct common HTTP::Request objects
|
|
<A NAME="lbAC"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
version 6.22
|
|
<A NAME="lbAD"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use HTTP::Request::Common;
|
|
$ua = LWP::UserAgent->new;
|
|
$ua->request(GET '<A HREF="http://www.sn.no/');">http://www.sn.no/');</A>
|
|
$ua->request(POST '<A HREF="http://somewhere/foo',">http://somewhere/foo',</A> [foo => bar, bar => foo]);
|
|
$ua->request(PATCH '<A HREF="http://somewhere/foo',">http://somewhere/foo',</A> [foo => bar, bar => foo]);
|
|
$ua->request(PUT '<A HREF="http://somewhere/foo',">http://somewhere/foo',</A> [foo => bar, bar => foo]);
|
|
$ua->request(OPTIONS '<A HREF="http://somewhere/foo',">http://somewhere/foo',</A> [foo => bar, bar => foo]);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This module provides functions that return newly created <TT>"HTTP::Request"</TT>
|
|
objects. These functions are usually more convenient to use than the
|
|
standard <TT>"HTTP::Request"</TT> constructor for the most common requests.
|
|
<P>
|
|
|
|
Note that LWP::UserAgent has several convenience methods, including
|
|
<TT>"get"</TT>, <TT>"head"</TT>, <TT>"delete"</TT>, <TT>"post"</TT> and <TT>"put"</TT>.
|
|
<P>
|
|
|
|
The following functions are provided:
|
|
<DL COMPACT>
|
|
<DT id="1"><FONT SIZE="-1">GET</FONT> $url<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="2"><FONT SIZE="-1">GET</FONT> $url, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
|
|
The <TT>"GET"</TT> function returns an HTTP::Request object initialized with
|
|
the ``<FONT SIZE="-1">GET''</FONT> method and the specified <FONT SIZE="-1">URL.</FONT> It is roughly equivalent to the
|
|
following call
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
HTTP::Request->new(
|
|
GET => $url,
|
|
HTTP::Headers->new(Header => Value,...),
|
|
)
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
but is less cluttered. What is different is that a header named
|
|
<TT>"Content"</TT> will initialize the content part of the request instead of
|
|
setting a header field. Note that <FONT SIZE="-1">GET</FONT> requests should normally not
|
|
have a content, so this hack makes more sense for the <TT>"PUT"</TT>, <TT>"PATCH"</TT>
|
|
<BR> and <TT>"POST"</TT> functions described below.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"get(...)"</TT> method of LWP::UserAgent exists as a shortcut for
|
|
<TT>"$ua->request(GET ...)"</TT>.
|
|
<DT id="3"><FONT SIZE="-1">HEAD</FONT> $url<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="4"><FONT SIZE="-1">HEAD</FONT> $url, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Like <FONT SIZE="-1"><B>GET</B></FONT><B>()</B> but the method in the request is ``<FONT SIZE="-1">HEAD''.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"head(...)"</TT> method of LWP::UserAgent exists as a shortcut for
|
|
<TT>"$ua->request(HEAD ...)"</TT>.
|
|
<DT id="5"><FONT SIZE="-1">DELETE</FONT> $url<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="6"><FONT SIZE="-1">DELETE</FONT> $url, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Like <TT>"GET"</TT> but the method in the request is <TT>"DELETE"</TT>. This function
|
|
is not exported by default.
|
|
<DT id="7"><FONT SIZE="-1">PATCH</FONT> $url<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="8"><FONT SIZE="-1">PATCH</FONT> $url, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="9"><FONT SIZE="-1">PATCH</FONT> $url, $form_ref, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="10"><FONT SIZE="-1">PATCH</FONT> $url, Header => Value,..., Content => $form_ref<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="11"><FONT SIZE="-1">PATCH</FONT> $url, Header => Value,..., Content => $content<DD>
|
|
|
|
|
|
|
|
|
|
|
|
The same as <TT>"POST"</TT> below, but the method in the request is <TT>"PATCH"</TT>.
|
|
<DT id="12"><FONT SIZE="-1">PUT</FONT> $url<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="13"><FONT SIZE="-1">PUT</FONT> $url, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="14"><FONT SIZE="-1">PUT</FONT> $url, $form_ref, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="15"><FONT SIZE="-1">PUT</FONT> $url, Header => Value,..., Content => $form_ref<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="16"><FONT SIZE="-1">PUT</FONT> $url, Header => Value,..., Content => $content<DD>
|
|
|
|
|
|
|
|
|
|
|
|
The same as <TT>"POST"</TT> below, but the method in the request is <TT>"PUT"</TT>
|
|
<DT id="17"><FONT SIZE="-1">OPTIONS</FONT> $url<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="18"><FONT SIZE="-1">OPTIONS</FONT> $url, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="19"><FONT SIZE="-1">OPTIONS</FONT> $url, $form_ref, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="20"><FONT SIZE="-1">OPTIONS</FONT> $url, Header => Value,..., Content => $form_ref<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="21"><FONT SIZE="-1">OPTIONS</FONT> $url, Header => Value,..., Content => $content<DD>
|
|
|
|
|
|
|
|
|
|
|
|
The same as <TT>"POST"</TT> below, but the method in the request is <TT>"OPTIONS"</TT>
|
|
<DT id="22"><FONT SIZE="-1">POST</FONT> $url<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="23"><FONT SIZE="-1">POST</FONT> $url, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="24"><FONT SIZE="-1">POST</FONT> $url, $form_ref, Header => Value,...<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="25"><FONT SIZE="-1">POST</FONT> $url, Header => Value,..., Content => $form_ref<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="26"><FONT SIZE="-1">POST</FONT> $url, Header => Value,..., Content => $content<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<TT>"POST"</TT>, <TT>"PATCH"</TT> and <TT>"PUT"</TT> all work with the same parameters.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
%data = ( title => 'something', body => something else' );
|
|
$ua = LWP::UserAgent->new();
|
|
$request = HTTP::Request::Common::POST( $url, [ %data ] );
|
|
$response = $ua->request($request);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
They take a second optional array or hash reference
|
|
parameter <TT>$form_ref</TT>. The content can also be specified
|
|
directly using the <TT>"Content"</TT> pseudo-header, and you may also provide
|
|
the <TT>$form_ref</TT> this way.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"Content"</TT> pseudo-header 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>$form_ref</TT> argument can be used to pass key/value pairs for the
|
|
form content. By default we will initialize a request using the
|
|
<TT>"application/x-www-form-urlencoded"</TT> content type. This means that
|
|
you can emulate an <FONT SIZE="-1">HTML</FONT> <form> POSTing like this:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
POST '<A HREF="http://www.perl.org/survey.cgi',">http://www.perl.org/survey.cgi',</A>
|
|
[ name => 'Gisle Aas',
|
|
email => '<A HREF="mailto:gisle@aas.no">gisle@aas.no</A>',
|
|
gender => 'M',
|
|
born => '1964',
|
|
perc => '3%',
|
|
];
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This will create an HTTP::Request object that looks like this:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
POST <A HREF="http://www.perl.org/survey.cgi">http://www.perl.org/survey.cgi</A>
|
|
Content-Length: 66
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Multivalued form fields can be specified by either repeating the field
|
|
name or by passing the value as an array reference.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <FONT SIZE="-1">POST</FONT> method also supports the <TT>"multipart/form-data"</TT> content used
|
|
for <I>Form-based File Upload</I> as specified in <FONT SIZE="-1">RFC 1867.</FONT> You trigger
|
|
this content format by specifying a content type of <TT>'form-data'</TT> as
|
|
one of the request headers. If one of the values in the <TT>$form_ref</TT> is
|
|
an array reference, then it is treated as a file part specification
|
|
with the following interpretation:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
[ $file, $filename, Header => Value... ]
|
|
[ undef, $filename, Header => Value,..., Content => $content ]
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"undef"</TT> as
|
|
<TT>$file</TT> value if you want to specify the content directly with a
|
|
<TT>"Content"</TT> header. The <TT>$filename</TT> is the filename to report in the
|
|
request. If this value is undefined, then the basename of the <TT>$file</TT>
|
|
will be used. You can specify an empty string as <TT>$filename</TT> if you
|
|
want to suppress sending the filename when you provide a <TT>$file</TT> value.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If a <TT>$file</TT> is provided by no <TT>"Content-Type"</TT> header, then <TT>"Content-Type"</TT>
|
|
and <TT>"Content-Encoding"</TT> will be filled in automatically with the values
|
|
returned by <TT>"LWP::MediaTypes::guess_media_type()"</TT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Sending my <I>~/.profile</I> to the survey used as example above can be
|
|
achieved by this:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
POST '<A HREF="http://www.perl.org/survey.cgi',">http://www.perl.org/survey.cgi',</A>
|
|
Content_Type => 'form-data',
|
|
Content => [ name => 'Gisle Aas',
|
|
email => '<A HREF="mailto:gisle@aas.no">gisle@aas.no</A>',
|
|
gender => 'M',
|
|
born => '1964',
|
|
init => ["$ENV{HOME}/.profile"],
|
|
]
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This will create an HTTP::Request object that almost looks this (the
|
|
boundary and the content of your <I>~/.profile</I> is likely to be
|
|
different):
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
POST <A HREF="http://www.perl.org/survey.cgi">http://www.perl.org/survey.cgi</A>
|
|
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"
|
|
|
|
<A HREF="mailto:gisle@aas.no">gisle@aas.no</A>
|
|
--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--
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you set the <TT>$DYNAMIC_FILE_UPLOAD</TT> variable (exportable) to some <FONT SIZE="-1">TRUE</FONT>
|
|
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 <I>/dev/audio</I> if you wish; however, if
|
|
the file is not a plain file, there will be no <TT>"Content-Length"</TT> 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 <TT>"Content-Length"</TT> is calculated and the time that the last
|
|
chunk is delivered, the subroutine will <TT>"Croak"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"post(...)"</TT> method of LWP::UserAgent exists as a shortcut for
|
|
<TT>"$ua->request(POST ...)"</TT>.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
HTTP::Request, LWP::UserAgent
|
|
<P>
|
|
|
|
Also, there are some examples in ``<FONT SIZE="-1">EXAMPLES''</FONT> in HTTP::Request that you might
|
|
find useful. For example, batch requests are explained there.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gisle Aas <<A HREF="mailto:gisle@activestate.com">gisle@activestate.com</A>>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
This software is copyright (c) 1994-2017 by Gisle Aas.
|
|
<P>
|
|
|
|
This is free software; you can redistribute it and/or modify it under
|
|
the same terms as the Perl 5 programming language system itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="27"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="28"><A HREF="#lbAC">VERSION</A><DD>
|
|
<DT id="29"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="30"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="31"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
<DT id="32"><A HREF="#lbAG">AUTHOR</A><DD>
|
|
<DT id="33"><A HREF="#lbAH">COPYRIGHT AND LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|