.\" -*- 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::Util 3" .TH AnyEvent::XMPP::Util 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::Util \- Utility functions for AnyEvent::XMPP .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& use AnyEvent::XMPP::Util qw/split_jid/; \& ... .Ve .SH FUNCTIONS .IX Header "FUNCTIONS" These functions can be exported if you want: .IP "\fBresourceprep ($string)\fR" 4 .IX Item "resourceprep ($string)" This function applies the stringprep profile for resources to \f(CW$string\fR and returns the result. .IP "\fBnodeprep ($string)\fR" 4 .IX Item "nodeprep ($string)" This function applies the stringprep profile for nodes to \f(CW$string\fR and returns the result. .ie n .IP "\fBprep_join_jid ($node, \fR\fB$domain\fR\fB, \fR\fB$resource\fR\fB)\fR" 4 .el .IP "\fBprep_join_jid ($node, \fR\f(CB$domain\fR\fB, \fR\f(CB$resource\fR\fB)\fR" 4 .IX Item "prep_join_jid ($node, $domain, $resource)" This function joins the parts \f(CW$node\fR, \f(CW$domain\fR and \f(CW$resource\fR to a full jid and applies stringprep profiles. If the profiles couldn't be applied undef will be returned. .ie n .IP "\fBjoin_jid ($user, \fR\fB$domain\fR\fB, \fR\fB$resource\fR\fB)\fR" 4 .el .IP "\fBjoin_jid ($user, \fR\f(CB$domain\fR\fB, \fR\f(CB$resource\fR\fB)\fR" 4 .IX Item "join_jid ($user, $domain, $resource)" This is a plain concatenation of \f(CW$user\fR, \f(CW$domain\fR and \f(CW$resource\fR without stringprep. .Sp See also prep_join_jid .IP "\fBsplit_uri ($uri)\fR" 4 .IX Item "split_uri ($uri)" This function splits up the \f(CW$uri\fR into service and node part and will return them as list. .Sp .Vb 1 \& my ($service, $node) = split_uri ($uri); .Ve .IP "\fBsplit_jid ($jid)\fR" 4 .IX Item "split_jid ($jid)" This function splits up the \f(CW$jid\fR into user/node, domain and resource part and will return them as list. .Sp .Vb 1 \& my ($user, $host, $res) = split_jid ($jid); .Ve .IP "\fBnode_jid ($jid)\fR" 4 .IX Item "node_jid ($jid)" See \f(CW\*(C`prep_res_jid\*(C'\fR below. .IP "\fBdomain_jid ($jid)\fR" 4 .IX Item "domain_jid ($jid)" See \f(CW\*(C`prep_res_jid\*(C'\fR below. .IP "\fBres_jid ($jid)\fR" 4 .IX Item "res_jid ($jid)" See \f(CW\*(C`prep_res_jid\*(C'\fR below. .IP "\fBprep_node_jid ($jid)\fR" 4 .IX Item "prep_node_jid ($jid)" See \f(CW\*(C`prep_res_jid\*(C'\fR below. .IP "\fBprep_domain_jid ($jid)\fR" 4 .IX Item "prep_domain_jid ($jid)" See \f(CW\*(C`prep_res_jid\*(C'\fR below. .IP "\fBprep_res_jid ($jid)\fR" 4 .IX Item "prep_res_jid ($jid)" These functions return the corresponding parts of a JID. The \f(CW\*(C`prep_\*(C'\fR prefixed JIDs return the stringprep'ed versions. .IP "\fBstringprep_jid ($jid)\fR" 4 .IX Item "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: .Sp .Vb 1 \& stringprep_jid ($jid_a) eq stringprep_jid ($jid_b) .Ve .Sp This function returns undef if the \f(CW$jid\fR couldn't successfully be parsed and the preparations done. .ie n .IP "\fBcmp_jid ($jid1, \fR\fB$jid2\fR\fB)\fR" 4 .el .IP "\fBcmp_jid ($jid1, \fR\f(CB$jid2\fR\fB)\fR" 4 .IX Item "cmp_jid ($jid1, $jid2)" This function compares two jids \f(CW$jid1\fR and \f(CW$jid2\fR whether they are equal. .ie n .IP "\fBcmp_bare_jid ($jid1, \fR\fB$jid2\fR\fB)\fR" 4 .el .IP "\fBcmp_bare_jid ($jid1, \fR\f(CB$jid2\fR\fB)\fR" 4 .IX Item "cmp_bare_jid ($jid1, $jid2)" This function compares two jids \f(CW$jid1\fR and \f(CW$jid2\fR whether their bare part is equal. .IP "\fBprep_bare_jid ($jid)\fR" 4 .IX Item "prep_bare_jid ($jid)" This function makes the jid \f(CW$jid\fR a bare jid, meaning: it will strip off the resource part. With stringprep. .IP "\fBbare_jid ($jid)\fR" 4 .IX Item "bare_jid ($jid)" This function makes the jid \f(CW$jid\fR a bare jid, meaning: it will strip off the resource part. But without stringprep. .IP "\fBis_bare_jid ($jid)\fR" 4 .IX Item "is_bare_jid ($jid)" This method returns a boolean which indicates whether \f(CW$jid\fR is a bare JID. .IP "\fBfilter_xml_chars ($string)\fR" 4 .IX Item "filter_xml_chars ($string)" This function removes all characters from \f(CW$string\fR which are not allowed in XML and returns the new string. .IP "\fBfilter_xml_attr_hash_chars ($hashref)\fR" 4 .IX Item "filter_xml_attr_hash_chars ($hashref)" This runs all values of the \f(CW$hashref\fR through \f(CW\*(C`filter_xml_chars\*(C'\fR (see above) and changes them in-place! .ie n .IP "\fBsimxml ($w, \fR\fB%xmlstruct\fR\fB)\fR" 4 .el .IP "\fBsimxml ($w, \fR\f(CB%xmlstruct\fR\fB)\fR" 4 .IX Item "simxml ($w, %xmlstruct)" This function takes a XML::Writer as first argument (\f(CW$w\fR) and the rest key value pairs: .Sp .Vb 5 \& simxml ($w, \& defns => \*(Aq\*(Aq, \& node => , \& prefixes => { prefix => namespace, ... }, \& ); .Ve .Sp Where node is: .Sp .Vb 10 \& := { \& ns => \*(Aq\*(Aq, \& name => \*(Aqtagname\*(Aq, \& attrs => [ \*(Aqname\*(Aq, \*(Aqvalue\*(Aq, \*(Aqname2\*(Aq, \*(Aqvalue2\*(Aq, ... ], \& childs => [ , ... ] \& } \& | { \& dns => \*(Aq\*(Aq, # this will set that namespace to \& # the default namespace before using it. \& name => \*(Aqtagname\*(Aq, \& attrs => [ \*(Aqname\*(Aq, \*(Aqvalue\*(Aq, \*(Aqname2\*(Aq, \*(Aqvalue2\*(Aq, ... ], \& childs => [ , ... ] \& } \& | sub { my ($w) = @_; ... } # with $w being a XML::Writer object \& | "textnode" .Ve .Sp Please note: \f(CW\*(C`childs\*(C'\fR stands for \f(CW\*(C`child sequence\*(C'\fR :\-) .Sp Also note that if you omit the \f(CW\*(C`ns\*(C'\fR key for nodes there is a fall back to the namespace of the parent element or the last default namespace. This makes it easier to write things like this: .Sp .Vb 4 \& { \& defns => \*(Aqmuc_owner\*(Aq, \& node => { name => \*(Aqquery\*(Aq } \& } .Ve .Sp (Without having to include \f(CW\*(C`ns\*(C'\fR in the node.) .Sp Please note that all attribute values and character data will be filtered by \f(CW\*(C`filter_xml_chars\*(C'\fR. .Sp This is a bigger example: .Sp .Vb 1 \& ... \& \& $msg\->append_creation( sub { \& my($w) = @_; \& simxml($w, \& defns => \*(Aqmuc_user\*(Aq, # sets the default namepsace for all following elements \& node => { \& name => \*(Aqx\*(Aq, # element \*(Aqx\*(Aq in namespace \*(Aqmuc_user\*(Aq \& childs => [ \& { \& \*(Aqname\*(Aq => \*(Aqinvite\*(Aq, # element \*(Aqinvite\*(Aq in namespace \*(Aqmuc_user\*(Aq \& \*(Aqattrs\*(Aq => [ \*(Aqto\*(Aq, $to_jid ], # to="$to_jid" attribute for \*(Aqinvite\*(Aq \& \*(Aqchilds\*(Aq => [ \& { # the $reason element in the invite element \& \*(Aqname\*(Aq => \*(Aqreason\*(Aq, \& childs => [ $reason ] \& } \& ], \& } \& ] \& } \& ); \& }); .Ve .ie n .IP "\fBto_xmpp_time ($sec, \fR\fB$min\fR\fB, \fR\fB$hour\fR\fB, \fR\fB$tz\fR\fB, \fR\fB$secfrac\fR\fB)\fR" 4 .el .IP "\fBto_xmpp_time ($sec, \fR\f(CB$min\fR\fB, \fR\f(CB$hour\fR\fB, \fR\f(CB$tz\fR\fB, \fR\f(CB$secfrac\fR\fB)\fR" 4 .IX Item "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 \f(CW$sec\fR, ..., \f(CW$hour\fR are explained in the perldoc of Perl's builtin \f(CW\*(C`localtime\*(C'\fR. .Sp \&\f(CW$tz\fR has to be either \f(CW"UTC"\fR or of the form \f(CW\*(C`[+\-]hh:mm\*(C'\fR, it can be undefined and wont occur in the time string then. .Sp \&\f(CW$secfrac\fR are optional and can be the fractions of the second. .Sp See also XEP\-0082. .ie n .IP "\fBto_xmpp_datetime ($sec,$min,$hour,$mday,$mon,$year,$tz, \fR\fB$secfrac\fR\fB)\fR" 4 .el .IP "\fBto_xmpp_datetime ($sec,$min,$hour,$mday,$mon,$year,$tz, \fR\f(CB$secfrac\fR\fB)\fR" 4 .IX Item "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 \f(CW$sec\fR, ..., \f(CW$year\fR are explained in the perldoc of Perl's \f(CW\*(C`localtime\*(C'\fR builtin and have the same value ranges. .Sp \&\f(CW$tz\fR has to be either \f(CW"Z"\fR (for UTC) or of the form \f(CW\*(C`[+\-]hh:mm\*(C'\fR (offset from UTC), if it is undefined "Z" will be used. .Sp \&\f(CW$secfrac\fR are optional and can be the fractions of the second. .Sp See also XEP\-0082. .IP "\fBfrom_xmpp_datetime ($string)\fR" 4 .IX Item "from_xmpp_datetime ($string)" This function transforms the \f(CW$string\fR 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: .Sp .Vb 2 \& my ($sec, $min, $hour, $mday, $mon, $year, $tz, $secfrac) \& = from_xmpp_datetime ($string); .Ve .Sp For the value ranges and semantics of \f(CW$sec\fR, ..., \f(CW$srcfrac\fR please look at the documentation for \f(CW\*(C`to_xmpp_datetime\*(C'\fR. .Sp \&\f(CW$tz\fR and \f(CW$secfrac\fR might be undefined. .Sp If \f(CW$tz\fR is undefined the timezone is to be assumed to be UTC. .Sp If \f(CW$string\fR contained just a time \f(CW$mday\fR, \f(CW$mon\fR and \f(CW$year\fR will be undefined. .Sp See also XEP\-0082. .IP "\fBxmpp_datetime_as_timestamp ($string)\fR" 4 .IX Item "xmpp_datetime_as_timestamp ($string)" This function takes the same arguments as \f(CW\*(C`from_xmpp_datetime\*(C'\fR, but returns a unix timestamp, like \f(CW\*(C`time ()\*(C'\fR would. .Sp This function requires the POSIX module. .SH AUTHOR .IX Header "AUTHOR" Robin Redeker, \f(CW\*(C`\*(C'\fR, JID: \f(CW\*(C`\*(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.