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.