Skip to content

LocationSync API

Version: 1.0.0

Status: ⚫⚪⚪

LocationSync interface for Thunder framework.

(Defined with ILocationSync in ILocationSync.h)

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the LocationSync interface (version 1.0.0). It includes detailed specification about its 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

LocationSync JSON-RPC interface.

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 interface:

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": "<callsign>.1.sync"
}

Response

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

Properties

The following properties are provided by the LocationSync interface:

LocationSync interface properties:

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

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": "<callsign>.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 interface:

LocationSync interface events:

Notification Description
updated / locationchange Signals a location change

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": "<callsign>.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.