perldoc > Net::XMPP::Message

man perldoc info pydoc3 ri search

📖 NAME

Net::XMPP::Message - XMPP Message Module

🚀 Quick Reference

Use Case	Command	Description
Create a new message object	Net::XMPP::Message->new()	Create a new message to send to the server
Set message fields	$Mess->SetMessage(to=>..., subject=>..., body=>...)	Set multiple fields in the <message/> tag
Get the ‘to’ attribute	$Mess->GetTo()	Returns the value in the to attribute
Get the ‘from’ attribute	$Mess->GetFrom()	Returns the value in the from attribute
Get the message type	$Mess->GetType()	Returns the type attribute (normal, chat, etc.)
Get the message body	$Mess->GetBody()	Returns the data in the <body/> tag
Get the subject	$Mess->GetSubject()	Returns the data in the <subject/> tag
Get the thread	$Mess->GetThread()	Returns the data in the <thread/> tag
Get error details	$Mess->GetError(), $Mess->GetErrorCode()	Returns error string and error code
Get timestamp	$Mess->GetTimeStamp()	Returns the time the message was created/received
Reply to a message	$Mess->Reply()	Creates a new Message object with to/from swapped and subject prefixed with “re: ”
Remove attributes	$Mess->RemoveTo(), etc.	Remove specific attributes from the message
Test if attribute defined	$Mess->DefinedTo(), etc.	Returns 1 if attribute is defined, 0 otherwise

📋 SYNOPSIS

Net::XMPP::Message is a companion to the Net::XMPP module. It provides the user a simple interface to set and retrieve all parts of an XMPP Message.

📝 DESCRIPTION

A Net::XMPP::Message object is passed to the callback function for the message. Also, the first argument to the callback functions is the session ID from XML::Stream. There are some cases where you might want this information, like if you created a Client that connects to two servers at once, or for writing a mini server.

use Net::XMPP;

sub message {
  my ($sid,$Mess) = @_;
  .
  .
  .
}

You now have access to all of the retrieval functions available.

To create a new message to send to the server:

use Net::XMPP;

$Mess = Net::XMPP::Message->new();

Now you can call the creation functions below to populate the tag before sending it.

⚙️ METHODS

🔍 Retrieval functions

• GetTo() and GetTo("jid") - returns the value in the to='' attribute for the <message/>. If you specify "jid" as an argument then a Net::XMPP::JID object is returned and you can easily parse the parts of the JID.

  $to    = $Mess->GetTo();
  $toJID = $Mess->GetTo("jid");

• GetFrom() and GetFrom("jid") - returns the value in the from='' attribute for the <message/>. If you specify "jid" as an argument then a Net::XMPP::JID object is returned and you can easily parse the parts of the JID.

  $from    = $Mess->GetFrom();
  $fromJID = $Mess->GetFrom("jid");

• GetType() - returns the type='' attribute of the <message/>. Each message is one of four types:
  • normal - regular message (default if type is blank)
  • chat - one on one chat
  • groupchat - multi-person chat
  • headline - headline
  • error - error message

  $type = $Mess->GetType();

• GetSubject() - returns the data in the <subject/> tag.

  $subject = $Mess->GetSubject();

• GetBody() - returns the data in the <body/> tag.

  $body = $Mess->GetBody();

• GetThread() - returns the data in the <thread/> tag.

  $thread = $Mess->GetThread();

• GetError() - returns a string with the data of the <error/> tag.

  $error = $Mess->GetError();

• GetErrorCode() - returns a string with the code='' attribute of the <error/> tag.

  $errCode = $Mess->GetErrorCode();

• GetTimeStamp() - returns a string that represents the time this message object was created (and probably received) for sending to the client. If there is a jabber:x:delay tag then that time is used to show when the message was sent.

  $date = $Mess->GetTimeStamp();

🛠️ Creation functions

• SetMessage(to=>string|JID, from=>string|JID, type=>string, subject=>string, body=>string, thread=>string, errorcode=>string, error=>string) - set multiple fields in the <message/> at one time. This is a cumulative and overwriting action. If you set the to attribute twice, the second setting is what is used. If you set the subject, and then set the body, then both will be in the <message/> tag. For valid settings read the specific Set functions below.

  $Mess->SetMessage(TO=>"bob\@jabber.org",
                    Subject=>"Lunch",
                    BoDy=>"Let's do lunch!");
  $Mess->SetMessage(to=>"bob\@jabber.org",
                    from=>"jabber.org",
                    errorcode=>404,
                    error=>"Not found");

