NAME
    Device::OUI - Resolve an Organizationally Unique Identifier

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

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 Device::MAC and Device::WWN modules
    for more information).

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 Class::Accessor::Grouped/get_inherited).

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

  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:\device_oui" on windows, and "/var/cache/device_oui"
    on everything else. Set this to undef to disable the cache database.
    ("Device::OUI->cache_db( undef )").

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

  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:\device_oui.txt" on windows, and
    "/var/cache/device_oui.txt" on everything else. Set this to undef to
    disable the cache file. ("Device::OUI->cache_file( undef )").

  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 /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
    perlfunc/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: "?arg=").

  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.

CLASS METHODS
  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 /oui method.

  Device::OUI->load_cache_from_file( $file );
    The /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 /cache_file will be used. If /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.

  Device::OUI->load_cache_from_web( $url, $file );
    The /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 /file_url will be used. If /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 LWP::Simple/mirror method from 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:

        use Device::OUI;
        if ( defined Device::OUI->mirror_file ) {
            Device::OUI->load_cache_from_file();
        }

  cache_handle( $new );
    Called with an argument, sets a new object for the cache handle. This
    object will be treated like a hash, so it either needs to be a hash
    reference, or a tied hash reference, or something along those lines.

    If called without an argument, returns the current cache handle, making
    a new one if necessary. If it's necessary to create a new handle and
    /cache_db is set, then a new hash will be created and tied to
    AnyDBM_File.

    If it's necessary to create a new handle and /cache_db is not defined
    (or the attempt to tie to AnyDBM_File fails), then a new anonymous hash
    will be used to create an in-memory cache that only lasts for the life
    of the program.

