Net/XMPP2/Error.pm

package Net::XMPP2::Error;
use strict;
use Net::XMPP2::Util qw/stringprep_jid prep_bare_jid/;
use Net::XMPP2::Error;

=head1 NAME

Net::XMPP2::Error - An error class hierarchy for error reporting

=head1 SYNOPSIS

   die $error->string;

=head1 DESCRIPTION

This module is a helper class for abstracting any kind
of error that occurs in Net::XMPP2.

You receive instances of these objects by various events.

=cut

sub new {
   my $this = shift;
   my $class = ref($this) || $this;
   my $self = bless { @_ }, $class;
   $self->init;
   $self
}

sub init { }

=head1 SUPER CLASS

Net::XMPP2::Error - The super class of all errors

=head2 METHODS

These methods are implemented by all subclasses.

=over 4

=item B<string ()>

Returns a humand readable string for this error.

=cut

sub string {
   my ($self) = @_;
   $self->{text}
}

=back

=cut

package Net::XMPP2::Error::Stanza;
our @ISA = qw/Net::XMPP2::Error/;

=head1 SUBCLASS

Net::XMPP2::Error::Stanza - Stanza errors

=cut

sub init {
   my ($self) = @_;
   my $node = $self->xml_node;

   unless (defined $node) {
      $self->{error_cond} = 'client-timeout';
      $self->{error_type} = 'cancel';
      return;
   }

   my @error;
   my ($err) = $node->find_all ([qw/client error/]);

   unless ($err) {
      warn "No error element found in error stanza!";
      $self->{text} = "Unknown Stanza error";
      return
   }

   $self->{error_type} = $err->attr ('type');
   $self->{error_code} = $err->attr ('code');

   if (my ($txt) = $err->find_all ([qw/stanzas text/])) {
      $self->{error_text} = $txt->text;
   }

   for my $er (
     qw/bad-request conflict feature-not-implemented forbidden
        gone internal-server-error item-not-found jid-malformed
        not-acceptable not-allowed not-authorized payment-required
        recipient-unavailable redirect registration-required
        remote-server-not-found remote-server-timeout resource-constraint
        service-unavailable subscription-required undefined-condition
        unexpected-request/)
   {
      if (my ($el) = $err->find_all ([stanzas => $er])) {
         $self->{error_cond}      = $er;
         $self->{error_cond_node} = $el;
         last;
      }
   }
}

=head2 METHODS

=over 4

=item B<xml_node ()>

Returns the L<Net::XMPP2::Node> object for this Stanza error.
This method returns undef if the Stanza timeouted.

In the case of a timeout the C<condition> method returns C<client-timeout>,
C<type> returns 'cancel' and C<code> undef.

=cut

sub xml_node {
   $_[0]->{node}
}

=item B<type ()>

This method returns one of:

   'cancel', 'continue', 'modify', 'auth' and 'wait'

=cut

sub type { $_[0]->{error_type} }

=item B<code ()>

This method returns the error code if one was found.

=cut

sub code { $_[0]->{error_code} }

=item B<condition ()>

Returns the error condition string if one was found when receiving the Stanza error.
It can be undef or one of:

   bad-request
   conflict
   feature-not-implemented
   forbidden
   gone
   internal-server-error
   item-not-found
   jid-malformed
   not-acceptable
   not-allowed
   not-authorized
   payment-required
   recipient-unavailable
   redirect
   registration-required
   remote-server-not-found
   remote-server-timeout
   resource-constraint
   service-unavailable
   subscription-required
   undefined-condition
   unexpected-request


=cut

sub condition { $_[0]->{error_cond} }

=item B<condition_node ()>

Returns the error condition node if one was found when receiving the Stanza error.
This is mostly for debugging purposes.

=cut

sub condition_node { $_[0]->{error_cond_node} }

=item B<text ()>

The humand readable error portion. Might be undef if none was received.

=cut

sub text { $_[0]->{error_text} }

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

   sprintf "stanza error: %s/%s (type %s): %s",
      $self->code || '',
      $self->condition || '',
      $self->type,
      $self->text
}

