/ 
WWW-CurlOO-0.12
/ WWW::CurlOO::Form

NAME

WWW::CurlOO::Form - Form builder for WWW::CurlOO

WARNING

THIS MODULE IS UNDER HEAVY DEVELOPEMENT AND SOME INTERFACE MAY CHANGE YET.

SYNOPSIS

use WWW::CurlOO::Form qw(:constants);

my $form = WWW::CurlOO::Form->new();
$form->add(
    CURLFORM_COPYNAME() => $name,
    CURLFORM_COPYCONTENTS() => $data
);
$form->add(
    CURLFORM_COPYNAME() => $filename,
    CURLFORM_FILE() => $filename
);


# most likely use:
$easy->setopt( CURLOPT_HTTPPOST() => $form );

# serialize
my $serial = $form->get();

DESCRIPTION

This module lets you build multipart/form-data HTTP POST. When finished it can be either supplied to WWW::CurlOO::Easy handle or serialized manually. WWW::CurlOO::Form does not export by default anything, but constants can be exported upon request.

use WWW::CurlOO::Form qw(:constants);

CONSTRUCTOR

new( [BASE] )

Creates new WWW::CurlOO::Form 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 $form = WWW::CurlOO::Form->new( [qw(my very private data)] );

METHODS

add( CURLFORM_option => DATA, ... )

Adds new section to form object. See curl_formadd(3) for more info.

Working options include: CURLFORM_COPYNAME, CURLFORM_NAMELENGTH, CURLFORM_COPYCONTENTS, CURLFORM_CONTENTSLENGTH, CURLFORM_FILECONTENT, CURLFORM_FILE, CURLFORM_CONTENTTYPE, CURLFORM_FILENAME.

Unlike in libcurl function, there is no need to add CURLFORM_END as the last argument.

On error this method dies with WWW::CurlOO::Form::Code error object.

Options CURLFORM_COPYNAME and CURLFORM_COPYCONTENTS automatibally set appropriate their length values (CURLFORM_NAMELENGTH and CURLFORM_CONTENTSLENGTH respectively) so there is no need to set length even if there is a NUL character in the data. If you want to shorten the buffer CURLFORM_*LENGTH options must be set inmediatelly after their CURLFORM_COPY* options, otherwise an CURL_FORMADD_OPTION_TWICE exception will occur.

$form->add(
    CURLFORM_COPYNAME() => "name",
    CURLFORM_COPYCONTENTS() => "content\0binary"
);
$form->add(
    CURLFORM_COPYNAME() => "name",
    CURLFORM_NAMELENGTH() => 2,
    CURLFORM_COPYCONTENTS() => "content",
    CURLFORM_CONTENTSLENGTH() => 4,
);
$form->add(
    CURLFORM_COPYNAME, "htmlcode",
    CURLFORM_COPYCONTENTS, "<HTML></HTML>",
    CURLFORM_CONTENTTYPE, "text/html"
);
$form->add(
    CURLFORM_COPYNAME, "picture",
    CURLFORM_FILE, "my-face.jpg"
);
$form->add(
    CURLFORM_COPYNAME, "picture",
    CURLFORM_FILE, "my-face.jpg",
    CURLFORM_CONTENTTYPE, "image/jpeg"
);
$form->add(
    CURLFORM_COPYNAME, "picture",
    CURLFORM_FILE, "my-face.jpg",
    CURLFORM_FILE, "your-face.jpg",
);
$form->add(
    CURLFORM_COPYNAME, "filecontent",
    CURLFORM_FILECONTENT, ".bashrc"
);
get( [BUFFER / FH / USERDATA], [CALLBACK] )

Use it to serialize the form object. Normally there is no need to use it because WWW::CurlOO::Easy will serialize it while uploading data.

There are multiple ways to perform serialization:

direct

With no arguments a scalar is returned.

my $serial = $form->get();
write to file handle

If there is only one argument and it is a GLOB or a GLOB reference, serialized contents will be written to that file handle.

open my $file, ">", "post.txt";
$form->get( $file );
write to buffer

If there is only one argument and it is writable, serialized contents will be concatenated to it.

my $serial;
$form->get( $serial );

# same as above
$form->get( \$serial );
use a callback

With two arguments, second one must be a function that will be called for serialization. First argument is a user data that will be passed to that function.

The callback will receive three arguments: form object, data buffer and user data. It must return the length of the data buffer, otherwise serialization will be aborted.

sub cb_serial
{
    my ( $form, $data, $uservar ) = @_;

    # do anything you want

    return length $data;
}
$form->get( "userdata", \&cb_serial );

Calls curl_formget(3).

DESTROY( )

Cleans up. It should not be called manually.

Calls curl_formfree(3).

FUNCTIONS

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

strerror( [WHATEVER], CODE )

Return a string for error code CODE. String is extracted from error constant name.

my $message = WWW::CurlOO::Form->strerror(
    WWW::CurlOO::Form::CURL_FORMADD_OPTION_TWICE
);

CONSTANTS

CURLFORM_*

Most of those constants can be used in add() method.

CURL_FORMADD_*

If add() fails it will return one of those values.

CALLBACKS

Callback for get() is described already in "use a callback" subsection.

SEE ALSO

WWW::CurlOO WWW::CurlOO::Easy

COPYRIGHT

Copyright (c) 2011 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.