/pps/services/geolocation/control

The Geolocation service listens for commands on this object

Publishers
Geolocation service; any app
Subscribers
Geolocation service; any app
Note: This object is a server object, designed to process requests from individual clients and deliver the results to the clients that issued the requests. For more information, see the "Server objects" subsection.

Message/response format

Commands sent to the /pps/services/geolocation/control object are of the form:

msg::command_string\nid::ID_number\ndat:json:{JSON_data}

Responses always reflect the command_string and ID_number that were sent in the message, along with any errors:

res::command_string\nid::ID_number\ndat::json:{JSON_data}\nerr::error_description

Commands

The control object accepts these commands:

Command Description
location Query the current location based on the IP address. The format for the dat field is as follows:

dat:json:{"period":2.0,"provider":"network","fix_type":"wifi"}

where:
  • period specifies the periodic delay (in seconds) between the update intervals. If this is 0, the update is provided only once.
  • provider names the geolocation source (always network).
  • fix_type names the geolocation fix type (e.g., wifi, but the value isn't significant because this field is for browser compatibility only).
cancel Cancel the currently running periodic request.
Note:

As soon as the Geolocation service receives the location message from the client, it queries http://www.hostip.info to get the current location based on the IP address. The correctness of the result depends on the contents of the database that the hostip.info site provides. The absence of an IP address for the requesting client in the database might yield an arbitrary result (e.g., "wrong location").

Because the Geolocation service is multithreaded, it can handle requests from multiple clients at the same time.

Messages sent by the Geolocation service

Besides returning the client's message and ID, the Geolocation service can also send these responses:

Response Description
accuracy A percentage value representing the accuracy of the location (e.g., 60).
latitude The latitude (e.g., 45.3333).
longitude The longitude (e.g., -75.9).

Examples

  1. If we want to observe responses from the Geolocation service, we need to force the shell to keep the file descriptor open (because this is a server object). We also use the ?wait option to ensure we receive all responses:

    # exec 3<> /pps/services/geolocation/control?wait &&

  2. Now, we'll send the location request:

    echo 'msg::location\nid::test_1\ndat:json:{"period":5.0,"provider":"network","fix_type":"wifi"}' >&3 && cat <&3

The control object might now look like this:

@control
res::location
id::test_1
dat:json:{"accuracy":60,"latitude":45.3333,"longitude":-75.9}