diff options
Diffstat (limited to 'perl/Curl_easy/easy.pm')
| -rw-r--r-- | perl/Curl_easy/easy.pm | 130 |
1 files changed, 120 insertions, 10 deletions
diff --git a/perl/Curl_easy/easy.pm b/perl/Curl_easy/easy.pm index 126be14a9..e484a28f2 100644 --- a/perl/Curl_easy/easy.pm +++ b/perl/Curl_easy/easy.pm @@ -29,6 +29,7 @@ CURLOPT_FTPASCII CURLOPT_FTPLISTONLY CURLOPT_FTPPORT CURLOPT_HEADER +CURLOPT_HEADERFUNCTION CURLOPT_HTTPHEADER CURLOPT_HTTPPOST CURLOPT_HTTPPROXYTUNNEL @@ -44,6 +45,8 @@ CURLOPT_NETRC CURLOPT_NOBODY CURLOPT_NOPROGRESS CURLOPT_NOTHING +CURLOPT_PASSWDDATA +CURLOPT_PASSWDFUNCTION CURLOPT_PORT CURLOPT_POST CURLOPT_POSTFIELDS @@ -88,8 +91,14 @@ CURLINFO_SPEED_DOWNLOAD CURLINFO_SPEED_UPLOAD CURLINFO_HEADER_SIZE CURLINFO_REQUEST_SIZE + +USE_INTERNAL_VARS ); -$VERSION = '1.0.1'; + +$VERSION = '1.1.3'; + +$Curl::easy::headers = ""; +$Curl::easy::content = ""; sub AUTOLOAD { # This AUTOLOAD is used to 'autoload' constants from the constant() @@ -116,21 +125,122 @@ 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); - - + + $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 -=head1 AUTHOR +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 |