=back

=cut

package Net::XMPP2::Error::Presence;
our @ISA = qw/Net::XMPP2::Error::Stanza/;

=head1 SUBCLASS

Net::XMPP2::Error::Presence - Message errors

(Subclass of L<Net::XMPP2::Error::Stanza>)

=cut

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

   sprintf "presence error: %s/%s (type %s): %s",
      $self->code || '',
      $self->condition || '',
      $self->type,
      $self->text
}

package Net::XMPP2::Error::Message;
our @ISA = qw/Net::XMPP2::Error::Stanza/;

=head1 SUBCLASS

Net::XMPP2::Error::Message - Message errors

(Subclass of L<Net::XMPP2::Error::Stanza>)

=cut

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

   sprintf "message error: %s/%s (type %s): %s",
      $self->code || '',
      $self->condition || '',
      $self->type,
      $self->text
}

package Net::XMPP2::Error::IQ;
our @ISA = qw/Net::XMPP2::Error::Stanza/;

=head1 SUBCLASS

Net::XMPP2::Error::IQ - IQ errors

(Subclass of L<Net::XMPP2::Error::Stanza>)

=cut

sub init {
   my ($self) = @_;
   my $node = $self->xml_node;

   unless (defined $node) {
      $self->{error_cond} = 'client-timeout';
      $self->{error_type} = 'cancel';
      return;
   }

   $self->SUPER::init;
}

=head2 METHODS

=over 4

=item B<condition ()>

Same as L<Net::XMPP2::Error::Stanza> except that
in case of a IQ timeout it returns:

   'client-timeout'

=cut

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

   sprintf "iq error: %s/%s (type %s): %s",
      $self->code || '',
      $self->condition || '',
      $self->type,
      $self->text
}

=back

=cut

package Net::XMPP2::Error::Stream;
our @ISA = qw/Net::XMPP2::Error/;

=head1 SUBCLASS

Net::XMPP2::Error::Stream - XML Stream errors

=cut

sub init {
   my ($self) = @_;
   my $node = $self->xml_node;

   my @txt = $node->find_all ([qw/streams text/]);
   my $error;
   for my $er (
      qw/bad-format bad-namespace-prefix conflict connection-timeout host-gone
         host-unknown improper-addressing internal-server-error invalid-from
         invalid-id invalid-namespace invalid-xml not-authorized policy-violation
         remote-connection-failed resource-constraint restricted-xml
         see-other-host system-shutdown undefined-condition unsupported-stanza-type
         unsupported-version xml-not-well-formed/)
   {
      if (my (@n) = $node->find_all ([streams => $er])) {
         $error = $n[0]->name;
         last;
      }
   }

   unless ($error) {
      #d# warn "got undefined error stanza, trying to find any undefined error...";
      for my $n ($node->nodes) {
         if ($n->eq_ns ('streams')) {
            $error = $n->name;
         }
      }
   }

   $self->{error_name} = $error;
   $self->{error_text} = @txt ? $txt[0]->text : '';
}

=head2 METHODS

=over 4

=item B<xml_node ()>

Returns the L<Net::XMPP2::Node> object for this stream error.

=cut

sub xml_node {
   $_[0]->{node}
}

=item B<name ()>

Returns the name of the error. That might be undef, one of the following
strings or some other string that has been discovered by a heuristic
(because some servers send errors that are not in the RFC).

   bad-format
   bad-namespace-prefix
   conflict
   connection-timeout
   host-gone
   host-unknown
   improper-addressing
   internal-server-error
   invalid-from
   invalid-id
   invalid-namespace
   invalid-xml
   not-authorized
   policy-violation
   remote-connection-failed
   resource-constraint
   restricted-xml
   see-other-host
   system-shutdown
   undefined-condition
   unsupported-stanza-type
   unsupported-version
   xml-not-well-formed

=cut

sub name { $_[0]->{error_name} }

=item B<text ()>

The humand readable error portion. Might be undef if none was received.

=cut

sub text { $_[0]->{error_text} }

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

   sprintf ("stream error: %s: %s",
      $self->name,
      $self->text)
}

