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');
      }
   },
   stream_pre_authentication => sub {
      my ($self, $rcon) = @_;
      $$rcon = 0;
   });

   $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.2
Committed:	Tue Jul 24 12:31:15 2007 UTC (19 years, 2 months ago) by elmex
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+0 -2 lines
Log Message:	documentation update
#	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			},
104			stream_pre_authentication => sub {
105			my ($self, $rcon) = @_;
106			$$rcon = 0;
107			});
108
109			$self
110			}
111
112			sub authenticate {
113			warn "authenticate called! Please read the documentation of "
114			."Net::XMPP2::Component why this is an error!"
115			}
116
117			=back
118
119			=head1 EVENTS
120
121			These additional events can be registered on with C<reg_cb>:
122
123			NOTE: The event C<stream_pre_authentication> should _not_ be handled
124			and just ignored. Don't attach callbacks to it!
125
126			=over 4
127
128			=item session_ready
129
130			This event indicates that the component has connected successfully
131			and can now be used to transmit stanzas.
132
133			=back
134
135			=head1 AUTHOR
136
137			Robin Redeker, C<< <elmex at ta-sa.org> >>, JID: C<< <elmex at jabber.org> >>
138
139			=head1 COPYRIGHT & LICENSE
140
141			Copyright 2007 Robin Redeker, all rights reserved.
142
143			This program is free software; you can redistribute it and/or modify it
144			under the same terms as Perl itself.
145
146			=cut
147
148			1; # End of Net::XMPP2::Component