| 1 | |||
| 2 | package Ham::APRS::IS; | ||
| 3 | |||
| 4 | =head1 NAME | ||
| 5 | |||
| 6 | Ham::APRS::IS - An APRS-IS client module | ||
| 7 | |||
| 8 | =head1 SYNOPSIS | ||
| 9 | |||
| 10 | use Ham::APRS::IS; | ||
| 11 | use Ham::APRS::FAP qw(parseaprs); | ||
| 12 | |||
| 13 | my $is = new Ham::APRS::IS('aprs.example.com:12345', 'N0CALL', 'appid' => 'IS-pm-test 1.0'); | ||
| 14 | $is->connect('retryuntil' => 3) || die "Failed to connect: $is->{error}"; | ||
| 15 | |||
| 16 | for (my $i = 0; $i < 10; $i += 1) { | ||
| 17 | my $l = $is->getline_noncomment(); | ||
| 18 | next if (!defined $l); | ||
| 19 | print "\n--- new packet ---\n$l\n"; | ||
| 20 | |||
| 21 | my %packetdata; | ||
| 22 | my $retval = parseaprs($l, \%packetdata); | ||
| 23 | |||
| 24 | if ($retval == 1) { | ||
| 25 | while (my ($key, $value) = each(%packetdata)) { | ||
| 26 | print "$key: $value\n"; | ||
| 27 | } | ||
| 28 | } else { | ||
| 29 | warn "Parsing failed: $packetdata{resultmsg} ($packetdata{resultcode})\n"; | ||
| 30 | } | ||
| 31 | } | ||
| 32 | |||
| 33 | $is->disconnect() || die "Failed to disconnect: $is->{error}"; | ||
| 34 | |||
| 35 | =head1 ABSTRACT | ||
| 36 | |||
| 37 | This module is a client library for the APRS-IS. It has an object-oriented | ||
| 38 | interface which contains methods to connect and disconnect from a server, | ||
| 39 | and to read and write lines on the connection. | ||
| 40 | |||
| 41 | =head1 DESCRIPTION | ||
| 42 | |||
| 43 | Unless a debugging mode is enabled, all errors and warnings are reported | ||
| 44 | through the API (as opposed to printing on STDERR or STDOUT), so that | ||
| 45 | they can be reported nicely on the user interface of an application. | ||
| 46 | |||
| 47 | =head1 EXPORT | ||
| 48 | |||
| 49 | None by default. | ||
| 50 | |||
| 51 | =head1 FUNCTION REFERENCE | ||
| 52 | |||
| 53 | |||
| 54 | =cut | ||
| 55 | |||
| 56 | |||
| 57 | use 5.006; | ||
| 58 | use strict; | ||
| 59 | use warnings; | ||
| 60 | |||
| 61 | use Time::HiRes qw( time sleep ); | ||
| 62 | use IO::Handle '_IOFBF'; | ||
| 63 | use IO::Socket::INET; | ||
| 64 | use IO::Select; | ||
| 65 | |||
| 66 | our $VERSION = '1.18'; | ||
| 67 | |||
| 68 | our $default_appid = "IS.pm $VERSION"; | ||
| 69 | |||
| 70 | =head1 new(hostport, mycall, option) | ||
| 71 | |||
| 72 | Initializes a new Ham::APRS::IS socket. Takes two mandatory arguments, | ||
| 73 | the host:port pair to connect to and your client's callsign, and one or more | ||
| 74 | optional named options: | ||
| 75 | |||
| 76 | =over | ||
| 77 | |||
| 78 | =item * filter: an APRS-IS filter string sent to the server | ||
| 79 | |||
| 80 | =item * passcode: an APRS-IS passcode | ||
| 81 | |||
| 82 | =item * appid: your application's name and version number direction finding | ||
| 83 | |||
| 84 | =back | ||
| 85 | |||
| 86 | my $is = new Ham::APRS::IS('aprs.server.com:12345', 'N0CALL', 'appid' => 'myapp 3.4b'); | ||
| 87 | my $is = new Ham::APRS::IS('aprs.server.com:12345', 'N0CALL', 'appid' => 'foobar 42', 'filter' => 'f/*'); | ||
| 88 | my $is = new Ham::APRS::IS('aprs.server.com:12345', 'N0CALL', 'passcode' => 1234, 'appid' => 'myapp 1.2'); | ||
| 89 | |||
| 90 | =cut | ||
| 91 | |||
| 92 | sub new($$$;%) | ||
| 93 | { | ||
| 94 | my $that = shift; | ||
| 95 | my $class = ref($that) || $that; | ||
| 96 | my $self = { }; | ||
| 97 | bless ($self, $class); | ||
| 98 | |||
| 99 | my($host_port, $mycall, %options) = @_; | ||
| 100 | |||
| 101 | $self->{'host_port'} = $host_port; | ||
| 102 | $self->{'mycall'} = $mycall; | ||
| 103 | $self->{'filter'} = $options{'filter'} if (defined $options{'filter'}); | ||
| 104 | |||
| 105 | if ($options{'passcode'}) { | ||
| 106 | $self->{'passcode'} = $options{'passcode'}; | ||
| 107 | } else { | ||
| 108 | $self->{'passcode'} = -1; | ||
| 109 | } | ||
| 110 | |||
| 111 | if ($options{'appid'}) { | ||
| 112 | $self->{'appid'} = $options{'appid'}; | ||
| 113 | } else { | ||
| 114 | $self->{'appid'} = $default_appid; | ||
| 115 | } | ||
| 116 | |||
| 117 | $self->{'state'} = 'init'; | ||
| 118 | $self->{'error'} = "No errors yet."; | ||
| 119 | |||
| 120 | return $self; | ||
| 121 | } | ||
| 122 | |||
| 123 | =head1 disconnect( ) | ||
| 124 | |||
| 125 | Disconnects from the server. Returns 1 on success, 0 on failure. | ||
| 126 | |||
| 127 | $is->disconnect() || die "Failed to disconnect: $is->{error}"; | ||
| 128 | |||
| 129 | =cut | ||
| 130 | |||
| 131 | sub disconnect($) | ||
| 132 | { | ||
| 133 | my($self) = @_; | ||
| 134 | |||
| 135 | if (defined $self->{'sock'}) { | ||
| 136 | $self->{'sock'}->close; | ||
| 137 | undef $self->{'sock'}; | ||
| 138 | } | ||
| 139 | |||
| 140 | $self->{'state'} = 'disconnected'; | ||
| 141 | |||
| 142 | return 1; | ||
| 143 | } | ||
| 144 | |||
| 145 | sub user_command($) | ||
| 146 | { | ||
| 147 | my($self) = @_; | ||
| 148 | |||
| 149 | if (defined($self->{'filter'})) { | ||
| 150 | return sprintf("user %s pass %s vers %s filter %s\r\n", | ||
| 151 | $self->{'mycall'}, | ||
| 152 | $self->{'passcode'}, | ||
| 153 | $self->{'appid'}, $self->{'filter'} ); | ||
| 154 | } else { | ||
| 155 | return sprintf("user %s pass %s vers %s\r\n", | ||
| 156 | $self->{'mycall'}, | ||
| 157 | $self->{'passcode'}, | ||
| 158 | $self->{'appid'} ); | ||
| 159 | } | ||
| 160 | } | ||
| 161 | |||
| 162 | =head1 connect(options) | ||
| 163 | |||
| 164 | Connects to the server. Returns 1 on success, 0 on failure. | ||
| 165 | Takes an optional options hash as a parameter. Currently knows only one parameter, | ||
| 166 | retryuntil, which specifies the number of seconds to retry the connection. After | ||
| 167 | each failed attempt the code sleeps for 0.5 seconds before trying again. Defaults | ||
| 168 | to 0 (no retries). | ||
| 169 | |||
| 170 | $is->connect('retryuntil' => 10) || die "Failed to connect: $is->{error}"; | ||
| 171 | |||
| 172 | =cut | ||
| 173 | |||
| 174 | sub connect($;%) | ||
| 175 | { | ||
| 176 | my($self) = shift; | ||
| 177 | |||
| 178 | my %options = @_; | ||
| 179 | |||
| 180 | if ($self->{'state'} eq 'connected') { | ||
| 181 | $self->{'error'} = 'Already connected'; | ||
| 182 | return 0; | ||
| 183 | } | ||
| 184 | |||
| 185 | $self->{'ibuf'} = ''; | ||
| 186 | |||
| 187 | my $retryuntil = defined $options{'retryuntil'} ? $options{'retryuntil'} : 0; | ||
| 188 | my $starttime = time(); | ||
| 189 | |||
| 190 | while (!defined $self->{'sock'}) { | ||
| 191 | $self->{'sock'} = IO::Socket::INET->new($self->{'host_port'}); | ||
| 192 | |||
| 193 | if (!defined($self->{'sock'})) { | ||
| 194 | $self->{'error'} = "Failed to connect to $self->{host_port}: $!"; | ||
| 195 | |||
| 196 | if (time() - $starttime >= $retryuntil) { | ||
| 197 | return 0; | ||
| 198 | } | ||
| 199 | |||
| 200 | select(undef, undef, undef, 0.5); | ||
| 201 | } | ||
| 202 | } | ||
| 203 | |||
| 204 | $self->{'error'} = 'Connected successfully'; | ||
| 205 | |||
| 206 | # printf ( "APRS::IS->new() mycall='%s' passcode=%d filterre='%s'\n", | ||
| 207 | # $self->{aprsmycall}, $self->{passcode}, $self->{filterre} ); | ||
| 208 | |||
| 209 | ## | ||
| 210 | ## * Need to send on initial connect the following logon line: | ||
| 211 | ## user callsign pass passcode vers appname versionnum rest_of_line | ||
| 212 | ## | ||
| 213 | ## callsign = login callsign-SSID | ||
| 214 | ## passcode = login passcode per APRS-IS algorithm, -1 = read-only | ||
| 215 | ## appname = application name (1 word) | ||
| 216 | ## versionnum = application version number (no spaces) | ||
| 217 | ## rest_of_line = server command if connecting to a port that supports commands (see Server Commands) | ||
| 218 | ## | ||
| 219 | ## (appname and versionnum should not exceed 15 characters) | ||
| 220 | ## | ||
| 221 | ## | ||
| 222 | ## * Need to recognize both TCPIP and TCPXX as TCP/IP stations | ||
| 223 | ## * Need to provide a means to perform the user validation. This can either be a user entered password, | ||
| 224 | ## or a client program can automatically figure out the password given the callsign. | ||
| 225 | ## If the later is used, it is the client programmer's responsibility to be certain that non-amateurs | ||
| 226 | ## are not given registrations that can validate themselves in APRS-IS. | ||
| 227 | ## * Probably a good idea to perform some feedback about the limitations of TCPIP without a registration number. | ||
| 228 | ## | ||
| 229 | |||
| 230 | $self->{'sock'}->blocking(1); | ||
| 231 | $self->{'state'} = 'connected'; | ||
| 232 | |||
| 233 | my $s = $self->user_command(); | ||
| 234 | |||
| 235 | #warn "login: $s\n"; | ||
| 236 | if (!$self->{'sock'}->print($s)) { | ||
| 237 | $self->{'error'} = "Failed to write login command to $self->{host_port}: $!"; | ||
| 238 | return 0; | ||
| 239 | } | ||
| 240 | |||
| 241 | if (!$self->{'sock'}->flush) { | ||
| 242 | $self->{'error'} = "Failed to flush login command to $self->{host_port}: $!"; | ||
| 243 | return 0; | ||
| 244 | } | ||
| 245 | |||
| 246 | $self->{'sock'}->blocking(0); | ||
| 247 | |||
| 248 | my $t = time(); | ||
| 249 | while (my $l = $self->getline()) { | ||
| 250 | return 1 if ($l =~ /^#\s+logresp\s+/); | ||
| 251 | if (time() - $t > 5) { | ||
| 252 | $self->{'error'} = "Login command timed out"; | ||
| 253 | return 0; | ||
| 254 | } | ||
| 255 | } | ||
| 256 | |||
| 257 | return 1; | ||
| 258 | } | ||
| 259 | |||
| 260 | =head1 connected( ) | ||
| 261 | |||
| 262 | Checks whether we're connected currently. Returns 1 for connected, 0 for not connected. | ||
| 263 | |||
| 264 | =cut | ||
| 265 | |||
| 266 | sub connected($) | ||
| 267 | { | ||
| 268 | my($self) = @_; | ||
| 269 | |||
| 270 | return 1 if $self->{'state'} eq 'connected'; | ||
| 271 | return 0; | ||
| 272 | } | ||
| 273 | |||
| 274 | |||
| 275 | |||
| 276 | # ------------------------------------------------------------------------- | ||
| 277 | # Get a line (blocking) | ||
| 278 | |||
| 279 | =head1 getline(timeout) | ||
| 280 | |||
| 281 | Reads a line from the server (blocking). Returns the line read, | ||
| 282 | or undefined if the reading fails. Takes an optional timeout argument, | ||
| 283 | which tells getline to stop reading after the specified amount of | ||
| 284 | secounds. The timeout defaults to 5 seconds. | ||
| 285 | |||
| 286 | $l = $is->getline(); | ||
| 287 | die "Failed to read: $is->{error}" if (!defined $l); | ||
| 288 | |||
| 289 | The returned line does not contain the <CR><LF> line feed used as a | ||
| 290 | separator between packets on the APRS-IS. | ||
| 291 | |||
| 292 | =cut | ||
| 293 | |||
| 294 | |||
| 295 | sub getline($;$) | ||
| 296 | { | ||
| 297 | my($self, $timeout) = @_; | ||
| 298 | |||
| 299 | if ($self->{'state'} ne 'connected') { | ||
| 300 | $self->{'error'} = "getline: not connected"; | ||
| 301 | return undef; | ||
| 302 | } | ||
| 303 | |||
| 304 | $timeout = 5 if (!defined $timeout); | ||
| 305 | |||
| 306 | my $end_t = time() + $timeout; | ||
| 307 | my $sock = $self->{'sock'}; | ||
| 308 | |||
| 309 | while (1) { | ||
| 310 | if ($self->{'ibuf'} =~ s/^(.*?)[\r\n]+//s) { | ||
| 311 | #warn "got: $1\n"; | ||
| 312 | return $1; | ||
| 313 | } | ||
| 314 | |||
| 315 | if (time() > $end_t) { | ||
| 316 | $self->{'error'} = "getline: timeout"; | ||
| 317 | return undef; | ||
| 318 | } | ||
| 319 | |||
| 320 | my($rin, $rout, $ein, $eout) = ('', '', '', ''); | ||
| 321 | vec($rin, fileno($sock), 1) = 1; | ||
| 322 | $ein = $rin; | ||
| 323 | my $nfound = select($rout = $rin, undef, $eout = $ein, 1); | ||
| 324 | |||
| 325 | if (($nfound) && ($rout)) { | ||
| 326 | my $rbuf; | ||
| 327 | my $nread = sysread($sock, $rbuf, 1024); | ||
| 328 | if ($nread > 0) { | ||
| 329 | $self->{'ibuf'} .= $rbuf; | ||
| 330 | } elsif ($nread < 1) { | ||
| 331 | $self->{'error'} = "Failed to read from server: $!"; | ||
| 332 | |||
| 333 | $self->disconnect(); | ||
| 334 | return undef; | ||
| 335 | } | ||
| 336 | } elsif (($nfound) && ($eout)) { | ||
| 337 | $self->{'error'} = "Failed to read from server (select returned errors): $!"; | ||
| 338 | #warn "getline: read error (on select)\n"; | ||
| 339 | $self->disconnect(); | ||
| 340 | return undef; | ||
| 341 | } | ||
| 342 | } | ||
| 343 | } | ||
| 344 | |||
| 345 | =head1 getline_noncomment(timeout) | ||
| 346 | |||
| 347 | Like getline, but only returns noncomment lines (ones which do not | ||
| 348 | begin with a '#' character). The server normally transmits keep-alive timestamp | ||
| 349 | messages, error and status messages as comments. | ||
| 350 | |||
| 351 | =cut | ||
| 352 | |||
| 353 | sub getline_noncomment($;$) | ||
| 354 | { | ||
| 355 | my($self, $timeout) = @_; | ||
| 356 | |||
| 357 | return undef if ($self->{'state'} ne 'connected'); | ||
| 358 | while (my $l = $self->getline($timeout)) { | ||
| 359 | return $l if !defined $l; | ||
| 360 | return $l if ($l !~ /^#/); | ||
| 361 | } | ||
| 362 | } | ||
| 363 | |||
| 364 | |||
| 365 | =head1 sendline(packet) | ||
| 366 | |||
| 367 | Transmits a line (typically an APRS packet) to the APRS-IS. The line | ||
| 368 | should be a complete packet but WITHOUT the <CR><LF> separator | ||
| 369 | used on the APRS-IS. | ||
| 370 | |||
| 371 | =cut | ||
| 372 | |||
| 373 | sub sendline($$) | ||
| 374 | { | ||
| 375 | my($self, $line) = @_; | ||
| 376 | return undef if ($self->{'state'} ne 'connected'); | ||
| 377 | |||
| 378 | if (!defined $self->{'sock'}->blocking(1)) { | ||
| 379 | #warn "sendline: blocking(1) failed: $!\n"; | ||
| 380 | $self->{'error'} = "sendline: blocking(1) failed: $!"; | ||
| 381 | return undef; | ||
| 382 | } | ||
| 383 | my $ret = $self->{'sock'}->printf( "%s\r\n", $line); | ||
| 384 | if (!$self->{'sock'}->flush) { | ||
| 385 | #warn "sendline: flush() failed: $!\n"; | ||
| 386 | $self->{'error'} = "sendline: flush() failed: $!"; | ||
| 387 | return undef; | ||
| 388 | } | ||
| 389 | |||
| 390 | if (!defined $self->{'sock'}->blocking(0)) { | ||
| 391 | #warn "sendline: blocking(1) failed: $!\n"; | ||
| 392 | $self->{'error'} = "sendline: blocking(1) failed: $!"; | ||
| 393 | return undef; | ||
| 394 | } | ||
| 395 | |||
| 396 | #warn "sent ($ret): $line\n"; | ||
| 397 | return $ret; | ||
| 398 | } | ||
| 399 | |||
| 400 | # aprspass($callsign) | ||
| 401 | # | ||
| 402 | # Calculates the APRS passcode for a given callsign. Ignores SSID | ||
| 403 | # and converts the callsign to uppercase as required. Returns an integer. | ||
| 404 | # | ||
| 405 | # my $passcode = Ham::APRS::IS::aprspass($callsign); | ||
| 406 | |||
| 407 | sub aprspass($) | ||
| 408 | { | ||
| 409 | my($call) = @_; | ||
| 410 | |||
| 411 | $call =~ s/-([^\-]+)$//; | ||
| 412 | $call = uc($call); | ||
| 413 | |||
| 414 | my ($a, $h) = (0, 0); | ||
| 415 | map($h ^= ord(uc) << ($a^=8), $call =~ m/./g); | ||
| 416 | return (($h ^ 29666) & 65535); | ||
| 417 | } | ||
| 418 | |||
| 419 | =head1 sock() | ||
| 420 | |||
| 421 | Returns the perl socket used on the connection. | ||
| 422 | |||
| 423 | =cut | ||
| 424 | |||
| 425 | sub sock { | ||
| 426 | my $self = shift; | ||
| 427 | return $self->{sock}; | ||
| 428 | } | ||
| 429 | |||
| 430 | 1; | ||
| 431 | __END__ |