Net::Curl::Form(3)

NAME
Net::Curl::Form - Form builder for Net::Curl

SYNOPSIS
 use Net::Curl::Form qw(:constants);

 my $form = Net::Curl::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 Net::Curl::Easy handle or serialized manually. Net::Curl::Form does not export by default anything, but constants can be exported upon request.

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

  CONSTRUCTOR

new( [BASE] )
    Creates new Net::Curl::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 = Net::Curl::Form->new( [qw(my very private data)] );

  METHODS

add( CURLFORM_option => DATA, ... )
    Adds new section to form object. See curl_formadd(3) <https://curl.haxx.se/libcurl/c/curl_formadd.html> for more info.

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

    On error this method dies with "Net::Curl::Form::Code" error object.

    Buffer and name options automatibally set their length values 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 buffer option, otherwise an CURL_FORMADD_OPTION_TWICE exception will occur.

     $form->add(
         CURLFORM_COPYNAME() => "name",
         CURLFORM_COPYCONTENTS() => "content\0binary"
     );
     $form->add(
         CURLFORM_PTRNAME() => "name",
         CURLFORM_NAMELENGTH() => 2,
         CURLFORM_PTRCONTENTS() => "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 Net::Curl::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) <https://curl.haxx.se/libcurl/c/curl_formget.html>. Rethrows exceptions from callbacks.

  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 = Net::Curl::Form->strerror(
         Net::Curl::Form::CURL_FORMADD_OPTION_TWICE
     );

  CONSTANTS

CURLFORM_*
    Most of those constants can be used in add() method. Currently CURLFORM_STREAM and CURLFORM_ARRAY are not supported. Others will behave in the way described in curl_formadd(3) <https://curl.haxx.se/libcurl/c/curl_formadd.html>.

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

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

  Net::Curl::Form::Code
Net::Curl::Form add() method on failure throws a Net::Curl::Form::Code error object. It has both numeric value and, when used as string, it calls strerror() function to display a nice message.

SEE ALSO
Net::Curl Net::Curl::Easy curl_formadd(3) <https://curl.haxx.se/libcurl/c/curl_formadd.html>

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.