NAME

Net::Curl::Simple - simplified Net::Curl interface

SYNOPSIS

 use Net::Curl::Simple;

 Net::Curl::Simple->new->get( $uri, \&finished );

 sub finished
 {
     my $curl = shift;
     print "document body: $curl->{body}\n";

     # reuse connection to get another file
     $curl->get( '/other_file', \&finished2 );
 }

 sub finished2 { }

 # wait until all requests are finished
 1 while Net::Curl::Simple->join;

WARNING

This module is under development. Its interface may change yet.

DESCRIPTION

Net::Curl::Simple is a thin layer over Net::Curl. It simplifies many common tasks, while providing access to full power of Net::Curl when its needed.

Net::Curl excells in asynchronous operations, thanks to a great design of libcurl(3). To take advantage of that power Net::Curl::Simple interface allways uses asynchronous mode. If you want a blocking request, you must either set callback to undef or call join() method right away.

CONSTRUCTOR

new( [%PERMANENT_OPTIONS] )

Creates new Net::Curl::Simple object.

 my $curl = Net::Curl::Simple->new( timeout => 60 );

See also Net::Curl::Simple::UserAgent which will allow you to create connected Net::Curl::Simple objects.

METHODS

setopt( NAME, VALUE, [TEMPORARY] )

Set some option. Either permanently or only for next request if TEMPORARY is true. NAME can be a string: name of the CURLOPT_* constants, without CURLOPT_ prefix, preferably in lower case. VALUE should be an appropriate value for that constant, as described in curl_easy_setopt(3).

 $curl->setopt( url => $some_uri );

Some options, those that require a constant or a bitmask as their value, can have a literal value specified instead of the constant. Bitmask values must be separated by commas, spaces, or combination of both; arrayrefs are accepted as well. Value names must be written without prefix common for all of values of this type.

 # single constant
 $curl->setopt( http_version => "1_0" );
 $curl->setopt( ipresolve => "v4" );

 # converted to a bitmask
 $curl->setopt( protocols => "http, https, ftp, file" );
 $curl->setopt( httpauth => "digest, gssnegotiate, ntlm" );

setopts( %PERMANENT_OPTIONS )

Set multiple options, permanently.

setopts_temp( %TEMPORARY_OPTIONS )

Set multiple options, only for next request.

getinfo( NAME )

Get connection information.

 my $value = $curl->getinfo( 'effective_url' );

getinfos( @INFO_NAMES )

Returns multiple getinfo values.

 my ( $v1, $v2 ) = $curl->getinfos( 'name1', 'name2' );

ua

Returns parent Net::Curl::Simple::UserAgent object.

get( URI, [%TEMPORARY_OPTIONS], [&CALLBACK] )

Issue a GET request.

CALLBACK will be called upon finishing with one argument: the Net::Curl::Simple object. CALLBACK can be set to undef, in which case the request will block and wait until it finishes.

If URI is incomplete, full uri will be constructed using $curl->{referer} as base. Net::Curl::Simple updates $curl->{referer} after every request. TEMPORARY_OPTIONS will be set for this request only.

 $curl->get( "http://full.uri/", sub {
     my $curl = shift;
     my $result = $curl->code;
     die "get() failed: $result\n" unless $result == 0;

     $curl->get( "/partial/uri", sub {} );
 } );

Returns the object itself to allow chaining.

 $curl->get( $uri, \&finished )->join();

head( URI, [%TEMPORARY_OPTIONS], [&CALLBACK] )

Issue a HEAD request. Otherwise it is exactly the same as get().

post( URI, POST, [%TEMPORARY_OPTIONS], [&CALLBACK] )

Issue a POST request. POST value can be either a scalar, in which case it will be sent literally, a HASHREF - will be uri-encoded, or a Net::Curl::Form object (Net::Curl::Simple::Form is OK as well).

 $curl->post( $uri,
     { username => "foo", password => "bar" },
     \&finished
 );

put( URI, PUTDATA, [%TEMPORARY_OPTIONS], [&CALLBACK] )

Issue a PUT request. PUTDATA value can be either a file name, in which case the file contents will be uploaded, a SCALARREF -- refered data will be uploaded, or a CODEREF -- sub will be called like a CURLOPT_READFUNCTION from Net::Curl::Easy, you should specify "infilesize" option in the last case.

 $curl1->put( $uri, "filename", \&finished );
 $curl2->put( $uri, \"some data", \&finished );
 $curl3->put( $uri, sub {
         my ( $curl, $maxsize, $uservar ) = @_;
         read STDIN, my ( $r ), $maxsize;
         return \$r;
     },
     infilesize => EXPECTED_SIZE,
     \&finished
 );

code

Return result code. Zero means we're ok.

headers

Return a list of all headers. Equivalent to @{ $curl->{headers} }.

content

Return transfer content. Equivalent to $curl->{body}.

join

Wait for this download "thread" to finish.

 $curl->join;

It can be called without an object to wait for any download request. It will return the Net::Curl::Simple that just finished. It is not guaranteed to return once for each request, if two requests finish at the same time only the first one will be notified.

 while ( my $curl = Net::Curl::Simple->join ) {
     my $result = $curl->code;
     warn "curl request finished: $result\n";
 }

It should not normally be used, only if you don't provide an event loop on your own.

CONSTANTS

can_ipv6

Bool, indicates whether libcurl has IPv6 support.

can_ssl

Bool, indicates whether libcurl has SSL support.

can_libz

Bool, indicates whether libcurl has compression support.

can_asynchdns

Bool, indicates whether libcurl can do asynchronous DNS requests.

OPTIONS

Options can be either CURLOPT_* values (import them from Net::Curl::Easy), or literal names, preferably in lower case, without the CURLOPT_ preffix. For description of available options see curl_easy_setopt(3).

Names for getinfo can also be either CURLINFO_* values or literal names without CURLINFO_ preffix.

SEE ALSO

Net::Curl::Simple::examples, Net::Curl::Simple::UserAgent, Net::Curl::Simple::Async, Net::Curl::Easy

COPYRIGHT

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

This program is free software; you can redistribute it and/or modify it under the same terms as perl itself.