view release on metacpan or  search on metacpan

lib/Net/Ncap.pm  view on Meta::CPAN

=item drop_if($name)

Removes the given network interface from the collection pool.

=item add_nf($file, [$label])

Adds the given NCAP file as a data source. If I<file> is a reference, it
is assumed to be an open file handle and is used directly. Otherwise it
is assumed to be a file name and is opened for reading. An optional
I<label> can be provided for this source; by default the label is either
the filename or file number, depending on what was provided in I<file>.

=item drop_nf($file)

Removes the given NCAP file as a data source. The provided I<file> can
either be the file name, handle, or label (if one was provided).

=item add_pf($file, [$label])

Adds the given PCAP file as a data source. I<file> can either be a file
name or a file handle. Otherwise identical to add_nf(), including
accepting an optional I<label>.

=item drop_pf($file)

Removes the given PCAP file as a data source. The provided I<file> can
either be the file name, handle, or label (if one was provided).

=item add_dg($socket)

Adds the given socket handle as a data source.

=item drop_dg($socket)

Removes the given socket handle as a data source.

=item filter($filter)

Installs an NCAP filter described by the given string. If any BPFs
(berkely packet filters) have been installed, this will fail.

=item collect($callback, [%opts])

Collect data from the collection pool, invoking the subroutine
referenced by I<callback> for each matching ncap message. There are
several named options available:

=over 4

=item polling

Controls whether collection happens continuously (the default) or once.

=item sigwrap

Disabled by default. Controls whether signal handlers are installed for
SIGHUP, SIGINT, and SIGTERM prior to passing control to the collection
loop. Perl only sees these events when it is in context (i.e. during the
callback). Until then they are queued by default, until perl can handle
them. If you are polling on an interface that is not very busy, or if
your filters only occasionally pass an interesting message, it might be
a while before perl gets a chance to handle signals. With this option
enabled, the program is interruptable. Whatever signal handlers were in
place prior to invoking collect are restored once complete.

=item timeout

Disabled by default. Specifies a time window for which your callback
will be invoked, regardless of whether any messages have matched your
filters. In such a case, the message provided to the callback will be
undef. Enabling I<timeout> automatically enables I<sigwrap> as
described above.

=item timeout_cb

Specifies an optional alternate callback reference for I<timeout>
induced callbacks, rather than sending undef to the primary callback.

=back

=item stop()

Halts the collection loop. There might be a few stray callbacks before
the loop actually exits, depending on the granularity configured into
the ncap library.

=item write($fh, [$msg])

Writes the given ncap message to the provided file handle in the ncap
portable binary format. If no message is provided, a proper file header
is written instead.

=item send($socket, [$msg, $flags])

Writes the given ncap message to the provided socket handle in the ncap
portable binary format. If no Net::Ncap::ncap_msg object is provided, an
NCAP file header is written instead. <em>flags<em> are an integer
representation of any flags as would be provided to the send(2) function
from the socket library (default MSG_DONTROUTE).

=back

=head1 CALLBACK

=over 4

=item callback($msg)

The callback function is handed a single parameter, a reference to a
message object. See below for more information. If collection was
invoked with either I<sigwrap> or I<timeout> enabled, the callback
might be invoked with C<undef>, depending on whether I<timeout_cb>
was provided.

The callback can abort the collection loop by invoking the stop() method
on the Net::Ncap object.

=back

=head1 MESSAGE OBJECTS