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 to report -- 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 for report. Also present is the key time 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.