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.

cpanm Ham::APRS::FAP

perl -MCPAN -e shell
install Ham::APRS::FAP