NAME

Net::CDP::Manager - Cisco Discovery Protocol (CDP) manager

SYNOPSIS

  use Net::CDP::Manager;
  
  # Available network ports
  @ports = cdp_ports;
  
  # Adding ports to manage
  cdp_manage(@ports);      # default is hard ports only
  cdp_manage_soft(@ports);
  
  # Removing ports to manage
  cdp_unmanage(@ports);
  
  # Returning managed ports
  @managed  = cdp_managed;
  @soft     = cdp_soft;
  @hard     = cdp_hard;
  @active   = cdp_active;
  @inactive = cdp_inactive;
  
  # Receiving a CDP packet by any managed port
  cdp_recv;
  
  # Send a CDP packet on all managed ports
  cdp_send;
  
  # Loop and dispatch CDP packets to callback
  sub callback { ($port, $packet) = @_; ... }
  cdp_loop(\&callback);
  
  # The template Net::CDP::Packet object
  $template = cdp_template;
        
  # Arguments used when creating Net::CDP objects
  %args     = cdp_args;

DESCRIPTION

The Net::CDP::Manager module provides a simple interface to manage multiple CDP advertiser/listeners (Net::CDP objects). With this module, CDP packets can be received and sent over multiple network ports.

Ports managed by this module are treated in one of two different ways. "Hard" ports must always exist -- if any errors occur while initializing the port, reading from it or writing to it, methods in this module will return an error. "Soft" ports, on the other hand, ignore errors generated by the port. Thus this module can manage

Each soft port is in one of two states. Ports on which the last receive or send was successful are deemed to be "active". Newly managed ports, or ports on which the last receive or send was unsuccessful are deemed to be "inactive".

If you are upgrading code from an older version of Net::CDP, please read the "UPGRADING FROM PREVIOUS VERSIONS" section below.

FUNCTIONS

cdp_ports

    @ports = cdp_ports;

Returns a list of network ports that can be used by this module. This method returns exactly that returned by the Net::CDP::ports class method.

cdp_manage

    @added = cdp_manage(@ports)

Adds the supplied network ports to the manager's list of managed ports. Returns the actual ports added, which may be fewer than provided if some ports are already managed. In scalar context the number of ports added is returned. If any ports could not be initialized, this method croaks.

Ports added by this function are hard -- that is, errors on them will generate errors by the functions of this module.

Any ports in @ports that are already managed by this module are hardened if they are currently soft. These ports are not in the list returned by this function.

cdp_manage_soft

    @added = cdp_manage_soft(@ports)

Adds the supplied network ports to the manager's list of managed ports. Returns the actual ports added, which may be fewer than provided if some ports are already managed. In scalar context the number of ports added is returned.

Ports added by this function are soft -- that is, errors on them will be silently ignored by the functions of this module.

Any ports in @ports that are already managed by this module are softened if they are currently hard. These ports are not in the list returned by this function.

cdp_unmanage

    @removed = cdp_unmanage(@ports)

Removes the supplied network ports from the manager's list of managed ports. Returns the actual ports removed, which may be fewer than provided if @ports contains duplicates. In scalar context the number of ports removed is returned.

cdp_managed

    @managed = cdp_managed()

Returns the list of ports currently being managed. In scalar context the number of ports is returned.

cdp_hard

    @hard = cdp_hard()

Returns the list of hard ports currently being managed. In scalar context the number of hard ports is returned.

cdp_soft

    @soft = cdp_soft()

Returns the list of soft ports currently being managed. In scalar context the number of soft ports is returned.

cdp_active

    @active = cdp_active()

Returns the list of active ports currently being managed. In scalar context the number of active ports is returned.

A port is active if it is hard, or if the last send or receive on the port succeeded.

cdp_inactive

    @inactive = cdp_inactive()

Returns the list of inactive ports currently being managed. In scalar context the number of inactive ports is returned.

A port is inactive if it is soft and the last send or receive on the port failed.