OBJECT METHODS
  $oui->oui( $oui )
    Called with no arguments, this returns the OUI that the object
    represents (in the same format it was originally provided to the
    object). If given an argument of an OUI, sets or changes the OUI
    represented by this object.

    Any reasonable OUI format should be accepted by this method. The most
    common formats (00:17:F2, 00-17-f2, 0017f2, 0:17:f2, etc) should be fine
    with any delimiter between the bytes. If no delimiter is provided (as in
    the case of '08001B', the argument must be exactly 6 characters long.

  $oui->normalized()
    Returns a normalized form of the OUI, with upper-case hex bytes
    zero-padded and separated with dashes (as in 00-17-F2). Also available
    as "$oui->norm".

  $oui->norm()
    This is an alias for /normalized;

  $oui->is_private()
    Returns a true value if the OUI is privately registered (in this case no
    information is available on the organization that owns it, they are
    simply listed in the registry file as 'PRIVATE').

  $oui->organization()
    Returns the organization the OUI is registered to. For private
    registrations, the organization is set to 'PRIVATE'.

  $oui->company_id()
    Returns the 'company_id' from the registry file. This is really just the
    OUI in a slightly different format (0019E3 instead of 00-19-E3).

  $oui->address()
    Returns the organization address from the registry file as a multiline
    string.

FUNCTIONS / EXPORTS
    Although this module is entirely object oriented, there are a handful of
    utility functions that you can import from this module if you find a
    need for them. Nothing is exported by default, so if you want to import
    any of these, you need to say so explicitly:

        use Device::OUI qw( ... );

    You can get all of them by importing the ':all' tag:

        use Device::OUI ':all';

  my $oui = normalize_oui( $input );
    Given an OUI, normalizes it into an upper-case, zero padded, dash
    separated format and returns the normalized OUI.

    This method only uses the last argument provided to it, so it can safely
    be called as a class method as well.

  oui_cmp( $oui, $oui );
    This is a convenience method, given two Device::OUI objects, or two OUIs
    (in any acceptable format) or one of each, will return -1, 0, or 1,
    depending on whether the first OUI is less than, equal to, or greater
    than the second one.

    Device::OUI objects have "cmp" and "<=>" overloaded so that simply
    comparing them will work as expected.

    This method only uses the last two arguments that it is provided, so it
    can safely be called as a class method, an instance method, or a
    function, as long as it is given two Device::OUI objects or OUIs.

        $oui->oui_cmp( $oui2 );
        Device::OUI->oui_cmp( $oui1, $oui2 );
        Device::OUI::oui_cmp( $oui1, $oui2 );
    
        my @sorted = sort Device::OUI::oui_cmp @ouis;

        use Device::OUI qw( oui_cmp );
        my @sorted = sort oui_cmp @ouis;

  parse_oui_entry( $entry );
    Given a text representation of a single entry from the OUI registry
    file, this method extracts the information from it and returns a data
    structure that looks like this:

        {
            oui          => '00-17-F2',
            company_id   => '0017F2',
            organization => 'Apple Computer',
            address      => [
                '1 Infinite Loop MS:35GPO',
                'Cupertino CA 95014',
                'UNITED STATES',
            ],
        }

    This method only uses the last argument provided to it, so it can safely
    be called as a class method as well.

  my @parts = oui_to_integers( $oui );
    Given an OUI in any acceptable format, returns an array of three
    integers representing the values of the three bytes of the OUI.

    This method only uses the last argument provided to it, so it can safely
    be called as a class method as well.

INTERNAL METHODS
    These are methods used internally, that you shouldn't need to mess with.

  $oui->lookup();
    Attempts to retireve information from the OUI registry. If another
    lookup method has already retrieved the information, then that saved
    structure will simply be returned. If not, then an attempt will be made
    to load the data from the /cache_db, from the /cache_file or from the
    internet, using the search interface indicated by /search_url. As a last
    resort, if /file_url is defined, it will attempt to download it and use
    it for searching.

    Returns a hash reference of the data found, or an empty hash reference
    if all these things failed.

  Device::OUI->cache( $oui, $data )
    This method is the main interface to the cache database.

    If called with one argument, then it returns the cached data for the OUI
    provided. If called with two arguments it replaces the existing cached
    data with the new data provided.

  $oui->cache( $data )
    If /cache is called as an object method, you don't have to include the
    OUI as an argument. If there are no arguments, then the OUI of the
    invocant will be used as the OUI. If there is one argument and it is a
    reference, then it will be assumed to be $data. If there is one argument
    and it is not a reference, then it will be assumed to be an OUI. If
    there are two arguments, then it behaves the same as when called as a
    class method.

  $oui->update_from_web()
    This method searches the OUI registry (using the URL configured in
    /search_url) for it's own OUI, and if successful, updates the cache with
    the information found.

    If a /cache_db is in use, this method will update the cache database.

    If the search is successful, this method also returns the data that was
    found.

  $oui->update_from_file()
    This method searches the OUI registry file, if you have one and it can
    be located with /cache_file.

    If a /cache_db is in use, this method will update the cache database.

    If the search is successful, this method also returns the data that was
    found.

  Device::OUI->dump_cache( $sort )
    This method is mostly for debugging purposes. When called, it will dump
    (to "STDOUT") the contents of the cache database in the same format as
    the entries appear in the OUI registry file.

    Takes one optional argument, if called with a true value, then the
    entries will be dumped in order, sorted by their OUIs. With sorting
    turned off, this method runs much faster and returns sooner, but if you
    turn sorting on then the output file should be round-trippable, meaning
    you can do this:

        # curl -O http://standards.ieee.org/regauth/oui/oui.txt
        ... Downloading ...
        # perl -MDevice::OUI -e 'Device::OUI->load_cache_from_file( "oui.txt" );'
        # perl -MDevice::OUI -e 'Device::OUI->dump_cache' > new-oui.txt
        # diff oui.txt new-oui.txt
        ( no differences )

  $oui->search_url_for( $oui )
    Fills in the URL indicated by /search_url with either the OUI provided
    as an argument, or the invocants OUI, if called as an object method and
    no argument is provided.

  Device::OUI->have_lwp_simple()
    This methods returns true if LWP::Simple is available and false if it is
    not available. The first time this method is called, an attempt will be
    made to "require LWP::Simple", and a warning will be issued if the
    "require" is not successful. This method is used internally by the web
    access features.

  Device::OUI->mirror_file( $url, $file )
    This method is a wrapper around LWP::Simple/mirror. It returns 1 if the
    file was mirrored successfully, 0 if the file was not mirrored because
    the web server reported that the version of the file already in
    "cache_file" was the latest version, and undef if no file was
    downloaded.

    If $file is not provided, then the value from /cache_file will be used.
    If $url is not provided, then the value from /file_url will be used.

  Device::OUI->get_url( $url )
    This method is a wrapper around LWP::Simple/get. It attempts to load the
    provided $url and returns the contents of the page if successful. It
    returns undef if unsucessful or if no URL is provided

  overload_cmp
    This is just a little wrapper that calls /oui_cmp, rearranging the order
    of the arguments if necessary.

CACHING INFORMATION
  LAZY CACHE LOADING
    There are a couple of ways you can use the cache features in this
    module. If you are only going to lookup a handful of OUIs and don't want
    to download and process the whole registry file at one time, you can
    simply let the module create a cache database for you, and populate it
    with entries one at a time as objects are created that are not already
    in the cache.

  PRE-POPULATING THE CACHE
    If you are going to be looking up a lot of OUIs (where a lot should
    probably be defined as "more than 4 or 5") then you would probably be
    better off pre-populating the cache, using either the
    /load_cache_from_web method or the /load_cache_from_file method. The
    first is the easiest, assuming the machine you are running it on has web
    access, you can simply run:

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

    If you don't have web access, you can transfer the file in whatever
    manner works for you, and then use it to populate the cache with:

        perl -MDevice::OUI -e 'Device::OUI->load_cache_file_file( "filename" )'

  PREVENTING CACHING
    To keep the module from creating a cache database, set /cache_db to
    undef before creating any Device::OUI objects:

        use Device::OUI;
        Device::OUI->cache_db( undef );

    If you don't have a cache database, but you do have a cache file, then
    the caching module will simply look each OUI up in the file every time.
    This is much slower than having a cache database, but may be necessary
    in some situations.

  PREVENTING NETWORK ACCESS
    To keep Device::OUI from attempting to access the network, set the URL
    configuration options to undef before creating any "Device::OUI"
    objects:

        use Device::OUI;
        Device::OUI->search_url( undef );
        Device::OUI->file_url( undef );

    Even with these two values set to undef, /load_cache_from_web will still
    work (and still attempt to access the internet) if you give it a URL as
    an argument when you call it.

    Network access will also be disabled if LWP::Simple is not available.

MODULE HOME PAGE
    The home page of this module is
    <http://www.jasonkohles.com/software/device-oui>. This is where you can
    always find the latest version, development versions, and bug reports.
    You will also find a link there to report bugs.

SEE ALSO
    <http://www.jasonkohles.com/software/device-oui>

    <http://en.wikipedia.org/wiki/Organizationally_Unique_Identifier>

    <http://standards.ieee.org/regauth/oui/index.shtml>

AUTHOR
    Jason Kohles "<email@jasonkohles.com>"

COPYRIGHT AND LICENSE
    Copyright (C) 2008, 2009 Jason Kohles

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