.\" Automatically generated by Pod::Man 4.14 (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
..
.\" 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::RegisterForm 3pm"
.TH AnyEvent::XMPP::Ext::RegisterForm 3pm "2022-12-06" "perl v5.36.0" "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::RegisterForm \- Handle for in band registration
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&   my $con = AnyEvent::XMPP::Connection\->new (...);
\&   ...
\&   $con\->do_in_band_register (sub {
\&      my ($form, $error) = @_;
\&      if ($error) { print "ERROR: ".$error\->string."\en" }
\&      else {
\&         if ($form\->type eq \*(Aqsimple\*(Aq) {
\&            if ($form\->has_field (\*(Aqusername\*(Aq) && $form\->has_field (\*(Aqpassword\*(Aq)) {
\&               $form\->set_field (
\&                  username => \*(Aqtest\*(Aq,
\&                  password => \*(Aqqwerty\*(Aq,
\&               );
\&               $form\->submit (sub {
\&                  my ($form, $error) = @_;
\&                  if ($error) { print "SUBMIT ERROR: ".$error\->string."\en" }
\&                  else {
\&                     print "Successfully registered as ".$form\->field (\*(Aqusername\*(Aq)."\en"
\&                  }
\&               });
\&            } else {
\&               print "Couldn\*(Aqt fill out the form: " . $form\->field (\*(Aqinstructions\*(Aq) ."\en";
\&            }
\&         } elsif ($form\->type eq \*(Aqdata_form\*(Aq {
\&            my $dform = $form\->data_form;
\&            ... fill out the form $dform (of type AnyEvent::XMPP::DataForm) ...
\&            $form\->submit_data_form ($dform, sub {
\&               my ($form, $error) = @_;
\&               if ($error) { print "DATA FORM SUBMIT ERROR: ".$error\->string."\en" }
\&               else {
\&                  print "Successfully registered as ".$form\->field (\*(Aqusername\*(Aq)."\en"
\&               }
\&            })
\&         }
\&      }
\&   });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module represents an in band registration form
which can be filled out and submitted.
.PP
You can get an instance of this class only by requesting it
from a AnyEvent::XMPP::Connection by calling the \f(CW\*(C`request_inband_register_form\*(C'\fR
method.
.IP "\fBnew (%args)\fR" 4
.IX Item "new (%args)"
Usually the constructor takes no arguments except when you want to construct
an answer form, then you call the constructor like this:
.Sp
If you have legacy form fields as a hash ref in \f(CW$filled_legacy_form\fR:
.Sp
.Vb 4
\&   AnyEvent::XMPP::Ext::RegisterForm (
\&      legacy_form => $filled_legacy_form,
\&      answered => 1
\&   );
.Ve
.Sp
If you have a data form in \f(CW$answer_data_form\fR:
.Sp
.Vb 4
\&   AnyEvent::XMPP::Ext::RegisterForm (
\&      legacy_form => $answer_data_form,
\&      answered => 1
\&   );
.Ve
.IP "\fBtry_fillout_registration ($username, \f(CB$password\fB)\fR" 4
.IX Item "try_fillout_registration ($username, $password)"
This method tries to fill out a form which was received from the
other end. It enters the username and password and returns a
new AnyEvent::XMPP::Ext::RegisterForm object which is the answer
form.
.Sp
\&\fB\s-1NOTE:\s0\fR This function is just a heuristic to fill out a form for automatic
registration, but it might fail if the forms are more complex and have
required fields that we don't know.
.Sp
Registration without user interaction is theoretically not possible because
forms can be different from server to server and require different information.
Please also have a look at \s-1XEP\-0077.\s0
.Sp
Note that if the form is more complicated this method will not work
and it's not guranteed that the registration will be successful.
.Sp
Calling this method on a answer form (where \f(CW\*(C`is_answer_form\*(C'\fR returns true)
will have an undefined result.
.IP "\fBis_answer_form\fR" 4
.IX Item "is_answer_form"
This method will return a true value if this form was returned by eg.
\&\f(CW\*(C`try_fillout_registration\*(C'\fR or generally represents an answer form.
.IP "\fBis_already_registered\fR" 4
.IX Item "is_already_registered"
This method returns true if the received form
were just the current registration data. Basically this method returns
true when you are already registered to the server.
.IP "\fBget_legacy_form_fields\fR" 4
.IX Item "get_legacy_form_fields"
This method returns a hash with the keys being the fields
of the legacy form as described in the \s-1XML\s0 scheme of \s-1XEP\-0077.\s0
.Sp
If the form contained just nodes the keys will have undef as value.
.Sp
If the form contained also register information, in case \f(CW\*(C`is_already_registered\*(C'\fR
returns a true value, the values will contain the strings for the fields.
.IP "\fBget_data_form\fR" 4
.IX Item "get_data_form"
This method returns the AnyEvent::XMPP::Ext::DataForm that came
with the registration response. If no data form was provided by the
server this method returns undef.
.IP "\fBget_oob\fR" 4
.IX Item "get_oob"
This method returns a hash like the one returned from
the function \f(CW\*(C`url_from_node\*(C'\fR in AnyEvent::XMPP::Ext::OOB.
It contains the out of band data for this registration form.
.IP "\fBanswer_form_to_simxml\fR" 4
.IX Item "answer_form_to_simxml"
This method returns a list of \f(CW\*(C`simxml\*(C'\fR nodes.
.SH "AUTHOR"
.IX Header "AUTHOR"
Robin Redeker, \f(CW\*(C`<elmex at ta\-sa.org>\*(C'\fR, \s-1JID:\s0 \f(CW\*(C`<elmex at jabber.org>\*(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.