# Copyright (c) 2013-2016 Sullivan Beck. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.

=pod

=head1 NAME

Data::Checker::Ping - check data to see if it contains hosts that respong to pings

=head1 SYNOPSIS

   use Data::Checker;
   $obj = new Data::Checker;

   $obj->check($data,"Ping",$check_opts);

=head1 DESCRIPTION

This module is meant to be used by the L<Data::Checker> module.

One set of checks that is often done on sets of hosts is to check
that they respond to pings.  This module provides several ping
related checks that can be performed.

=head1 FUNCTIONS

=over 4

=item B<check>

This is the only function provided by this module, and it is
intended to be used by the L<Data::Checker> module.

=back

=head1 CHECKS OPTIONS

The B<$check_opts> hashref defines exactly what ping checks to
perform, and some options used by those checks.  Known keys that
specify the checks are:

=over 4

=item tcp, udp, icmp, stream, syn, external

These specify what protocol to use for sending a ping.  The default
is to use tcp.  Refer to the L<Net::Ping> manual for information about
each.

=back

The following keys can also be present to specify additional options:

=over 4

=item timeout

This is the timeout to use for a given check.

=back

=head1 EXAMPLES

All examples include the following lines:

   use Data::Checker;
   $obj = new Data::Checker;

   $data = ...
   $opts = ...

   ($pass,$fail,$info,$warn) = $obj->check($data,"Ping",$opts);

The value of C<$data> and C<$opts> is listed below in the examples.

=over 4

=item To test if a host responds to external pings

   $data = [ 'cpan.org', 'aaa.bbb.ccc' ];
   $opts = { 'external' => undef };

Produces:

   $pass = [ 'cpan.org' ]
   $fail = {'aaa.bbb.ccc' => ['Host does not respond to external pings']};

=back

=head1 KNOWN BUGS AND LIMITATIONS

None known.

=head1 SEE ALSO

L<Data::Checker>, L<Net::Ping>

=head1 LICENSE

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

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut
