NAME

SYNOPSIS

   use Net::XMPP2::IM::Message;

   my $con = Net::XMPP2::IM::Connection->new (...);

   Net::XMPP2::IM::Message->new (
      body => "Hello there!",
      to   => "elmex@jabber.org"
   )->send ($con);

DESCRIPTION

A Net::XMPP2::IM::Message object overloads the stringification operation. The string represenation of this object is the return value of the "any_body" method.

Net::XMPP2::IM::Message is derived from Net::XMPP2::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 Net::XMPP2::IM::Message.

%args is the argument hash. All arguments to "new" are optional.

These are the possible keys:

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 Net::XMPP2::IM::Message. The destination address, connection and type of the returned message object will be set.

If $msg is defined and an instance of Net::XMPP2::IM::Message the destination address, connection and type of $msg will be changed and this method will not return a new instance of Net::XMPP2::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 =
      Net::XMPP2::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

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.