=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated.  Please do not edit
this file, but rather the original, inline with Protocol::XMPP::IQ::Roster
at lib/Protocol/XMPP/IQ/Roster.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.

=cut

=head1 NAME

=head1 SYNOPSIS

=head1 VERSION

Version 0.006

=head1 DESCRIPTION

Example from RFC3921:

 <iq from='juliet@example.com/balcony'
     id='bv1bs71f'
     type='get'>
  <query xmlns='jabber:iq:roster'/>
 </iq>

Response from server:

 <iq id='bv1bs71f'
     to='juliet@example.com/chamber'
     type='result'>
  <query xmlns='jabber:iq:roster' ver='ver7'>
    <item jid='nurse@example.com'/>
    <item jid='romeo@example.net'/>
  </query>
 </iq>

IQ start - stash current IQ on stream
Query start - set IQ query type to xmlns

Each item is parsed as a roster entry.

A roster request for a user that does not exist will return an error as follows:

 <iq id='bv1bs71f'
     to='juliet@example.com/chamber'
     type='error'>
  <error type='auth'>
    <item-not-found
        xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
 </iq>

Updates:

An update request is as follows:

 <iq from='juliet@example.com/balcony'
     id='rs1'
     type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='nurse@example.com'/>
  </query>
 </iq>

Pass C<subscription='remove'> as the item attribute to remove rather than adding the contact.

More detailed example:

   C: <iq from='juliet@example.com/balcony'
          id='ph1xaz53'
          type='set'>
        <query xmlns='jabber:iq:roster'>
          <item jid='nurse@example.com'
                name='Nurse'>
            <group>Servants</group>
          </item>
        </query>
      </iq>
Server push requests can be sent through as follows:

 <iq id='a78b4q6ha463'
     to='juliet@example.com/chamber'
     type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='nurse@example.com'/>
  </query>
 </iq>

with the client reponse being an empty result:

 <iq from='juliet@example.com/balcony'
     id='a78b4q6ha463'
     type='result'/>

Until the client sends the initial roster request, it will not receive any server push information.

Subscribe by sending something like this:

   UC: <presence id='xk3h1v69'
                 to='juliet@example.com'
                 type='subscribe'/>
Requesting a new contact will cause the server to send out an ask request:

   US: <iq id='b89c5r7ib574'
           to='romeo@example.net/foo'
           type='set'>
         <query xmlns='jabber:iq:roster'>
           <item ask='subscribe'
                 jid='juliet@example.com'
                 subscription='none'/>
         </query>
       </iq>
=head1 METHODS

=head1 INHERITED METHODS

=over 4

=item L<Protocol::XMPP::ElementBase>

L<attributes|Protocol::XMPP::ElementBase/attributes>, L<characters|Protocol::XMPP::ElementBase/characters>, L<class_from_element|Protocol::XMPP::ElementBase/class_from_element>, L<end_element|Protocol::XMPP::ElementBase/end_element>, L<new|Protocol::XMPP::ElementBase/new>, L<parent|Protocol::XMPP::ElementBase/parent>

=item L<Protocol::XMPP::Base>

L<debug|Protocol::XMPP::Base/debug>, L<dispatch_event|Protocol::XMPP::Base/dispatch_event>, L<is_authorised|Protocol::XMPP::Base/is_authorised>, L<is_loggedin|Protocol::XMPP::Base/is_loggedin>, L<new_future|Protocol::XMPP::Base/new_future>, L<next_id|Protocol::XMPP::Base/next_id>, L<stream|Protocol::XMPP::Base/stream>, L<write_text|Protocol::XMPP::Base/write_text>, L<write_xml|Protocol::XMPP::Base/write_xml>

=item L<Mixin::Event::Dispatch>

L<add_handler_for_event|Mixin::Event::Dispatch/add_handler_for_event>, L<clear_event_handlers|Mixin::Event::Dispatch/clear_event_handlers>, L<event_handlers|Mixin::Event::Dispatch/event_handlers>, L<invoke_event|Mixin::Event::Dispatch/invoke_event>, L<subscribe_to_event|Mixin::Event::Dispatch/subscribe_to_event>, L<unsubscribe_from_event|Mixin::Event::Dispatch/unsubscribe_from_event>

=back

=head1 AUTHOR

Tom Molesworth <cpan@entitymodel.com>

=head1 LICENSE

Copyright Tom Molesworth 2010-2014. Licensed under the same terms as Perl itself.
