Net::Curl::Easy(3)

NAME
Net::Curl::Easy - Perl interface for curl_easy_* functions

SYNOPSIS
Direct use.

 use Net::Curl::Easy qw(:constants);

 my $easy = Net::Curl::Easy->new();
 $easy->setopt( CURLOPT_URL, "http://example.com/" );

 $easy->perform();

Build your own browser.

 package MyBrowser;
 use Net::Curl::Easy qw(/^CURLOPT_/ /^CURLINFO_/);
 use base qw(Net::Curl::Easy);

 sub new
 {
     my $class = shift;
     my $self = $class->SUPER::new( { head => '', body => ''} );
     $self->setopt( CURLOPT_USERAGENT, "MyBrowser v0.1" );
     $self->setopt( CURLOPT_FOLLOWLOCATION, 1 );
     $self->setopt( CURLOPT_COOKIEFILE, "" ); # enable cookie session
     $self->setopt( CURLOPT_FILE, \$self->{body} );
     $self->setopt( CURLOPT_HEADERDATA, \$self->{head} );
     return $self;
 }

 sub get
 {
     my ( $self, $uri ) = @_;
     $self->setopt( CURLOPT_URL, $uri );
     @$self{qw(head body)} = ('', '');
     $self->perform();
     my $ref = $self->getinfo( CURLINFO_EFFECTIVE_URL );
     $self->setopt( CURLOPT_REFERER, $ref );
     return @$self{qw(head body)};
 }

DESCRIPTION
This module wraps easy handle from libcurl and all related functions and constants. It does not export by default anything, but constants can be exported upon request.

 use Net::Curl::Easy qw(:constants);

  CONSTRUCTOR

new( [BASE] )
    Creates new Net::Curl::Easy object. If BASE is specified it will be used as object base, otherwise an empty hash will be used. BASE must be a valid reference which has not been blessed already. It will not be used by the object.

     my $easy = Net::Curl::Easy->new( [qw(my very private data)] );

    Calls curl_easy_init(3) <https://curl.haxx.se/libcurl/c/curl_easy_init.html> and presets some defaults.

  METHODS

duphandle( [BASE] )
    Clone Net::Curl::Easy object. It will not copy BASE from the source object. If you want it copied you must do it on your own.

     my $hash_clone = $easy->duphandle( { %$easy } );

     use Storable qw(dclone);
     my $deep_clone = $easy->duphandle( dclone( $easy ) );

    Calls curl_easy_duphandle(3) <https://curl.haxx.se/libcurl/c/curl_easy_duphandle.html>.

setopt( OPTION, VALUE )
    Set an option. OPTION is a numeric value, use one of CURLOPT_* constants. VALUE depends on whatever that option expects.

     $easy->setopt( Net::Curl::Easy::CURLOPT_URL, $uri );

    Calls curl_easy_setopt(3) <https://curl.haxx.se/libcurl/c/curl_easy_setopt.html>. Throws "Net::Curl::Easy::Code" on error.

pushopt( OPTION, ARRAYREF )
    If option expects a slist, specified array will be appended instead of replacing the old slist.

     $easy->pushopt( Net::Curl::Easy::CURLOPT_HTTPHEADER,
         ['More: headers'] );

    Builds a slist and calls curl_easy_setopt(3) <https://curl.haxx.se/libcurl/c/curl_easy_setopt.html>. Throws "Net::Curl::Easy::Code" on error.

reset( )
    Reinitializes easy handle (was broken before v0.27!).

     $easy->reset();

    Calls curl_easy_reset(3) <https://curl.haxx.se/libcurl/c/curl_easy_reset.html> and presets some defaults.

perform( )
    Perform upload and download process.

     $easy->perform();

    Calls curl_easy_perform(3) <https://curl.haxx.se/libcurl/c/curl_easy_perform.html>. Rethrows exceptions from callbacks. Throws "Net::Curl::Easy::Code" on other errors.

getinfo( OPTION )
    Retrieve a value. OPTION is one of "CURLINFO_*" constants.

     my $socket = $self->getinfo( CURLINFO_LASTSOCKET );

    Calls curl_easy_getinfo(3) <https://curl.haxx.se/libcurl/c/curl_easy_getinfo.html>. Throws "Net::Curl::Easy::Code" on error.

    In the case of "CURLINFO_CERTINFO", the return is an array reference of hash references; each hash represents one certificate.

