Linux Certif

Toute la documentation sur la certification Linux LPI

Ham::Reference::QRZ.3pm

NAME

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

VERSION

Version 0.02

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 and bio
  my $listing = $qrz->get_listing;
  my $bio = $qrz->get_bio;
 
  # dump the data to see how it's structured
  print Dumper($listing);
  print Dumper($bio);
 
  # 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";
 
 

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.

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.  do 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.  do a new set_callsign() if you need to refresh
             the data with a new call to the qrz database.
 
 

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

*

An Internet connection

*

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

TODO

*

Improve error checking and handling.

*

Session key reuse between instances (maybe).

*

Look into any possible needed escaping, filtering, etc.

ACKNOWLEDGEMENTS

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://online.qrz.com

*

The technical reference for the QRZ XML Database Service is at http://online.qrz.com/specifications.html

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright 2008-2009 Brad McConahay N8QQ, all rights reserved.

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