NAME
    Ham::Reference::QRZ - An object oriented front end for the QRZ.COM
    Amateur Radio callsign database

VERSION
    Version 0.03

INSTALLATION
    To install this module, run the following commands:

    perl Makefile.PL
    make
    make test
    make install

SYNOPSIS
     use Ham::Reference::QRZ;
     use Data::Dumper;

     my $qrz = Ham::Reference::QRZ->new(
       callsign => 'N8QQ',
       username => 'your_username',
       password => 'your_password'
     );

     # get the listing, bio and other information
     my $listing = $qrz->get_listing;
     my $bio = $qrz->get_bio;
     my $dxcc = $qrz->get_dxcc;
     my $session = $qrz->get_session;

     # dump the data to see how it's structured
     print Dumper($listing);
     print Dumper($bio);
     print Dumper($dxcc);
     print Dumper($session);

     # set a different callsign to look up
     $qrz->set_callsign('W8IRC');

     # get the listing and print some specific info
     $listing = $qrz->get_listing;
     print "Name: $listing->{name}\n";

     # show some dxcc info
     print "DXCC Continent: $dxcc->{continent}\n";
     print "DXCC Name: $dxcc->{name}\n";
     print "CQ Zone: $dxcc->{cqzone}\n";

     # show some session info
     print "Lookups in current 24 hour period: $session->{Count}\n";
     print "QRZ subscription expiration: $session->{SubExp}\n";

     # show the ARRL section
     my $arrl_section = $qrz->get_arrl_section;
     print "ARRL Section: $arrl_section\n";

     # show biography details, if any
     my $bio = $qrz->get_bio_file;
     print "Biography: $bio\n";

DESCRIPTION
    The "Ham::Reference::QRZ" module provides an easy object oriented front
    end to access Amateur Radio callsign data from the QRZ.COM online
    database.

    This module uses the QRZ XML Database Service, which requires a
    subscription from QRZ.COM.

    The QRZ XML Database Service specification states "The data supplied by
    the XML port may be extended in a forwardly compatible manner. New XML
    elements and database objects (with their associated elements) may be
    transmitted at any time. It is the developers responsibility to have
    their program ignore any unrecognized objects and/or elements without
    raising an error, so long as the information received consists of
    properly formatted XML."

    Therefore, this module will not attempt to list or manage individual
    elements of a callsign. You will need to inspect the hash reference keys
    to see which elements are available for any given callsign, as
    demonstrated in the synopsis.

    This module does not handle any management of reusing session keys at
    this time.

CONSTRUCTOR
  new()
     Usage    : my $qrz = Ham::Reference::QRZ->new;
     Function : creates a new Ham::Reference::QRZ object
     Returns  : a Ham::Reference::QRZ object
     Args     : a hash:

                key       required?   value
                -------   ---------   -----
                timeout   no          an integer of seconds to wait for
                                       the timeout of the xml site
                                       default = 10
                callsign  no          you may specify a callsign to look up
                                       here, or you may do it later with the
                                       set_callsign() method
                username  no          you may specify a username to log in with
                                       here, or you may do it later with the
                                       set_username() method
                password  no          you may specify a password to log in with
                                       here, or you may do it later with the
                                       set_password() method
                key       no          set a session key here if you have a valid key so
                                       that no time is wasted doing another login. only
                                       useful if you are managing the reuse of your own keys

