NAME

Net::Curl::Simple - simplifies Net::Curl::Easy interface

SYNOPSIS

use Net::Curl::Simple;

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

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

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

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

sub finished2 { }

WARNING

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

Documentation may not be up to date with latest interface changes.

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 uses callbacks even in synchronous mode, this should allow to quickly switch to async when the time comes.

CONSTRUCTOR

new( [PERMANENT_OPTIONS] )

Creates new Net::Curl::Simple object.

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

METHODS

setopt( NAME, VALUE, [TEMPORARY] )

Set some option. Either permanently or only for next request if TEMPORARY is true.

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 )

Get multiple getinfo values.

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

ua

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

get( URI, [TEMPORARY_OPTIONS], CALLBACK )

Issue a GET request. CALLBACK will be called upon finishing with two arguments: Net::Curl::Simple object and the result value. 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 {} );
} );

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

NOT IMPLEMENTED YET

Wait for this download "thread" to finish.

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::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.