#include "_doctype.html" WWW::Curl::easy - Perl extension for libcurl #include "css.t" #define LIBCURL_PERL #include "_menu.html" #include "setup.t" WHERE2(libcurl, "/libcurl/", Perl Interface) TITLE(WWW::Curl::easy -- accessing libcurl from perl)


NAME

WWW::Curl::easy - Perl extension interface for libcurl


SYNOPSIS

        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.


DESCRIPTION


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.

FILES and CALLBACKS

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);

WRITE callback

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.

READ callback

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.

PROGRESS callback

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.

PASSWD callback

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.

STDERR redirection

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);


COMPATABILITY NOTES

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:


KNOWN BUGS

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.


AUTHOR

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

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.


SEE ALSO

http://curl.haxx.se/

#include "_footer.html"