DIME::Payload(3pm)

💖 DIME::Payload 💖

ok so bestie, welcome to DIME::Payload, a little module from the User Contributed Perl Documentation corner of the world (the manual page is literally called DIME::Payload(3pm), iykyk). It's the implementation of a payload of a DIME message, and honestly? she's iconic.

---

✨ NAME ✨

DIME::Payload — implementation of a payload of a DIME message 🎀

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready:

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

  use DIME::Payload;

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

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

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

like yes, that's the whole flow, slay 💅

---

🦋 DESCRIPTION 🦋

DIME::Payload represents the content of a DIME message. A message is composed of one or many Payload objects — so think of it like, one payload is a single baddie, and a whole message is the entire friend group ✨

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. (yes the grammar is doing its own thing, we don't gatekeep 🌈)

---

🎀 CHUNKED AND DYNAMIC CONTENT 🎀

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

        # This create a dynamic payload with records of 16384 bytes

        my $payload = DIME::Payload->new();
        $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. 👑

ngl, that's the whole tea: Dynamic = lazy-loading era, no Dynamic = everything in RAM at once. choose wisely bestie 💀

---

🌈 CONTENT TYPE 🌈

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

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

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

one key for the MIME media-type, one key for the absolute URI — pick your fighter 💜

---

⭐ 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 = DIME::Payload->new();
        print $payload->id();

not her generating her own unique identifier on creation, main character energy fr fr 🫶

---

💜 AUTHOR 💜

Domingo Alcazar Larrea, <dalcazar@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

Copyright (C) 2004 Domingo Alcázar 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

---

ok that's the whole page bestie, ily, go forth and payload 💖✨🎀🦋🌸💅🫶

and for the cute sign-off: this whole thing is running under perl v5.32.1, dated 2021-03-22, and it's the DIME::Payload(3pm) manual — mwah, periodt 💅