view release on metacpan or  search on metacpan

lib/Device/OUI.pm  view on Meta::CPAN

=head1 NAME

Device::OUI - Resolve an Organizationally Unique Identifier

=head1 SYNOPSIS

    use Device::OUI;
    
    my $oui = Device::OUI->new( '00:17:F2' );
    printf( "Organization: %s\n", $oui->organization );

=head1 DESCRIPTION

This module provides an interface to the IEEE OUI (Organizationally Unique
Identifier) registry.  The registry contains information on what company
an OUI is assigned to.  OUIs are used in various networking devices as part
of a unique ID method (network MAC addresses and Fiber Channel WWNs in
particular, see the L<Device::MAC> and L<Device::WWN> modules for more
information).

=head1 CONFIGURATION

This module has a handful of configuration options, mostly dealing with
where to get the source for the registry data, and where to store the cache.

These configuration options are inherited, and you can change them for the
main class, a subclass, or a specific object.  Note that changing a
configuration option for an object does not change it for other objects of
that class (see L<Class::Accessor::Grouped/get_inherited|get_inherited in
the Class::Accessor::Grouped docs>).

    use Device::OUI;
    Device::OUI->cache_db( '/tmp/oui_cache' );

=head2 Device::OUI->cache_db( $db )

Returns the filename where the cache database should be stored.  If given an
argument you can change the file to store the cache database in.

The default is C<C:\device_oui> on windows, and C</var/cache/device_oui> on
everything else.  Set this to undef to disable the cache database.
(C<< Device::OUI->cache_db( undef ) >>).

Note that L<AnyDBM_File|AnyDBM_File> may append an extension (usually '.db')
to whatever you use as the filename, depending on which C<*DBM_File> classes
are available on your machine.

=head2 Device::OUI->cache_file( $filename )

Returns the filename where the oui.txt file should be stored when downloaded
from the internet, or where the file can be found if you are downloading it
by some other means.

The default is C<C:\device_oui.txt> on windows, and
C</var/cache/device_oui.txt> on everything else.  Set this to undef to
disable the cache file.  (C<< Device::OUI->cache_file( undef ) >>).

=head2 Device::OUI->search_url( $url )

The URL for the OUI search page.  Normally you don't need to change this,
but it is provided as a configuration option in case the page is relocated.
You can also set this to undef to disable runtime searches.

This value is used by L</search_url_for|search_url_for> to create a search
url for a specific OUI.  The default implementation allows you to include
a '%s' token in the URL, in which case the URL will be formatted with
L<perlfunc/sprintf|sprintf>, using the OUI as an argument.  If the url
provided does not contain a '%s' token, then the OUI will simply be appended
to the end (in which case, the URL provided should probably end with
something like: C<?arg=>).

=head2 Device::OUI->file_url( $url );

The URL to download the entire oui.txt registry file.  Normally you don't need
to change this either, but you can set it to undef to disable registry
downloading.

=head1 CLASS METHODS

=head2 my $oui = Device::OUI->new( $oui );

Creates and returns a new Device::OUI object.  If an OUI is provided, it will
be passed to the oui method detailed below.  Creating an object without an
oui is not an error, but any method that should return data will croak when
you call it if no oui has been provided either at construction time or by
calling the L</oui|oui> method.

=head2 Device::OUI->load_cache_from_file( $file );

The L</load_cache_from_file|load_cache_from_file> method is used to load up
the cache database with data from an OUI registry file.  If no filename
is provided, then the value returned by L</cache_file|cache_file> will be
used.  If L</cache_file|cache_file> is not defined and you don't provide a
filename when you call this method, then it will simply return without
doing anything.

Returns the number of records processed into the cache database, if no cache
file can be located, then it will return.

=head2 Device::OUI->load_cache_from_web( $url, $file );

The L</load_cache_from_web|load_cache_from_web> method attempts to download
an updated version of the indicated file and load it into the cache database.
If no url is provided then the value returned by L</file_url|file_url> will
be used.  If L</file_url|file_url> is not defined, then either you must
provide a url when calling this method, or it will return without
doing anything.

This method uses the L<LWP::Simple/mirror|mirror> method from
L<LWP::Simple|LWP::Simple> to update the cache file, so it will not download
a new registry file if it already has the latest version.  This makes it
easy to have a cron job that updates the registry file using a command like:

    perl -MDevice::OUI -e 'Device::OUI->load_cache_from_web'

Returns undef if the update failed, or no update was necessary.  Returns the
number of records inserted into the cache database if successful.  This method
also will not update the cache database if a new file wasn't downloaded.  If
you want to update the cache database regardless of whether a new file was
downloaded or not, try this: