XMPP2/IM/Connection.pm

package Net::XMPP2::IM::Connection;
use warnings;
use strict;
use Net::XMPP2::Connection;
use Net::XMPP2::Namespaces qw/xmpp_ns/;
our @ISA = qw/Net::XMPP2::Connection/;

=head1 NAME

Net::XMPP2::Connection - A XML stream that implements the XMPP RFC 3920.

=head1 SYNOPSIS

   use Net::XMPP2::Connection;

   my $con = Net::XMPP2::Connection->new;

=head1 DESCRIPTION

This module represents a XMPP instant messaging connection and implements
RFC 3921.

This module is a subclass of C<Net::XMPP2::Connection> and inherits all methods.
For example C<reg_cb> and the stanza sending routines.

For additional events that can be registered to look below in the EVENTS section.

=head1 METHODS

=cut

sub new {
   my $this = shift;
   my $class = ref($this) || $this;
   my $self = $class->SUPER::new (@_);

   $self->{ext} = {}; # reserved for extensions

   $self->reg_cb (message_xml  => sub { $self->handle_message (@_); 1 });
   $self->reg_cb (presence_xml => sub { $self->handle_presence (@_); 1 });

   $self->reg_cb (stream_ready => sub {
      my ($jid) = @_;
      if ($self->features ()->find_all ([qw/session session/])) {
         $self->send_session_iq;
      } else {
         $self->{session_active} = 1;
         $self->send_presence ();
         $self->event ('session_ready');
      }
   });
   $self
}

sub send_session_iq {
   my ($self) = @_;

   $self->send_iq (set => sub {
      my ($w) = @_;
      $w->addPrefix (xmpp_ns ('session'), '');
      $w->emptyTag ([xmpp_ns ('session'), 'session']);

   }, sub {
      my ($node, $errnode, $errar) = @_;
      if ($node) {
         $self->{session_active} = 1;
         $self->send_presence;
         $self->retrieve_roster;
         $self->event ('session_ready');
      } else {
         $self->event (session_error => $errnode, $errar); # TODO: make error obj
      }
   });
}

sub retrieve_roster {
   my ($self) = @_;

   $self->send_iq (get => sub {
      my ($w) = @_;
      $w->addPrefix (xmpp_ns ('roster'), '');
      $w->emptyTag ([xmpp_ns ('roster'), 'query']);

   }, sub {
      my ($node, $errnode, $errar) = @_;
      if ($node) {
         $self->store_roster ($node);
      } else {
         $self->event (roster_error => $errnode, $errar); # TODO: make error obj
      }
   });
}

sub store_roster {
   my ($self, $node) = @_;

   my ($query) = $node->find_all ([qw/roster query/]);
   return unless $query;

   for my $item ($query->find_all ([qw/roster item/])) {
      my ($jid, $name, $subscription) =
         ($item->attr ('jid'), $item->attr ('name'), $item->attr ('subscription'));
      my @groups;
      push @groups, $_->text for $item->find_all ([qw/roster group/]);

      my $ro = $self->{roster}->{$jid} = {
         jid          => $jid,
         name         => $name,
         subscription => $subscription,
         groups       => [ @groups ]
      };
   }

   $self->event ('roster_update'); # TODO, pass object!
}

sub handle_presence {
   my ($self) = @_;

}

sub handle_message {
   my ($self) = @_;
}

=head1 EVENTS

These additional events can be registered on with C<reg_cb>:

=over 4

=item session_ready

This event is generated when the session has been fully established and
can be used to send around messages and other stuff.

=item session_error => $erriq, $errarr

If an error happened during establishment of the session this
event will be generated. C<$erriq> is the L<Net::XMPP2::Node> object
of the error iq tag and C<$errar> is an error array as described in
L<Net::XMPP2::Connection::send_iq> for error responses for iq requests.

=back

=head1 AUTHOR

Robin Redeker, C<< <elmex at ta-sa.org> >>

=head1 BUGS

Please report any bugs or feature requests to
C<bug-net-xmpp2 at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::XMPP2

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Net-XMPP2>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Net-XMPP2>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-XMPP2>

=item * Search CPAN

L<http://search.cpan.org/dist/Net-XMPP2>

=back

=head1 ACKNOWLEDGEMENTS

=head1 COPYRIGHT & LICENSE

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

=cut


