.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Net::XMPP::Message 3pm"
.TH Net::XMPP::Message 3pm 2025-12-14 "perl v5.42.0" "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
Net::XMPP::Message \- XMPP Message Module
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  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.
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
.Vb 5
\&  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 thisinformation, 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.
.Ve
.SH METHODS
.IX Header "METHODS"
.SS "Retrieval functions"
.IX Subsection "Retrieval functions"
.Vb 4
\&  GetTo()      \- returns the value in the to=\*(Aq\*(Aq attribute for the
\&  GetTo("jid")   <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()      \- returns the value in the from=\*(Aq\*(Aq attribute for the
\&  GetFrom("jid")   <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=\*(Aq\*(Aq 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=\*(Aq\*(Aq 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();
.Ve
.SS "Creation functions"
.IX Subsection "Creation functions"
.Vb 9
\&  SetMessage(to=>string|JID,    \- set multiple fields in the <message/>
\&             from=>string|JID,    at one time.  This is a cumulative
\&             type=>string,        and over writing action.  If you set
\&             subject=>string,     the "to" attribute twice, the second
\&             body=>string,        setting is what is used.  If you set
\&             thread=>string,      the subject, and then set the body
\&             errorcode=>string,   then both will be in the <message/>
\&             error=>string)       tag.  For valid settings read the
\&                                  specific Set functions below.
\&
\&                            $Mess\->SetMessage(TO=>"bob\e@jabber.org",
\&                                              Subject=>"Lunch",
\&                                              BoDy=>"Let\*(Aqs do lunch!");
\&                            $Mess\->SetMessage(to=>"bob\e@jabber.org",
\&                                              from=>"jabber.org",
\&                                              errorcode=>404,
\&                                              error=>"Not found");
\&
\&  SetTo(string) \- sets the to=\*(Aq\*(Aq attribute.  You can either pass
\&  SetTo(JID)      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\e@jabber.org");
\&
\&  SetFrom(string) \- sets the from=\*(Aq\*(Aq attribute.  You can either pass
\&  SetFrom(JID)      a string or a JID object.  They must be valid JIDs
\&                    or the server will return an error message. (ie.
\&                    jabber: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\e@jabber.org");
\&
\&  SetType(string) \- sets the type attribute.  Valid settings are:
\&
\&                      normal         regular message (default if blank)
\&                      chat           one one 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");
.Ve
.SS "Removal functions"
.IX Subsection "Removal functions"
.Vb 1
\&  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();
.Ve
.SS "Test functions"
.IX Subsection "Test functions"
.Vb 2
\&  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();
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Originally authored by Ryan Eatmon.
.PP
Previously maintained by Eric Hacker.
.PP
Currently maintained by Darian Anthony Patrick.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
This module is free software, you can redistribute it and/or modify it
under the LGPL 2.1.