cdp_recv

    $packet                   = cdp_recv()
    ($packet, $port, $remain) = cdp_recv($timeout)

Returns the next available CDP packet on any managed port as a Net::CDP::Packet object.

If $timeout is ommitted or undefined, this method will block until a packet is received or an error occurs. Otherwise, this method will wait for up to $timeout seconds before returning. If no packets are received before this timeout expires, an undefined value is returned.

When evaluated in list context, this function also returns the port on which the packet was received and the time remaining out of the original timeout, or an undefined value if no original timeout was specified.

If an error occurs on a hard port, this function croaks with an error message.

For non-blocking operation, specify a timeout of 0.

cdp_send

    @ports = cdp_send()

Sends a CDP packet over all managed ports, and returns the ports on which packets were successfully sent. In scalar context the number of such ports is returned.

Internally, an appropriate packet is generated and sent for each port in turn. If an error occurs while generating or sending a packet for a hard port, this function croaks. Note that in this case some packets for other ports may have already been sent.

Errors while generating or sending a packet for a soft port cause the port to become inactive. Other errors will cause this function to croak with an error message.

cdp_loop

    $count = cdp_loop(\&callback)
    $count = cdp_loop(\&callback, $timeout)

Enters a loop to continually process received packets from managed ports and dispatches them to the specified callback function. Returns the number of packets processed.

Upon receiving each packet callback is called with the following three parameters:

1. The packet, as a Net::CDP::Packet object;

2. The port on which the packet was received; and

3. If $timeout was specified, the time remaining time out of the original timeout, otherwise an undefined value.

The third parameter may be modified in-place, and cdp_loop will use it as a new time remaining.

It is safe for the callback function to call any function in Net::CDP::Manager, including "cdp_recv" or "cdp_loop". It is also safe for the callback function to modify the packet template through "cdp_template".

The cdp_loop function will continue processing packets until:

1. callback returns the special value CDP_LOOP_ABORT;

2. If $timeout was specified, the timeout expires; or

If an error occurs on a hard port, this function croaks with an error message.

When an error is detected on a soft port, it is deactivated for up to 30 seconds. No errors are generated by this function in this case.

Note that if $timeout is not specified and the callback function does not modify its third argument, this function may never exit.

cdp_template

    $template = cdp_template()
    $template = cdp_template($new_template)

Returns the current template Net::CDP::Packet object. If $new_template is supplied and defined, the template will be updated first.

The template Net::CDP::Packet object is used by "cdp_send" to generate port-specific packets to send. For each managed port "cdp_send" clones the template, fills in the addresses and port fields with data relevant to the port, then sends the packet via the port.

The object returned by cdp_template may be manipulated directly. Note, however, that the port and addresses fields will always be ignored by "cdp_send".

cdp_args

    %args = cdp_args(
                [ promiscuous => $promiscuous, ] # default = 0
            )

Returns the current settings this module will use when creating Net::CDP objects.

This method allows you to change the default values for a subset of the arguments allowed in the "new" in Net::CDP method. Currently, the only argument permitted is promiscuous.

This function replaces the cdp_flags function from previous versions of Net::CDP::Manager. Do not use the cdp_flags function -- replace it with calls to cdp_args instead.

EXAMPLES

A typical application could have the following form:

  use Net::CDP::Manager;

  # Callback to process each packet.
  sub callback {
    my ($packet, $port) = @_;
    print "Received packet on $port from ", $packet->device, "\n";
  }
  
  # Manage all available ports.
  cdp_manage(cdp_ports);
  
  # Send a packet every minute. Pass received packets to callback.
  while (1) {
    cdp_send;
    cdp_loop(\&callback, 60);
  }

SEE ALSO

Net::CDP, Net::CDP::Packet

AUTHOR

Michael Chapman, <cpan@very.puzzling.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Michael Chapman

libcdp is released under the terms and conditions of the GNU Library General Public License version 2. Net::CDP may be redistributed and/or modified under the same terms as Perl itself.