Lite.pm untested

filter: Statementstmt 0.0% 0 / 94 Branchbran 0.0% 0 / 16 Conditioncond 0.0% 0 / 32 MC/DCmcdc 0.0% 0 / 21 Subroutinesub 0.0% 0 / 10 Podpod 0.0% 0 / 3 totaltotal 0.0% 0 / 176 CC 9 SCAR 26.5
CC
9
Cov
0%
_beep_listen_fork
30.0
beep_listen
20.0
beep_connect
6.0
CRAP 14.2
1 # $Id: Lite.pm,v 1.13 2004/04/22 20:55:45 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;
21  
22 use IO::Socket;
23  
24 use Net::BEEP::Lite::ServerSession;
25 use Net::BEEP::Lite::ClientSession;
26  
27 use Carp;
28  
29 use strict;
30 use warnings;
31  
32 require Exporter;
33  
34 our @ISA = qw(Exporter);
35  
36 our %EXPORT_TAGS = ( 'all' => [ qw(beep_listen), qw(beep_connect) ] );
37 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
38  
39 our $VERSION = '0.06';
40  
41 our $errorstr;
42 our $debug;
43 our $trace;
44  
45 =head1 NAME
46  
47 Net::BEEP::Lite - Perl framework for BEEP (RFC 3080, 3081).
48  
49 =head1 SYNOPSIS
50  
51 use Net::BEEP::Lite qw(beep_connect);
52 use Net::BEEP::Lite::ClientSession;
53  
54 my $session = beep_connect(Host => localhost,
55 Port => 10288);
56  
57 my $channel_num = $session->start_channel
58 (URI => 'http://xml.resources.org/profiles/NULL/ECHO');
59  
60 my $resp_msg = $session->send_and_recv_message
61 (Content => "some content",
62 ContentType => 'text/plain');
63  
64 print "received response: ", $resp_msg->content(), "\n";
65  
66 ---
67  
68 use Net::BEEP::Lite::ServerSession;
69  
70 my $profile = Net::BEEP::Lite::BaseProfile->new
71  
72 beep_listen( Port => 12345,
73 Address => 127.0.0.1,
74 Profiles => [ $profile ],
75 Method => 'fork' );
76  
77 =head1 ABSTRACT
78  
79 Net::BEEP::Lite is a lightweight implementation of a BEEP client/server
80 framework. This package is intended for implementing fairly simple
81 BEEP clients and servers.
82  
83 =head1 DESCRIPTION
84  
85 Net::BEEP::Lite is a "lightweight" implementation of a BEEP
86 client/server framework, born out of a desire to have the ability to
87 simple BEEP client and server work without attempting to be the last
88 word on BEEP in Perl.
89  
90 One thing this package does is intentionally fuse the BEEP Listener
91 role with the Server role, and the Initiatior role with the Client
92 role. That is, it makes no attempt to support the peer-to-peer
93 capabilities of BEEP.
94  
95 Also, it has only rudimentary support for multiple channels,
96 especially on the server side. In particular, by avoiding the use of
97 threads (or some other complicated forking scheme) it does not handle
98 asynchronous channels. Ultimately, on the server side, messages on
99 different channels are processed serially. This eliminates one of the
100 main purposes of using multiple channels. In fact, the system
101 defaults not allowing clients to open more than one channel at a time.
102  
103 That being said, it is possible to support multiple channels, but this
104 package is easiest to use when using only one.
105  
106 =head2 EXPORT
107  
108 =over 4
109  
110 =item beep_listen( I<ARGS> )
111  
112 This is a main entry function for running a BEEP server. It takes a
113 named arguement list. It supports the following arguments, in
114 addition to the arguments accepted by the
115 C<Net::BEEP::Lite::ServerSession> constructor.:
116  
117 =over 4
118  
119 =item Port
120  
121 The TCP port on which to listen.
122  
123 =item Address
124  
125 The address to bind to, if there is more than one interface.
126  
127 =item Profiles
128  
129 This should be an array reference of a list of objects that inherit
130 from C<Net::BEEP::Lite::BaseProfile> (or at least support the same
131 methods). At least one profile MUST be supplied here, or clients will
132 not be able to start any channels.
133  
134 =item Method
135  
136 This is a string describing the multitasking method to use. Currently
137 the only supported option is 'fork'. Future options may be 'prefork'
138 and 'prepostfork'.
139  
140 =item Socket
141  
142 If you wish to use this code but want to setup the socket yourself,
143 you can pass the socket in using this. If you do so, the Port and
144 Address parameters will be ignored.
145  
146 =item Debug
147  
148 If true, this will spew forth (some) stuff to STDERR. It defaults to
149 false.
150  
151 =item Trace
152  
153 If true, this will spew forth even more stuff to STDERR, including the
154 entire conversation.
155  
156 =back
157  
158 In general, this function does not return, forming the main event loop
159 of the server.
160  
161 =cut
162  
163 sub beep_listen {
164 my %args = @_;
165  
166 my ($port, $addr, $sock);
167 my $method = 'fork';
168  
169 for (keys %args) {
170 my $val = $args{$_};
171  
172 /^Port$/i and do {
173 $port = $val;
174 next;
175 };
176 /^Address|Addr$/i and do {
177 $addr = $val;
178 next;
179 };
180 /^Method$/i and do {
181 $method = lc $val;
182 next;
183 };
184 /^Debug$/io and do {
185 $debug = $val;
186 next;
187 };
188 /^Trace$/io and do {
189 $trace = $val;
190 next;
191 };
192 /^Socket$/io and do {
193 $sock = $val;
194 next;
195 };
196 }
197  
198 # for now, we have one common listen socket creation.
199 if (not $sock) {
200 $sock = new IO::Socket::INET(LocalPort => $port,
201 LocalAddr => $addr,
202 Proto => 'tcp',
203 ReuseAddr => 1,
204 Listen => 5)
205 || die "could not create listener socket on port $port: $!";
206  
207 print STDERR "Listening on port $port\n" if $debug;
208 }
209  
210 if ($method eq "fork") {
211 _beep_listen_fork($sock, %args);
212 }
213 else {
214 croak "Method '$method' is not implemented";
215 }
216 }
217  
218 # Use a simple, straight forking method.
219 sub _beep_listen_fork {
220 my $sock = shift;
221 my %args = @_;
222  
223 # we aren't tracking the children, so just ignore their deaths.
224 $SIG{CHLD} = 'IGNORE';
225  
226 # we will just modify forked copies of this session.
227 $args{NoGreeting} = 1;
228 my $session = Net::BEEP::Lite::ServerSession->new(%args);
229  
230 while (1) {
231 my $client_sock = $sock->accept();
232 next if not $client_sock;
233  
234 my $pid = fork();
235  
236 next if $pid; # the parent just loops on accept.
237  
238 # child code:
239 $session->_set_socket($client_sock);
240  
241 print STDERR "New session started\n" if $debug;
242 $session->send_greeting();
243  
244 $session->process_messages();
245 print STDERR "session ended.\n" if $debug;
246 exit(0);
247 }
248 }
249  
250 =item beep_connect( I<ARGS> )
251  
252 This is the main entry point for the client. It will either return a
253 C<Net::BEEP::Lite::ClientSession>, already connected to the BEEP peer,
254 or it will return undef and have set C<Net::BEEP::Lite::errorstr>.
255  
256 It accepts a named parameter list with the following parameters, in
257 addition to the parameters accepted by the
258 C<Net::BEEP::Lite::ClientSession> constructor:
259  
260 =over 4
261  
262 =item Host
263  
264 The host to connect to.
265  
266 =item Port
267  
268 The port to connect to.
269  
270 =back
271  
272 =cut
273  
274 sub beep_connect {
275 my %args = @_;
276  
277 my ($host, $port, $socket);
278  
279 for (keys %args) {
280 my $val = $args{$_};
281  
282 /^Port/io and do {
283 $port = $val;
284 next;
285 };
286 /^Host/io and do {
287 $host = $val;
288 next;
289 };
290 /^Socket$/io and do {
291 $socket = $val;
292 next;
293 };
294 }
295  
296 if (! $socket) {
297 $socket = new IO::Socket::INET(PeerAddr => $host,
298 PeerPort => $port,
299 Proto => 'tcp')
300 || do {
301 $errorstr = "could not connect to $host:$port: $!";
302 return undef;
303 };
304  
305 $args{Socket} = $socket;
306 }
307 return Net::BEEP::Lite::ClientSession->new(%args);
308 }
309  
310 =pod
311  
312 =back
313  
314 =head2 DEPENDENCIES
315  
316 This modules depends on:
317  
318 =over 4
319  
320 =item C<XML::LibXML>
321  
322 Available on CPAN.
323  
324 =back
325  
326 =head1 SEE ALSO
327  
328 =over 4
329  
330 =item RFC 3080
331  
332 =item RFC 3081
333  
334 =item L<XML::LibXML>
335  
336 =back
337  
338 =head1 AUTHOR
339  
340 David Blacka, E<lt>davidb@verisignlabs.comE<gt>
341  
342 =head1 COPYRIGHT AND LICENSE
343  
344 Copyright 2003 by Verisign, Inc.
345 Copyright 2003 by David Blacka
346  
347 This software is licensed under the GNU LGPL. See the file
348 F<beeplite-license.txt>, included in the distribution for the full
349 license.
350  
351 =cut
352  
353 1;