• SetTo(string) and SetTo(JID) - sets the to='' attribute. You can either pass a string or a JID object. They must be valid JIDs or the server will return an error message. (ie. bob@jabber.org/Work)

  $Mess->SetTo("test\@jabber.org");

• SetFrom(string) and SetFrom(JID) - sets the from='' attribute. You can either pass a string or a JID object. They must be valid JIDs or the server will return an error message. (ie. bob@jabber.org/Work) This field is not required if you are writing a Client since the server will put the JID of your connection in there to prevent spamming.

  $Mess->SetFrom("me\@jabber.org");

• SetType(string) - sets the type attribute. Valid settings are:
  • normal - regular message (default if blank)
  • chat - one on one chat style message
  • groupchat - multi-person chatroom message
  • headline - news headline, stock ticker, etc.
  • error - error message

  $Mess->SetType("groupchat");

• SetSubject(string) - sets the subject of the <message/>.

  $Mess->SetSubject("This is a test");

• SetBody(string) - sets the body of the <message/>.

  $Mess->SetBody("To be or not to be...");

• SetThread(string) - sets the thread of the <message/>. You should copy this out of the message being replied to so that the thread is maintained.

  $Mess->SetThread("AE912B3");

• SetErrorCode(string) - sets the error code of the <message/>.

  $Mess->SetErrorCode(403);

• SetError(string) - sets the error string of the <message/>.

  $Mess->SetError("Permission Denied");

• Reply(hash) - creates a new Message object and populates the to/from, and the subject by putting “re: ” in front. If you specify a hash the same as with SetMessage then those values will override the Reply values.

  $Reply = $Mess->Reply();
  $Reply = $Mess->Reply(type=>"chat");

🗑️ Removal functions

• RemoveTo() - removes the to attribute from the <message/>. $Mess->RemoveTo();
• RemoveFrom() - removes the from attribute from the <message/>. $Mess->RemoveFrom();
• RemoveType() - removes the type attribute from the <message/>. $Mess->RemoveType();
• RemoveSubject() - removes the <subject/> element from the <message/>. $Mess->RemoveSubject();
• RemoveBody() - removes the <body/> element from the <message/>. $Mess->RemoveBody();
• RemoveThread() - removes the <thread/> element from the <message/>. $Mess->RemoveThread();
• RemoveError() - removes the <error/> element from the <message/>. $Mess->RemoveError();
• RemoveErrorCode() - removes the code attribute from the <error/> element in the <message/>. $Mess->RemoveErrorCode();

✅ Test functions

• DefinedTo() - returns 1 if the to attribute is defined in the <message/>, 0 otherwise. $test = $Mess->DefinedTo();
• DefinedFrom() - returns 1 if the from attribute is defined in the <message/>, 0 otherwise. $test = $Mess->DefinedFrom();
• DefinedType() - returns 1 if the type attribute is defined in the <message/>, 0 otherwise. $test = $Mess->DefinedType();
• DefinedSubject() - returns 1 if <subject/> is defined in the <message/>, 0 otherwise. $test = $Mess->DefinedSubject();
• DefinedBody() - returns 1 if <body/> is defined in the <message/>, 0 otherwise. $test = $Mess->DefinedBody();
• DefinedThread() - returns 1 if <thread/> is defined in the <message/>, 0 otherwise. $test = $Mess->DefinedThread();
• DefinedErrorCode() - returns 1 if <error/> is defined in the <message/>, 0 otherwise. $test = $Mess->DefinedErrorCode();
• DefinedError() - returns 1 if the code attribute is defined in the <error/>, 0 otherwise. $test = $Mess->DefinedError();

✍️ AUTHOR

Originally authored by Ryan Eatmon.

Previously maintained by Eric Hacker.

Currently maintained by Darian Anthony Patrick.

©️ COPYRIGHT

This module is free software, you can redistribute it and/or modify it under the LGPL 2.1.

📖 NAME 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION ⚙️ METHODS ✍️ AUTHOR ©️ COPYRIGHT