Net/XMPP2/Component.pm

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

=head1 NAME

Net::XMPP2::Component - "XML" stream that implements the XEP-0114

=head1 SYNOPSIS

   use Net::XMPP2::Component;

   my $con = Net::XMPP2::Component->new (
                domain => 'chat.jabber.org'
                server => 'jabber.org',
                port   => 5347,
                secret => 'insecurepasswordforthehackers'
             );
   $con->connect;
   $con->init;
   $con->reg_cb (session_ready => sub { ... });

=head1 DESCRIPTION

This module represents a XMPP connection to a server that authenticates as
component.

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.

Please note that for component several functionality in L<Net::XMPP2::Connection>
might have no effect or not the desired effect. Basically you should
use the L<Net::XMPP2::Component> as component and only handle events
the handle with incoming data. And only use functions that send stanzas.

No effect has the event C<stream_pre_authentication> and the C<authenticate>
method of L<Net::XMPP2::Connection>, because those handle the usual SASL or iq-auth
authentication. "Jabber" components have a completly different authentication
mechanism.

Also note that the support for some XEPs in L<Net::XMPP2::Ext> is just thought
for client side usage, if you miss any functionaly don't hesitate to ask the
author or send him a patch! (See L<Net::XMPP2> for contact information).

=head1 METHODS

=over 4

=item B<new (%args)>

This is the constructor. It takes the same arguments as
the constructor of L<Net::XMPP2::Connection> along with a
few others:

B<NOTE>: Please note that some arguments that L<Net::XMPP2::Connection>
usually takes have no effect when using this class. (That would be
the 'username', 'password', 'resource' and 'jid' arguments for example.)

=over 4

=item secret => $secret

C<$secret> is the secret that will be used for authentication with the server.

=back

=cut

sub new {
   my $this = shift;
   my $class = ref($this) || $this;

   my %args = @_;

   unless (exists $args{initial_presence}) {
      $args{stream_namespace} = 'component';
   }
   $args{override_host} = delete $args{server};
   $args{override_host}
      or die "Required 'server' argument missing to new for this component!";

   unless (defined $args{port}) {
      $args{port} = 5347;
   }

   my $self = $class->SUPER::new (%args);

   $self->{parser}->set_stream_cb (sub {
      my $secret = $self->{parser}->{parser}->xml_escape ($self->{secret});
      $self->{writer}->send_handshake ($_[0]->attr ('id'), $secret);
   });

   $self->reg_cb (recv_stanza_xml => sub {
      my ($self, $node) = @_;
      if ($node->eq (component => 'handshake')) {
         $self->{authenticated} = 1;
         $self->event ('session_ready');
      }
      1
   },
   stream_pre_authentication => sub {
      my ($self, $rcon) = @_;
      $$rcon = 0;
      1
   });

   $self
}

sub authenticate {
   warn "authenticate called! Please read the documentation of "
       ."Net::XMPP2::Component why this is an error!"
}

=back

=head1 EVENTS

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

NOTE: The event C<stream_pre_authentication> should _not_ be handled
and just ignored. Don't attach callbacks to it!

=over 4

=item session_ready

This event indicates that the component has connected successfully
and can now be used to transmit stanzas.

=back

=head1 AUTHOR

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

