/pps/services/geolocation/control

The Geolocation service listens for commands on this object

Publishers
Geolocation service; any app
Subscribers
Any app
Note: This type of object is known as a server object, a special PPS object designed for point-to-point communication between a server and one or more clients. For details, see "Server objects" in the Persistent Publish/Subscribe Developer's Guide.

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 the following commands:

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

msg::location\nid::test_1\ndat:json:{"period": 2.0, "provider":"network", "fix_type":"wifi"}

where:
  • period—specifies the periodic delay (in seconds) between the update intervals. If period is 0 then the update is provided only once.
  • provider—geolocation source (always network).
  • fix_type—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"). Note also that the Geolocation service is multithreaded, so 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}