NAME
Net::Friends - Perl extension for interacting with GPSDrive friendsd server
SYNOPSIS
use Net::Friends;
$friends = new Net::Friends $server
$friends->report(
name => 'Ry4an',
lat => '44.988050',
lon => '-93.274450',
speed => 5,
dir => 180
);
%someone = $friends->query($nick);
%everyone = $friends->query;
ABSTRACT
Net::Friends allows for the reporting to and querying of GPSDrive-style
friendsd servers. The friendsd server used simple UDP messages to update and
report the most recent known position, speed, and direction of people and
things.
DESCRIPTION
The Net::Friends module offers basic reporting and querying methods. The report
method is used to tell a remote friendsd server where an entity is, the speed at which it's traveling, the direction in which it's traveling, and when the provided information was last correct. The query
method polls a remote friendsd server and return results for a specific requested person or for all people. Each is discussed in more detail below.
Objects of type Net::Friends retain state between report() invocations. If multiple people/entities are being reported about either a separate Net::Friends instance must be used for each person/entity or all the named parameters must be provided on each call to report
. See the detailed description of the report
method for more information.
The friendsd program comes with GPSDrive written by Fritz Ganter. GPSDrive can be found on the web at http://www.gpsdrive.de
report
-
Updates the remote server's information about an entity. Parameters include:
name
-
The name of the person/entity whose position is being reported. Should be provided on the first call to
report
. lat
-
Current latitude of the person/entity whose position is being reported. Value is in degrees. Locations in the Southern hemisphere should be negative values. Values should have size decimal places of precision.
lon
-
Current longitude of the person/entity whose position is being reported. Value is in degrees. Locations in the Western hemisphere should be negative values. Values should have size decimal places of precision.
speed
-
Current speed in kilometers per hour of the person/entity whose position is being reported.
dir
-
Current heading in degrees of the person/entity whose position is being reported
id
-
The 'id' parameter is used by friends servers to guarantee uniqueness amongst people/entities which may have identical names. Any report to the friendsd server will overwrite any previous report with the same id. A random id is generated on the first call to report. Subsequent calls to report will use the same id. Manually specifying an id can be used to allow for updating between invocations. Id values should be 22 character alphanumeric strings. The randomly selected id is available as
$friends-
{id}>. If a single Net::Friend instance is used to report on multiple people/entities the id corresponding to each name should be provided with every report. One can safely ignore id altogether if all reports are about the same people/entity.
Each call to
report
sends an update to the remote friendsd server. This method need only be called when updated data is available. All values are recalled between calls toreport
-- only values which have changed need be reported. query
-
Calls to the
query
method return information about other persons known to the friendsd server. If the server has not been polled for data in over 60 seconds new information will be fetched; otherwise cached values will be used.A single optional parameter limits the returned data to that of a single name. When returning data about a single person a hash is returned whose keys are
name
,lat
,lon
,speed
,dir
with values as explained in the parameters forreport
. Also present is the keytime
indicating the seconds from the UNIX epoch UTC that the data was reported.If no parameter is provided data about all other people known by the friendsd server are returned. The return value is a hash whose keys are the names of each person known to the friendsd server and whose values are hashes with the format described in the previous paragraph.
EXPORT
None by default. Optionally the 'query' and 'report' methods which are both covered in the export group ':all'.
SEE ALSO
gpsdrive
(1) as found at http://www.gpsdrive.de
AUTHOR
Ry4an Brase, <ry4an-cpan@ry4an.org<gt>
COPYRIGHT AND LICENSE
Copyright 2004 by Ry4an Brase
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.