.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "AnyEvent::XMPP::IM::Message 3"
.TH AnyEvent::XMPP::IM::Message 3 2024-07-13 "perl v5.38.2" "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
AnyEvent::XMPP::IM::Message \- Instant message
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&   use AnyEvent::XMPP::IM::Message;
\&
\&   my $con = AnyEvent::XMPP::IM::Connection\->new (...);
\&
\&   AnyEvent::XMPP::IM::Message\->new (
\&      body => "Hello there!",
\&      to   => "elmex@jabber.org"
\&   )\->send ($con);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module represents an instant message. It's mostly
a shortlived object and acts as wrapper object around the
XML stuff that is happening under the hood.
.PP
A AnyEvent::XMPP::IM::Message object overloads the stringification
operation. The string represenation of this object is the return
value of the \f(CW\*(C`any_body\*(C'\fR method.
.PP
AnyEvent::XMPP::IM::Message is derived from AnyEvent::XMPP::IM::Delayed,
use the interface described there to find out whether this message was delayed.
.SH METHODS
.IX Header "METHODS"
.IP "\fBnew (%args)\fR" 4
.IX Item "new (%args)"
This method creates a new instance of a AnyEvent::XMPP::IM::Message.
.Sp
\&\f(CW%args\fR is the argument hash. All arguments to \f(CW\*(C`new\*(C'\fR are optional.
.Sp
These are the possible keys:
.RS 4
.ie n .IP "connection => $connection" 4
.el .IP "connection => \f(CW$connection\fR" 4
.IX Item "connection => $connection"
This is the AnyEvent::XMPP::IM::Connection object that will
be used to send this message when the \f(CW\*(C`send\*(C'\fR method is called.
.ie n .IP "to => $jid" 4
.el .IP "to => \f(CW$jid\fR" 4
.IX Item "to => $jid"
This is the destination JID of this message.
\&\f(CW$jid\fR should be full if this message is send within a conversation
\&'context', for example when replying to a previous message.
.Sp
Replies can also be generated by the \f(CW\*(C`make_reply\*(C'\fR method, see also
the \f(CW\*(C`from\*(C'\fR argument below.
.ie n .IP "from => $jid" 4
.el .IP "from => \f(CW$jid\fR" 4
.IX Item "from => $jid"
This is the source JID of this message, it's mainly
used by the \f(CW\*(C`make_reply\*(C'\fR method.
.ie n .IP "lang => $lang" 4
.el .IP "lang => \f(CW$lang\fR" 4
.IX Item "lang => $lang"
This is the default language that will be used to tag the values
passed in the \f(CW\*(C`body\*(C'\fR and \f(CW\*(C`subject\*(C'\fR argument to \f(CW\*(C`new\*(C'\fR.
.ie n .IP "body => $body" 4
.el .IP "body => \f(CW$body\fR" 4
.IX Item "body => $body"
This is the text \f(CW$body\fR of the message either with the language
tag from the \f(CW\*(C`lang\*(C'\fR attached or without any language tag.
.Sp
If you want to attach multiple bodies with different languages use the \f(CW\*(C`add_body\*(C'\fR
method.
.ie n .IP "subject => $subject" 4
.el .IP "subject => \f(CW$subject\fR" 4
.IX Item "subject => $subject"
This is the \f(CW$subject\fR of the message either with the language
tag from the \f(CW\*(C`lang\*(C'\fR attached or without any language tag.
.Sp
If you want to attach the subject with a different language use the \f(CW\*(C`add_subject\*(C'\fR
method.
.ie n .IP "type => $type" 4
.el .IP "type => \f(CW$type\fR" 4
.IX Item "type => $type"
This field sets the type of the message. See also the type method below.
.Sp
The default value for \f(CW$type\fR is 'normal'.
.RE
.RS 4
.RE
.IP "\fBid ([$msg_id])\fR" 4
.IX Item "id ([$msg_id])"
This method returns the ID of this message.
If \f(CW$msg_id\fR is not undef it will replace the current
message id.
.IP "\fBfrom ([$jid])\fR" 4
.IX Item "from ([$jid])"
This method returns the source JID of this message.
If \f(CW$jid\fR is not undef it will replace the current
source address.
.IP "\fBto ([$jid])\fR" 4
.IX Item "to ([$jid])"
This method returns the destination JID of this message.
If \f(CW$jid\fR is not undef it will replace the current
destination address.
.IP "\fBmake_reply ([$msg])\fR" 4
.IX Item "make_reply ([$msg])"
This method returns a new instance of AnyEvent::XMPP::IM::Message.
The destination address, connection and type of the returned message
object will be set.
.Sp
If \f(CW$msg\fR is defined and an instance of AnyEvent::XMPP::IM::Message
the destination address, connection and type of \f(CW$msg\fR will be changed
and this method will not return a new instance of AnyEvent::XMPP::IM::Message.
.IP "\fBis_connected ()\fR" 4
.IX Item "is_connected ()"
This method returns 1 when the message is "connected".
That means: It returns 1 when you can call the \f(CW\*(C`send\*(C'\fR method
without a connection argument. (It will also return only 1 when
the connection that is referenced by this message is still
connected).
.IP "\fBsend ([$connection])\fR" 4
.IX Item "send ([$connection])"
This method send this message. If \f(CW$connection\fR
is defined it will set the connection of this
message object before it is send.
.IP "\fBtype ([$type])\fR" 4
.IX Item "type ([$type])"
This method returns the type of the message, which
is either undefined or one of the following values:
.Sp
.Vb 1
\&   \*(Aqchat\*(Aq, \*(Aqerror\*(Aq, \*(Aqgroupchat\*(Aq, \*(Aqheadline\*(Aq, \*(Aqnormal\*(Aq
.Ve
.Sp
If the \f(CW$type\fR argument is defined it will set the type
of this message.
.IP "\fBthread ([$thread])\fR" 4
.IX Item "thread ([$thread])"
This method returns the thread id of this message,
which might be undefined.
.Sp
If you want to set the threadid simply pass the \f(CW$thread\fR
argument.
.IP "\fBlang ([$lang])\fR" 4
.IX Item "lang ([$lang])"
This returns the default language tag of this message,
which can be undefined.
.Sp
To set the language tag pass the \f(CW$lang\fR argument, which
should be the new default language tag.
.Sp
If you do not want to specify any language pass the empty
string as language tag.
.IP "\fBsubject ([$lang])\fR" 4
.IX Item "subject ([$lang])"
This method returns the subject of this message.
If the \f(CW$lang\fR argument is defined a subject of that
language will be returned or undef.
If the \f(CW$lang\fR argument is undefined this method will
return either the subject in the default language.
.IP "\fBany_subject ([$lang])\fR" 4
.IX Item "any_subject ([$lang])"
This method will try to find any subject on the message with the
following try order of languagetags:
.Sp
.Vb 5
\&  1. $lang argument if one passed
\&  2. default language
\&  3. subject without any language tag
\&  4. subject with the \*(Aqen\*(Aq language tag
\&  5. any subject from any language
.Ve
.ie n .IP "\fBadd_subject ($subject, [$lang], [$subject2, \fR\fB$lang2\fR\fB, ...])\fR" 4
.el .IP "\fBadd_subject ($subject, [$lang], [$subject2, \fR\f(CB$lang2\fR\fB, ...])\fR" 4
.IX Item "add_subject ($subject, [$lang], [$subject2, $lang2, ...])"
This method adds the subject \f(CW$subject\fR with the optional
language tag \f(CW$lang\fR to this message. If no \f(CW$lang\fR
argument is passed the default language for this message will be used.
.Sp
Further subject => lang pairs can passed to this function like this:
.Sp
.Vb 1
\&   $msg\->add_subject (\*(Aqfoobar\*(Aq => undef, "barfooo" => "de");
.Ve
.IP \fBsubjects\fR 4
.IX Item "subjects"
This method returns a list of key value pairs
with the language tag as key and the subject as value.
.Sp
The subject which has the empty string as key has no
language attached.
.IP "\fBbody ([$lang])\fR" 4
.IX Item "body ([$lang])"
This method returns the body of this message.
If the \f(CW$lang\fR argument is defined a body of that
language will be returned or undef.
If the \f(CW$lang\fR argument is undefined this method will
return either the body in the default language.
.IP "\fBany_body ([$lang])\fR" 4
.IX Item "any_body ([$lang])"
This method will try to find any body on the message with the
following try order of languagetags:
.Sp
.Vb 5
\&  1. $lang argument if one passed
\&  2. default language
\&  3. body without any language tag
\&  4. body with the \*(Aqen\*(Aq language tag
\&  5. any body from any language
.Ve
.ie n .IP "\fBadd_body ($body, [$lang], [$body2, \fR\fB$lang2\fR\fB, ...])\fR" 4
.el .IP "\fBadd_body ($body, [$lang], [$body2, \fR\f(CB$lang2\fR\fB, ...])\fR" 4
.IX Item "add_body ($body, [$lang], [$body2, $lang2, ...])"
This method adds the body \f(CW$body\fR with the optional
language tag \f(CW$lang\fR to this message. If no \f(CW$lang\fR
argument is passed the default language for this message will be used.
.Sp
Further body => lang pairs can passed to this function like this:
.Sp
.Vb 1
\&   $msg\->add_body (\*(Aqfoobar\*(Aq => undef, "barfooo" => "de");
.Ve
.IP \fBbodies\fR 4
.IX Item "bodies"
This method returns a list of key value pairs
with the language tag as key and the body as value.
.Sp
The body which has the empty string as key has no
language attached.
.IP "\fBappend_creation ($create_cb)\fR" 4
.IX Item "append_creation ($create_cb)"
This method allows the user to append custom XML stuff to the message
when it is sent. This is an example:
.Sp
.Vb 11
\&   my $msg =
\&      AnyEvent::XMPP::IM::Message\->new (
\&         body => "Test!",
\&         to => "test@test.tld",
\&      );
\&   $msg\->append_creation (sub {
\&      my ($w) = @_;
\&      $w\->startTag ([\*(Aqhttp://test.namespace\*(Aq,\*(Aqtest\*(Aq]);
\&      $w\->characters ("TEST");
\&      $w\->endTag;
\&   });
\&
\&   $msg\->send ($con);
.Ve
.Sp
This should send a message stanza similar to this:
.SH AUTHOR
.IX Header "AUTHOR"
Robin Redeker, \f(CW\*(C`<elmex at ta\-sa.org>\*(C'\fR, JID: \f(CW\*(C`<elmex at jabber.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2007, 2008 Robin Redeker, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.