pause( )
    Pause the transfer.

    Calls curl_easy_pause(3) <https://curl.haxx.se/libcurl/c/curl_easy_pause.html>. Not available in curl before 7.18.0. Throws "Net::Curl::Easy::Code" on error.

send( BUFFER )
    Send raw data.

     $easy->send( $data );

    Calls curl_easy_send(3) <https://curl.haxx.se/libcurl/c/curl_easy_send.html>. Not available in curl before 7.18.2. Throws "Net::Curl::Easy::Code" on error.

recv( BUFFER, MAXLENGTH )
    Receive raw data. Will receive at most MAXLENGTH bytes. New data will be concatenated to BUFFER.

     $easy->recv( $buffer, $len );

    Calls curl_easy_recv(3) <https://curl.haxx.se/libcurl/c/curl_easy_recv.html>. Not available in curl before 7.18.2. Throws "Net::Curl::Easy::Code" on error.

error( )
    Get last error message.

    See information on "CURLOPT_ERRORBUFFER" in curl_easy_setopt(3) <https://curl.haxx.se/libcurl/c/curl_easy_setopt.html> for a longer description.

     my $error = $easy->error();
     print "Last error: $error\n";

multi( )
    If easy object is associated with any multi handles, it will return that multi handle.

     my $multi = $easy->multi;

    Use $multi->add_handle() to attach the easy object to the multi interface.

share( )
    If share object is attached to this easy handle, this method will return that share object.

     my $share = $easy->share;

    Use setopt() with CURLOPT_SHARE option to attach the share object.

form( )
    If form object is attached to this easy handle, this method will return that form object.

     my $form = $easy->form;

    Use setopt() with CURLOPT_HTTPPOST option to attach the share object.

escape( )
    URL encodes the given string.

     my $escaped = $easy->escape( "+foo" );

    Calls curl_easy_escape(3) <https://curl.haxx.se/libcurl/c/curl_easy_escape.html> which URL encode the given string.

unescape( )
    URL decodes the given string.

     my $unescaped = $easy->unescape( "%2Bbar" );

    Calls curl_easy_unescape(3) <https://curl.haxx.se/libcurl/c/curl_easy_unescape.html> which URL decodes the given string.

    If you are sure the unescaped data contains a utf8 string, you can mark it with utf8::decode( $unescaped )

  FUNCTIONS
None of those functions are exported, you must use fully qualified names.

strerror( [WHATEVER], CODE )
    Return a string for error code CODE.

     my $message = Net::Curl::Easy::strerror(
         Net::Curl::Easy::CURLE_OK
     );

    Calls curl_easy_strerror(3) <https://curl.haxx.se/libcurl/c/curl_easy_strerror.html>.

  CONSTANTS
Net::Curl::Easy contains all the constants that do not form part of any other Net::Curl modules. List below describes only the ones that behave differently than their C counterparts.

CURLOPT_PRIVATE
    setopt() does not allow to use this constant. Hide any private data in your base object.

CURLOPT_ERRORBUFFER
    setopt() does not allow to use this constant. You can always retrieve latest error message with $easy->error() method.

  CALLBACKS
Reffer to libcurl documentation for more detailed info on each of those. Callbacks can be set using setopt() method.

 $easy->setopt( CURLOPT_somethingFUNCTION, \&callback_function );
 # or
 $easy->setopt( CURLOPT_somethingFUNCTION, "callback_method" );
 $easy->setopt( CURLOPT_somethingDATA, [qw(any additional data
     you want)] );

CURLOPT_WRITEFUNCTION ( CURLOPT_WRITEDATA )
    write callback receives 3 arguments: easy object, data to write, and whatever CURLOPT_WRITEDATA was set to. It must return number of data bytes.

     sub cb_write {
         my ( $easy, $data, $uservar ) = @_;
         # ... process ...
         return CURL_WRITEFUNC_PAUSE if $want_pause;
         return length $data;
     }

CURLOPT_READFUNCTION ( CURLOPT_READDATA )
    read callback receives 3 arguments: easy object, maximum data length, and CURLOPT_READDATA value. It must return either a reference to data read or one of numeric values: 0 - transfer completed, CURL_READFUNC_ABORT - abort upload, CURL_READFUNC_PAUSE - pause upload. Reference to any value that is zero in length ("", undef) will also signalize completed transfer.

     sub cb_read {
         my ( $easy, $maxlen, $uservar ) = @_;
         # ... read $data, $maxlen ...
         return \$data;
     }