=back

=cut

package Net::XMPP2::Error::SASL;
our @ISA = qw/Net::XMPP2::Error/;

=head1 SUBCLASS

Net::XMPP2::Error::SASL - SASL authentication error

=cut

sub init {
   my ($self) = @_;
   my $node = $self->xml_node;

   my $error;
   for ($node->nodes) {
      $error = $_->name;
      last
   }

   $self->{error_cond} = $error;
}

=head2 METHODS

=over 4

=item B<xml_node ()>

Returns the L<Net::XMPP2::Node> object for this stream error.

=cut

sub xml_node {
   $_[0]->{node}
}

=item B<condition ()>

Returns the error condition, which might be one of:

   aborted
   incorrect-encoding
   invalid-authzid
   invalid-mechanism
   mechanism-too-weak
   not-authorized
   temporary-auth-failure

=cut

sub condition {
   $_[0]->{error_cond}
}

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

   sprintf "sasl error: %s",
      $self->condition
}

=back

=cut

package Net::XMPP2::Error::Register;
our @ISA = qw/Net::XMPP2::Error::IQ/;

=head1 SUBCLASS

Net::XMPP2::Error::Register - In band registration error

=cut

=head2 METHODS

=over 4

=item B<register_state ()>

Returns the state of registration, one of:

   form-request
   form-submitted

=cut

sub register_state {
   my ($self) = @_;
   $self->{register_state}
}

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

   sprintf "ibb registration error (in %s): %s",
      $self->register_state,
      $self->SUPER::string
}

