.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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::Ext::OOB 3pm"
.TH AnyEvent::XMPP::Ext::OOB 3pm "2019-02-18" "perl v5.28.1" "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::Ext::OOB \- XEP\-0066 Out of Band Data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&   my $con = AnyEvent::XMPP::Connection\->new (...);
\&   $con\->add_extension (my $disco = AnyEvent::XMPP::Ext::Disco\->new);
\&   $con\->add_extension (my $oob = AnyEvent::XMPP::Ext::OOB\->new);
\&   $disco\->enable_feature ($oob\->disco_feature);
\&
\&   $oob\->reg_cb (oob_recv => sub {
\&      my ($oob, $con, $node, $url) = @_;
\&
\&      if (got ($url)) {
\&         $oob\->reply_success ($con, $node);
\&      } else {
\&         $oob\->reply_failure ($con, $node, \*(Aqnot\-found\*(Aq);
\&      }
\&   });
\&
\&   $oob\->send_url (
\&      $con, \*(Aqsomeonewho@wants.an.url.com\*(Aq, "http://nakedgirls.com/marie_021.jpg",
\&      "Yaww!!! Hot like SUN!",
\&      sub {
\&         my ($error) = @_;
\&         if ($error) { # then error
\&         } else { # everything fine
\&         }
\&      }
\&   )
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a helper abstraction for handling out of band
data as specified in \s-1XEP\-0066.\s0
.PP
The object that is generated handles out of band data requests to and
from others.
.PP
There is are also some utility function defined to get for example the
oob info from an \s-1XML\s0 element:
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBurl_from_node ($node)\fR" 4
.IX Item "url_from_node ($node)"
This function extracts the \s-1URL\s0 and optionally a description
field from the \s-1XML\s0 element in \f(CW$node\fR (which must be a
AnyEvent::XMPP::Node).
.Sp
\&\f(CW$node\fR must be the \s-1XML\s0 node which contains the <url> and optionally <desc> element
(which is eg. a <x xmlns='jabber:x:oob'> element)!
.Sp
(This method searches both, the jabber:x:oob and jabber:iq:oob namespaces for
the <url> and <desc> elements).
.Sp
It returns a hash reference which should have following structure:
.Sp
.Vb 4
\&   {
\&      url  => "http://someurl.org/mycoolparty.jpg",
\&      desc => "That was a party!",
\&   }
.Ve
.Sp
If nothing was found this method returns nothing (undef).
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew ()\fR" 4
.IX Item "new ()"
This is the constructor, it takes no further arguments.
.IP "\fBreply_success ($con, \f(CB$node\fB)\fR" 4
.IX Item "reply_success ($con, $node)"
This method replies to the sender of the oob that the \s-1URL\s0
was retrieved successfully.
.Sp
\&\f(CW$con\fR and \f(CW$node\fR are the \f(CW$con\fR and \f(CW$node\fR arguments
of the \f(CW\*(C`oob_recv\*(C'\fR event you want to reply to.
.IP "\fBreply_failure ($con, \f(CB$node\fB, \f(CB$type\fB)\fR" 4
.IX Item "reply_failure ($con, $node, $type)"
This method replies to the sender that either the transfer was rejected
or it was not fount.
.Sp
If the transfer was rejectes you have to set \f(CW$type\fR to 'reject',
otherwise \f(CW$type\fR must be 'not\-found'.
.Sp
\&\f(CW$con\fR and \f(CW$node\fR are the \f(CW$con\fR and \f(CW$node\fR arguments
of the \f(CW\*(C`oob_recv\*(C'\fR event you want to reply to.
.IP "\fBsend_url ($con, \f(CB$jid\fB, \f(CB$url\fB, \f(CB$desc\fB, \f(CB$cb\fB)\fR" 4
.IX Item "send_url ($con, $jid, $url, $desc, $cb)"
This method sends a out of band file transfer request to \f(CW$jid\fR.
\&\f(CW$url\fR is the \s-1URL\s0 that the otherone has to download. \f(CW$desc\fR is an optional
description string (human readable) for the file pointed at by the url and
can be undef when you don't want to transmit any description.
.Sp
\&\f(CW$cb\fR is a callback that will be called once the transfer is successful.
.Sp
The first argument to the callback will either be undef in case of success
or 'reject' when the other side rejected the file or 'not\-found' if the other
side was unable to download the file.
.SH "EVENTS"
.IX Header "EVENTS"
These events can be registered to whith \f(CW\*(C`reg_cb\*(C'\fR:
.ie n .IP "oob_recv => $con, $node, $url" 4
.el .IP "oob_recv => \f(CW$con\fR, \f(CW$node\fR, \f(CW$url\fR" 4
.IX Item "oob_recv => $con, $node, $url"
This event is generated whenever someone wants to send you a out of band data file.
\&\f(CW$url\fR is a hash reference like it's returned by \f(CW\*(C`url_from_node\*(C'\fR.
.Sp
\&\f(CW$con\fR is the AnyEvent::XMPP::Connection (Or AnyEvent::XMPP::IM::Connection)
the data was received from.
.Sp
\&\f(CW$node\fR is the AnyEvent::XMPP::Node of the \s-1IQ\s0 request, you can get the senders
\&\s-1JID\s0 from the 'from' attribute of it.
.Sp
If you fetched the file successfully you have to call \f(CW\*(C`reply_success\*(C'\fR.
If you want to reject the file or couldn't get it call \f(CW\*(C`reply_failure\*(C'\fR.