view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    AnyEvent::Porttracker - Porttracker/PortIQ API client interface.

SYNOPSIS
       use AnyEvent::Porttracker;

       my $api = new AnyEvent::Porttracker
          host => "10.0.0.1",
          user => "admin",
          pass => "31331",
          tls  => 1,
       ;

       # Example 1
       # a simple request: ping the server synchronously

       my ($timestamp, $pid) = $api->req_sync ("ping");

       # Example 2
       # find all realms, start a discovery on all of them
       # and wait until all discovery processes have finished
       # but execute individual discoveries in parallel,
       # asynchronously

       my $cv = AE::cv;

       $cv->begin;
       # find all realms
       $api->req (realm_info => ["gid", "name"], sub {
          my ($api, @realms) = @_;

          # start discovery on all realms
          for my $realm (@realms) {
             my ($gid, $name) = @$realm;

             $cv->begin;
             $api->req (realm_discover => $gid, sub {
                warn "discovery for realm '$name' finished\n";
                $cv->end;
             });
          }

          $cv->end;
       });

       $cv->recv;

       # Example 3
       # subscribe to realm_poll_stop events and report each occurance

       $api->req (subscribe => "realm_poll_stop", sub {});
       $api->on (realm_poll_stop_event => sub {
          my ($api, $gid) = @_;
          warn "this just in: poll for realm <$gid> finished.\n";
       });

       AE::cv->recv; # wait forever

DESCRIPTION
    Porttracker (<http://www.porttracker.com/>) is a product that (among
    other things) scans switches and routers in a network and gives a
    coherent view of which end devices are connected to which switch ports
    on which switches and routers. It also offers a JSON-based client API,
    for which this module is an implementation.

    In addition to Porttracker, the PortIQ product is also supported, as it
    uses the same protocol.

    If you do not have access to either a Porttracker or PortIQ box then
    this module will be of little value to you.

    This module is an AnyEvent user, you need to make sure that you use and
    run a supported event loop.

    To quickly understand how this module works you should read how to
    construct a new connection object and then read about the event/callback
    system.

    The actual low-level protocol and, more importantly, the existing
    requests and responses, are documented in the official Porttracker API
    documentation (a copy of which is included in this module as
    AnyEvent::Porttracker::protocol.

THE AnyEvent::Porttracker CLASS
    The AnyEvent::Porttracker class represents a single connection.

    $api = new AnyEvent::Porttracker [key => value...]
        Creates a new porttracker API connection object and tries to connect
        to the specified host (see below). After the connection has been
        established, the TLS handshake (if requested) will take place,
        followed by a login attempt using either the "none",
        "login_cram_md6" or "login" methods, in this order of preference
        (typically, "login_cram_md6" is used, which shields against some
        man-in-the-middle attacks and avoids transferring the password).

        It is permissible to send requests immediately after creating the
        object - they will be queued until after successful login.

        Possible key-value pairs are:

        host => $hostname [MANDATORY]
            The hostname or IP address of the Porttracker box.

        port => $service
            The service (port) to use (default: "porttracker=55").

        user => $string, pass => $string
            These are the username and password to use when authentication
            is required (which it is in almost all cases, so these keys are
            normally mandatory).

        tls => $bool
            Enables or disables TLS (default: disables). When enabled, then
            the connection will try to handshake a TLS connection before

README  view on Meta::CPAN

    $api->req ($type => @args, $callback->($api, @reply))
        Sends a generic request of type $type to the server. When the server
        responds, the API object and the response arguments (without the
        success status) are passed to the callback, which is the last
        argument to this method.

        If the request fails, then a fatal error will be raised. If you want
        to handle failures gracefully, you need to use "->req_failok"
        instead.

        The available requests are documented in the Porttracker API
        documentation (a copy of which is included in this module as
        AnyEvent::Porttracker::protocol.

        It is permissible to call this (or any other request function) at
        any time, even before the connection has been established - the API
        object always waits until after login before it actually sends the
        requests, and queues them until then.

        Example: ping the porttracker server.

           $api->req ("ping", sub {
              my ($api, $ok, $timestamp, $pid) = @_;
              ...
           });

        Example: determine the product ID.

           $api->req (product_id => sub {
              my ($api, $ok, $branding, $product_id) = @_;
              ...
           });

        Example: set a new license.

           $api->req (set_license => $LICENSE_STRING, sub {
              my ($api, $ok) = @_;

              $ok or die "failed to set license";
           });

    @res = $api->req_sync ($type => @args)
        Similar to "->req", but waits for the results of the request and on
        success, returns the values instead (without the success flag, and
        only the first value in scalar context). On failure, the method will
        "croak" with the error message.

    $api->req_failok ($type => @args, $callback->($api, $success, @reply))
        Just like "->req", with two differences: first, a failure will not
        raise an error, second, the initial status reply which indicates
        success or failure is not removed before calling the callback.

    $api->on (XYZ => $callback)
        Overwrites any currently registered handler for "on_XYZ" or installs
        a new one. Or, when $callback is undef, unregisters any
        currently-registered handler.

        Example: replace/set the handler for "on_discover_stop_event".

           $api->on (discover_stop_event => sub {
              my ($api, $gid) = @_;
              ...
           });

EVENTS/CALLBACKS
    AnyEvent::Porttracker connections are fully event-driven, and naturally
    there are a number of events that can occur. All these events have a
    name starting with "on_" (example: "on_login_failure").

    Programs can catch these events in two ways: either by providing
    constructor arguments with the event name as key and a code-ref as
    value:

       my $api = new AnyEvent::Porttracker
          host => ...,
          user => ..., pass => ...,
          on_error => sub {
             my ($api, $msg) = @_;
             warn $msg;
             exit 1;
          },
       ;

    Or by sub-classing "AnyEvent::Porttracker" and overriding methods of the
    same name:

       package MyClass;

       use base AnyEvent::Porttracker;

       sub on_error {
          my ($api, $msg) = @_;
          warn $msg;
          exit 1;
       }

    Event callbacks are not expected to return anything and are always
    passed the API object as first argument. Some might have default
    implementations (for example, "on_error"), others are ignored unless
    overriden.

    Description of individual events follow:

    on_error $api, $msg
        Is called for every (fatal) error, including "error" notifies. The
        default prints the message and destroys the object, so it is highly
        advisable to override this event.

    on_login $api, $method
        Called after a successful login, after which commands can be send.
        It is permissible to send commands before a successful login: those
        will be queued and sent just before this event is invoked. $method
        is the auth method that was used.

    on_login_failure $api, $msg
        Called when all login attempts have failed - the default raises a
        fatal error with the error message from the server.

    on_hello_notify $api, $version, $authtypes, $nonce
        This protocol notification is used internally by
        AnyEvent::Porttracker - you can override it, but the module will