JsVar is a C library for Linux/Unix systems allowing easy creation of
web GUIs with websockets.
JsVar provides compact and lightweight web and websocket servers. When
a browser connects to JsVar a websocket connection is open and can be
used for bidirectional communication between C code running on the
server side and Javascript code running on the client (browser) side.
Data are transmitted to javascript immediately after having been sent
(PUSH method).
JsVar can be used to provide both plain (unencrypted) and SSL
connectivity. It operates on both 'char*' and 'wchar_t*' strings. It
allows to send both binary and text websocket messages. It is written
in a common subsets of C and C++ languages and compiles with both C
and C++ compilers.
JsVar can be useful in education, embedded systems and anywhere where
a web GUI is an appropriate option, especially if server is streaming
live data. JsVar is a single-thread application. It is perfectly
suited for embedded systems and professional use. Originally, it was
developed for a brokerage server streaming prices, I've extracted it
from the production version of that software. In order to use jsVar
one has to be familiar with HTML and Javascript programming language.
Creation of basic web GUIs is pretty simple, here is a full example
from our sample set.
//////////////////////////////////////////////////////////////////////
//
// This program demonstrates howto dynamically update web page from C
// using the function 'jsVarEvalAll'. This function executes a
// javascript code on all connected clients.
//
// The program launches a secure webserver listening on port 4321 and
// dynamically updates current (server) time on all connected
// browsers.
//
// URL: https://localhost:4321
//
#include <time.h>
#include "jsvar.h"
int main() {
time_t lastSentTime;
// Create new web/websocket server showing the following html page
// on each request. Note that "active" pages include the script
// "/jsvarmainjavascript.js"!
jsVarNewSinglePageServer(
4321, BAIO_SSL_YES, 0,
"<html><body><script src='/jsvarmainjavascript.js'></script>"
"Server Time: <span id=mainSpan>nothing here for now</span>"
"</body></html>"
);
lastSentTime = 0;
// The main loop
for(;;) {
if (lastSentTime != time(NULL)) {
// Time changed.
lastSentTime = time(NULL);
// Send eval request to all connected clients. jsVarEvalAll
// has variable number of arguments with the same meaning
// as printf.
jsVarEvalAll("document.getElementById('mainSpan').innerHTML = '%.20s';", ctime(&lastSentTime));
}
// Actually, all previous jsVar actions were buffered. To
// perform real I/O operations one have to call "baioPoll".
// It shall be called as often as possible. It never blocks
// execution on I/O. If there is no I/O to do baioPoll waits
// until timeout, in this case 100000us aka 100ms.
baioPoll(100000);
}
}
//////////////////////////////////////////////////////////////////////
DEPENDENCIES
^^^^^^^^^^^^
If you want to use SSL you will need OpenSSL library. You can install
it with the command:
sudo apt-get install libssl-dev
JsVar uses "sglib.h". The file is included in this package. If you
want to use jsVar in your own directory you will have to copy this
file together with "jsvar.h" and "jsvar.c"
GETTING STARTED
^^^^^^^^^^^^^^^
After having downloaded and unpacked the library goto "examples" and
type:
make e1 run
It will compile and run the example "e1". Once running, open your web
browser and browse to the URL:
https://localhost:4321
Do the same for other examples (e2, e3, etc.) except of "e8" which
demonstrates the use of plain (non SSL) server and you have to connect
to:
http://localhost:4321
DOCUMENTATION
^^^^^^^^^^^^^
For the moment the documentation consists of a set of very simple
commented examples. Examples are short and easy to understand. They
demonstrate the major functions of the library. All examples are
simplified to maximum, there are no bells and whistles, no
overwhelming safety checks. They are meant to demonstrate jsVar
features without having any meaning in their own. If there is an
interest in this library I'll prepare a deeper documentation of all
provided functionalities.
The list of examples:
e1 - The simplest example showing current server time.
e2 - Sending binary data through binary websocket messages
e3 - 'Installing' your custom SSL certificates
e4 - Bidirectional communication between C and Javascript
e5 - Multi-page web server with HTML files.
e6 - Multi-page web server without file system.
e7 - International wide characters wchar_t.
e8 - Plain server not linked with Open-SSL.
e9 - A multiuser web page with "login" and "content" pages showing how
to add custom data to connection structure.