.\" -*- 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::Ext::OOB 3"
.TH AnyEvent::XMPP::Ext::OOB 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::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 XEP\-0066.
.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 XML element:
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.IP "\fBurl_from_node ($node)\fR" 4
.IX Item "url_from_node ($node)"
This function extracts the URL and optionally a description
field from the XML element in \f(CW$node\fR (which must be a
AnyEvent::XMPP::Node).
.Sp
\&\f(CW$node\fR must be the XML 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.
.ie n .IP "\fBreply_success ($con, \fR\fB$node\fR\fB)\fR" 4
.el .IP "\fBreply_success ($con, \fR\f(CB$node\fR\fB)\fR" 4
.IX Item "reply_success ($con, $node)"
This method replies to the sender of the oob that the URL
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.
.ie n .IP "\fBreply_failure ($con, \fR\fB$node\fR\fB, \fR\fB$type\fR\fB)\fR" 4
.el .IP "\fBreply_failure ($con, \fR\f(CB$node\fR\fB, \fR\f(CB$type\fR\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.
.ie n .IP "\fBsend_url ($con, \fR\fB$jid\fR\fB, \fR\fB$url\fR\fB, \fR\fB$desc\fR\fB, \fR\fB$cb\fR\fB)\fR" 4
.el .IP "\fBsend_url ($con, \fR\f(CB$jid\fR\fB, \fR\f(CB$url\fR\fB, \fR\f(CB$desc\fR\fB, \fR\f(CB$cb\fR\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 URL 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 IQ request, you can get the senders
JID 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.