CURLOPT_IOCTLFUNCTION ( CURLOPT_IOCTLDATA )
    ioctl callback receives 3 arguments: easy object, ioctl command, and CURLOPT_IOCTLDATA value. It must return a curlioerr value.

     sub cb_ioctl {
         my ( $easy, $command, $uservar ) = @_;

         if ( $command == CURLIOCMD_RESTARTREAD ) {
             if ( restart_read() ) {
                 return CURLIOE_OK;
             } else {
                 return CURLIOE_FAILRESTART;
             }
         }
         return CURLIOE_UNKNOWNCMD;
     }

CURLOPT_SEEKFUNCTION ( CURLOPT_SEEKDATA ) 7.18.0+
    seek callback receives 4 arguments: easy object, offset / position, origin / whence, and CURLOPT_SEEKDATA value. Must return one of CURL_SEEKFUNC_* values.

     use Fcntl qw(:seek);
     sub cb_seek {
         my ( $easy, $offset, $origin, $uservar ) = @_;
         if ( $origin = SEEK_SET ) {
             if ( seek SOMETHING, $offset, SEEK_SET ) {
                 return CURL_SEEKFUNC_OK;
             }
             return CURL_SEEKFUNC_CANTSEEK;
         }
         return CURL_SEEKFUNC_FAIL
     }

CURLOPT_SOCKOPTFUNCTION ( CURLOPT_SOCKOPTDATA ) 7.15.6+
    sockopt callback receives 4 arguments: easy object, socket fd, socket purpose, and CURLOPT_SOCKOPTDATA value. Is should return one of CURL_SOCKOPT_* values.

     sub cb_sockopt {
         my ( $easy, $socket, $purpose, $uservar ) = @_;
         # ... do something with the socket ...
         return CURL_SOCKOPT_OK;
     }

CURLOPT_OPENSOCKETFUNCTION ( CURLOPT_OPENSOCKETDATA ) 7.17.1+
    opensocket callback receives 4 arguments: easy object, socket purpose, address structure (in form of a hashref), and CURLOPT_OPENSOCKETDATA value. The address structure has following numeric values: "family", "socktype", "protocol"; and "addr" in binary form. Use Socket module to decode "addr" field. You are also allowed to change those values.

    Callback must return fileno of the socket or CURL_SOCKET_BAD on error.

     use Socket;
     sub cb_opensocket {
         my ( $easy, $purpose, $address, $uservar ) = @_;

         # decode addr information
         my ( $port, $ip ) = unpack_sockaddr_in( $address->{addr} );
         my $ip_string = inet_ntoa( $ip );

         # open the socket
         socket my $socket, $address->{family}, $address->{socktype},
             $address->{protocol};

         # save it somewhere so perl won't close the socket
         $opened_sockets{ fileno( $socket ) } = $socket;

         # return the socket
         return fileno $socket;
     }

CURLOPT_CLOSESOCKETFUNCTION ( CURLOPT_CLOSESOCKETDATA ) 7.21.7+
    closesocket callback receives 3 arguments: easy object, socket fileno, and CURLOPT_CLOSESOCKETDATA value.

     sub cb_closesocket {
         my ( $easy, $fileno, $uservar ) = @_;
         my $socket = delete $opened_sockets{ $fileno };
         close $socket;
     }

CURLOPT_PROGRESSFUNCTION ( CURLOPT_PROGRESSDATA )
    Progress callback receives 6 arguments: easy object, dltotal, dlnow, ultotal, ulnow and CURLOPT_PROGRESSDATA value. It should return 0.

     sub cb_progress {
         my ( $easy, $dltotal, $dlnow, $ultotal, $ulnow, $uservar ) = @_;
         # ... display progress ...
         return 0;
     }

    Since CURLOPT_XFERINFODATA is an alias to CURLOPT_PROGRESSDATA, they both set the same callback data for both CURLOPT_PROGRESSFUNCTION and CURLOPT_PROGRESSFUNCTION callbacks.

CURLOPT_XFERINFOFUNCTION ( CURLOPT_XFERINFODATA ) 7.32.0+
    Works exactly like CURLOPT_PROGRESSFUNCTION callback, except that dltotal, dlnow, ultotal and ulnow are now integer values instead of double.

    Since CURLOPT_XFERINFODATA is an alias to CURLOPT_PROGRESSDATA, they both set the same callback data for both CURLOPT_PROGRESSFUNCTION and CURLOPT_PROGRESSFUNCTION callbacks.

