NAME
Ham::APRS::IS - An APRS-IS client module
SYNOPSIS
use Ham::APRS::IS;
use Ham::APRS::FAP qw(parseaprs);
my $is = new Ham::APRS::IS('aprs.example.com:12345', 'N0CALL', 'appid' => 'IS-pm-test 1.0');
$is->connect('retryuntil' => 3) || die "Failed to connect: $is->{error}";
for (my $i = 0; $i < 10; $i += 1) {
my $l = $is->getline_noncomment();
next if (!defined $l);
print "\n--- new packet ---\n$l\n";
my %packetdata;
my $retval = parseaprs($l, \%packetdata);
if ($retval == 1) {
while (my ($key, $value) = each(%packetdata)) {
print "$key: $value\n";
}
} else {
warn "Parsing failed: $packetdata{resultmsg} ($packetdata{resultcode})\n";
}
}
$is->disconnect() || die "Failed to disconnect: $is->{error}";ABSTRACT
This module is a client library for the APRS-IS. It has an object-oriented interface which contains methods to connect and disconnect from a server, and to read and write lines on the connection.
DESCRIPTION
Unless a debugging mode is enabled, all errors and warnings are reported through the API (as opposed to printing on STDERR or STDOUT), so that they can be reported nicely on the user interface of an application.
EXPORT
None by default.
FUNCTION REFERENCE
new(hostport, mycall, option)
Initializes a new Ham::APRS::IS socket. Takes two mandatory arguments, the host:port pair to connect to and your client's callsign, and one or more optional named options:
filter: an APRS-IS filter string sent to the server
passcode: an APRS-IS passcode
appid: your application's name and version number direction finding
my $is = new Ham::APRS::IS('aprs.server.com:12345', 'N0CALL', 'appid' => 'myapp 3.4b');
my $is = new Ham::APRS::IS('aprs.server.com:12345', 'N0CALL', 'appid' => 'foobar 42', 'filter' => 'f/*');
my $is = new Ham::APRS::IS('aprs.server.com:12345', 'N0CALL', 'passcode' => 1234, 'appid' => 'myapp 1.2');disconnect( )
Disconnects from the server. Returns 1 on success, 0 on failure.
$is->disconnect() || die "Failed to disconnect: $is->{error}";connect(options)
Connects to the server. Returns 1 on success, 0 on failure. Takes an optional options hash as a parameter. Currently knows only one parameter, retryuntil, which specifies the number of seconds to retry the connection. After each failed attempt the code sleeps for 0.5 seconds before trying again. Defaults to 0 (no retries).
$is->connect('retryuntil' => 10) || die "Failed to connect: $is->{error}";connected( )
Checks whether we're connected currently. Returns 1 for connected, 0 for not connected.
getline(timeout)
Reads a line from the server (blocking). Returns the line read, or undefined if the reading fails. Takes an optional timeout argument, which tells getline to stop reading after the specified amount of secounds. The timeout defaults to 5 seconds.
$l = $is->getline();
die "Failed to read: $is->{error}" if (!defined $l);The returned line does not contain the <CR><LF> line feed used as a separator between packets on the APRS-IS.
getline_noncomment(timeout)
Like getline, but only returns noncomment lines (ones which do not begin with a '#' character). The server normally transmits keep-alive timestamp messages, error and status messages as comments.
sendline(packet)
Transmits a line (typically an APRS packet) to the APRS-IS. The line should be a complete packet but WITHOUT the <CR><LF> separator used on the APRS-IS.
sock()
Returns the perl socket used on the connection.
SEE ALSO
Ham::APRS::FAP, the Fabulous APRS parser
AUTHORS
Matti Aarnio, OH2MQK
Heikki Hannikainen, OH7LZB <hessu@hes.iki.fi>
COPYRIGHT AND LICENSE
Copyright 2000-3000 by Matti Aarnio
Copyright 2000-3000 by Heikki Hannikainen
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.