1; # End of Net::XMPP2
Revision:	1.4
Committed:	Sat Feb 3 11:39:55 2007 UTC (19 years, 7 months ago) by elmex
Branch:	MAIN
Changes since 1.3:	+7 -5 lines
Log Message:	marked low level events with an _xml. changed documentation a bit.
#	User	Rev	Content
1	elmex	1.1	package Net::XMPP2::IM::Connection;
2			use warnings;
3			use strict;
4			use Net::XMPP2::Connection;
5			use Net::XMPP2::Namespaces qw/xmpp_ns/;
6			our @ISA = qw/Net::XMPP2::Connection/;
7
8			=head1 NAME
9
10			Net::XMPP2::Connection - A XML stream that implements the XMPP RFC 3920.
11
12			=head1 SYNOPSIS
13
14			use Net::XMPP2::Connection;
15
16			my $con = Net::XMPP2::Connection->new;
17
18			=head1 DESCRIPTION
19
20			This module represents a XMPP instant messaging connection and implements
21			RFC 3921.
22
23			This module is a subclass of C<Net::XMPP2::Connection> and inherits all methods.
24			For example C<reg_cb> and the stanza sending routines.
25
26			For additional events that can be registered to look below in the EVENTS section.
27
28			=head1 METHODS
29
30			=cut
31
32			sub new {
33			my $this = shift;
34			my $class = ref($this) \|\| $this;
35			my $self = $class->SUPER::new (@_);
36	elmex	1.2
37			$self->{ext} = {}; # reserved for extensions
38
39	elmex	1.4	$self->reg_cb (message_xml => sub { $self->handle_message (@_); 1 });
40			$self->reg_cb (presence_xml => sub { $self->handle_presence (@_); 1 });
41	elmex	1.2
42	elmex	1.1	$self->reg_cb (stream_ready => sub {
43			my ($jid) = @_;
44	elmex	1.2	if ($self->features ()->find_all ([qw/session session/])) {
45			$self->send_session_iq;
46			} else {
47			$self->{session_active} = 1;
48			$self->send_presence ();
49	elmex	1.1	$self->event ('session_ready');
50	elmex	1.2	}
51	elmex	1.1	});
52			$self
53			}
54
55	elmex	1.2	sub send_session_iq {
56			my ($self) = @_;
57
58			$self->send_iq (set => sub {
59			my ($w) = @_;
60			$w->addPrefix (xmpp_ns ('session'), '');
61			$w->emptyTag ([xmpp_ns ('session'), 'session']);
62
63			}, sub {
64			my ($node, $errnode, $errar) = @_;
65			if ($node) {
66			$self->{session_active} = 1;
67			$self->send_presence;
68	elmex	1.3	$self->retrieve_roster;
69	elmex	1.2	$self->event ('session_ready');
70			} else {
71	elmex	1.4	$self->event (session_error => $errnode, $errar); # TODO: make error obj
72	elmex	1.2	}
73			});
74			}
75
76	elmex	1.3	sub retrieve_roster {
77			my ($self) = @_;
78	elmex	1.4
79	elmex	1.3	$self->send_iq (get => sub {
80			my ($w) = @_;
81			$w->addPrefix (xmpp_ns ('roster'), '');
82			$w->emptyTag ([xmpp_ns ('roster'), 'query']);
83	elmex	1.4
84	elmex	1.3	}, sub {
85			my ($node, $errnode, $errar) = @_;
86			if ($node) {
87			$self->store_roster ($node);
88			} else {
89	elmex	1.4	$self->event (roster_error => $errnode, $errar); # TODO: make error obj
90	elmex	1.3	}
91			});
92			}
93
94			sub store_roster {
95			my ($self, $node) = @_;
96
97			my ($query) = $node->find_all ([qw/roster query/]);
98			return unless $query;
99
100			for my $item ($query->find_all ([qw/roster item/])) {
101			my ($jid, $name, $subscription) =
102			($item->attr ('jid'), $item->attr ('name'), $item->attr ('subscription'));
103			my @groups;
104			push @groups, $_->text for $item->find_all ([qw/roster group/]);
105
106			my $ro = $self->{roster}->{$jid} = {
107			jid => $jid,
108			name => $name,
109			subscription => $subscription,
110			groups => [ @groups ]
111			};
112			}
113
114	elmex	1.4	$self->event ('roster_update'); # TODO, pass object!
115	elmex	1.3	}
116
117	elmex	1.2	sub handle_presence {
118			my ($self) = @_;
119
120			}
121
122			sub handle_message {
123			my ($self) = @_;
124			}
125
126	elmex	1.1	=head1 EVENTS
127
128			These additional events can be registered on with C<reg_cb>:
129
130			=over 4
131
132			=item session_ready
133
134	elmex	1.2	This event is generated when the session has been fully established and
135			can be used to send around messages and other stuff.
136
137			=item session_error => $erriq, $errarr
138
139			If an error happened during establishment of the session this
140			event will be generated. C<$erriq> is the L<Net::XMPP2::Node> object
141			of the error iq tag and C<$errar> is an error array as described in
142			L<Net::XMPP2::Connection::send_iq> for error responses for iq requests.
143	elmex	1.1
144			=back
145
146			=head1 AUTHOR
147
148			Robin Redeker, C<< <elmex at ta-sa.org> >>
149
150			=head1 BUGS
151
152			Please report any bugs or feature requests to
153			C<bug-net-xmpp2 at rt.cpan.org>, or through the web interface at
154			L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>.
155			I will be notified, and then you'll automatically be notified of progress on
156			your bug as I make changes.
157
158			=head1 SUPPORT
159
160			You can find documentation for this module with the perldoc command.
161
162			perldoc Net::XMPP2
163
164			You can also look for information at:
165
166			=over 4
167
168			=item * AnnoCPAN: Annotated CPAN documentation
169
170			L<http://annocpan.org/dist/Net-XMPP2>
171
172			=item * CPAN Ratings
173
174			L<http://cpanratings.perl.org/d/Net-XMPP2>
175
176			=item * RT: CPAN's request tracker
177
178			L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-XMPP2>
179
180			=item * Search CPAN
181
182			L<http://search.cpan.org/dist/Net-XMPP2>
183
184			=back
185
186			=head1 ACKNOWLEDGEMENTS
187
188			=head1 COPYRIGHT & LICENSE
189
190			Copyright 2007 Robin Redeker, all rights reserved.
191
192			This program is free software; you can redistribute it and/or modify it
193			under the same terms as Perl itself.
194
195			=cut
196
197
198
199			1; # End of Net::XMPP2