ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/AnyEvent-Porttracker/Porttracker.pm
(Generate patch)

Comparing cvsroot/AnyEvent-Porttracker/Porttracker.pm (file contents):
Revision 1.11 by root, Tue Nov 16 02:09:00 2010 UTC vs.
Revision 1.18 by root, Wed Jan 7 01:41:33 2015 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent::Porttracker - Porttracker/PortIQ API client interface. 3AnyEvent::Porttracker - Porttracker API client interface.
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::Porttracker; 7 use AnyEvent::Porttracker;
8 8
9 my $api = new AnyEvent::Porttracker 9 my $api = new AnyEvent::Porttracker
10 host => "10.0.0.1", 10 host => "10.0.0.1",
11 user => "admin", 11 user => "admin",
12 pass => "31331", 12 pass => "31331",
13 tls => 1, 13 tls => 1,
14 on_error => sub {
15 die $_[1];
16 },
14 ; 17 ;
15 18
16 # Example 1 19 # Example 1
17 # a simple request: ping the server 20 # a simple request: ping the server synchronously
18 21
19 $api->req ("ping", sub { 22 my ($timestamp, $pid) = $api->req_sync ("ping");
20 my ($api, $ok, $timestamp, $pid) = @_;
21 ...
22 });
23 23
24 # Example 2 24 # Example 2
25 # find all realms, start a discovery on all of them 25 # find all realms, start a discovery on all of them
26 # and wait until all discovery processes have finished 26 # and wait until all discovery processes have finished
27 # but execute individual discoveries in parallel,
28 # asynchronously
27 29
28 my $cv = AE::cv; 30 my $cv = AE::cv;
29 31
30 $cv->begin; 32 $cv->begin;
31 # find all realms 33 # find all realms
… …
35 # start discovery on all realms 37 # start discovery on all realms
36 for my $realm (@realms) { 38 for my $realm (@realms) {
37 my ($gid, $name) = @$realm; 39 my ($gid, $name) = @$realm;
38 40
39 $cv->begin; 41 $cv->begin;
40 $api->req (realm_discover => $realm->[0], sub { 42 $api->req (realm_discover => $gid, sub {
41 warn "discovery for realm '$realm->[1]' finished\n"; 43 warn "discovery for realm '$name' finished\n";
42 $cv->end; 44 $cv->end;
43 }); 45 });
44 } 46 }
45 47
46 $cv->end; 48 $cv->end;
… …
55 $api->on (realm_poll_stop_event => sub { 57 $api->on (realm_poll_stop_event => sub {
56 my ($api, $gid) = @_; 58 my ($api, $gid) = @_;
57 warn "this just in: poll for realm <$gid> finished.\n"; 59 warn "this just in: poll for realm <$gid> finished.\n";
58 }); 60 });
59 61
62 AE::cv->recv; # wait forever
63
60=head1 DESCRIPTION 64=head1 DESCRIPTION
61 65
62Porttracker (L<http://www.porttracker.com/>) is a product that (among 66Porttracker (L<http://www.porttracker.com/>) is a product that (among
63other things) scans switches and routers in a network and gives a coherent 67other things) scans switches and routers in a network and gives a coherent
64view of which end devices are connected to which switch ports on which 68view of which end devices are connected to which switch ports on which
65switches and routers. It also offers a JSON-based client API, for which 69switches and routers. It also offers a JSON-based client API, for which
66this module is an implementation. 70this module is an implementation.
67 71
68In addition to Porttracker, the PortIQ product is also supported, as it
69uses the same protocol.
70
71If you do not have access to either a Porttracker or PortIQ box then this 72If you do not have access to a Porttracker box then this module will be of
72module will be of little value to you. 73little value to you.
73 74
74This module is an L<AnyEvent> user, you need to make sure that you use and 75This module is an L<AnyEvent> user, you need to make sure that you use and
75run a supported event loop. 76run a supported event loop.
76 77
77To quickly understand how this module works you should read how to 78To quickly understand how this module works you should read how to
… …
93 94
94package AnyEvent::Porttracker; 95package AnyEvent::Porttracker;
95 96
96use common::sense; 97use common::sense;
97 98
99use Carp ();
98use Scalar::Util (); 100use Scalar::Util ();
99 101
100use AnyEvent (); 102use AnyEvent ();
101use AnyEvent::Handle (); 103use AnyEvent::Handle ();
102 104
103use MIME::Base64 (); 105use MIME::Base64 ();
104use Digest::HMAC_MD6 (); 106use Digest::HMAC_MD6 ();
105use JSON (); 107use JSON ();
106 108
107our $VERSION = '0.0'; 109our $VERSION = '1.01';
108 110
109sub call { 111sub call {
110 my ($self, $type, @args) = @_; 112 my ($self, $type, @args) = @_;
111 113
112 $self->{$type} 114 $self->{$type}
… …
150 152
151Enables or disables TLS (default: disables). When enabled, then the 153Enables or disables TLS (default: disables). When enabled, then the
152connection will try to handshake a TLS connection before logging in. If 154connection will try to handshake a TLS connection before logging in. If
153unsuccessful a fatal error will be raised. 155unsuccessful a fatal error will be raised.
154 156
155Since most Porttracker/PortIQ boxes will not have a sensible/verifiable 157Since most Porttracker boxes will not have a sensible/verifiable
156certificate, no attempt at verifying it will be done (which means 158certificate, no attempt at verifying it will be done (which means
157man-in-the-middle-attacks will be trivial). If you want some form of 159man-in-the-middle-attacks will be trivial). If you want some form of
158verification you need to provide your own C<tls_ctx> object with C<< 160verification you need to provide your own C<tls_ctx> object with C<<
159verify => 1, verify_peername => [1, 1, 1] >> or whatever verification mode 161verify => 1, verify_peername => [1, 1, 1] >> or whatever verification mode
160you wish to use. 162you wish to use.
… …
310 $_[0]{queue} 312 $_[0]{queue}
311 ? push @{ $_[0]{queue} }, [@_] 313 ? push @{ $_[0]{queue} }, [@_]
312 : &_req 314 : &_req
313} 315}
314 316
317=item @res = $api->req_sync ($type => @args)
318
319Similar to C<< ->req >>, but waits for the results of the request and on
320success, returns the values instead (without the success flag, and only
321the first value in scalar context). On failure, the method will C<croak>
322with the error message.
323
324=cut
325
326sub req_sync {
327 push @_, my $cv = AE::cv;
328 &req;
329 my ($ok, @res) = $cv->recv;
330
331 $ok
332 or Carp::croak $res[0];
333
334 wantarray ? @res : $res[0]
335}
336
315=item $api->req_failok ($type => @args, $callback->($api, $success, @reply)) 337=item $api->req_failok ($type => @args, $callback->($api, $success, @reply))
316 338
317Just like C<< ->req >>, with two differences: first, a failure will not 339Just like C<< ->req >>, with two differences: first, a failure will not
318raise an error, second, the initial status reply which indicates success 340raise an error, second, the initial status reply which indicates success
319or failure is not removed before calling the callback. 341or failure is not removed before calling the callback.
… …
463 call $self, "on_${event}_event", @args; 485 call $self, "on_${event}_event", @args;
464} 486}
465 487
466=back 488=back
467 489
468=head1 EVENTS 490=head1 EVENTS/CALLBACKS
469 491
470AnyEvent::Porttracker connections are fully event-driven, and naturally 492AnyEvent::Porttracker connections are fully event-driven, and naturally
471there are a number of events that can occur. All these events have a name 493there are a number of events that can occur. All these events have a name
472starting with C<on_> (example: C<on_login_failure>). 494starting with C<on_> (example: C<on_login_failure>).
473 495
… …
561 583
562=back 584=back
563 585
564=head1 SEE ALSO 586=head1 SEE ALSO
565 587
566L<AnyEvent>, L<http://www.porttracker.com/>, L<http://www.infoblox.com/en/products/portiq.html>. 588L<AnyEvent>, L<http://www.porttracker.com/>.
567 589
568=head1 AUTHOR 590=head1 AUTHOR
569 591
570 Marc Lehmann <marc@porttracker.net> 592 Marc Lehmann <marc@nethype.de>
571 593
572=cut 594=cut
573 595
5741 5961

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines