-
Notifications
You must be signed in to change notification settings - Fork 26
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(integration): Introduce integration and event sharing with third…
…-party plugins (#303) * Add Interface For Outbound Message * Fix Comment * Add Message Targets * Add Equality Operator * Add More Interfaces * Start Integration Guide * Start Winsock Implementation * Try More Things * Server Works * Get Receive Messages Back, Nice * Fix Styling * Add Inbound Message Processing * Fix Weird Binary File * Fix Compilation * Fixing Tests * Style * Finish Initialisation Manager Test * Tidy Up * Inbound Message Processor Test * All The Tests * Add Initialisation Failure Response * Update Docs * Make The Build Stricter * Use Higher Order Functions * feat(integration): Allow external apps to view handoff frequencies and intention codes (#305) * Implement Intention Code Update Events * Add Handoff Events
- Loading branch information
Showing
91 changed files
with
4,438 additions
and
126 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # Departure Handoff Frequencies | ||
|
|
||
| ## Events | ||
|
|
||
| ### Frequency Updated | ||
|
|
||
| ```JSON | ||
| { | ||
| "type": "departure_frequency_updated", | ||
| "version": 1, | ||
| "data": { | ||
| "callsign": "BAW123", | ||
| "frequency": "129.420", | ||
| } | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # Feature Integrations | ||
|
|
||
| This is the index to all feature integrations provided by the UK Controller Plugin. | ||
|
|
||
| - [Intention Codes](IntentionCode.md) | ||
| - [Departure Handoff Frequencies](DepartureHandoffs.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # Intention Codes | ||
|
|
||
| ## Events | ||
|
|
||
| ### Code Updated | ||
|
|
||
| ```JSON | ||
| { | ||
| "type": "intention_code_updated", | ||
| "version": 1, | ||
| "data": { | ||
| "callsign": "BAW123", | ||
| "exit_point": "REDFA", | ||
| "code": "C2", | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| In the event that an aircraft will not be exiting the FIR, the `exit_point` shall be set as `null`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| # Initialisation | ||
|
|
||
| Once a prospective client has successfully established a connection with the UK Controller Plugin, the next expected | ||
| message will be that of initialisation. A client will not be able to send to or receive from the UK Controller Plugin | ||
| any data until this has been completed. | ||
|
|
||
| ## The initialisation message | ||
|
|
||
| The initialisation message is structured as follows. | ||
|
|
||
| ```JSON | ||
| { | ||
| "type": "initialise", | ||
| "version": 1, | ||
| "data": { | ||
| "integration_name": "string", | ||
| "integration_version": "string", | ||
| "event_subscriptions": [ | ||
| { | ||
| "type": "string", | ||
| "version": "integer" | ||
| }, | ||
| { | ||
| "type": "string", | ||
| "version": "integer" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The integration name and version allows for appropriate logging to take place, in order to help developers on both | ||
| sides to debug any issues. | ||
|
|
||
| The message id is a string that identifies this message to the plugin, which will be used in order to respond. | ||
|
|
||
| ## The initialisation response | ||
|
|
||
| ### Success | ||
|
|
||
| After a successful initialisation, the following response will be returned. | ||
|
|
||
| ```JSON | ||
| { | ||
| "type": "initialisation_success", | ||
| "version": 1, | ||
| "data": { | ||
| "ukcp_version": "string" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Note, that until this response has been sent, the plugin will not action any other messages received from the integration. | ||
|
|
||
| **Any messages received before the initialisation response has been sent will be ignored**. | ||
|
|
||
| ### Failure | ||
|
|
||
| After a failed initialisation, the following response will be returned. | ||
| ```JSON | ||
| { | ||
| "type": "initialisation_failure", | ||
| "version": 1, | ||
| "errors": [ | ||
| "string" | ||
| ] | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # Integration Guide | ||
|
|
||
| The UK Controller Plugin provides a means of sharing its functionality with other software used by controllers on | ||
| VATSIM. This is achieved via a means to connect to the plugin and a JSON message passing protocol, allowing the plugin | ||
| to notify listeners of pertinent events or perform actions on their behalf. | ||
|
|
||
| ## Contents | ||
|
|
||
| - [Overview](Overview/Overview.md) | ||
| - [Initialisation](Initialisation/Initialisation.md) | ||
| - [Standard Message Responses](Responses/StandardResponses.md) | ||
| - [Feature Messages Index](Features/Index.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| # Overview | ||
|
|
||
| The integration protocol consists of JSON messages, passed back and forth over communication channels. | ||
|
|
||
| ## Message Format | ||
|
|
||
| All messages follow the same basic JSON format, containing a message type and a version. Some messages will also require | ||
| a unique message identifier, which will allow for a response to be returned. | ||
|
|
||
| This is the basic format of a message: | ||
|
|
||
| ```JSON | ||
| { | ||
| "type": "event_type", | ||
| "version": 1, | ||
| "data": { | ||
| "some_field": "some_value" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Communication Channels | ||
|
|
||
| There is currently one communication channel available for integration. | ||
|
|
||
| ### Windows Sockets | ||
|
|
||
| The UK Controller Plugin listens for connecting integrations via **TCP port 52814** using Windows Sockets. Once a client | ||
| has connected, the plugin expects to receive an initialisation message (covered later in this guide) which lets it | ||
| know what events the integration wishes to receive. | ||
|
|
||
| As TCP can break up any messages into arbitrary sized chunks for the purpose of transmission, it is necessary for each | ||
| message to be delimited with a special character so that the boundaries of each message can be determined. | ||
|
|
||
| As control characters are not valid in well-formed JSON, the Unit Separator character `\0x1F` is used to delimited | ||
| individual JSON messages. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # Standard Message Responses | ||
|
|
||
| This section provides details of generic responses to messages provided by the UK Controller Plugin. | ||
|
|
||
| ## Success | ||
|
|
||
| This response will be sent following a successful action performed as a result of a message from the client. | ||
|
|
||
| ```JSON | ||
| { | ||
| "type": "action_success", | ||
| "version": 1, | ||
| } | ||
| ``` | ||
|
|
||
| ## Failure | ||
|
|
||
| This response will be sent if the plugin fails to perform an action following a message from the client. | ||
|
|
||
| ```JSON | ||
| { | ||
| "type": "action_failure", | ||
| "version": 1, | ||
| "errors": [ | ||
| "string", | ||
| "string" | ||
| ] | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.