METHODS
  set_callsign()
     Usage    : $qrz->set_callsign( $callsign );
     Function : set the callsign to look up at QRZ
     Returns  : n/a
     Args     : a case-insensitive string containing an Amateur Radio callsign.
     Notes    : calling this will reset the listing and bio data to null until
                you do another get_listing() or get_bio(), respectively.

  set_username()
     Usage    : $qrz->set_username( $username );
     Function : set the username for your QRZ subscriber login
     Returns  : n/a
     Args     : a string

  set_password()
     Usage    : $qrz->set_password( $password );
     Function : set the password for your QRZ subscriber login
     Returns  : n/a
     Args     : a string

  set_key()
     Usage    : $qrz->set_key( $session_key );
     Function : set a session key for retrieving data at QRZ
     Returns  : n/a
     Args     : a string
     Notes    : this is useful only if you already have a valid key before the first login
                during a particular instance of the module.

  set_timeout()
     Usage    : $qrz->set_timeout( $seconds );
     Function : sets the number of seconds to wait on the xml server before timing out
     Returns  : n/a
     Args     : an integer

  get_listing()
     Usage    : $hashref = $qrz->get_listing;
     Function : retrieves data for the standard listing of a callsign from QRZ
     Returns  : a hash reference
     Args     : n/a
     Notes    : if a session key has not already been set, this method will automatically login.
                if a there is already listing information set from a previous lookup,
                this will just return that data.  call a new set_callsign() if you need to refresh
                the data with a new call to the qrz database.

  get_bio()
     Usage    : $hashref = $qrz->get_bio;
     Function : retrieves data for the biography of a callsign from QRZ
     Returns  : a hash reference
     Args     : n/a
     Notes    : if a session key has not already been set, this method will automatically login.
                if a there is already biographical information set from a previous lookup,
                this will just return that data.  call a new set_callsign() if you need to refresh
                the data with a new call to the qrz database.  this method only retrieves the meta
                information about the bio.  call get_bio_file to get the actual contents of the bio.

  get_bio_file()
     Usage    : $scalar = $qrz->get_bio_file;
     Function : retrieves the full biography of a callsign from QRZ, if any is available
     Returns  : a scalar
     Args     : n/a
     Notes    : if the get_bio method has not been called yet, it will be called first to get
                the url for the bio file.  any html entities in the contents of the bio will be
                converted to plain text, and all html will be stripped.  hard line breaks will be
                left in place.  suggestions are welcome on how this data might better be filtered.

  get_dxcc()
     Usage    : $hashref = $qrz->get_dxcc;
     Function : retrieves DXCC information for a callsign from QRZ
     Returns  : a hash reference
     Args     : n/a
     Notes    : if a session key has not already been set, this method will automatically login.
                if a there is already dxcc information set from a previous lookup,
                this will just return that data.  call a new set_callsign() if you need to refresh
                the data with a new call to the qrz database.

  get_arrl_section()
     Usage    : $scalar = $qrz->get_arrl_section;
     Function : returns ARRL Section information for a callsign
     Returns  : a scalar
     Args     : n/a
     Notes    : if get listing has not yet been called, it will call get_listing to get state and county.
                this method gets its data internally, and does not query the qrz xml server.

  login()
     Usage    : $session = $qrz->login;
     Function : initiates a login to the QRZ xml server
     Returns  : a hash reference of the session data
     Args     : n/a
     Notes    : this generally shouldn't need to be used since the get_listing() and get_bio()
                methods will automatically initiate a login to the server if it hasn't already
                been done.

  get_session()
     Usage    : $session = $qrz->get_session;
     Function : retrieves the session information from the most recent call to the XML site
     Returns  : a hash reference of the session data
     Args     : n/a

  is_error()
     Usage    : if ( $qrz->is_error )
     Function : test for an error if one was returned from the call to the XML site
     Returns  : a true value if there has been an error
     Args     : n/a

  error_message()
     Usage    : my $err_msg = $qrz->error_message;
     Function : if there was an error message when trying to call the XML site, this is it
     Returns  : a string (the error message)
     Args     : n/a

DEPENDENCIES
    *   XML::Simple

    *   LWP::UserAgent

    *   HTML::Entities

    *   An Internet connection

    *   A QRZ.COM subscription that includes access to the QRZ XML Database
        Service

TODO
    *   Session key reuse between instances (maybe).

    *   Look into any escaping or filtering of data that would be helpful,
        particularly with regard to get_bio_file().

ACKNOWLEDGEMENTS
    Thanks to Thomas Schaefer NY4I for the idea, original code, and data for
    the ARRL Section additions!

    This module accesses data from the widely popular QRZ.COM Database. See
    http://www.qrz.com

SEE ALSO
    *   In order to use this module you need to have a subscription for the
        QRZ XML Database Service. See http://www.qrz.com/XML/index.html

    *   The technical reference for the QRZ XML Database Service is at
        http://www.qrz.com/XML/current_spec.html

AUTHOR
    Brad McConahay N8QQ, "<brad at n8qq.com>"

COPYRIGHT AND LICENSE
    "Ham::Reference::QRZ" is Copyright (C) 2008-2010 Brad McConahay N8QQ.

    This module is free software; you can redistribute it and/or modify it
    under the terms of the Artistic License 2.0. For details, see the full
    text of the license in the file LICENSE.

    This program is distributed in the hope that it will be useful, but it
    is provided "as is" and without any express or implied warranties. For
    details, see the full text of the license in the file LICENSE.

