|
SilverQube API: JavaScript
|
|
Overview
|
|
The SilverQube API is used by clients and servers to connect and share data.
|
|
Clients and servers may be mobile apps (native or hybrid), HTML5 web apps (mobile or non-mobile), or any other program that has access to a WiFi connection. In general, this means any system attached to WiFi, including servers, desktops, laptops, netbooks, sensor devices, and so on.
|
The SilverQube JavaScript API binding is a library of functions for establishing and managing a set of server and client connections
using the native SilverQube API, and operates roughly as follows:
- A server connects to SilverQube, and then awaits client connections
- The server is notified each time a client connects
- Once a client has connected, the server and client may exchange data
- Clients may connect and disconnect at any time
- A server may also disconnect a client (or itself) at any time
|
|
SilverQube independently supports WebSockets and HTTP for both servers and clients, as described below. The API specifies a set of function calls and notification callbacks for each type of caller and network communication method.
|
|
The API is asynchronous, and supports cross-domain access (CORS).
|
| |
| |
| WebSocket API: Server
|
Synopsis:
var ws = new WebSocketServer(String address, String authentication_key);
ws.onready = function(Object obj) { ...server is connected... };
ws.onconnect = function(Object obj} { ...client is connected... };
ws.onmessage = function(Object obj) { ...client message received... };
ws.onclose = function(Object obj) { ...client has closed... };
ws.onerror = function(Object obj) { ...error... };
ws.connect();
ws.send(String session, String data);
ws.close(String session);
ws.disconnect();
|
| |
| Functions
|
new WebSocketServer(String address, String authentication_key)
Create a new server connection.
Parameters:
address - specifies the server url and WebSocket service endpoint ('server') e.g. http://IP:PORT/server
authentication_key - server authentication key; may be randomly generated or set using SilverQube UI.
|
| |
connect()
Establish server connection using WebSocket.
No parameters.
When the connection is established, the 'onready' callback will occur.
|
| |
send(String session, String data)
Send message data to client.
Parameters:
session - client session identifier
data - message data
|
| |
close(String session)
Close client connection.
Parameters:
session - client session identifier
|
| |
disconnect()
Close connection.
Parameters:
none
|
| |
| Callbacks
|
onready(Object obj)
obj callback parameter properties:
'session' - server session identifier
|
| |
onconnect(Object obj)
obj callback parameter properties:
'ip' - client IP address
'session' - client session identifier
|
| |
onmessage(Object obj)
obj callback parameter properties:
'ip' - client IP address
'session' - client session identifier
'data' - message data
|
| |
onclose(Object obj)
obj callback parameter properties:
'ip' - client IP address
'session' - client session identifier
|
| |
onerror(Object obj)
obj callback parameter properties:
'code' - client error code, see WebSocket error codes
'reason' - client error reason
|
| |
| |
| WebSocket API: Client
|
Synopsis:
var ws = new WebSocketClient(String address);
ws.onready = function(Object obj) { ...client is connected... };
ws.onmessage = function(Object obj) { ...server message received... };
ws.onerror = function(Object obj) { ...error... };
ws.connect();
ws.send(String data);
ws.disconnect();
|
| |
| Functions
|
new WebSocketClient(String address)
Create a new client connection.
Parameters:
address - specifies the client url and WebSocket service endpoint ('client') e.g. http://IP:PORT/client
|
| |
connect()
Establish client connection using WebSocket.
No parameters.
When the connection is established, the 'onready' callback will occur.
|
| |
send(data)
Send message data to server.
Parameters:
data - message data
|
| |
disconnect()
Close connection.
Parameters:
none
|
| |
| Callbacks
|
onready(Object obj)
obj callback parameter properties:
'session' - client session identifier
|
| |
onmessage(data)
data - message data
|
| |
onerror(Object obj)
obj callback parameter properties:
'code' - client error code (a number), see WebSocket error codes
'reason' - client error reason
|
| |
| WebSocket Error Codes
|
1000 - normal connection close (not an error)
1001 - endpoint is "going away"
1002 - endpoint terminating connection (protocol error)
1003 - endpoint terminating connection (data type error)
1005 - no code (WebSocket library return code)
1007 - endpoint terminating connection (data type inconsistent)
1008 - server is not connected (for clients), authentication error (for servers)
1009 - endpoint terminating connection (data too large)
For more information, see Status Codes in the WebSocket Protocol
|
| |
| |
| HTTP API: Server
|
Synopsis:
var http = new AJAXServer(String address, String authentication_key);
http.onready = function(Object obj) { ...server is connected... };
http.onconnect = function(Object obj} { ...client is connected... };
http.onmessage = function(Object obj) { ...client message received... };
http.onclose = function(Object obj) { ...client has closed... };
http.ondisconnect = function(Object obj) { ...server has disconnected... };
http.onerror = function(Object obj) { ...error... };
http.connect();
http.send(String session, String data);
http.close(String session);
http.disconnect();
|
| |
| Functions
|
new AJAXServer(String address, String authentication_key)
Create a new server connection.
Parameters:
address - specifies the server url and WebSocket service endpoint ('server.http') e.g. http://IP:PORT/server.http
authentication_key - server authentication key. May be randomly generated or set using SilverQube UI.
|
| |
connect()
Establish server connection using HTTP.
No parameters.
When the connection is established, the 'onready' callback will occur.
|
| |
send(session, data)
Send message data to client.
Parameters:
session - client session identifier
data - message data
|
| |
close(String session)
Close client connection.
Parameters:
session - client session identifier
|
| |
disconnect()
Disconnect server connection.
No parameters.
|
| |
| Callbacks
|
onready(Object obj)
obj callback parameter properties:
'session' - server session identifier
|
| |
onconnect(Object obj)
obj callback parameter properties:
'ip' - client IP address
'session' - client session identifier
|
| |
onmessage(Object obj)
obj callback parameter properties:
'ip' - client IP address
'session' - client session identifier
'data' - message data
|
| |
onclose(Object obj)
obj callback parameter properties:
'ip' - client IP address
'session' - client session identifier
|
| |
onerror(Object obj)
obj callback parameter properties:
'code' - client error code (a number), see HTTP error codes
'reason' - client error reason
|
| |
| |
| HTTP API: Client
|
Synopsis:
var http = new AJAXClient(String address, String session);
http.onready = function(Object obj) { ...server is connected... };
http.onmessage = function(Object obj) { ...client message received... };
http.onclose = function(Object obj) { ...client has closed... };
http.ondisconnect = function(Object obj) { ...server disconnected... };
http.onerror = function(Object obj) { ...error... };
http.connect();
http.send(String data);
http.close();
|
|
|
| Functions
|
new AJAXClient(address, session)
Create a new client connection.
Parameters:
address - specifies the client url and WebSocket service endpoint ('client.http') e.g. http://IP:PORT/client.http
session - client session identifier (optional)
|
| |
connect()
Establish client connection using WebSocket.
No parameters.
When the connection is established, the 'onready' callback will occur.
|
| |
send(data)
Send message data to server.
Parameters:
data - message data
|
| |
close()
Close client connection.
No parameters.
|
| |
| Callbacks
|
onready(Object obj)
obj callback parameter properties:
'session' - client session identifier
|
| |
onmessage(data)
data - message data
|
| |
onclose()
|
| |
onerror(Object obj)
obj callback parameter properties:
'code' - client error code (a number), eee HTTP error codes
'reason' - client error reason
|
| |
| |
| |
| HTTP Error Codes
|
400 - request invalid (JSON error, missing parameter)
401 - session invalid
409 - request has not yet been fulfilled
503 - no server listening
|