NAME

Ham::Resources::HamQTH - A simple and easy object oriented front end for HAMQTH.COM Amateur Radio callsign free database service.

VERSION

Version 0.02

SYNOPSIS

        use Ham::Resources::HamQTH;

        my $qth = Ham::Resources::HamQTH->new(
                callsign => 'callsign to find',
                username => 'your HamQTH username',
                password => 'your HamQTH password'
        );

        # get information from one callsign found
        my $bio = $qth->get_bio;
        foreach (sort keys %{$bio}){
                print $_.": ".$bio->{$_}."\n";
        }
        
        # print a specific info
        my $bio = $qth->get_bio;
        print "grid: ".$bio->{grid};
        
        # get a list of available elements
        my $bio = $qth->get_list;
        
        

DESCRIPTION

The Ham::Resources::HamQTH module provides an easy way to access Amateur Radio callsign data from the HamQTH.COM online free database.

This module uses the HamQTH XML database service, which requires a valid user account. Create an account is free.

The number of response elements by the XML database can be different between each callsign, depending if it has any information of a callsign or not.

The duration of the SESSION is 1 hour, so the module save it a SESSION_ID and a timestamp into a file to check when is neccesary turn on login or use the saved SESSION_ID.

CONSTRUCTOR

new()

 Usage  : my $qth = Ham::Resources::HamQTH->new(
                callsign => 'callsign to search',
                username => 'your HamQTH username',
                password => 'your HamQTH password'
                );
 Funtion : creates a new Ham::Resources::HamQTH object
 Returns : an object
 Args    : a hash:
        
 key            required?       value
 -------        ---------       -----
 callsign       yes             a text with the callsign to find
 username       yes             a text with a valid username HamQTH.com  account
 password       yes             a text with a valid password HamQTH.com  account
 timeout        no              an integer of seconds to wait for the timeout of the XML service. By default = 10

METHODS

get_list()

 Usage    : my $bio = $qth->get_list;
 Function : gets a list of elements (tags) availables of a callsign found 
 Returns  : an array
 Args     : n/a

get_bio()

 Usage    : my $bio = $qth->get_bio;
 Function : retrieves data of a XML query, that is, all the data found a callsign or error occurred
 Returns  : a hash
 Args     : n/a

error()

 Usage    : my $error = $bio->{error}
 Function : retrieves an error message if not callsign found, lost internet connection, don't access to session file, fail on server response or run it without a callsign to find
 Returns  : a string, the error message. Only after call get_bio() method
 Args     : n/a

EXPORT

None by default.

REQUIRES

• LWP::UserAgent

• XML::Reader;

• Internet connection

ACKNOWLEDGEMENTS

This module accesses the data provided free by Petr (OK2CQR). See http://www.hamqth.com

SEE ALSO

You can view a complete example of use at http://cjuan.wordpress.com/hamresourceshamqth

You can also find a test script in test folder, you just need to edit and add your user account HamQTH.com to work. The callsign is passed as an argument to the script from the command line.

You can create an account for use this module at http://www.hamqth.com

AUTHOR

Carlos Juan, <ea3hmb_at_gmail.com>

COPYRIGHT AND LICENSE

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.

Copyright (C) 2012 by Carlos Juan Diaz (CJUAN) - EA3HMB <ea3hmb_at_gmail.com>

cpanm Ham::Resources::HamQTH

perl -MCPAN -e shell
install Ham::Resources::HamQTH