=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::Component
Revision:	1.1
Committed:	Fri Jul 20 20:41:48 2007 UTC (19 years, 2 months ago) by elmex
Branch:	MAIN
Log Message:	lots of changes. added as_string to Net::XMPP2::Node to restore the original xml document part of a stanza or subtree. also implemented the jabber component protocol.
#	User	Rev	Content
1	elmex	1.1	package Net::XMPP2::Component;
2			use strict;
3			use Net::XMPP2::Connection;
4			use Net::XMPP2::Namespaces qw/xmpp_ns/;
5			our @ISA = qw/Net::XMPP2::Connection/;
6
7			=head1 NAME
8
9			Net::XMPP2::Component - "XML" stream that implements the XEP-0114
10
11			=head1 SYNOPSIS
12
13			use Net::XMPP2::Component;
14
15			my $con = Net::XMPP2::Component->new (
16			domain => 'chat.jabber.org'
17			server => 'jabber.org',
18			port => 5347,
19			secret => 'insecurepasswordforthehackers'
20			);
21			$con->connect;
22			$con->init;
23			$con->reg_cb (session_ready => sub { ... });
24
25			=head1 DESCRIPTION
26
27			This module represents a XMPP connection to a server that authenticates as
28			component.
29
30			This module is a subclass of C<Net::XMPP2::Connection> and inherits all methods.
31			For example C<reg_cb> and the stanza sending routines.
32
33			For additional events that can be registered to look below in the EVENTS section.
34
35			Please note that for component several functionality in L<Net::XMPP2::Connection>
36			might have no effect or not the desired effect. Basically you should
37			use the L<Net::XMPP2::Component> as component and only handle events
38			the handle with incoming data. And only use functions that send stanzas.
39
40			No effect has the event C<stream_pre_authentication> and the C<authenticate>
41			method of L<Net::XMPP2::Connection>, because those handle the usual SASL or iq-auth
42			authentication. "Jabber" components have a completly different authentication
43			mechanism.
44
45			Also note that the support for some XEPs in L<Net::XMPP2::Ext> is just thought
46			for client side usage, if you miss any functionaly don't hesitate to ask the
47			author or send him a patch! (See L<Net::XMPP2> for contact information).
48
49			=head1 METHODS
50
51			=over 4
52
53			=item B<new (%args)>
54
55			This is the constructor. It takes the same arguments as
56			the constructor of L<Net::XMPP2::Connection> along with a
57			few others:
58
59			B<NOTE>: Please note that some arguments that L<Net::XMPP2::Connection>
60			usually takes have no effect when using this class. (That would be
61			the 'username', 'password', 'resource' and 'jid' arguments for example.)
62
63			=over 4
64
65			=item secret => $secret
66
67			C<$secret> is the secret that will be used for authentication with the server.
68
69			=back
70
71			=cut
72
73			sub new {
74			my $this = shift;
75			my $class = ref($this) \|\| $this;
76
77			my %args = @_;
78
79			unless (exists $args{initial_presence}) {
80			$args{stream_namespace} = 'component';
81			}
82			$args{override_host} = delete $args{server};
83			$args{override_host}
84			or die "Required 'server' argument missing to new for this component!";
85
86			unless (defined $args{port}) {
87			$args{port} = 5347;
88			}
89
90			my $self = $class->SUPER::new (%args);
91
92			$self->{parser}->set_stream_cb (sub {
93			my $secret = $self->{parser}->{parser}->xml_escape ($self->{secret});
94			$self->{writer}->send_handshake ($_[0]->attr ('id'), $secret);
95			});
96
97			$self->reg_cb (recv_stanza_xml => sub {
98			my ($self, $node) = @_;
99			if ($node->eq (component => 'handshake')) {
100			$self->{authenticated} = 1;
101			$self->event ('session_ready');
102			}
103			1
104			},
105			stream_pre_authentication => sub {
106			my ($self, $rcon) = @_;
107			$$rcon = 0;
108			1
109			});
110
111			$self
112			}
113
114			sub authenticate {
115			warn "authenticate called! Please read the documentation of "
116			."Net::XMPP2::Component why this is an error!"
117			}
118
119			=back
120
121			=head1 EVENTS
122
123			These additional events can be registered on with C<reg_cb>:
124
125			NOTE: The event C<stream_pre_authentication> should _not_ be handled
126			and just ignored. Don't attach callbacks to it!
127
128			=over 4
129
130			=item session_ready
131
132			This event indicates that the component has connected successfully
133			and can now be used to transmit stanzas.
134
135			=back
136
137			=head1 AUTHOR
138
139			Robin Redeker, C<< <elmex at ta-sa.org> >>, JID: C<< <elmex at jabber.org> >>
140
141			=head1 COPYRIGHT & LICENSE
142
143			Copyright 2007 Robin Redeker, all rights reserved.
144
145			This program is free software; you can redistribute it and/or modify it
146			under the same terms as Perl itself.
147
148			=cut
149
150			1; # End of Net::XMPP2::Component