.\" 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::Tools 3pm"
.TH DIME::Tools 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::Tools \- modules for parsing and generate DIME messages
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Generating \s-1DIME\s0 messages
.PP
.Vb 4
\&                my $payload = DIME::Payload\->new();
\&                $payload\->attach(Path => "/mydata/index.html",
\&                                 MIMEType => \*(Aqtext/html\*(Aq,
\&                                 Dynamic => 1);
\&
\&                my $payload2 = DIME::Payload\->new();
\&                $payload2\->attach( Data => "HELLO WORLD!!!",
\&                                   MIMEType => \*(Aqtext/plain\*(Aq );
\&
\&                my $message = DIME::Message\->new();
\&
\&        my $payload = DIME::Payload\->new();
\&        $payload\->attach(Path => "/mydata/index.html",
\&                         MIMEType => \*(Aqtext/html\*(Aq,
\&                         Dynamic => 1);
\&
\&                $message\->add_payload($payload);
\&                $message\->add_payload($payload2);
\&
\&                # Print the encoded message to STDOUT
\&                $message\->print(\e*STDOUT);
.Ve
.PP
Parsing \s-1DIME\s0 messages
.PP
.Vb 1
\&        my $parser = DIME::Parser\->new();
\&
\&                # Open a file with a dime encoded message
\&        $f = IO::File\->new("dime.message","r");
\&        my $message = $parser\->parse($f);
\&        $f\->close();
\&
\&                # Print the content of each payload to STDOUT
\&        for my $i ($message\->payloads())
\&        {
\&                print $i\->print_content(\e*STDOUT);
\&        }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
DIME-tools is a collection of \s-1DIME::\s0 modules for parsing and generating \s-1DIME\s0 encoded messages
(Direct Internet Message Encapsulation).
DIME-tools support single-record and chunked payloads for sending big attachments.
.PP
This distribution hasn't been actively developed since 2004.
Subsequent releases have been to get the distribution following \s-1CPAN\s0 conventions,
as there is one distribution depending on it
.SH "GENERATING MESSAGES"
.IX Header "GENERATING MESSAGES"
For any content you want to send in a message, you have to create a Payload object:
.PP
.Vb 4
\&        my $payload = DIME::Payload\->new();
\&        $payload\->attach(Path => "/mydata/index.html",
\&                         MIMEType => \*(Aqtext/html\*(Aq,
\&                         Dynamic => 1);
.Ve
.PP
With the attach method you can specify the next keys:
.IP "\fBPath\fR:" 4
.IX Item "Path:"
the name of the file you want to attach to the payload object.
If the data you want to attach isn't in a file, you can use the Data key.
.IP "\fBData\fR:" 4
.IX Item "Data:"
it's the reference to a scalar in which you store the data you want to attach.
.IP "\fBDynamic\fR:" 4
.IX Item "Dynamic:"
if Path is declared, the data is not loaded fully in memory.
The only that you attach to the payload object is the name of the file of the Path key,
not the content itself.
.IP "\fBChunked\fR:" 4
.IX Item "Chunked:"
if it's declared, it represents the size of the chunk records in bytes.
If you don't declare it, the message will not be chunked.
.IP "\fBMIMEType\fR:" 4
.IX Item "MIMEType:"
the type of the payload. It must be a string with a \s-1MIME\s0 standard type. Other possibility is to use URIType.
.IP "\fBURIType\fR:" 4
.IX Item "URIType:"
specifies an \s-1URI\s0 that defines that type of the content.
.SH "ATTACH A PAYLOAD TO A MESSAGE"
.IX Header "ATTACH A PAYLOAD TO A MESSAGE"
.Vb 2
\&        my $message = DIME::Message\->new();
\&        $message\->add_payload($payload);
.Ve
.SH "PRINT A ENCODED MESSAGE"
.IX Header "PRINT A ENCODED MESSAGE"
.Vb 2
\&        # Print prints to any IO::Handle
\&        $message\->print(\e*STDOUT);
\&
\&        or
\&
\&        # print_data returns a reference to a scalar
\&        print ${$message\->print_data()};
.Ve
.SH "PARSING MESSAGES"
.IX Header "PARSING MESSAGES"
All you have to do is create a DIME::Parser object and call the parse method with a IO::Handle to a \s-1DIME\s0 message. Then you can iterate over the \f(CW$message\fR\->\fBpayloads()\fR array to get the contents of the message:
.PP
.Vb 8
\&        my $parser = DIME::Parser\->new();
\&        $f = IO::File\->new("dime.message","r");
\&        my $message = $parser\->parse($f);
\&        $f\->close();
\&        for my $i ($message\->payloads())
\&        {
\&                print $i\->print_content(\e*STDOUTs);
\&        }
.Ve
.PP
You can also call to parse_data if you have a \s-1DIME\s0 message in a scalar variable:
.PP
.Vb 2
\&        my $dime_message;
\&        my $message = $parser\->parse_data(\e$dime_message);
.Ve
.PP
And call print_content_data if what you want is to get a reference to the content-data.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Direct Internet Message Encapsulation draft:
 http://www.gotdotnet.com/team/xml_wsspecs/dime/dime.htm
.PP
DIME::Message,
DIME::Payload,
DIME::Record.
.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