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.7 by root, Tue Nov 16 01:16:58 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
9 my $api = new AnyEvent::Porttracker
10 host => "10.0.0.1",
11 user => "admin",
12 pass => "31331",
13 tls => 1,
14 on_error => sub {
15 die $_[1];
16 },
17 ;
18
19 # Example 1
20 # a simple request: ping the server synchronously
21
22 my ($timestamp, $pid) = $api->req_sync ("ping");
23
24 # Example 2
25 # find all realms, start a discovery on all of them
26 # and wait until all discovery processes have finished
27 # but execute individual discoveries in parallel,
28 # asynchronously
29
30 my $cv = AE::cv;
31
32 $cv->begin;
33 # find all realms
34 $api->req (realm_info => ["gid", "name"], sub {
35 my ($api, @realms) = @_;
36
37 # start discovery on all realms
38 for my $realm (@realms) {
39 my ($gid, $name) = @$realm;
40
41 $cv->begin;
42 $api->req (realm_discover => $gid, sub {
43 warn "discovery for realm '$name' finished\n";
44 $cv->end;
45 });
46 }
47
48 $cv->end;
49 });
50
51 $cv->recv;
52
53 # Example 3
54 # subscribe to realm_poll_stop events and report each occurance
55
56 $api->req (subscribe => "realm_poll_stop", sub {});
57 $api->on (realm_poll_stop_event => sub {
58 my ($api, $gid) = @_;
59 warn "this just in: poll for realm <$gid> finished.\n";
60 });
61
62 AE::cv->recv; # wait forever
8 63
9=head1 DESCRIPTION 64=head1 DESCRIPTION
10 65
11Porttracker (L<http://www.porttracker.com/>) is a product that (among 66Porttracker (L<http://www.porttracker.com/>) is a product that (among
12other 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
13view 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
14switches 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
15this module is an implementation. 70this module is an implementation.
16 71
17In addition to Porttracker, the PortIQ product is also supported, as it
18uses the same protocol.
19
20If 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
21module will be of little value to you. 73little value to you.
22 74
23This 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
24run a supported event loop. 76run a supported event loop.
25 77
26To quickly understand how this module works you should read how to 78To quickly understand how this module works you should read how to
… …
42 94
43package AnyEvent::Porttracker; 95package AnyEvent::Porttracker;
44 96
45use common::sense; 97use common::sense;
46 98
99use Carp ();
47use Scalar::Util (); 100use Scalar::Util ();
48 101
49use AnyEvent (); 102use AnyEvent ();
50use AnyEvent::Handle (); 103use AnyEvent::Handle ();
51 104
52use MIME::Base64 (); 105use MIME::Base64 ();
53use Digest::HMAC_MD6 (); 106use Digest::HMAC_MD6 ();
54use JSON (); 107use JSON ();
55 108
56our $VERSION = '0.0'; 109our $VERSION = '1.01';
57 110
58sub call { 111sub call {
59 my ($self, $type, @args) = @_; 112 my ($self, $type, @args) = @_;
60 113
61 $self->{$type} 114 $self->{$type}
… …
99 152
100Enables or disables TLS (default: disables). When enabled, then the 153Enables or disables TLS (default: disables). When enabled, then the
101connection will try to handshake a TLS connection before logging in. If 154connection will try to handshake a TLS connection before logging in. If
102unsuccessful a fatal error will be raised. 155unsuccessful a fatal error will be raised.
103 156
104Since most Porttracker/PortIQ boxes will not have a sensible/verifiable 157Since most Porttracker boxes will not have a sensible/verifiable
105certificate, no attempt at verifying it will be done (which means 158certificate, no attempt at verifying it will be done (which means
106man-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
107verification 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<<
108verify => 1, verify_peername => [1, 1, 1] >> or whatever verification mode 161verify => 1, verify_peername => [1, 1, 1] >> or whatever verification mode
109you wish to use. 162you wish to use.
110 163
111=item tls_ctx => $tls_ctx 164=item tls_ctx => $tls_ctx
112 165
113The L<AnyEvent::TLS> object to use. 166The L<AnyEvent::TLS> object to use. See C<tls>, above.
114
115#TODO#
116 167
117=item on_XYZ => $coderef 168=item on_XYZ => $coderef
118 169
119You can specify event callbacks either by subclassing and overriding the 170You can specify event callbacks either by sub-classing and overriding the
120respective methods or by specifying coderefs as key-value pairs when 171respective methods or by specifying code-refs as key-value pairs when
121constructing the object. 172constructing the object. You add or remove event handlers at any time with
173the C<event> method.
122 174
123=back 175=back
124 176
125=cut 177=cut
126 178
… …
128 my $class = shift; 180 my $class = shift;
129 181
130 my $self = bless { 182 my $self = bless {
131 id => "a", 183 id => "a",
132 ids => [], 184 ids => [],
133 queue => [], # ininitially queue everything 185 queue => [], # initially queue everything
134 @_, 186 @_,
135 }, $class; 187 }, $class;
136 188
137 { 189 {
138 Scalar::Util::weaken (my $self = $self); 190 Scalar::Util::weaken (my $self = $self);
… …
260 $_[0]{queue} 312 $_[0]{queue}
261 ? push @{ $_[0]{queue} }, [@_] 313 ? push @{ $_[0]{queue} }, [@_]
262 : &_req 314 : &_req
263} 315}
264 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
265=item $api->req_failok ($type => @args, $callback->($api, $success, @reply)) 337=item $api->req_failok ($type => @args, $callback->($api, $success, @reply))
266 338
267Just like C<< ->req >>, with two differences: first, a failure will not 339Just like C<< ->req >>, with two differences: first, a failure will not
268raise an error, second, the initial status reply which indicates success 340raise an error, second, the initial status reply which indicates success
269or failure is not removed before calling the callback. 341or failure is not removed before calling the callback.
… …
272 344
273sub req_failok { 345sub req_failok {
274 $_[0]{queue} 346 $_[0]{queue}
275 ? push @{ $_[0]{queue} }, [@_] 347 ? push @{ $_[0]{queue} }, [@_]
276 : &_req 348 : &_req
349}
350
351=item $api->on (XYZ => $callback)
352
353Overwrites any currently registered handler for C<on_XYZ> or
354installs a new one. Or, when C<$callback> is undef, unregisters any
355currently-registered handler.
356
357Example: replace/set the handler for C<on_discover_stop_event>.
358
359 $api->on (discover_stop_event => sub {
360 my ($api, $gid) = @_;
361 ...
362 });
363
364=cut
365
366sub on {
367 my $self = shift;
368
369 while (@_) {
370 my ($event, $cb) = splice @_, 0, 2;
371 $event =~ s/^on_//;
372
373 $self->{"on_$event"} = $cb;
374 }
277} 375}
278 376
279sub on_start_tls_notify { 377sub on_start_tls_notify {
280 my ($self) = @_; 378 my ($self) = @_;
281 379
… …
379 477
380 $msg =~ s/\n$//; 478 $msg =~ s/\n$//;
381 $self->error ("login failed: $msg"); 479 $self->error ("login failed: $msg");
382} 480}
383 481
482sub on_event_notify {
483 my ($self, $event, @args) = @_;
484
485 call $self, "on_${event}_event", @args;
486}
487
384=back 488=back
385 489
386=head2 EVENTS 490=head1 EVENTS/CALLBACKS
387 491
388AnyEvent::Porttracker conenctions are fully event-driven, and naturally 492AnyEvent::Porttracker connections are fully event-driven, and naturally
389there 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
390starting with C<on_> (example: C<on_login_failure>). 494starting with C<on_> (example: C<on_login_failure>).
391 495
392Programs can catch these events in two ways: either by providing 496Programs can catch these events in two ways: either by providing
393constructor arguments with the event name as key and a coderef as value: 497constructor arguments with the event name as key and a code-ref as value:
394 498
395 my $api = new AnyEvent::Porttracker 499 my $api = new AnyEvent::Porttracker
396 host => ..., 500 host => ...,
397 user => ..., pass => ..., 501 user => ..., pass => ...,
398 on_error => sub { 502 on_error => sub {
… …
400 warn $msg; 504 warn $msg;
401 exit 1; 505 exit 1;
402 }, 506 },
403 ; 507 ;
404 508
405Or by subclassing C<AnyEvent::Porttracker> and overriding methods of the 509Or by sub-classing C<AnyEvent::Porttracker> and overriding methods of the
406same name: 510same name:
407 511
408 package MyClass; 512 package MyClass;
409 513
410 use base AnyEvent::Porttracker; 514 use base AnyEvent::Porttracker;
… …
458 562
459=item on_start_tls_notify $api 563=item on_start_tls_notify $api
460 564
461Called when the server wants to start TLS negotiation. This is used 565Called when the server wants to start TLS negotiation. This is used
462internally and - while it is possible to override it - should not be 566internally and - while it is possible to override it - should not be
463overriden. 567overridden.
568
569=item on_event_notify $api, $eventname, @args
570
571Called when the server broadcasts an event the API object is subscribed
572to. The default implementation (which should not be overridden) simply
573re-issues an "on_eventname_event" event with the @args.
464 574
465=item on_XYZ_notify $api, ... 575=item on_XYZ_notify $api, ...
466 576
467In general, any protocol notification will result in an event of the form 577In general, any protocol notification will result in an event of the form
468C<on_NOTIFICATION_notify>. 578C<on_NOTIFICATION_notify>.
469 579
580=item on_XYZ_event $api, ...
581
582Called when the server broadcasts the named (XYZ) event.
583
470=back 584=back
471 585
472=head1 SEE ALSO 586=head1 SEE ALSO
473 587
474L<AnyEvent>, L<http://www.porttracker.com/>, L<http://www.infoblox.com/en/products/portiq.html>. 588L<AnyEvent>, L<http://www.porttracker.com/>.
475 589
476=head1 AUTHOR 590=head1 AUTHOR
477 591
478 Marc Lehmann <marc@porttracker.net> 592 Marc Lehmann <marc@nethype.de>
479 593
480=cut 594=cut
481 595
4821 5961

Diff Legend

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