canmove, Confirmed users, Bureaucrats and Sysops emeriti
3,628
edits
Talkilla/SPA API: Difference between revisions
no edit summary
No edit summary |
|||
| (19 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
{{Note|Talkilla has now been superseded by the [[Loop]] project}} | |||
{{Template:Draft}} | {{Template:Draft}} | ||
__TOC__ | __TOC__ | ||
| Line 19: | Line 21: | ||
It is advisable to make the Javascript web worker as lightweight as possible, as this will be continuously running in the background of the browser. | It is advisable to make the Javascript web worker as lightweight as possible, as this will be continuously running in the background of the browser. | ||
==SPA Code Configuration== | |||
An SPA's code should be in one directory, under <code>static/spa/<spa name></code>. The directory structure may be whatever is appropriate. Other Talkilla files may be used, but we do not currently specify an API for these. | |||
Configuration of the SPA is by a single file, <code>static/spa/<spa name>/config.json</code>. The file should contain: | |||
{ | |||
loginURL: "/url/to/login/page.html" | |||
} | |||
The <code>loginURL</code> should point to the URL of the iframe to load for logging into the service provider. Typically this is expected to be hosted on a provider's own site. | |||
As detailed elsewhere, the url of the worker to use for the SPA is detailed in the <code>talkilla.spa-enable</code> message received from the login page and all other SPA loading/controls will come from the worker. | |||
==SPA Installation== | ==SPA Installation== | ||
| Line 67: | Line 83: | ||
These are the possible capabilities an SPA can advertise: | These are the possible capabilities an SPA can advertise: | ||
* | * <code>call</code>: The SPA can make calls | ||
* | * <code>hold</code>: The SPA supports hold and resume for calls | ||
* | * <code>move</code>: The SPA supports call move to other devices | ||
* | * <code>spachannel</code>: The SPA does not support the data channel and routes text messages and file transfers via its server. | ||
* <code>pstn-call</code>: The SPA supports calls to a PSTN network | |||
== Call Handling == | == Call Handling == | ||
| Line 88: | Line 105: | ||
These are the data structures associated with calls | These are the data structures associated with calls | ||
* <code><peer></code> is a string which is the id of the peer that the call is with. | * <code><peer></code> is a string which is the id of the peer that the call is with. e.g. <code>0123456798</code> or <code>foo@example.com</code> | ||
* <code><call id></code> contains the call id for a single call sequence. | * <code><call id></code> contains the integer call id for a single call sequence. | ||
** This is used to ensure that messages from one call with a peer don't affect other calls/actions with the same peer. | ** This is used to ensure that messages from one call with a peer don't affect other calls/actions with the same peer. | ||
** Currently, sending a new call id for a call with a peer does not force a new call to be started. | ** Currently, sending a new call id for a call with a peer does not force a new call to be started. | ||
| Line 160: | Line 177: | ||
{topic: "resume", data: {peer: <peer>, callid: <call id>, media: { | {topic: "resume", data: {peer: <peer>, callid: <call id>, media: { | ||
video: <boolean> } | |||
}} | }} | ||
Note: The media parameter is a temporary option until Firefox supports session re-negotiation. On receiving a resume message, Talkilla will only enable the | Note: The media parameter is a temporary option until Firefox supports session re-negotiation. On receiving a resume message, Talkilla will only enable the video tracks if the video parameter is true. | ||
==== Text Messages ==== | |||
''This part of the API only applies when the SPA advertises "spachannel" in its capabilities'' | |||
===== Sending a text message ===== | |||
This message can be sent either way. | |||
{topic: "message", data: {peer: <peer>, type: "chat:message", message: <string>}} | |||
* Peer is the peer the message is being sent to | |||
* username is the user the peer was from | |||
===== Typing notifications ===== | |||
{topic: "message", data: {peer: <peer>, type: "chat:typing", message: {}} | |||
* Peer is the peer the message is being sent to | |||
* username is the user the peer was from | |||
* message is an empty object, it is not used - this may go away in the future. | |||
==== File Transfer ==== | |||
''This part of the API only applies when the SPA advertises "spachannel" in its capabilities'' | |||
===== Starting a new file ===== | |||
This message can be sent either way. | |||
{topic: "message", data: {peer: <peer>, type: "file:new", | |||
message: {filename: <string>, size: <integer>, id: <integer>, type:<string>}} | |||
* Peer is the peer the message is being sent to | |||
* filename is the filename string | |||
* size is the size of the file | |||
* type is the mime type of the file (if known). | |||
* id is the identifier for this specific file transfer (e.g. will be different for different transfers of the same filename). | |||
==== Sending a | ===== Sending a file chunk ===== | ||
{topic: "message", data: {peer: <peer>, type: "file:chunk", message: {id: <integer>, chunk: <chunk>}} | |||
* Peer is the peer the message is being sent to | |||
* id is the identifier for this specific file transfer | |||
* chunk is the binary string for the file chunk | |||
=== Handling ICE Candidates === | === Handling ICE Candidates === | ||