1AnyEvent::XMPP::IM::MesUssaegre(C3o)ntributed Perl DocumAennytEavteinotn::XMPP::IM::Message(3)
2
6 AnyEvent::XMPP::IM::Message - Instant message
7
9 use AnyEvent::XMPP::IM::Message;
10 my $con = AnyEvent::XMPP::IM::Connection->new (...);
12 AnyEvent::XMPP::IM::Message->new (
14 body => "Hello there!",
15 to => "elmex@jabber.org"
16 )->send ($con);
17
19 This module represents an instant message. It's mostly a shortlived
20 object and acts as wrapper object around the XML stuff that is
21 happening under the hood.
22 A AnyEvent::XMPP::IM::Message object overloads the stringification
24 operation. The string represenation of this object is the return value
25 of the "any_body" method.
26 AnyEvent::XMPP::IM::Message is derived from
28 AnyEvent::XMPP::IM::Delayed, use the interface described there to find
29 out whether this message was delayed.
30
32 new (%args)
33 This method creates a new instance of a
34 AnyEvent::XMPP::IM::Message.
35 %args is the argument hash. All arguments to "new" are optional.
37 These are the possible keys:
39 connection => $connection
41 This is the AnyEvent::XMPP::IM::Connection object that will be
42 used to send this message when the "send" method is called.
43 to => $jid
45 This is the destination JID of this message. $jid should be
46 full if this message is send within a conversation 'context',
47 for example when replying to a previous message.
48 Replies can also be generated by the "make_reply" method, see
50 also the "from" argument below.
51 from => $jid
53 This is the source JID of this message, it's mainly used by the
54 "make_reply" method.
55 lang => $lang
57 This is the default language that will be used to tag the
58 values passed in the "body" and "subject" argument to "new".
59 body => $body
61 This is the text $body of the message either with the language
62 tag from the "lang" attached or without any language tag.
63 If you want to attach multiple bodies with different languages
65 use the "add_body" method.
66 subject => $subject
68 This is the $subject of the message either with the language
69 tag from the "lang" attached or without any language tag.
70 If you want to attach the subject with a different language use
72 the "add_subject" method.
73 type => $type
75 This field sets the type of the message. See also the type
76 method below.
77 The default value for $type is 'normal'.
79 id ([$msg_id])
81 This method returns the ID of this message. If $msg_id is not
82 undef it will replace the current message id.
83 from ([$jid])
85 This method returns the source JID of this message. If $jid is not
86 undef it will replace the current source address.
87 to ([$jid])
89 This method returns the destination JID of this message. If $jid
90 is not undef it will replace the current destination address.
91 make_reply ([$msg])
93 This method returns a new instance of AnyEvent::XMPP::IM::Message.
94 The destination address, connection and type of the returned
95 message object will be set.
96 If $msg is defined and an instance of AnyEvent::XMPP::IM::Message
98 the destination address, connection and type of $msg will be
99 changed and this method will not return a new instance of
100 AnyEvent::XMPP::IM::Message.
101 is_connected ()
103 This method returns 1 when the message is "connected". That means:
104 It returns 1 when you can call the "send" method without a
105 connection argument. (It will also return only 1 when the
106 connection that is referenced by this message is still connected).
107 send ([$connection])
109 This method send this message. If $connection is defined it will
110 set the connection of this message object before it is send.
111 type ([$type])
113 This method returns the type of the message, which is either
114 undefined or one of the following values:
115 'chat', 'error', 'groupchat', 'headline', 'normal'
117 If the $type argument is defined it will set the type of this
119 message.
120 thread ([$thread])
122 This method returns the thread id of this message, which might be
123 undefined.
124 If you want to set the threadid simply pass the $thread argument.
126 lang ([$lang])
128 This returns the default language tag of this message, which can be
129 undefined.
130 To set the language tag pass the $lang argument, which should be
132 the new default language tag.
133 If you do not want to specify any language pass the empty string as
135 language tag.
136 subject ([$lang])
138 This method returns the subject of this message. If the $lang
139 argument is defined a subject of that language will be returned or
140 undef. If the $lang argument is undefined this method will return
141 either the subject in the default language.
142 any_subject ([$lang])
144 This method will try to find any subject on the message with the
145 following try order of languagetags:
146 1. $lang argument if one passed
148 2. default language
149 3. subject without any language tag
150 4. subject with the 'en' language tag
151 5. any subject from any language
152 add_subject ($subject, [$lang], [$subject2, $lang2, ...])
154 This method adds the subject $subject with the optional language
155 tag $lang to this message. If no $lang argument is passed the
156 default language for this message will be used.
157 Further subject => lang pairs can passed to this function like
159 this:
160 $msg->add_subject ('foobar' => undef, "barfooo" => "de");
162 subjects
164 This method returns a list of key value pairs with the language tag
165 as key and the subject as value.
166 The subject which has the empty string as key has no language
168 attached.
169 body ([$lang])
171 This method returns the body of this message. If the $lang
172 argument is defined a body of that language will be returned or
173 undef. If the $lang argument is undefined this method will return
174 either the body in the default language.
175 any_body ([$lang])
177 This method will try to find any body on the message with the
178 following try order of languagetags:
179 1. $lang argument if one passed
181 2. default language
182 3. body without any language tag
183 4. body with the 'en' language tag
184 5. any body from any language
185 add_body ($body, [$lang], [$body2, $lang2, ...])
187 This method adds the body $body with the optional language tag
188 $lang to this message. If no $lang argument is passed the default
189 language for this message will be used.
190 Further body => lang pairs can passed to this function like this:
192 $msg->add_body ('foobar' => undef, "barfooo" => "de");
194 bodies
196 This method returns a list of key value pairs with the language tag
197 as key and the body as value.
198 The body which has the empty string as key has no language
200 attached.
201 append_creation ($create_cb)
203 This method allows the user to append custom XML stuff to the
204 message when it is sent. This is an example:
205 my $msg =
207 AnyEvent::XMPP::IM::Message->new (
208 body => "Test!",
209 to => "test@test.tld",
210 );
211 $msg->append_creation (sub {
212 my ($w) = @_;
213 $w->startTag (['http://test.namespace','test']);
214 $w->characters ("TEST");
215 $w->endTag;
216 });
217 $msg->send ($con);
219 This should send a message stanza similar to this:
221
223 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
224
226 Copyright 2007, 2008 Robin Redeker, all rights reserved.
227 This program is free software; you can redistribute it and/or modify it
229 under the same terms as Perl itself.
230perl v5.12.0 2009-08-14 AnyEvent::XMPP::IM::Message(3)