--- name: "AnyEvent::XMPP::IM::Message" section: "3pm" platform: "linux" package: "perl-anyevent-xmpp" version: "0.55-7" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/AnyEvent::XMPP::IM::Message" --- # AnyEvent::XMPP::IM::Message(3pm) Instant message ## NAME AnyEvent::XMPP::IM::Message - Instant message ## SYNOPSIS ``` 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); ``` ## 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. A AnyEvent::XMPP::IM::Message object overloads the stringification operation. The string represenation of this object is the return value of the `"any_body"` method. AnyEvent::XMPP::IM::Message is derived from AnyEvent::XMPP::IM::Delayed, use the interface described there to find out whether this message was delayed. ## METHODS - **new (%args)** This method creates a new instance of a AnyEvent::XMPP::IM::Message. `%args` is the argument hash. All arguments to `"new"` are optional. These are the possible keys: - connection =\> $connection This is the AnyEvent::XMPP::IM::Connection object that will be used to send this message when the `"send"` method is called. - to =\> $jid This is the destination JID of this message. `$jid` should be full if this message is send within a conversation 'context', for example when replying to a previous message. Replies can also be generated by the `"make_reply"` method, see also the `"from"` argument below. - from =\> $jid This is the source JID of this message, it's mainly used by the `"make_reply"` method. - lang =\> $lang This is the default language that will be used to tag the values passed in the `"body"` and `"subject"` argument to `"new"`. - body =\> $body This is the text `$body` of the message either with the language tag from the `"lang"` attached or without any language tag. If you want to attach multiple bodies with different languages use the `"add_body"` method. - subject =\> $subject This is the `$subject` of the message either with the language tag from the `"lang"` attached or without any language tag. If you want to attach the subject with a different language use the `"add_subject"` method. - type =\> $type This field sets the type of the message. See also the type method below. The default value for `$type` is 'normal'. - **id (\[$msg\_id\])** This method returns the ID of this message. If `$msg_id` is not undef it will replace the current message id. - **from (\[$jid\])** This method returns the source JID of this message. If `$jid` is not undef it will replace the current source address. - **to (\[$jid\])** This method returns the destination JID of this message. If `$jid` is not undef it will replace the current destination address. - **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. If `$msg` is defined and an instance of AnyEvent::XMPP::IM::Message the destination address, connection and type of `$msg` will be changed and this method will not return a new instance of AnyEvent::XMPP::IM::Message. - **is\_connected ()** This method returns 1 when the message is "connected". That means: It returns 1 when you can call the `"send"` method without a connection argument. (It will also return only 1 when the connection that is referenced by this message is still connected). - **send (\[$connection\])** This method send this message. If `$connection` is defined it will set the connection of this message object before it is send. - **type (\[$type\])** This method returns the type of the message, which is either undefined or one of the following values: ``` 'chat', 'error', 'groupchat', 'headline', 'normal' ``` If the `$type` argument is defined it will set the type of this message. - **thread (\[$thread\])** This method returns the thread id of this message, which might be undefined. If you want to set the threadid simply pass the `$thread` argument. - **lang (\[$lang\])** This returns the default language tag of this message, which can be undefined. To set the language tag pass the `$lang` argument, which should be the new default language tag. If you do not want to specify any language pass the empty string as language tag. - **subject (\[$lang\])** This method returns the subject of this message. If the `$lang` argument is defined a subject of that language will be returned or undef. If the `$lang` argument is undefined this method will return either the subject in the default language. - **any\_subject (\[$lang\])** This method will try to find any subject on the message with the following try order of languagetags: ``` 1. $lang argument if one passed 2. default language 3. subject without any language tag 4. subject with the 'en' language tag 5. any subject from any language ``` - **add\_subject ($subject, \[$lang\], \[$subject2, $lang2, ...\])** This method adds the subject `$subject` with the optional language tag `$lang` to this message. If no `$lang` argument is passed the default language for this message will be used. Further subject =\> lang pairs can passed to this function like this: ``` $msg->add_subject ('foobar' => undef, "barfooo" => "de"); ``` - **subjects** This method returns a list of key value pairs with the language tag as key and the subject as value. The subject which has the empty string as key has no language attached. - **body (\[$lang\])** This method returns the body of this message. If the `$lang` argument is defined a body of that language will be returned or undef. If the `$lang` argument is undefined this method will return either the body in the default language. - **any\_body (\[$lang\])** This method will try to find any body on the message with the following try order of languagetags: ``` 1. $lang argument if one passed 2. default language 3. body without any language tag 4. body with the 'en' language tag 5. any body from any language ``` - **add\_body ($body, \[$lang\], \[$body2, $lang2, ...\])** This method adds the body `$body` with the optional language tag `$lang` to this message. If no `$lang` argument is passed the default language for this message will be used. Further body =\> lang pairs can passed to this function like this: ``` $msg->add_body ('foobar' => undef, "barfooo" => "de"); ``` - **bodies** This method returns a list of key value pairs with the language tag as key and the body as value. The body which has the empty string as key has no language attached. - **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: ``` my $msg = AnyEvent::XMPP::IM::Message->new ( body => "Test!", to => "test@test.tld", ); $msg->append_creation (sub { my ($w) = @_; $w->startTag (['http://test.namespace','test']); $w->characters ("TEST"); $w->endTag; }); $msg->send ($con); ``` This should send a message stanza similar to this: ## AUTHOR Robin Redeker, `""`, JID: `""` ## COPYRIGHT & LICENSE Copyright 2007, 2008 Robin Redeker, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.