Skip to content

Location Sync Plugin

Version: 1.0

Status: ⚫⚫⚫

LocationSync plugin for Thunder framework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the LocationSync plugin. It includes detailed specification about its configuration, methods and properties as well as sent notifications.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
Thunder Thunder API Reference

Description

The LocationSync plugin provides geo-location functionality.

The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].

Configuration

The table below lists configuration options of the plugin.

Name Type M/O Description
callsign string mandatory Plugin instance name (default: LocationSync)
classname string mandatory Class name: LocationSync
locator string mandatory Library name: libWPELocationSync.so
startmode string mandatory Determines in which state the plugin should be moved to at startup of the framework
configuration object optional ...
configuration?.interval integer optional Maximum time duration between each request to the Location Server (default: 10)
configuration?.retries integer optional Maximum number of request reties to the Location Server (default:20)
configuration?.source string optional URI of the Location Server (default:"http://jsonip.metrological.com/?maf=true")
configuration?.timezone string optional With this the timezone can be overridden, otherwise taken from location (note can als be overriden with JSONRPC call)

Interfaces

This plugin implements the following interfaces:

  • ITimeZone (ITimeZone.h) (version 1.0.0) (compliant format)

    This interface uses legacy lowercase naming convention. With the next major release the naming convention will change to camelCase.

  • ILocationSync (ILocationSync.h) (version 1.0.0) (compliant format)

    This interface uses legacy lowercase naming convention. With the next major release the naming convention will change to camelCase.

Methods

The following methods are provided by the LocationSync plugin:

LocationSync interface methods:

Method Description
sync Synchronize the location

sync method

Synchronize the location.

Parameters

This method takes no parameters.

Result

Name Type M/O Description
result null mandatory Always null

Errors

Message Description
ERROR_GENERAL Failed to synchdonize the location
ERROR_UNAVAILABLE Locator is not available
ERROR_INCORRECT_URL The URL is incorrect
ERROR_INPROGRESS Probing is still in progress

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "LocationSync.1.sync"
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

Properties

The following properties are provided by the LocationSync plugin:

TimeZone interface properties:

Property R/W Description
timezone read/write TimeZone for system

LocationSync interface properties:

Property R/W Description
location read-only Get information about the location

timezone property

Provides access to the timeZone for system.

Value

Name Type M/O Description
(property) string mandatory TimeZone for system

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "LocationSync.1.timezone"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "..."
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "LocationSync.1.timezone",
  "params": "..."
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

location property

Provides access to the get information about the location.

This property is read-only.

Value

Name Type M/O Description
(property) object mandatory Get information about the location
(property)?.city string optional City name
(property)?.country string optional Country name
(property)?.region string optional Region name
(property)?.timezone string optional (deprecated) Time zone information
(property)?.publicip string optional (deprecated) Public IP

Errors

Message Description
ERROR_UNAVAILABLE Either the internet or the location information is not available

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "LocationSync.1.location"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "city": "Wroclaw",
    "country": "Poland",
    "region": "Silesia"
  }
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the LocationSync plugin:

TimeZone interface events:

Notification Description
timezonechanged TimeZone was set for the system

LocationSync interface events:

Notification Description
updated / locationchange Signals a location change

timezonechanged notification

TimeZone was set for the system.

Notification Parameters

Name Type M/O Description
params string mandatory New TimeZone

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "LocationSync.1.register",
  "params": {
    "event": "timezonechanged",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.timezonechanged",
  "params": "..."
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.timezonechanged.

updated notification

Signals a location change.

locationchange is an alternative name for this notification. This name is deprecated and may be removed in the future. It is not recommended for use in new implementations.

Notification Parameters

This notification carries no parameters.

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "LocationSync.1.register",
  "params": {
    "event": "updated",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.updated"
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.updated.