CURLOPT_HEADERFUNCTION ( CURLOPT_WRITEHEADER )
    Behaviour is the same as in write callback. Callback is called once for every header line.

CURLOPT_DEBUGFUNCTION ( CURLOPT_DEBUGDATA )
    Debug callback receives 4 arguments: easy object, message type, debug data and CURLOPT_DEBUGDATA value. Must return 0.

     sub cb_debug {
         my ( $easy, $type, $data, $uservar ) = @_;
         # ... display debug info ...
         return 0;
     }

CURLOPT_SSL_CTX_FUNCTION ( CURLOPT_SSL_CTX_DATA )
    Not supported, probably will never be.

CURLOPT_INTERLEAVEFUNCTION ( CURLOPT_INTERLEAVEDATA ) 7.20.0+
    Behaviour is the same as in write callback.

CURLOPT_CHUNK_BGN_FUNCTION ( CURLOPT_CHUNK_DATA ) 7.21.0+
    chunk_bgn callback receives 4 arguments: easy object, fileinfo structure (in form of a hashref), number of remaining chunks, and CURLOPT_CHUNK_DATA value. It must return one of CURL_CHUNK_BGN_FUNC_* values.

     sub cb_chunk_bgn {
         my ( $easy, $fileinfo, $remaining, $uservar ) = @_;

         if ( exists $fileinfo->{filetype} and
                 $fileinfo->{filetype} != CURLFILETYPE_FILE ) {
             # download regular files only
             return CURL_CHUNK_BGN_FUNC_SKIP;
         }
         my $filename = "unknown." . $remaining;
         $filename = $fileinfo->{filename}
             if defined $fileinfo->{filename};

         open $easy->{myfile}, '>', $filename
             or return CURL_CHUNK_BGN_FUNC_FAIL;

         return CURL_CHUNK_BGN_FUNC_OK;
     }

CURLOPT_CHUNK_END_FUNCTION ( CURLOPT_CHUNK_DATA ) 7.21.0+
    chunk_end callback receives 2 arguments: easy object and CURLOPT_CHUNK_DATA value. Must return one of CURL_CHUNK_END_FUNC_* values.

     sub cb_chunk_end {
         my ( $easy, $uservar ) = @_;
         # ... close $easy-{myfile} ...
         return CURL_CHUNK_END_FUNC_OK;
     }

CURLOPT_FNMATCH_FUNCTION ( CURLOPT_FNMATCH_DATA ) 7.21.0+
    fnmatch callback receives 4 arguments: easy object, pattern, string, and CURLOPT_FNMATCH_DATA value. Must return one of CURL_FNMATCHFUNC_* values.

     sub cb_fnmatch {
         my ( $easy, $pattern, $string, $uservar ) = @_;
         return ( $string =~ m/$pattern/i
             ? CURL_FNMATCHFUNC_MATCH
             : CURL_FNMATCHFUNC_NOMATCH );
     }

CURLOPT_SSH_KEYFUNCTION ( CURLOPT_SSH_KEYDATA ) 7.19.6+
    sshkey callback receives 4 arguments: easy object, known key, found key, khmatch status and CURLOPT_SSH_KEYDATA value. Must return one of CURLKHSTAT_* values.

     sub cb_sshkey {
         my ( $easy, $knownkey, $foundkey, $khmatch, $uservar ) = @_;
         return CURLKHSTAT_FINE_ADD_TO_FILE;
     }

  Net::Curl::Easy::Code
Most Net::Curl::Easy methods on failure throw a Net::Curl::Easy::Code error object. It has both numeric value and, when used as string, it calls strerror() function to display a nice message.

 eval {
     $easy->somemethod();
 };
 if ( ref $@ eq "Net::Curl::Easy::Code" ) {
     if ( $@ == CURLE_SOME_ERROR_WE_EXPECTED ) {
         warn "Expected error, continuing\n";
     } else {
         die "Unexpected curl error: $@\n";
     }
 } else {
     # rethrow everyting else
     die $@;
 }

SEE ALSO
Net::Curl Net::Curl::Multi Net::Curl::examples libcurl-easy(3) libcurl-errors(3)

COPYRIGHT
Copyright (c) 2011-2015 Przemyslaw Iskra <sparky at pld-linux.org>.

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.