.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DIME::Payload 3pm"
.TH DIME::Payload 3pm "2021-03-22" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DIME::Payload \- implementation of a payload of a DIME message
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # Create a standard DIME message from an existing file
\&  # and a string
\&
\&  use DIME::Payload;
\&
\&  $payload1 = DIME::Payload\->new();
\&  $payload1\->attach(Path => \*(Aqexistingfile.jpg\*(Aq,
\&                    MIMEType => \*(Aqimage/jpeg\*(Aq,
\&                    Dynamic => 1);
\&
\&  $payload2 = DIME::Payload\->new();
\&  my $data = \*(AqHello World!!!\*(Aq;
\&  $payload2\->attach(Data => \e$data,     
\&                    MIMEType => \*(Aqtext/plain\*(Aq);
\&
\&  my $message = DIME::Message\->new();
\&  $message\->add_payload($payload1);
\&  $message\->add_payload($payload2);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
DIME::Payload represents the content of \s-1DIME\s0 message. A message is composed of one or many Payload objects.
.PP
There are two types of \s-1DIME\s0 payloads: chunked and not chunked. A \s-1DIME\s0 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.
.SH "CHUNKED AND DYNAMIC CONTENT"
.IX Header "CHUNKED AND DYNAMIC CONTENT"
To create a chunked message you have to specify the Chunked key:
.PP
.Vb 1
\&        # This create a dynamic payload with records of 16384 bytes
\&
\&        my $payload = DIME::Payload\->new();
\&        $payload\->attach(Path => \*(Aqbigfile.avi\*(Aq,
\&                         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 \*(Aq\*(Aq);
.Ve
.PP
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.
.SH "CONTENT TYPE"
.IX Header "CONTENT TYPE"
To specify the type of content of a Payload, you should use the MIMEType and URIType keys:
.PP
.Vb 4
\&        # MIME media\-type
\&        my $payload = DIME::Payload\->new();
\&        $payload\->attach(Path => \*(Aqimage.jpg\*(Aq,
\&                         MIMEType => \*(Aqimage/jpeg\*(Aq);
\&
\&        # absolute URI 
\&        my $payload = DIME::Payload\->new();
\&        $payload\->attach(Path => \*(Aqmessage.xml\*(Aq,
\&                         URIType => \*(Aqhttp://schemas.xmlsoap.org/soap/envelope/\*(Aq);
.Ve
.SH "PAYLOAD IDENTIFIER"
.IX Header "PAYLOAD IDENTIFIER"
When you create a new Payload, a unique identifier is generated automatically. You can get/set it with the \fBid()\fR method:
.PP
.Vb 2
\&        my $payload = DIME::Payload\->new();
\&        print $payload\->id();
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Domingo Alcazar Larrea, <dalcazar@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2004 Domingo Alcázar Larrea
.PP
This program is free software; you can redistribute it and/or
modify it under the terms of the version 2 of the \s-1GNU\s0 General
Public License as published by the Free Software Foundation.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place \- Suite 330, Boston, \s-1MA\s0  02111\-1307