Net::DB...:Message(3)

📦
version 1.2.0 · 12 versions
, in opensuse-leap 16.0

💖 Net::DBus::Binding::Message — the base class for messages, bestie 💖

okay so real talk, this page is Net::DB...:Message(3) from the User Contributed Perl Documentation, and it's basically the mother of all message objects. she's the blueprint, the blueprint that never gets instantiated directly, iykyk 🎀

✨ NAME ✨

Net::DBus::Binding::Message — the base class for messages. that's it, that's her whole job. queen of being a foundation 💅

🌸 SYNOPSIS 🌸

here's the vibe — sending a message, in all her glory:

  my $msg = new Net::DBus::Binding::Message::Signal;
  my $iterator = $msg->iterator;

  $iterator->append_byte(132);
  $iterator->append_int32(14241);

  $connection->send($msg);

look at her go. no notes. 🔥

🦋 DESCRIPTION 🦋

okay so this class is the base class for all the different kinds of message that can be sent and received on the bus. she's the parent, the origin story, the main character energy of the whole message family.

but here's the thing — and this is important, bestie — instances of this class are never instantiated directly. never ever. instead you use one of the four sub-types:

  • Net::DBus::Binding::Message::Signal
  • Net::DBus::Binding::Message::MethodCall
  • Net::DBus::Binding::Message::MethodReturn
  • Net::DBus::Binding::Message::Error

those are the ones you actually build. this one's just the blueprint. periodt. 💀

👑 CONSTANTS 👑

these constants live in this module, but heads up — they are not exported into the caller's namespace, so you gotta reference them with their fully qualified package names. no shortcuts, no import, just the full name or nothing. 🫶

  • TYPE_ARRAY — the signature value for the array data type
  • TYPE_BOOLEAN — the signature value for the boolean data type
  • TYPE_BYTE — the signature value for the byte data type
  • TYPE_DICT_ENTRY — the signature value for the dictionary entry data type
  • TYPE_DOUBLE — the signature value for the IEEE double precision floating point data type
  • TYPE_INT16 — the signature value for the signed 16 bit integer data type
  • TYPE_INT32 — the signature value for the signed 32 bit integer data type
  • TYPE_INT64 — the signature value for the signed 64 bit integer data type
  • TYPE_OBJECT_PATH — the signature value for the object path data type
  • TYPE_STRING — the signature value for the UTF-8 string data type
  • TYPE_SIGNATURE — the signature value for the signature data type
  • TYPE_STRUCT — the signature value for the struct data type
  • TYPE_UINT16 — the signature value for the unsigned 16 bit integer data type
  • TYPE_UINT32 — the signature value for the unsigned 32 bit integer data type
  • TYPE_UINT64 — the signature value for the unsigned 64 bit integer data type
  • TYPE_VARIANT — the signature value for the variant data type
  • TYPE_UNIX_FD — the signature value for the unix file descriptor data type

that's the whole squad. seventeen icons, all accounted for. 🧚

💜 METHODS 💜

💖 my $msg = Net::DBus::Binding::Message->new(message => $rawmessage);

creates a new message object, initializing it with the underlying C message object given by the "message" object.

ok so this one is intended for internal use only — do not come for her. instead, refer to one of the four sub-types of this class for your specific message type. fr fr, don't @ me if you use this directly. 🙈

💖 my $type = $msg->get_type

gets the type code for this message. whatever comes back corresponds to one of the four "Net::DBus::Binding::Message::MESSAGE_TYPE_*" constants. iykyk.

💖 my $interface = $msg->get_interface

retrieves the name of the interface targeted by this message — and it might be an empty string if there's no applicable interface for this message. no interface, no problem. 😭

💖 my $path = $msg->get_path

retrieves the object path associated with the message. possibly an empty string if there's no applicable object for this message. same deal.

💖 my $name = $msg->get_destination

retrieves the unique or well-known bus name for the client that's intended to be the recipient of the message. possibly returns an empty string if the message is being broadcast to all clients. everybody gets a slice 🍓

💖 my $name = $msg->get_sender

retrieves the unique name of the client sending the message. that's the sender, the one who sent it, the origin. 💅

💖 my $serial = $msg->get_serial

retrieves the unique serial number of this message. and it's guaranteed unique for as long as the connection over which the message was sent remains open. may return zero if the message is yet to be sent — so a zero means "not yet, babe". ⭐

💖 my $name = $msg->get_member

for method calls, retrieves the name of the method to be invoked. for signals, retrieves the name of the signal. dual purpose icon. 🌈

💖 my $sig = $msg->get_signature

retrieves a string representing the type signature of the values packed into the body of the message. basically the receipts for what's inside. 🎀

💖 $msg->set_sender($name)

sets the name of the client sending the message. and the name must be the unique name of the client — non-negotiable, bestie.

💖 $msg->set_destination($name)

sets the name of the intended recipient of the message. this is typically used for signals to switch them from broadcast to unicast. glow-up from "everyone" to "just you" 💌

💖 my $iterator = $msg->iterator;

retrieves an iterator you can use for reading or writing fields of the message. the returned object is an instance of the "Net::DBus::Binding::Iterator" class. she's the one who handles the actual touching. 🦋

💖 $boolean = $msg->get_no_reply()

gets the flag that says whether the message is expecting a reply to be sent.

💖 $msg->set_no_reply($boolean)

toggles that flag — the one saying whether the message is expecting a reply to be sent. all method call messages expect a reply by default. by toggling this flag you reduce communication latency by removing the need for the client to wait. speedrun strats 🔥

💖 my @values = $msg->get_args_list

de-marshalls all the values in the body of the message, using the message signature to identify data types. the values come back as a list. unpacking the haul 🎁

💖 $msg->append_args_list(@values)

appends a set of values to the body of the message. values get encoded as either a string, list or dictionary as appropriate to their Perl data type. for more specific data typing needs, use the Net::DBus::Binding::Iterator object instead. no cap, that's the move. 💯

🌟 AUTHOR 🌟

Daniel P. Berrange — the legend, the icon, the moment. 👑

Copyright (C) 2004-2011 Daniel P. Berrange

🌈 SEE ALSO 🌈

go read these next, bestie, they're all connected:

  • Net::DBus::Binding::Server
  • Net::DBus::Binding::Connection
  • Net::DBus::Binding::Message::Signal
  • Net::DBus::Binding::Message::MethodCall
  • Net::DBus::Binding::Message::MethodReturn
  • Net::DBus::Binding::Message::Error

and that's the whole page, bestie — you ate that 💅✨

this lil masterpiece is perl v5.42.0, dated 2019-12-17, and appears on page Net::DB...:Message(3). go forth and send messages responsibly 🫶💖

📦 where this page comes from