| 1 | # $Id: BaseProfile.pm,v 1.7 2003/09/11 19:57:31 davidb Exp $ | ||||||||||||||||||||||||||
| 2 | # | ||||||||||||||||||||||||||
| 3 | # Copyright (C) 2003 Verisign, Inc. | ||||||||||||||||||||||||||
| 4 | # | ||||||||||||||||||||||||||
| 5 | # This library is free software; you can redistribute it and/or | ||||||||||||||||||||||||||
| 6 | # modify it under the terms of the GNU Lesser General Public | ||||||||||||||||||||||||||
| 7 | # License as published by the Free Software Foundation; either | ||||||||||||||||||||||||||
| 8 | # version 2.1 of the License, or (at your option) any later version. | ||||||||||||||||||||||||||
| 9 | # | ||||||||||||||||||||||||||
| 10 | # This library is distributed in the hope that it will be useful, | ||||||||||||||||||||||||||
| 11 | # but WITHOUT ANY WARRANTY; without even the implied warranty of | ||||||||||||||||||||||||||
| 12 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||||||||||||||||||||||||||
| 13 | # Lesser General Public License for more details. | ||||||||||||||||||||||||||
| 14 | # | ||||||||||||||||||||||||||
| 15 | # You should have received a copy of the GNU Lesser General Public | ||||||||||||||||||||||||||
| 16 | # License along with this library; if not, write to the Free Software | ||||||||||||||||||||||||||
| 17 | # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 | ||||||||||||||||||||||||||
| 18 | # USA | ||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||
| 20 | package Net::BEEP::Lite::BaseProfile; | ||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||
| 22 | =head1 NAME | ||||||||||||||||||||||||||
| 23 | |||||||||||||||||||||||||||
| 24 | Net::BEEP::Lite::BaseProfile | ||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||
| 26 | =head1 SYNOPIS | ||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||
| 28 | $profile = Net::BEEP::Lite::BaseProfile->new(); | ||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||
| 30 | my $uri = $profile->uri(); | ||||||||||||||||||||||||||
| 31 | |||||||||||||||||||||||||||
| 32 | if ($message->isa('Net::BEEP::Lite::Message') { | ||||||||||||||||||||||||||
| 33 | $profile->handle_message($session, $message); | ||||||||||||||||||||||||||
| 34 | } | ||||||||||||||||||||||||||
| 35 | |||||||||||||||||||||||||||
| 36 | =head1 DESCRIPTION | ||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||
| 38 | "Net::BEEP::Lite::BaseProfile" is the base class Net::BEEP::Lite profiles | ||||||||||||||||||||||||||
| 39 | should inherit from/implement. It is not intended to be instantiated | ||||||||||||||||||||||||||
| 40 | on its own. This class provides the basic structure of profile. | ||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||
| 42 | In general, subclasses only need to override the constructor (for | ||||||||||||||||||||||||||
| 43 | additional initialization parameters, if any) and the various message | ||||||||||||||||||||||||||
| 44 | handler methods (MSG(), RPY(), etc.). | ||||||||||||||||||||||||||
| 45 | |||||||||||||||||||||||||||
| 46 | Note that in general BEEP "client" applications generally do not need | ||||||||||||||||||||||||||
| 47 | to create profiles (although they may if they wish). "Server" | ||||||||||||||||||||||||||
| 48 | applications generally do need to create profiles. | ||||||||||||||||||||||||||
| 49 | |||||||||||||||||||||||||||
| 50 | Normally profiles are designed to be shared between Sessions. This | ||||||||||||||||||||||||||
| 51 | primarily means that no session or channel base state is stored in the | ||||||||||||||||||||||||||
| 52 | profile object itself. Designers of profiles need not stick to this | ||||||||||||||||||||||||||
| 53 | constraint, however. In this framework, most often each Session is in | ||||||||||||||||||||||||||
| 54 | a different process and thus not actually shared amongst Sessions. | ||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||
| 56 | =cut | ||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||
| 58 | 3 | ▶ | use Carp; | ||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||
| 60 | 3 | ▶ | use strict; | ||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||
| 61 | 3 | ▶ | use warnings; | ||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||
| 63 | =head1 CONSTRUCTOR | ||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||
| 65 | =over 4 | ||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||
| 67 | =item new( I<ARGS> ) | ||||||||||||||||||||||||||
| 68 | |||||||||||||||||||||||||||
| 69 | This constructor currently has no valid arguments. | ||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||
| 71 | =back | ||||||||||||||||||||||||||
| 72 | |||||||||||||||||||||||||||
| 73 | =cut | ||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||
| 75 | 1 | ▶ | sub new { | ||||||||||||||||||||||||
|
Subroutine
new: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||||||||||||||||||
| 76 | 1 | my $this = shift; | |||||||||||||||||||||||||
| 77 | 1 | ▶ | my $class = ref($this) || $this; | ||||||||||||||||||||||||
|
Condition33%1/3
ref $this || $this
MC/DC0%0/2
ref $this || $this
ref $this
$this
Truth table33%1/3
A || B
A= ref $thisB= $this
| |||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||
| 79 | 1 | my $self = {}; | |||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||
| 81 | 1 | bless $self, $class; | |||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||
| 83 | 1 | $self->initialize(@_); | |||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||
| 85 | 1 | $self; | |||||||||||||||||||||||||
| 86 | } | ||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||
| 88 | =head1 METHODS | ||||||||||||||||||||||||||
| 89 | |||||||||||||||||||||||||||
| 90 | =over 4 | ||||||||||||||||||||||||||
| 91 | |||||||||||||||||||||||||||
| 92 | =item initialize( I<ARGS> ) | ||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||
| 94 | This method initializes the object. The arguments are named value | ||||||||||||||||||||||||||
| 95 | pairs, although currently none are defined. Users of this class do | ||||||||||||||||||||||||||
| 96 | not call this method, as it is invoked by the constructor. | ||||||||||||||||||||||||||
| 97 | Subclasses, however, should invoke this in their constructors. (i.e., | ||||||||||||||||||||||||||
| 98 | as $self->SUPER::initialize(@_)). | ||||||||||||||||||||||||||
| 99 | |||||||||||||||||||||||||||
| 100 | =cut | ||||||||||||||||||||||||||
| 101 | |||||||||||||||||||||||||||
| 102 | 6 | ▶ | sub initialize { | ||||||||||||||||||||||||
|
Subroutine
initialize: called CC=4 SCAR=15.8
Pod
documented
| |||||||||||||||||||||||||||
| 103 | 6 | my $self = shift; | |||||||||||||||||||||||||
| 104 | 6 | my %args = @_; | |||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||
| 106 | 6 | $self->{debug} = 0; | |||||||||||||||||||||||||
| 107 | 6 | $self->{trace} = 0; | |||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||
| 109 | 6 | for (keys %args) { | |||||||||||||||||||||||||
| 110 | 1 | my $val = $args{$_}; | |||||||||||||||||||||||||
| 111 | 1 | ▶ | /^debug/io and do { | ||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||
| 112 | 0 | $self->{debug} = $val; | |||||||||||||||||||||||||
| 113 | 0 | next; | |||||||||||||||||||||||||
| 114 | }; | ||||||||||||||||||||||||||
| 115 | 1 | ▶ | /^trace/io and do { | ||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||
| 116 | 0 | $self->{trace} = $val; | |||||||||||||||||||||||||
| 117 | 0 | next; | |||||||||||||||||||||||||
| 118 | }; | ||||||||||||||||||||||||||
| 119 | } | ||||||||||||||||||||||||||
| 120 | } | ||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||
| 122 | =item uri([$va]) | ||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||
| 124 | This returns the profile\'s identifying URI (e.g., | ||||||||||||||||||||||||||
| 125 | http://iana.org/beep/SASL/PLAIN). If passed an optional value, it | ||||||||||||||||||||||||||
| 126 | sets that to the profile's URI. | ||||||||||||||||||||||||||
| 127 | |||||||||||||||||||||||||||
| 128 | =cut | ||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||
| 130 | 5 | ▶ | sub uri { | ||||||||||||||||||||||||
|
Subroutine
uri: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||
| 131 | 5 | my $self = shift; | |||||||||||||||||||||||||
| 132 | 5 | my $val = shift; | |||||||||||||||||||||||||
| 133 | |||||||||||||||||||||||||||
| 134 | 5 | ▶ | $self->{uri} = $val if $val; | ||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||
| 135 | 5 | ▶ | $self->{uri} || confess "profile has no URI!\n"; | ||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||
| 136 | } | ||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||
| 138 | =item handle_message($session, $message) | ||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||
| 140 | Handle a BEEP message based on its type. This just invokes the | ||||||||||||||||||||||||||
| 141 | profile's various handler functions (MSG(), ERR(), etc.). Returns | ||||||||||||||||||||||||||
| 142 | whatever the handler method returns (generally the original message). | ||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||
| 144 | =cut | ||||||||||||||||||||||||||
| 145 | |||||||||||||||||||||||||||
| 146 | 6 | ▶ | sub handle_message { | ||||||||||||||||||||||||
|
Subroutine
handle_message: called CC=6 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||
| 147 | 6 | my $self = shift; | |||||||||||||||||||||||||
| 148 | 6 | my $session = shift; | |||||||||||||||||||||||||
| 149 | 6 | my $message = shift; | |||||||||||||||||||||||||
| 150 | |||||||||||||||||||||||||||
| 151 | 6 | ▶ | if ($message->type() eq "MSG") { | ||||||||||||||||||||||||
|
Branch: 5 branches
| |||||||||||||||||||||||||||
| 152 | 1 | $self->MSG($session, $message); | |||||||||||||||||||||||||
| 153 | } elsif ($message->type() eq "RPY") { | ||||||||||||||||||||||||||
| 154 | 1 | $self->RPY($session, $message); | |||||||||||||||||||||||||
| 155 | } elsif ($message->type() eq "ERR") { | ||||||||||||||||||||||||||
| 156 | 1 | $self->ERR($session, $message); | |||||||||||||||||||||||||
| 157 | } elsif ($message->type() eq "ANS") { | ||||||||||||||||||||||||||
| 158 | 1 | $self->ANS($session, $message); | |||||||||||||||||||||||||
| 159 | } elsif ($message->type() eq "NUL") { | ||||||||||||||||||||||||||
| 160 | 1 | $self->NUL($session, $message); | |||||||||||||||||||||||||
| 161 | } else { | ||||||||||||||||||||||||||
| 162 | 1 | croak $message->type(), " is unknown"; | |||||||||||||||||||||||||
| 163 | } | ||||||||||||||||||||||||||
| 164 | } | ||||||||||||||||||||||||||
| 165 | |||||||||||||||||||||||||||
| 166 | =item start_channel_request($session, $message, $data) | ||||||||||||||||||||||||||
| 167 | |||||||||||||||||||||||||||
| 168 | Handle a start channel request. This is a place for profiles to | ||||||||||||||||||||||||||
| 169 | control what happens when a start channel request for this profile is | ||||||||||||||||||||||||||
| 170 | handled by the management profile. $session is the session the | ||||||||||||||||||||||||||
| 171 | request was received by, $message is the original request, and $data | ||||||||||||||||||||||||||
| 172 | is the data contained within the <start> element, extracted and | ||||||||||||||||||||||||||
| 173 | decoded from base64 (if necessary). | ||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||
| 175 | This method must return one of the following responses: | ||||||||||||||||||||||||||
| 176 | |||||||||||||||||||||||||||
| 177 | =over 4 | ||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||
| 179 | =item undef | ||||||||||||||||||||||||||
| 180 | |||||||||||||||||||||||||||
| 181 | This means that the caller (the management profile) will return a | ||||||||||||||||||||||||||
| 182 | normal <profile> response with no included data and start the channel | ||||||||||||||||||||||||||
| 183 | This is what the base version of this method will return. | ||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||
| 185 | =item ('RPY', $content, [$encode]) | ||||||||||||||||||||||||||
| 186 | |||||||||||||||||||||||||||
| 187 | This means that the caller should return a <profile> response with the | ||||||||||||||||||||||||||
| 188 | included content. If $encode is true, it should base64 encode the | ||||||||||||||||||||||||||
| 189 | content first. | ||||||||||||||||||||||||||
| 190 | |||||||||||||||||||||||||||
| 191 | =item ('ERR', $code, $content) | ||||||||||||||||||||||||||
| 192 | |||||||||||||||||||||||||||
| 193 | This means that the caller should return this error instead of | ||||||||||||||||||||||||||
| 194 | starting the channel. | ||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||
| 196 | =item 'NUL' | ||||||||||||||||||||||||||
| 197 | |||||||||||||||||||||||||||
| 198 | This means that the caller should do nothing (don't send a response, | ||||||||||||||||||||||||||
| 199 | don't start the channel), this routine has handled the start channel | ||||||||||||||||||||||||||
| 200 | request. | ||||||||||||||||||||||||||
| 201 | |||||||||||||||||||||||||||
| 202 | =back | ||||||||||||||||||||||||||
| 203 | |||||||||||||||||||||||||||
| 204 | If not overridden, this routine will return undef, and will stow the | ||||||||||||||||||||||||||
| 205 | data in $session->{start_channel_data}, if there was any. | ||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||
| 207 | =cut | ||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||
| 209 | 1 | ▶ | sub start_channel_request { | ||||||||||||||||||||||||
|
Subroutine
start_channel_request: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||||||||
| 210 | 1 | my $self = shift; | |||||||||||||||||||||||||
| 211 | 1 | my $session = shift; | |||||||||||||||||||||||||
| 212 | 1 | my $message = shift; | |||||||||||||||||||||||||
| 213 | 1 | my $data = shift; | |||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||||
| 215 | 1 | ▶ | $session->{start_channel_data} = $data if $data; | ||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||||
| 217 | 1 | return undef; | |||||||||||||||||||||||||
| 218 | } | ||||||||||||||||||||||||||
| 219 | |||||||||||||||||||||||||||
| 220 | =item MSG($session, $message) | ||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||
| 222 | Handle MSG type messages. This should be overridden by the subclass. | ||||||||||||||||||||||||||
| 223 | Subclasses should have this method return the original method. This | ||||||||||||||||||||||||||
| 224 | version will simply croak if invoked. | ||||||||||||||||||||||||||
| 225 | |||||||||||||||||||||||||||
| 226 | =cut | ||||||||||||||||||||||||||
| 227 | |||||||||||||||||||||||||||
| 228 | 2 | ▶ | sub MSG { | ||||||||||||||||||||||||
|
Subroutine
MSG: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||
| 229 | 2 | my $self = shift; | |||||||||||||||||||||||||
| 230 | 2 | my $session = shift; | |||||||||||||||||||||||||
| 231 | 2 | my $message = shift; | |||||||||||||||||||||||||
| 232 | |||||||||||||||||||||||||||
| 233 | 2 | croak "MSG handling not implemented\n"; | |||||||||||||||||||||||||
| 234 | } | ||||||||||||||||||||||||||
| 235 | |||||||||||||||||||||||||||
| 236 | =item RPY($session, $message) | ||||||||||||||||||||||||||
| 237 | |||||||||||||||||||||||||||
| 238 | Handle RPY type messages. This should be overridden by the subclass. | ||||||||||||||||||||||||||
| 239 | Subclasses should have this method return the original method. This | ||||||||||||||||||||||||||
| 240 | version will simply croak if invoked. | ||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||
| 242 | =cut | ||||||||||||||||||||||||||
| 243 | |||||||||||||||||||||||||||
| 244 | 1 | ▶ | sub RPY { | ||||||||||||||||||||||||
|
Subroutine
RPY: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||
| 245 | 1 | my $self = shift; | |||||||||||||||||||||||||
| 246 | 1 | my $session = shift; | |||||||||||||||||||||||||
| 247 | 1 | my $message = shift; | |||||||||||||||||||||||||
| 248 | |||||||||||||||||||||||||||
| 249 | 1 | croak "RPY handling not implemented\n"; | |||||||||||||||||||||||||
| 250 | } | ||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||
| 252 | =item ERR($session, $message) | ||||||||||||||||||||||||||
| 253 | |||||||||||||||||||||||||||
| 254 | Handle ERR type messages. This should be overridden by the subclass. | ||||||||||||||||||||||||||
| 255 | Subclasses should have this method return the original method. This | ||||||||||||||||||||||||||
| 256 | version will simply croak if invoked. | ||||||||||||||||||||||||||
| 257 | |||||||||||||||||||||||||||
| 258 | =cut | ||||||||||||||||||||||||||
| 259 | |||||||||||||||||||||||||||
| 260 | 1 | ▶ | sub ERR { | ||||||||||||||||||||||||
|
Subroutine
ERR: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||
| 261 | 1 | my $self = shift; | |||||||||||||||||||||||||
| 262 | 1 | my $session = shift; | |||||||||||||||||||||||||
| 263 | 1 | my $message = shift; | |||||||||||||||||||||||||
| 264 | |||||||||||||||||||||||||||
| 265 | 1 | croak "ERR handling not implemented\n"; | |||||||||||||||||||||||||
| 266 | } | ||||||||||||||||||||||||||
| 267 | |||||||||||||||||||||||||||
| 268 | =item ANS($session, $message) | ||||||||||||||||||||||||||
| 269 | |||||||||||||||||||||||||||
| 270 | Handle ANS type messages. This should be overridden by the subclass. | ||||||||||||||||||||||||||
| 271 | Subclasses should have this method return the original method. This | ||||||||||||||||||||||||||
| 272 | version will simply croak if invoked. | ||||||||||||||||||||||||||
| 273 | |||||||||||||||||||||||||||
| 274 | =cut | ||||||||||||||||||||||||||
| 275 | |||||||||||||||||||||||||||
| 276 | 1 | ▶ | sub ANS { | ||||||||||||||||||||||||
|
Subroutine
ANS: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||
| 277 | 1 | my $self = shift; | |||||||||||||||||||||||||
| 278 | 1 | my $session = shift; | |||||||||||||||||||||||||
| 279 | 1 | my $message = shift; | |||||||||||||||||||||||||
| 280 | |||||||||||||||||||||||||||
| 281 | 1 | croak "ANS handling not implemented\n"; | |||||||||||||||||||||||||
| 282 | } | ||||||||||||||||||||||||||
| 283 | |||||||||||||||||||||||||||
| 284 | =item NUL($message) | ||||||||||||||||||||||||||
| 285 | |||||||||||||||||||||||||||
| 286 | Handle NUL type messages. This should be overridden by the subclass. | ||||||||||||||||||||||||||
| 287 | Subclasses should have this method return the original method. This | ||||||||||||||||||||||||||
| 288 | version will simply croak if invoked. | ||||||||||||||||||||||||||
| 289 | |||||||||||||||||||||||||||
| 290 | =cut | ||||||||||||||||||||||||||
| 291 | |||||||||||||||||||||||||||
| 292 | 1 | ▶ | sub NUL { | ||||||||||||||||||||||||
|
Subroutine
NUL: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||
| 293 | 1 | my $self = shift; | |||||||||||||||||||||||||
| 294 | 1 | my $session = shift; | |||||||||||||||||||||||||
| 295 | 1 | my $message = shift; | |||||||||||||||||||||||||
| 296 | |||||||||||||||||||||||||||
| 297 | 1 | croak "NUL handling not implemented\n"; | |||||||||||||||||||||||||
| 298 | } | ||||||||||||||||||||||||||
| 299 | |||||||||||||||||||||||||||
| 300 | =pod | ||||||||||||||||||||||||||
| 301 | |||||||||||||||||||||||||||
| 302 | =back | ||||||||||||||||||||||||||
| 303 | |||||||||||||||||||||||||||
| 304 | =head1 SEE ALSO | ||||||||||||||||||||||||||
| 305 | |||||||||||||||||||||||||||
| 306 | =over 4 | ||||||||||||||||||||||||||
| 307 | |||||||||||||||||||||||||||
| 308 | =item L<Net::BEEP::Lite::Message> | ||||||||||||||||||||||||||
| 309 | |||||||||||||||||||||||||||
| 310 | =item L<Net::BEEP::Lite::MgmtProfile> | ||||||||||||||||||||||||||
| 311 | |||||||||||||||||||||||||||
| 312 | =back | ||||||||||||||||||||||||||
| 313 | |||||||||||||||||||||||||||
| 314 | =cut | ||||||||||||||||||||||||||
| 315 | |||||||||||||||||||||||||||
| 316 | 3 | 1; | |||||||||||||||||||||||||