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.12 by root, Tue Nov 16 02:09:21 2010 UTC

… …
3AnyEvent::Porttracker - Porttracker/PortIQ API client interface. 3AnyEvent::Porttracker - Porttracker/PortIQ 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 ;
15
16 # Example 1
17 # a simple request: ping the server
18
19 $api->req ("ping", sub {
20 my ($api, $ok, $timestamp, $pid) = @_;
21 ...
22 });
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
28 my $cv = AE::cv;
29
30 $cv->begin;
31 # find all realms
32 $api->req (realm_info => ["gid", "name"], sub {
33 my ($api, @realms) = @_;
34
35 # start discovery on all realms
36 for my $realm (@realms) {
37 my ($gid, $name) = @$realm;
38
39 $cv->begin;
40 $api->req (realm_discover => $realm->[0], sub {
41 warn "discovery for realm '$realm->[1]' finished\n";
42 $cv->end;
43 });
44 }
45
46 $cv->end;
47 });
48
49 $cv->recv;
50
51 # Example 3
52 # subscribe to realm_poll_stop events and report each occurance
53
54 $api->req (subscribe => "realm_poll_stop", sub {});
55 $api->on (realm_poll_stop_event => sub {
56 my ($api, $gid) = @_;
57 warn "this just in: poll for realm <$gid> finished.\n";
58 });
8 59
9=head1 DESCRIPTION 60=head1 DESCRIPTION
10 61
11Porttracker (L<http://www.porttracker.com/>) is a product that (among 62Porttracker (L<http://www.porttracker.com/>) is a product that (among
12other things) scans switches and routers in a network and gives a coherent 63other things) scans switches and routers in a network and gives a coherent
… …
108verify => 1, verify_peername => [1, 1, 1] >> or whatever verification mode 159verify => 1, verify_peername => [1, 1, 1] >> or whatever verification mode
109you wish to use. 160you wish to use.
110 161
111=item tls_ctx => $tls_ctx 162=item tls_ctx => $tls_ctx
112 163
113The L<AnyEvent::TLS> object to use. 164The L<AnyEvent::TLS> object to use. See C<tls>, above.
114
115#TODO#
116 165
117=item on_XYZ => $coderef 166=item on_XYZ => $coderef
118 167
119You can specify event callbacks either by subclassing and overriding the 168You can specify event callbacks either by sub-classing and overriding the
120respective methods or by specifying coderefs as key-value pairs when 169respective methods or by specifying code-refs as key-value pairs when
121constructing the object. 170constructing the object. You add or remove event handlers at any time with
171the C<event> method.
122 172
123=back 173=back
124 174
125=cut 175=cut
126 176
… …
128 my $class = shift; 178 my $class = shift;
129 179
130 my $self = bless { 180 my $self = bless {
131 id => "a", 181 id => "a",
132 ids => [], 182 ids => [],
133 queue => [], # ininitially queue everything 183 queue => [], # initially queue everything
134 @_, 184 @_,
135 }, $class; 185 }, $class;
136 186
137 { 187 {
138 Scalar::Util::weaken (my $self = $self); 188 Scalar::Util::weaken (my $self = $self);
… …
274 $_[0]{queue} 324 $_[0]{queue}
275 ? push @{ $_[0]{queue} }, [@_] 325 ? push @{ $_[0]{queue} }, [@_]
276 : &_req 326 : &_req
277} 327}
278 328
329=item $api->on (XYZ => $callback)
330
331Overwrites any currently registered handler for C<on_XYZ> or
332installs a new one. Or, when C<$callback> is undef, unregisters any
333currently-registered handler.
334
335Example: replace/set the handler for C<on_discover_stop_event>.
336
337 $api->on (discover_stop_event => sub {
338 my ($api, $gid) = @_;
339 ...
340 });
341
342=cut
343
344sub on {
345 my $self = shift;
346
347 while (@_) {
348 my ($event, $cb) = splice @_, 0, 2;
349 $event =~ s/^on_//;
350
351 $self->{"on_$event"} = $cb;
352 }
353}
354
279sub on_start_tls_notify { 355sub on_start_tls_notify {
280 my ($self) = @_; 356 my ($self) = @_;
281 357
282 $self->{hdl}->starttls (connect => $self->{tls_ctx}); 358 $self->{hdl}->starttls (connect => $self->{tls_ctx});
283 $self->{tls} ||= 1; 359 $self->{tls} ||= 1;
… …
379 455
380 $msg =~ s/\n$//; 456 $msg =~ s/\n$//;
381 $self->error ("login failed: $msg"); 457 $self->error ("login failed: $msg");
382} 458}
383 459
460sub on_event_notify {
461 my ($self, $event, @args) = @_;
462
463 call $self, "on_${event}_event", @args;
464}
465
384=back 466=back
385 467
386=head2 EVENTS 468=head1 EVENTS/CALLBACKS
387 469
388AnyEvent::Porttracker conenctions are fully event-driven, and naturally 470AnyEvent::Porttracker connections are fully event-driven, and naturally
389there are a number of events that can occur. All these events have a name 471there are a number of events that can occur. All these events have a name
390starting with C<on_> (example: C<on_login_failure>). 472starting with C<on_> (example: C<on_login_failure>).
391 473
392Programs can catch these events in two ways: either by providing 474Programs can catch these events in two ways: either by providing
393constructor arguments with the event name as key and a coderef as value: 475constructor arguments with the event name as key and a code-ref as value:
394 476
395 my $api = new AnyEvent::Porttracker 477 my $api = new AnyEvent::Porttracker
396 host => ..., 478 host => ...,
397 user => ..., pass => ..., 479 user => ..., pass => ...,
398 on_error => sub { 480 on_error => sub {
… …
400 warn $msg; 482 warn $msg;
401 exit 1; 483 exit 1;
402 }, 484 },
403 ; 485 ;
404 486
405Or by subclassing C<AnyEvent::Porttracker> and overriding methods of the 487Or by sub-classing C<AnyEvent::Porttracker> and overriding methods of the
406same name: 488same name:
407 489
408 package MyClass; 490 package MyClass;
409 491
410 use base AnyEvent::Porttracker; 492 use base AnyEvent::Porttracker;
… …
458 540
459=item on_start_tls_notify $api 541=item on_start_tls_notify $api
460 542
461Called when the server wants to start TLS negotiation. This is used 543Called when the server wants to start TLS negotiation. This is used
462internally and - while it is possible to override it - should not be 544internally and - while it is possible to override it - should not be
463overriden. 545overridden.
546
547=item on_event_notify $api, $eventname, @args
548
549Called when the server broadcasts an event the API object is subscribed
550to. The default implementation (which should not be overridden) simply
551re-issues an "on_eventname_event" event with the @args.
464 552
465=item on_XYZ_notify $api, ... 553=item on_XYZ_notify $api, ...
466 554
467In general, any protocol notification will result in an event of the form 555In general, any protocol notification will result in an event of the form
468C<on_NOTIFICATION_notify>. 556C<on_NOTIFICATION_notify>.
469 557
558=item on_XYZ_event $api, ...
559
560Called when the server broadcasts the named (XYZ) event.
561
470=back 562=back
471 563
472=head1 SEE ALSO 564=head1 SEE ALSO
473 565
474L<AnyEvent>, L<http://www.porttracker.com/>, L<http://www.infoblox.com/en/products/portiq.html>. 566L<AnyEvent>, L<http://www.porttracker.com/>, L<http://www.infoblox.com/en/products/portiq.html>.

Diff Legend

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