=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
Revision:	1.7
Committed:	Wed Jul 4 16:05:22 2007 UTC (19 years, 2 months ago) by elmex
Branch:	MAIN
Changes since 1.6:	+51 -17 lines
Log Message:	major documentation refresh. preparing for release
#	User	Rev	Content
1	elmex	1.1	package Net::XMPP2::Error;
2			use strict;
3			use Net::XMPP2::Util qw/stringprep_jid prep_bare_jid/;
4			use Net::XMPP2::Error;
5
6			=head1 NAME
7
8			Net::XMPP2::Error - An error class hierarchy for error reporting
9
10			=head1 SYNOPSIS
11
12			die $error->string;
13
14			=head1 DESCRIPTION
15
16			This module is a helper class for abstracting any kind
17			of error that occurs in Net::XMPP2.
18
19			You receive instances of these objects by various events.
20
21			=cut
22
23			sub new {
24			my $this = shift;
25			my $class = ref($this) \|\| $this;
26			my $self = bless { @_ }, $class;
27			$self->init;
28			$self
29			}
30
31			sub init { }
32
33			=head1 SUPER CLASS
34
35			Net::XMPP2::Error - The super class of all errors
36
37			=head2 METHODS
38
39			These methods are implemented by all subclasses.
40
41	elmex	1.7	=over 4
42
43			=item B<string ()>
44	elmex	1.1
45			Returns a humand readable string for this error.
46
47			=cut
48
49			sub string {
50			my ($self) = @_;
51			$self->{text}
52			}
53
54	elmex	1.7	=back
55
56			=cut
57
58	elmex	1.6	package Net::XMPP2::Error::Stanza;
59	elmex	1.1	our @ISA = qw/Net::XMPP2::Error/;
60
61			=head1 SUBCLASS
62
63	elmex	1.6	Net::XMPP2::Error::Stanza - Stanza errors
64	elmex	1.1
65			=cut
66
67			sub init {
68			my ($self) = @_;
69			my $node = $self->xml_node;
70
71	elmex	1.4	unless (defined $node) {
72	elmex	1.6	$self->{error_cond} = 'client-timeout';
73			$self->{error_type} = 'cancel';
74	elmex	1.4	return;
75			}
76
77	elmex	1.1	my @error;
78			my ($err) = $node->find_all ([qw/client error/]);
79
80			unless ($err) {
81			warn "No error element found in error stanza!";
82	elmex	1.6	$self->{text} = "Unknown Stanza error";
83	elmex	1.1	return
84			}
85
86	elmex	1.6	$self->{error_type} = $err->attr ('type');
87			$self->{error_code} = $err->attr ('code');
88	elmex	1.1
89			if (my ($txt) = $err->find_all ([qw/stanzas text/])) {
90	elmex	1.6	$self->{error_text} = $txt->text;
91	elmex	1.1	}
92
93			for my $er (
94			qw/bad-request conflict feature-not-implemented forbidden
95			gone internal-server-error item-not-found jid-malformed
96			not-acceptable not-allowed not-authorized payment-required
97			recipient-unavailable redirect registration-required
98			remote-server-not-found remote-server-timeout resource-constraint
99			service-unavailable subscription-required undefined-condition
100			unexpected-request/)
101			{
102			if (my ($el) = $err->find_all ([stanzas => $er])) {
103	elmex	1.6	$self->{error_cond} = $er;
104			$self->{error_cond_node} = $el;
105	elmex	1.1	last;
106			}
107			}
108			}
109
110			=head2 METHODS
111
112	elmex	1.7	=over 4
113
114			=item B<xml_node ()>
115	elmex	1.1
116	elmex	1.6	Returns the L<Net::XMPP2::Node> object for this Stanza error.
117			This method returns undef if the Stanza timeouted.
118	elmex	1.4
119			In the case of a timeout the C<condition> method returns C<client-timeout>,
120			C<type> returns 'cancel' and C<code> undef.
121	elmex	1.1
122			=cut
123
124			sub xml_node {
125			$_[0]->{node}
126			}
127
128	elmex	1.7	=item B<type ()>
129	elmex	1.1
130			This method returns one of:
131
132			'cancel', 'continue', 'modify', 'auth' and 'wait'
133
134			=cut
135
136	elmex	1.6	sub type { $_[0]->{error_type} }
137	elmex	1.1
138	elmex	1.7	=item B<code ()>
139	elmex	1.1
140			This method returns the error code if one was found.
141
142			=cut
143
144	elmex	1.6	sub code { $_[0]->{error_code} }
145	elmex	1.1
146	elmex	1.7	=item B<condition ()>
147	elmex	1.1
148	elmex	1.6	Returns the error condition string if one was found when receiving the Stanza error.
149	elmex	1.1	It can be undef or one of:
150
151			bad-request
152			conflict
153			feature-not-implemented
154			forbidden
155			gone
156			internal-server-error
157			item-not-found
158			jid-malformed
159			not-acceptable
160			not-allowed
161			not-authorized
162			payment-required
163			recipient-unavailable
164			redirect
165			registration-required
166			remote-server-not-found
167			remote-server-timeout
168			resource-constraint
169			service-unavailable
170			subscription-required
171			undefined-condition
172			unexpected-request
173
174	elmex	1.4
175	elmex	1.1	=cut
176
177	elmex	1.6	sub condition { $_[0]->{error_cond} }
178	elmex	1.1
179	elmex	1.7	=item B<condition_node ()>
180	elmex	1.1
181	elmex	1.6	Returns the error condition node if one was found when receiving the Stanza error.
182	elmex	1.1	This is mostly for debugging purposes.
183
184			=cut
185
186	elmex	1.6	sub condition_node { $_[0]->{error_cond_node} }
187	elmex	1.1
188	elmex	1.7	=item B<text ()>
189	elmex	1.1
190			The humand readable error portion. Might be undef if none was received.
191
192			=cut
193
194	elmex	1.6	sub text { $_[0]->{error_text} }
195
196			sub string {
197			my ($self) = @_;
198
199			sprintf "stanza error: %s/%s (type %s): %s",
200			$self->code \|\| '',
201			$self->condition \|\| '',
202			$self->type,
203			$self->text
204			}
205
206	elmex	1.7	=back
207
208			=cut
209
210	elmex	1.6	package Net::XMPP2::Error::Presence;
211			our @ISA = qw/Net::XMPP2::Error::Stanza/;
212
213			=head1 SUBCLASS
214
215			Net::XMPP2::Error::Presence - Message errors
216
217			(Subclass of L<Net::XMPP2::Error::Stanza>)
218
219			=cut
220
221			sub string {
222			my ($self) = @_;
223
224			sprintf "presence error: %s/%s (type %s): %s",
225			$self->code \|\| '',
226			$self->condition \|\| '',
227			$self->type,
228			$self->text
229			}
230
231			package Net::XMPP2::Error::Message;
232			our @ISA = qw/Net::XMPP2::Error::Stanza/;
233
234			=head1 SUBCLASS
235
236			Net::XMPP2::Error::Message - Message errors
237
238			(Subclass of L<Net::XMPP2::Error::Stanza>)
239
240			=cut
241
242			sub string {
243			my ($self) = @_;
244
245			sprintf "message error: %s/%s (type %s): %s",
246			$self->code \|\| '',
247			$self->condition \|\| '',
248			$self->type,
249			$self->text
250			}
251
252			package Net::XMPP2::Error::IQ;
253			our @ISA = qw/Net::XMPP2::Error::Stanza/;
254
255			=head1 SUBCLASS
256
257			Net::XMPP2::Error::IQ - IQ errors
258
259			(Subclass of L<Net::XMPP2::Error::Stanza>)
260
261			=cut
262
263			sub init {
264			my ($self) = @_;
265			my $node = $self->xml_node;
266
267			unless (defined $node) {
268			$self->{error_cond} = 'client-timeout';
269			$self->{error_type} = 'cancel';
270			return;
271			}
272
273			$self->SUPER::init;
274			}
275
276	elmex	1.7	=head2 METHODS
277
278			=over 4
279
280			=item B<condition ()>
281	elmex	1.6
282			Same as L<Net::XMPP2::Error::Stanza> except that
283			in case of a IQ timeout it returns:
284
285			'client-timeout'
286
287			=cut
288	elmex	1.1
289			sub string {
290			my ($self) = @_;
291
292			sprintf "iq error: %s/%s (type %s): %s",
293			$self->code \|\| '',
294			$self->condition \|\| '',
295			$self->type,
296			$self->text
297			}
298
299	elmex	1.7	=back
300
301			=cut
302
303	elmex	1.2	package Net::XMPP2::Error::Stream;
304	elmex	1.1	our @ISA = qw/Net::XMPP2::Error/;
305
306			=head1 SUBCLASS
307
308			Net::XMPP2::Error::Stream - XML Stream errors
309
310			=cut
311
312			sub init {
313			my ($self) = @_;
314			my $node = $self->xml_node;
315
316	elmex	1.5	my @txt = $node->find_all ([qw/streams text/]);
317	elmex	1.1	my $error;
318			for my $er (
319			qw/bad-format bad-namespace-prefix conflict connection-timeout host-gone
320			host-unknown improper-addressing internal-server-error invalid-from
321			invalid-id invalid-namespace invalid-xml not-authorized policy-violation
322			remote-connection-failed resource-constraint restricted-xml
323			see-other-host system-shutdown undefined-condition unsupported-stanza-type
324			unsupported-version xml-not-well-formed/)
325			{
326	elmex	1.5	if (my (@n) = $node->find_all ([streams => $er])) {
327			$error = $n[0]->name;
328			last;
329	elmex	1.1	}
330			}
331
332			unless ($error) {
333			#d# warn "got undefined error stanza, trying to find any undefined error...";
334	elmex	1.5	for my $n ($node->nodes) {
335			if ($n->eq_ns ('streams')) {
336			$error = $n->name;
337	elmex	1.1	}
338			}
339			}
340
341			$self->{error_name} = $error;
342			$self->{error_text} = @txt ? $txt[0]->text : '';
343			}
344
345	elmex	1.3	=head2 METHODS
346
347	elmex	1.7	=over 4
348
349			=item B<xml_node ()>
350	elmex	1.1
351			Returns the L<Net::XMPP2::Node> object for this stream error.
352
353			=cut
354
355			sub xml_node {
356			$_[0]->{node}
357			}
358
359	elmex	1.7	=item B<name ()>
360	elmex	1.1
361			Returns the name of the error. That might be undef, one of the following
362			strings or some other string that has been discovered by a heuristic
363			(because some servers send errors that are not in the RFC).
364
365			bad-format
366			bad-namespace-prefix
367			conflict
368			connection-timeout
369			host-gone
370			host-unknown
371			improper-addressing
372			internal-server-error
373			invalid-from
374			invalid-id
375			invalid-namespace
376			invalid-xml
377			not-authorized
378			policy-violation
379			remote-connection-failed
380			resource-constraint
381			restricted-xml
382			see-other-host
383			system-shutdown
384			undefined-condition
385			unsupported-stanza-type
386			unsupported-version
387			xml-not-well-formed
388
389			=cut
390
391	elmex	1.2	sub name { $_[0]->{error_name} }
392	elmex	1.1
393	elmex	1.7	=item B<text ()>
394	elmex	1.1
395			The humand readable error portion. Might be undef if none was received.
396
397			=cut
398
399			sub text { $_[0]->{error_text} }
400
401			sub string {
402			my ($self) = @_;
403
404	elmex	1.5	sprintf ("stream error: %s: %s",
405	elmex	1.1	$self->name,
406	elmex	1.5	$self->text)
407	elmex	1.1	}
408
409	elmex	1.7	=back
410
411			=cut
412
413	elmex	1.2	package Net::XMPP2::Error::SASL;
414			our @ISA = qw/Net::XMPP2::Error/;
415
416			=head1 SUBCLASS
417
418			Net::XMPP2::Error::SASL - SASL authentication error
419
420			=cut
421
422			sub init {
423			my ($self) = @_;
424			my $node = $self->xml_node;
425
426			my $error;
427			for ($node->nodes) {
428			$error = $_->name;
429			last
430			}
431
432			$self->{error_cond} = $error;
433			}
434
435	elmex	1.3	=head2 METHODS
436
437	elmex	1.7	=over 4
438
439			=item B<xml_node ()>
440	elmex	1.2
441			Returns the L<Net::XMPP2::Node> object for this stream error.
442
443			=cut
444
445			sub xml_node {
446			$_[0]->{node}
447			}
448
449	elmex	1.7	=item B<condition ()>
450	elmex	1.2
451			Returns the error condition, which might be one of:
452
453			aborted
454			incorrect-encoding
455			invalid-authzid
456			invalid-mechanism
457			mechanism-too-weak
458			not-authorized
459			temporary-auth-failure
460
461			=cut
462
463			sub condition {
464			$_[0]->{error_cond}
465			}
466
467			sub string {
468			my ($self) = @_;
469
470			sprintf "sasl error: %s",
471			$self->condition
472			}
473
474	elmex	1.7	=back
475
476			=cut
477
478	elmex	1.3	package Net::XMPP2::Error::Register;
479			our @ISA = qw/Net::XMPP2::Error::IQ/;
480
481			=head1 SUBCLASS
482
483			Net::XMPP2::Error::Register - In band registration error
484
485			=cut
486
487			=head2 METHODS
488
489	elmex	1.7	=over 4
490
491			=item B<register_state ()>
492	elmex	1.3
493			Returns the state of registration, one of:
494
495			form-request
496			form-submitted
497
498			=cut
499
500			sub register_state {
501			my ($self) = @_;
502			$self->{register_state}
503			}
504
505			sub string {
506			my ($self) = @_;
507
508			sprintf "ibb registration error (in %s): %s",
509			$self->register_state,
510			$self->SUPER::string
511			}
512
513	elmex	1.7	=back
514
515	elmex	1.1	=head1 AUTHOR
516
517	elmex	1.7	Robin Redeker, C<< <elmex at ta-sa.org> >>, JID: C<< <elmex at jabber.org> >>
518	elmex	1.1
519			=head1 COPYRIGHT & LICENSE
520
521			Copyright 2007 Robin Redeker, all rights reserved.
522
523			This program is free software; you can redistribute it and/or modify it
524			under the same terms as Perl itself.
525
526			=cut
527
528			1; # End of Net::XMPP2