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.8 by root, Tue Nov 16 01:22:03 2010 UTC vs.
Revision 1.13 by root, Tue Nov 16 17:37:49 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
… …
51 102
52use MIME::Base64 (); 103use MIME::Base64 ();
53use Digest::HMAC_MD6 (); 104use Digest::HMAC_MD6 ();
54use JSON (); 105use JSON ();
55 106
56our $VERSION = '0.0'; 107our $VERSION = '0.1';
57 108
58sub call { 109sub call {
59 my ($self, $type, @args) = @_; 110 my ($self, $type, @args) = @_;
60 111
61 $self->{$type} 112 $self->{$type}
… …
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;
… …
387 call $self, "on_${event}_event", @args; 463 call $self, "on_${event}_event", @args;
388} 464}
389 465
390=back 466=back
391 467
392=head2 EVENTS 468=head1 EVENTS/CALLBACKS
393 469
394AnyEvent::Porttracker conenctions are fully event-driven, and naturally 470AnyEvent::Porttracker connections are fully event-driven, and naturally
395there 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
396starting with C<on_> (example: C<on_login_failure>). 472starting with C<on_> (example: C<on_login_failure>).
397 473
398Programs can catch these events in two ways: either by providing 474Programs can catch these events in two ways: either by providing
399constructor 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:
400 476
401 my $api = new AnyEvent::Porttracker 477 my $api = new AnyEvent::Porttracker
402 host => ..., 478 host => ...,
403 user => ..., pass => ..., 479 user => ..., pass => ...,
404 on_error => sub { 480 on_error => sub {
… …
406 warn $msg; 482 warn $msg;
407 exit 1; 483 exit 1;
408 }, 484 },
409 ; 485 ;
410 486
411Or by subclassing C<AnyEvent::Porttracker> and overriding methods of the 487Or by sub-classing C<AnyEvent::Porttracker> and overriding methods of the
412same name: 488same name:
413 489
414 package MyClass; 490 package MyClass;
415 491
416 use base AnyEvent::Porttracker; 492 use base AnyEvent::Porttracker;
… …
464 540
465=item on_start_tls_notify $api 541=item on_start_tls_notify $api
466 542
467Called when the server wants to start TLS negotiation. This is used 543Called when the server wants to start TLS negotiation. This is used
468internally and - while it is possible to override it - should not be 544internally and - while it is possible to override it - should not be
469overriden. 545overridden.
470 546
471=item on_event_notify $api, $eventname, @args 547=item on_event_notify $api, $eventname, @args
472 548
473Called when the server broadcasts an event the API object is subscribed 549Called when the server broadcasts an event the API object is subscribed
474to. The default implementation (which should not be overridden) simply 550to. The default implementation (which should not be overridden) simply
475re-issues an "on_evenname_event" event with the @args. 551re-issues an "on_eventname_event" event with the @args.
476 552
477=item on_XYZ_notify $api, ... 553=item on_XYZ_notify $api, ...
478 554
479In 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
480C<on_NOTIFICATION_notify>. 556C<on_NOTIFICATION_notify>.

Diff Legend

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