NAME

       DIME::Payload - implementation of a payload of a DIME message

SYNOPSIS

         # Create a standard DIME message from an existing file
         # and a string

         use DIME::Payload;

         $payload1 = new DIME::Payload;
         $payload1->attach(Path => 'existingfile.jpg',
                           MIMEType => 'image/jpeg',
                           Dynamic => 1);

         $payload2 = new DIME::Payload;
         my $data = 'Hello World!!!';
         $payload2->attach(Data => \$data,
                           MIMEType => 'text/plain');

         my $message = new DIME::Message;
         $message->add_payload($payload1);
         $message->add_payload($payload2);

DESCRIPTION

       DIME::Payload represents the content of DIME message. A message is composed of one or many
       Payload objects.

       There are two types of DIME payloads: chunked and not chunked. A DIME message that isn't
       chunked has only one record with all the Payload content. A chunked message is splited in
       several records, allowing to sender and receiver process the content without know the
       total size of this.

CHUNKED AND DYNAMIC CONTENT

       To create a chunked message you have to specify the Chunked key:

               # This create a dynamic payload with records of 16384 bytes

               my $payload = new DIME::Payload;
               $payload->attach(Path => 'bigfile.avi',
                                Chunked => 16384,
                                Dynamic => 1);

               # You can encode all the payload at once:

               my $dime_encoded_message = ${$payload->print_data()};

               # Or, if you prefer, you can generate each chunk

               my $ret;
               do
               {
                       $chunk = ${$payload->print_chunk_data()};
               } while ($chunk ne '');

       The Dynamic key is used to avoid load all the file in memory. What DIME::Payload does is
       to open the file and, when it need more content, read from the file. If you don't set the
       Dynamic key, all the data is loaded in memory.

CONTENT TYPE

       To specify the type of content of a Payload, you should use the MIMEType and URIType keys:

               # MIME media-type
               my $payload = new DIME::Payload;
               $payload->attach(Path => 'image.jpg',
                                MIMEType => 'image/jpeg');

               # absolute URI
               my $payload = new DIME::Payload;
               $payload->attach(Path => 'message.xml',
                                URIType => 'http://schemas.xmlsoap.org/soap/envelope/');

PAYLOAD IDENTIFIER

       When you create a new Payload, a unique identifier is generated automatically. You can
       get/set it with the id() method:

               my $payload = new DIME::Payload;
               print $payload->id();

AUTHOR

       Domingo Alcazar Larrea, <dalcazar@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2004 Domingo Alcazar Larrea

       This program is free software; you can redistribute it and/or modify it under the terms of
       the version 2 of the GNU General Public License as published by the Free Software
       Foundation.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
       MA  02111-1307

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 474:
           Non-ASCII character seen before =encoding in 'Alcazar'. Assuming ISO8859-1