#include "_doctype.html"
FILE *
handles (GLOBS)
WWW::Curl::easy - Perl extension interface for libcurl
use WWW::Curl::easy;
my $curl = WWW::Curl::easy::new(); # an alias for WWW::Curl::easy::init my $code = $curl->setopt(CURLOPT_option, ....); $code = $curl->perform($curl); my $err = $curl->errbuf; # report any error message my $info = $curl->getinfo(CURLINFO_option);
$curl->cleanup(); # optional
WWW::Curl::easy::global_cleanup(); # optional cleanup at exit
Read the curl man pages, curl_easy_setopt(3)
and curl_easy_getinfo(3)
for details of CURLOPT_option and CURLINFO_option values.
B<WWW::Curl::easy> provides an interface to the libcurl C library. See http://curl.haxx.se/ for more information on cURL and libcurl.
From v1.30, this interface supports the perl OO style of creating $curl handles, and calling methods to get and set curl parameters. Previous versions of this interface only supported the straight 'subroutine' call style of accessing curl. Scripts using the older style are still compatible (but see COMPATABILITY, below), but this documentation and the test scripts have been updated to the OO style.
WWW::Curl::easy supports the various options of curl_easy_setopt which require either a FILE * or a callback (subroutine) reference.
Callback to perl subroutines are handled by this XS interface through a wrapper which takes care of converting from C to perl variables and back again. This wrapper also simplifies some 'C' style arguments to make them behave in a more 'perl' like manner. In particular, the read and write callbacks do not look just like the 'fread' and 'fwrite' C functions - perl variables do not need separate length parameters, and perl functions can return a list of variables, instead of needing a pointer to modify. The details are described below.
FILE *
handles (GLOBS)Curl options which take a C<FILE *>, such as C<CURLOPT_FILE>, C<CURLOPT_WRITEHEADER>, C<CURLOPT_INFILE> can be passed a perl file handle:
open BODY,">body.out"; $code = $curl->setopt(CURLOPT_FILE, *BODY);
The CUROPT_WRITEFUNCTION
option may be set which will cause libcurl to call back to
the referenced perl subroutine:
sub chunk { my ($data,$pointer)=@_; ...do something...; return length($data) }
# call the above routine from curl: $code = $curl->setopt(CURLOPT_WRITEFUNCTION, \&chunk ); $code = $curl->setopt(CURLOPT_FILE, \$variable ); $curl->perform();
The subroutine will be passed whatever is defined by CURLOPT_FILE
. This can be
a reference to a regular variable (as above), or a glob or anything else you like.
The callback function must return the number of bytes 'handled' ( length($data)
) or
the transfer will abort. A transfer can be aborted by returning a value of 0, for example.
The option CURLOPT_WRITEHEADER
can be set to pass a different $pointer
into the
CURLOPT_WRITEFUNCTION for header values. This lets you collect the headers and body separately, as
shown in the example below:
use WWW::Curl::easy; my $headers=""; my $body=""; sub chunk { my ($data,$pointer)=@_; ${$pointer}.=$data; return length($data) }
my $curl=WWW::Curl::easy->new my $code = $curl->setopt(CURLOPT_WRITEFUNCTION, \&chunk ); $code = $curl->setopt(CURLOPT_WRITEHEADER, \$headers ); $code = $curl->setopt(CURLOPT_FILE, \$body ); $curl->perform(); print $body;
If you have libcurl > 7.7.1, then you could instead set CURLOPT_HEADERFUNCTION
to a different
callback, and have the header collected that way.
WWW::Curl::easy supports CURLOPT_READFUNCTION
. This function should follow this prototype:
sub read_callback { my ($maxlength,$pointer)=@_; .... return $data; }
The subroutine must return an empty string ``'' at the end of the data. Note that this function isn't told how much data to provide - $maxlength is just the maximum size of the buffer provided by libcurl. If you are doing an HTTP POST or PUT for example, it is important that this function only returns (in total) as much data as the 'Content-Length' header specifies, followed by a an empty (0 length) buffer.
WWW::Curl::easy supports CURLOPT_PROGRESSFUNCTION
. This function should follow this prototype:
sub progress_callback { my ($clientp,$dltotal,$dlnow,$ultotal,$ulnow)=@_; .... return 0; }
The function should return 0 normally, or -1 which will abort/cancel the
transfer. $clientp
is whatever is set using the CURLOPT_PROGRESSDATA
option.
WWW::Curl::easy supports CURLOPT_PASSWDFUNCTION
. This function should look something like this:
sub passwd_callback { my ($clientp,$prompt,$buflen)=@_; ... return (0,$data); }
$clientp
is whatever scalar is set using the CURLOPT_PASSWDDATA
option.
$prompt
is a text string which can be used to prompt for a password.
$buflen
is the maximum length of the accepted password reply.
The function must return 0 (for 'OK') and the password data as a list. Return (-1,``'') to indicate an error.
You can use set the option CURLOPT_STDERR
to an alternate file handle glob
to redirect stderr messages from libcurl, if your libcurl version has this option.
open(OTHERFILE,">/dev/null") or die; $curl->setopt(CURLOPT_STDERR,*OTHERFILE);
Previous releases of this module didn't reliably deal with more than a single curl handle per process, because of the use of a number of global 'glue' variables in various places. This should now be fixed, but certain interface features could not be made reliably forward compatible if you intend to use multiple handles or threading:
$curl->setopt
is ugly. It is still supported, but instead, you can get the information by calling the new method
$curl-
errbuf> directly.
$curl->getinfo
is ugly.
It is still supported, but instead, you can get the information as the return value from
getinfo. Instead of:
my $bytes; WWW::Curl::easy::getinfo($curl, CURLINFO_SIZE_DOWNLOAD, $bytes);
use: | |
my $bytes=$curl->getinfo(CURLINFO_SIZE_DOWNLOAD); |
$curl->cleanup
( WWW::Curl::easy::cleanup($curl) ) no longer actually does anything. Curl
handles will be automatically cleaned up by perl when they are no longer used.
There is a slow leak of a few bytes each time a WWW::Curl::easy handle is created and destroyed (despite careful cleanup efforts) at least when testing with libcurl-7.9.8. Hopefully this will be fixed in the next release.
Also note the above problems with the USE_INTERNAL_VARS interface.
Versions 1.30, a (hopefully) threadable, object-oriented, multiple-callback compatible version of WWW::Curl::easy was substantially reworked from the previous WWW::Curl::easy release (1.21) by Cris Bailiff.
Original Author Georg Horn <horn@koblenz-net.de>, with additional callback, pod and test work by Cris Bailiff <c.bailiff+curl@devsecure.com> and Forrest Cahoon <forrest.cahoon@merrillcorp.com>
Currently maintained by Cris Bailiff <c.bailiff+curl@devsecure.com>
Copyright (C) 2000,2001,2002 Daniel Stenberg, Cris Bailiff, et al.
You may opt to use, copy, modify, merge, publish, distribute and/or sell copies of the Software, and permit persons to whom the Software is furnished to do so, under the terms of the MPL or the MIT/X-derivate licenses. You may pick one of these licenses.