265 lines
7.0 KiB
Perl
265 lines
7.0 KiB
Perl
# Perl interface for libcurl. Check out the file README for more info.
|
|
|
|
package Curl::easy;
|
|
|
|
use strict;
|
|
use Carp;
|
|
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
|
|
|
|
require Exporter;
|
|
require DynaLoader;
|
|
require AutoLoader;
|
|
|
|
@ISA = qw(Exporter DynaLoader);
|
|
# Items to export into callers namespace by default. Note: do not export
|
|
# names by default without a very good reason. Use EXPORT_OK instead.
|
|
# Do not simply export all your public functions/methods/constants.
|
|
@EXPORT = qw(
|
|
CURLOPT_AUTOREFERER
|
|
CURLOPT_COOKIE
|
|
CURLOPT_COOKIEFILE
|
|
CURLOPT_CRLF
|
|
CURLOPT_CUSTOMREQUEST
|
|
CURLOPT_ERRORBUFFER
|
|
CURLOPT_FAILONERROR
|
|
CURLOPT_FILE
|
|
CURLOPT_FOLLOWLOCATION
|
|
CURLOPT_FTPAPPEND
|
|
CURLOPT_FTPASCII
|
|
CURLOPT_FTPLISTONLY
|
|
CURLOPT_FTPPORT
|
|
CURLOPT_HEADER
|
|
CURLOPT_HEADERFUNCTION
|
|
CURLOPT_HTTPHEADER
|
|
CURLOPT_HTTPPOST
|
|
CURLOPT_HTTPPROXYTUNNEL
|
|
CURLOPT_HTTPREQUEST
|
|
CURLOPT_INFILE
|
|
CURLOPT_INFILESIZE
|
|
CURLOPT_INTERFACE
|
|
CURLOPT_KRB4LEVEL
|
|
CURLOPT_LOW_SPEED_LIMIT
|
|
CURLOPT_LOW_SPEED_TIME
|
|
CURLOPT_MUTE
|
|
CURLOPT_NETRC
|
|
CURLOPT_NOBODY
|
|
CURLOPT_NOPROGRESS
|
|
CURLOPT_NOTHING
|
|
CURLOPT_PASSWDDATA
|
|
CURLOPT_PASSWDFUNCTION
|
|
CURLOPT_PORT
|
|
CURLOPT_POST
|
|
CURLOPT_POSTFIELDS
|
|
CURLOPT_POSTFIELDSIZE
|
|
CURLOPT_POSTQUOTE
|
|
CURLOPT_PROGRESSDATA
|
|
CURLOPT_PROGRESSFUNCTION
|
|
CURLOPT_PROXY
|
|
CURLOPT_PROXYPORT
|
|
CURLOPT_PROXYUSERPWD
|
|
CURLOPT_PUT
|
|
CURLOPT_QUOTE
|
|
CURLOPT_RANGE
|
|
CURLOPT_READFUNCTION
|
|
CURLOPT_REFERER
|
|
CURLOPT_RESUME_FROM
|
|
CURLOPT_SSLCERT
|
|
CURLOPT_SSLCERTPASSWD
|
|
CURLOPT_SSLVERSION
|
|
CURLOPT_STDERR
|
|
CURLOPT_TIMECONDITION
|
|
CURLOPT_TIMEOUT
|
|
CURLOPT_TIMEVALUE
|
|
CURLOPT_TRANSFERTEXT
|
|
CURLOPT_UPLOAD
|
|
CURLOPT_URL
|
|
CURLOPT_USERAGENT
|
|
CURLOPT_USERPWD
|
|
CURLOPT_VERBOSE
|
|
CURLOPT_WRITEFUNCTION
|
|
CURLOPT_WRITEHEADER
|
|
CURLOPT_MAXREDIRS
|
|
CURLOPT_FILETIME
|
|
CURLOPT_TELNETOPTIONS
|
|
CURLOPT_MAXCONNECTS
|
|
CURLOPT_CLOSEPOLICY
|
|
CURLOPT_CLOSEFUNCTION
|
|
CURLOPT_FRESH_CONNECT
|
|
CURLOPT_FORBID_REUSE
|
|
CURLOPT_RANDOM_FILE
|
|
CURLOPT_EGD_SOCKET
|
|
CURLOPT_CONNECTTIMEOUT
|
|
|
|
CURLINFO_EFFECTIVE_URL
|
|
CURLINFO_HTTP_CODE
|
|
CURLINFO_TOTAL_TIME
|
|
CURLINFO_NAMELOOKUP_TIME
|
|
CURLINFO_CONNECT_TIME
|
|
CURLINFO_PRETRANSFER_TIME
|
|
CURLINFO_SIZE_UPLOAD
|
|
CURLINFO_SIZE_DOWNLOAD
|
|
CURLINFO_SPEED_DOWNLOAD
|
|
CURLINFO_SPEED_UPLOAD
|
|
CURLINFO_HEADER_SIZE
|
|
CURLINFO_REQUEST_SIZE
|
|
CURLINFO_SSL_VERIFYRESULT
|
|
CURLINFO_FILETIME
|
|
CURLINFO_CONTENT_LENGTH_DOWNLOAD
|
|
CURLINFO_CONTENT_LENGTH_UPLOAD
|
|
|
|
USE_INTERNAL_VARS
|
|
);
|
|
|
|
$VERSION = '1.1.5';
|
|
|
|
$Curl::easy::headers = "";
|
|
$Curl::easy::content = "";
|
|
|
|
sub AUTOLOAD {
|
|
# This AUTOLOAD is used to 'autoload' constants from the constant()
|
|
# XS function.
|
|
|
|
(my $constname = $AUTOLOAD) =~ s/.*:://;
|
|
return constant($constname, 0);
|
|
}
|
|
|
|
bootstrap Curl::easy $VERSION;
|
|
|
|
# Preloaded methods go here.
|
|
|
|
# Autoload methods go after =cut, and are processed by the autosplit program.
|
|
|
|
1;
|
|
__END__
|
|
# Below is the stub of documentation for your module. You better edit it!
|
|
|
|
=head1 NAME
|
|
|
|
Curl::easy - Perl extension for libcurl
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Curl::easy;
|
|
|
|
$curl = Curl::easy::init();
|
|
$CURLcode = Curl::easy::setopt($curl, CURLoption, Value);
|
|
$CURLcode = Curl::easy::perform($curl);
|
|
Curl::easy::cleanup($curl);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This perl module provides an interface to the libcurl C library. See
|
|
http://curl.haxx.se/ for more information on cURL and libcurl.
|
|
|
|
=head1 FILES and CALLBACKS
|
|
|
|
Curl::easy supports the various options of curl_easy_setopt which require either a FILE * or
|
|
a callback function.
|
|
|
|
The perl callback functions are handled through a C wrapper which takes care of converting
|
|
from C to perl variables and back again. This wrapper simplifies some C 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.
|
|
|
|
=head2 FILE handles (GLOBS)
|
|
|
|
Curl options which take a FILE, such as CURLOPT_FILE, CURLOPT_WRITEHEADER, CURLOPT_INFILE
|
|
can be passed a perl file handle:
|
|
|
|
open BODY,">body.out";
|
|
$CURLcode = Curl::easy::setopt($curl, CURLOPT_FILE, BODY);
|
|
|
|
=head2 WRITE callback
|
|
|
|
The CUROPT_WRITEFUNCTION option may be set which will cause libcurl to callback to
|
|
the given subroutine:
|
|
|
|
sub chunk { my ($data,$pointer)=@_; ...; return length($data) }
|
|
$CURLcode = Curl::easy::setopt($curl, CURLOPT_WRITEFUNCTION, \&chunk );
|
|
$CURLcode = Curl::easy::setopt($curl, CURLOPT_FILE, );
|
|
|
|
In this case, the subroutine will be passed whatever is defined by CURLOPT_FILE. This can be
|
|
a ref to a scalar, 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 'length' of '-1'.
|
|
|
|
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:
|
|
|
|
my $headers="";
|
|
my $body="";
|
|
sub chunk { my ($data,$pointer)=@_; ${$pointer}.=$data; return length($data) }
|
|
|
|
$CURLcode = Curl::easy::setopt($curl, CURLOPT_WRITEFUNCTION, \&chunk );
|
|
$CURLcode = Curl::easy::setopt($curl, CURLOPT_WRITEHEADER, \$header );
|
|
$CURLcode = Curl::easy::setopt($curl, CURLOPT_FILE, \$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.
|
|
|
|
=head2 READ callback
|
|
|
|
Curl::easy supports CURLOPT_READFUNCTION. This function should look something like this:
|
|
|
|
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 as much data as the 'Content-Length' header specifies, followed by a
|
|
an empty (0 length) buffer.
|
|
|
|
=head2 PROGRESS callback
|
|
|
|
Curl::easy supports CURLOPT_PROGRESSFUNCTION. This function should look something like this:
|
|
|
|
sub prog_callb
|
|
{
|
|
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
|
|
value/scalar is set using the CURLOPT_PROGRESSDATA option.
|
|
|
|
=head2 PASSWD callback
|
|
|
|
Curl::easy supports CURLOPT_PASSWDFUNCTION. This function should look something like this:
|
|
|
|
sub passwd_callb
|
|
{
|
|
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 accepted password reply.
|
|
|
|
The function must return 0 (for 'OK') and the password data as a list. Return (-1,"") to
|
|
indicate an error.
|
|
|
|
=head1 AUTHOR
|
|
|
|
Georg Horn <horn@koblenz-net.de>
|
|
|
|
Additional callback,pod and tes work by Cris Bailiff <c.bailiff@devsecure.com>
|
|
and Forrest Cahoon <forrest.cahoon@merrillcorp.com>
|
|
|
|
=head1 SEE ALSO
|
|
|
|
http://curl.haxx.se/
|
|
|
|
=cut
|