#
# $Id: Packet.pod,v 1.1.1.1 2004/06/04 06:01:29 mchapman Exp $
#

=head1 NAME

Net::CDP::Packet - Cisco Discovery Protocol (CDP) packet

=head1 SYNOPSIS

  use Net::CDP qw(:caps);
  use Net::CDP::Packet;
  
  # Constructors
  $packet = new Net::CDP::Packet;
  $packet = new Net::CDP::Packet($cdp);
  $cloned = clone $packet;
  
  # Object methods
  $version               = $packet->version;
  $ttl                   = $packet->ttl;
  $checksum              = $packet->checksum;
  $device                = $packet->device;
  @addresses             = $packet->addresses;
  $port                  = $packet->port;
  $capabilities          = $packet->capabilities;
  $ios_version           = $packet->ios_version;
  $platform              = $packet->platform;
  @ip_prefixes           = $packet->ip_prefixes;
  $vtp_management_domain = $packet->vtp_management_domain;
  $native_vlan           = $packet->native_vlan;
  $duplex                = $packet->duplex;

=head1 DESCRIPTION

A Net::CDP::Packet object represents a single CDP packet.

=head1 CONSTRUCTORS

=over

=item B<new>

    $packet = new Net::CDP::Packet()
    $packet = new Net::CDP::Packet($cdp)

Returns a new Net::CDP::Packet object.

The returned object will have the following fields set:

    Version: 1
    TTL: 180
    Device ID: `hostname`
    Capabilities: CDP_CAP_HOST
    IOS Version: `uname -a`
    Platform: `uname -s`

If supplied, C<$cdp> must be a L<Net::CDP> object. C<new> will use this to
generate the following fields:

    Port ID: $cdp->port()
    Addresses: $cdp->addresses()

=item B<clone>

    $cloned = clone $packet;

Returns a deep copy of the supplied Net::CDP::Packet object.

=back

=head1 OBJECT METHODS

=over

=item B<version>

    $version = $packet->version()

Returns this packet's Version field. For packets generated by L</new>, this
is always 1.

=item B<ttl>

    $ttl = $packet->ttl()
    $ttl = $packet->ttl($new_ttl)

Returns this packet's Time-to-live field. If C<$new_ttl> is supplied and
positive, the field will be updated first.

The Time-to-live field specifies how long a receiving CDP implementation may
cache the data in this packet.

=item B<checksum>

    $checksum = $packet->checksum()

Returns this packet's Checksum field. This checksum will be automatically
updated when other fields are modified.

=item B<device>

    $device = $packet->device()
    $device = $packet->device($new_device)

Returns this packet's Device ID field if present, C<undef> otherwise. If
C<$new_device> is supplied, the field will be updated first. If C<$new_device>
is undefined, the Device ID field is removed from the packet.

For packets received from other devices, the Device ID field specifies the name
of the device that generated the packet.

=item B<addresses>

    @addresses = $packet->addresses()
    @addresses = $packet->addresses($new_addresses)

Returns this packet's Addresses field as a list of L<Net::CDP::Address>
objects. In scalar context, the number of addresses is returned, or C<undef> if
no Addresses field is present.

If C<$new_addresses> is supplied, the field will be updated first. If
C<$new_addresses> is C<undef>, the Addresses field is removed from the packet.
Otherwise C<$new_addresses> must be a reference to an array of
L<Net::CDP::Address> objects. The array may be empty.

For packets received from other devices, the Addresses field specifies the
addresses of the network port (interface) upon which the packet was sent.

=item B<port>

    $port = $packet->port()
    $port = $packet->port($new_port)

Returns this packet's Port ID field if present, C<undef> otherwise. If
C<$new_port> is supplied, the field will be updated first. If C<$new_device> is
undefined, the Port ID field is removed from the packet.

For packets received from other devices, the Port ID field specifies the network
port (interface) upon which the packet was sent.

=item B<capabilities>

    $capabilities = $packet->capabilities()
    $capabilities = $packet->capabilities($new_capabilities)

Returns this packet's Capabilities field if present, C<undef> otherwise. If
$new_capabilities is supplied, the field will be updated first. If
$new_capabilities is undefined, the Capabilities field is removed from the
packet.

The Capabilities field is a bitmask specifying one or more of the following
constants:

    CDP_CAP_ROUTER
    CDP_CAP_TRANSPARENT_BRIDGE
    CDP_CAP_SOURCE_BRIDGE
    CDP_CAP_SWITCH
    CDP_CAP_HOST
    CDP_CAP_IGMP
    CDP_CAP_REPEATER

These constants can be exported from Net::CDP using the tag C<:caps>. See
L<Exporter>.

=item B<ios_version>

    $ios_version = $packet->ios_version()
    $ios_version = $packet->ios_version($new_ios_version)

Returns this packet's IOS Version field if present, C<undef> otherwise. If
$new_ios_version is supplied, the field will be updated first. If
$new_ios_version is undefined, the IOS Version field is removed from the packet.

=item B<platform>

    $platform = $packet->platform()
    $platform = $packet->platform($new_platform)

Returns this packet's Platform field if present, C<undef> otherwise. If
$new_platform is supplied, the field will be updated first. If $new_platform is
undefined, the Platform field is removed from the packet.

=item B<ip_prefixes>

    @ip_prefixes = $packet->ip_prefixes()
    @ip_prefixes = $packet->ip_prefixes($new_ip_prefixes)

Returns this packet's IP Prefixes field as a list of L<Net::CDP::IPPrefix>
objects.  In scalar context, the number of prefixes is returned, or C<undef> if
no IP Prefixes field is present.

If C<$new_ip_prefix> is supplied, the field will be updated first. If
C<$new_ip_prefix> is C<undef>, the IP Prefixes field is removed from the packet.
Otherwise C<$new_ip_prefix> must be a reference to an array of
L<Net::CDP::IPPrefix> objects. The array may be empty.

=item B<vtp_management_domain>

    $vtp_management_domain = $packet->vtp_management_domain()
    $vtp_management_domain =
        $packet->vtp_management_domain($new_vtp_management_domain)

Returns this packet's VTP Management Domain field if present, C<undef>
otherwise. If C<$new_vtp_management_domain> is supplied, the field will be
updated first. If C<$new_vtp_management_domain> is undefined, the VTP ManagementDomain field is removed from the packet.

=item B<native_vlan>

    $native_vlan = $packet->native_vlan()
    $native_vlan = $packet->native_vlan($new_native_vlan)

Returns this packet's Native VLAN field if present, C<undef> otherwise. If
C<$new_native_vlan> is supplied, the field will be updated first. If
C<$new_native_vlan> is undefined, the Native VLAN field is removed from the
packet.

=item B<duplex>

    $duplex = $packet->duplex()
    $duplex = $packet->duplex($new_duplex)

Returns this packet's Duplex field if present, C<undef> otherwise. If
C<$new_duplex> is supplied, the field will be updated first. If C<$new_duplex>
is undefined, the Duplex field is removed from the packet.

The Duplex field contains a boolean value. If it is true, the interface
supplied in the Port ID field supports full-duplex communication. Otherwise,
only half-duplex communication is supported.

=back

=head1 SEE ALSO

L<Net::CDP>, L<Net::CDP::Address>, L<Net::CDP::IPPrefix>

=head1 AUTHOR

Michael Chapman, E<lt>mike.chapman@optusnet.com.auE<gt>

=head1 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.
