1package GSSAPI::Status;
2
3require 5.005_62;
4use strict;
5use warnings;
6
7use overload
8	'bool' => "is_true",
9	'!'    => "is_false",
10	'""'   => "stringify";
11
12our @ISA = qw(GSSAPI);
13
14sub import { 1 }			# for GSSAPI::import()
15
16sub generic_message ($) {
17    my $self = shift;
18    display_status($self->major, GSSAPI::GSS_C_GSS_CODE);
19}
20
21sub specific_message ($) {
22    my $self = shift;
23    display_status($self->minor, GSSAPI::GSS_C_MECH_CODE);
24}
25
26sub is_true ($$$) {
27    my $self = shift;
28    ! GSS_ERROR($self->major)
29}
30
31sub is_false ($$$) {
32    my $self = shift;
33    GSS_ERROR($self->major)
34}
35
36sub stringify ($$$) {
37    my $self = shift;
38    join("\n", $self->generic_message, $self->specific_message, '')
39}
40
41# Autoload methods go after =cut, and are processed by the autosplit program.
42
431;
44__END__
45
46=head1 NAME
47
48GSSAPI::Status - methods for handlings GSSAPI statuses
49
50=head1 SYNOPSIS
51
52  use GSSAPI;
53
54  $status = GSSAPI::Status->new(GSS_S_COMPLETE, 0);
55
56  if (GSS_ERROR($status->major)) {
57    die "a horrible death";
58  }
59  if (! $status) {			# another way of writing the above
60    die "a horrible death";
61  }
62
63  $status = $some_GSSAPI->someop($args1, etc);
64  if ($status) {
65    foreach ($status->generic_message, $status->specific_message) {
66      print "GSSAPI error: $_\n";
67    }
68    die "help me";
69  }
70
71
72=head1 DESCRIPTION
73
74C<GSSAPI::Status> objects are returned by most other GSSAPI operations.
75Such statuses consist of a GSSAPI generic code and, for most
76operations, a mechanism specific code.  These numeric codes can be
77accessed via the methods C<major> and C<minor>.  The standard textual
78messages that go with the current status can be obtained via the
79C<generic_message> and C<specific_message> methods.  Each of these
80returns a list of text which should presumably be displayed in
81order.
82
83The generic code part of a GSSAPI::Status is composed of three
84subfields that can be accessed with the C<GSS_CALLING_ERROR>,
85C<GSS_ROUTINE_ERROR>, and C<GSS_SUPPLEMENTARY_INFO> functions.  The
86returned values can be compared against the constants whose names
87start with C<GSS_S_> if your code wants to handle particular errors
88itself.  The C<GSS_ERROR> function returns true if and only if the
89given generic code contains neither a calling error nor a routine
90error.
91
92When evaluated in a boolean context, a C<GSSAPI::Status> object
93will be true if and only if the major status code is C<GSS_S_COMPLETE>.
94
95When evaluated in a string contect, a C<GSSAPI::Status> object will
96return the generic and specific messages all joined together with
97newlines.  This may or may not make C<die $status> work usefully.
98
99=head1 BUGS
100
101The base objects are currently implmented as a blessed C structure
102containing the major and minor status codes.  It should probably
103be a blessed array or hash instead, thereby cutting down on the
104amount of C code involved and making it more flexible.
105
106=head1 AUTHOR
107
108Philip Guenther <pguen@cpan.org>
109
110=head1 SEE ALSO
111
112perl(1)
113RFC2743
114
115=cut
116