NAME

Net::XMPP2::Util - Utility functions for Net::XMPP2

SYNOPSIS

use Net::XMPP2::Util qw/split_jid/;
...

FUNCTIONS

These functions can be exported if you want:

resourceprep ($string)

This function applies the stringprep profile for resources to $string and returns the result.

nodeprep ($string)

This function applies the stringprep profile for nodes to $string and returns the result.

prep_join_jid ($node, $domain, $resource)

This function joins the parts $node, $domain and $resource to a full jid and applies stringprep profiles. If the profiles couldn't be applied undef will be returned.

join_jid ($user, $domain, $resource)

This is a plain concatenation of $user, $domain and $resource without stringprep.

See also prep_join_jid

split_jid ($jid)

This function splits up the $jid into user/node, domain and resource part and will return them as list.

my ($user, $host, $res) = split_jid ($jid);

node_jid ($jid)

See prep_res_jid below.

domain_jid ($jid)

See prep_res_jid below.

res_jid ($jid)

See prep_res_jid below.

prep_node_jid ($jid)

See prep_res_jid below.

prep_domain_jid ($jid)

See prep_res_jid below.

prep_res_jid ($jid)

These functions return the corresponding parts of a JID. The prep_ prefixed JIDs return the stringprep'ed versions.

stringprep_jid ($jid)

This applies stringprep to all parts of the jid according to the RFC 3920. Use this if you want to compare two jids like this:

stringprep_jid ($jid_a) eq stringprep_jid ($jid_b)

This function returns undef if the $jid couldn't successfully be parsed and the preparations done.

cmp_jid ($jid1, $jid2)

This function compares two jids $jid1 and $jid2 whether they are equal.

prep_bare_jid ($jid)

This function makes the jid $jid a bare jid, meaning: it will strip off the resource part. With stringprep.

bare_jid ($jid)

This function makes the jid $jid a bare jid, meaning: it will strip off the resource part. But without stringprep.

is_bare_jid ($jid)

This method returns a boolean which indicates whether $jid is a bare JID.

filter_xml_chars ($string)

This function removes all characters from $string which are not allowed in XML and returns the new string.

filter_xml_attr_hash_chars ($hashref)

This runs all values of the $hashref through filter_xml_chars (see above) and changes them in-place!

simxml ($w, %xmlstruct)

This function takes a XML::Writer as first argument ($w) and the rest key value pairs:

simxml ($w,
   defns    => '<xmlnamespace>',
   node     => <node>,
   prefixes => { prefix => namespace, ... },
);

Where node is:

<node> := {
             ns => '<xmlnamespace>',
             name => 'tagname',
             attrs => [ ['name', 'value'], ... ],
             childs => [ <node>, ... ]
          }
        | {
             dns => '<xmlnamespace>',  # this will set that namespace to
                                       # the default namespace before using it.
             name => 'tagname',
             attrs => [ ['name', 'value'], ... ],
             childs => [ <node>, ... ]
          }
        | "textnode"

Please note: childs stands for child sequence :-)

Also note that if you omit the ns key for nodes there is a fallback to the namespace of the parent element or the last default namespace. This makes it easier to write things like this:

{
   defns => 'muc_owner,
   node => { name => 'query' }
}

(Without having to include ns in the node.)

Please note that all attribute values and character data will be filtered by filter_xml_chars.

to_xmpp_time ($sec, $min, $hour, $tz, $secfrac)

This function transforms a time to the XMPP date time format. The meanings and value ranges of $sec, ..., $hour are explained in the perldoc of Perl's builtin localtime.

$tz has to be either "UTC" or of the form [+-]hh:mm, it can be undefined and wont occur in the time string then.

$secfrac are optional and can be the fractions of the second.

See also XEP-0082.

to_xmpp_datetime ($sec,$min,$hour,$mday,$mon,$year,$tz, $secfrac)

This function transforms a time to the XMPP date time format. The meanings of $sec, ..., $year are explained in the perldoc of Perl's localtime builtin and have the same value ranges.

$tz has to be either "UTC" or of the form [+-]hh:mm, if it is undefined "UTC" will be used.

$secfrac are optional and can be the fractions of the second.

See also XEP-0082.

from_xmpp_datetime ($string)

This function transforms the $string which is either a time or datetime in XMPP format. If the string was not in the right format an empty list is returned. Otherwise this is returned:

my ($sec, $min, $hour, $mday, $mon, $year, $tz, $secfrac)
   = from_xmpp_datetime ($string);

For the value ranges and semantics of $sec, ..., $srcfrac please look at the documentation for to_xmpp_datetime.

$tz and $secfrac might be undefined.

If $string contained just a time $mday, $mon and $year will be undefined.

See also XEP-0082.

AUTHOR

Robin Redeker, <elmex at ta-sa.org>, JID: <elmex at jabber.org>

COPYRIGHT & LICENSE

Copyright 2007 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.