NAME

       AnyEvent::XMPP::Ext::RegisterForm - Handle for in band registration

SYNOPSIS

          my $con = AnyEvent::XMPP::Connection->new (...);
          ...
          $con->do_in_band_register (sub {
             my ($form, $error) = @_;
             if ($error) { print "ERROR: ".$error->string."\n" }
             else {
                if ($form->type eq 'simple') {
                   if ($form->has_field ('username') && $form->has_field ('password')) {
                      $form->set_field (
                         username => 'test',
                         password => 'qwerty',
                      );
                      $form->submit (sub {
                         my ($form, $error) = @_;
                         if ($error) { print "SUBMIT ERROR: ".$error->string."\n" }
                         else {
                            print "Successfully registered as ".$form->field ('username')."\n"
                         }
                      });
                   } else {
                      print "Couldn't fill out the form: " . $form->field ('instructions') ."\n";
                   }
                } elsif ($form->type eq 'data_form' {
                   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."\n" }
                      else {
                         print "Successfully registered as ".$form->field ('username')."\n"
                      }
                   })
                }
             }
          });

DESCRIPTION

       This module represents an in band registration form which can be filled out and submitted.

       You can get an instance of this class only by requesting it from a AnyEvent::XMPP::Connection by calling
       the "request_inband_register_form" method.

       new (%args)
           Usually the constructor takes no arguments except when you want to construct an answer form, then you
           call the constructor like this:

           If you have legacy form fields as a hash ref in $filled_legacy_form:

              AnyEvent::XMPP::Ext::RegisterForm (
                 legacy_form => $filled_legacy_form,
                 answered => 1
              );

           If you have a data form in $answer_data_form:

              AnyEvent::XMPP::Ext::RegisterForm (
                 legacy_form => $answer_data_form,
                 answered => 1
              );

       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.

           NOTE: 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.

           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 XEP-0077.

           Note that if the form is more complicated this method will not work and it's not guranteed  that  the
           registration will be successful.

           Calling  this  method  on  a answer form (where "is_answer_form" returns true) will have an undefined
           result.

       is_answer_form
           This method will return a true value if this form was returned by eg.  "try_fillout_registration"  or
           generally represents an answer form.

       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.

       get_legacy_form_fields
           This  method returns a hash with the keys being the fields of the legacy form as described in the XML
           scheme of XEP-0077.

           If the form contained just nodes the keys will have undef as value.

           If the form contained also register information,  in  case  "is_already_registered"  returns  a  true
           value, the values will contain the strings for the fields.

       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.

       get_oob
           This   method   returns   a  hash  like  the  one  returned  from  the  function  "url_from_node"  in
           AnyEvent::XMPP::Ext::OOB.  It contains the out of band data for this registration form.

       answer_form_to_simxml
           This method returns a list of "simxml" nodes.

AUTHOR

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

COPYRIGHT & LICENSE

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

perl v5.20.2                                       2012-12-25             AnyEvent::XMPP::Ext::RegisterForm(3pm)