NAME

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

SYNOPSIS

use Net::CDP::Manager;

# Available ports (interfaces)
@ports = cdp_ports;

# Adding ports (interfaces) to manage
cdp_manage(@ports);      # default is hard ports only
cdp_manage_soft(@ports);

# Removing ports (interfaces) to manage
cdp_unmanage(@ports);

# Returning managed ports (interfaces)
@managed  = cdp_managed;
@soft     = cdp_soft;
@hard     = cdp_hard;
@active   = cdp_active;
@inactive = cdp_inactive;

# Receiving a CDP packet by any managed port (interface)
cdp_recv;

# Send a CDP packet on all managed ports (interfaces)
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;

DESCRIPTION

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

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".

FUNCTIONS

cdp_ports

@ports = cdp_ports;

Returns a list of network ports (interfaces) 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 (interfaces) 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 (interfaces) 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 (interfaces) 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 (interface) 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 (interfaces), 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 (interfaces) 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".

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, <mike.chapman@optusnet.com.au>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Michael Chapman

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.