WebSockets in C

WIC is a C99 implementation of rfc6455 websockets designed for embedded applications.

WIC decouples the websocket protocol from the transport layer. This makes it possible to use WIC over any transport layer assuming that you are prepared to do the integration work.

WIC is a work in progress. This means that:

server role is not supported yet
handshake implementation is not very robust
interfaces may change

Features

doesn't call malloc
handshake header fields passed through to application
convenience functions for dissecting URLs
convenience functions for implementing redirection
works with any transport layer you like
automatic payload fragmentation on receive
trivial to integrate with an existing build system

Limitations

interfaces are not thread-safe (provide your own solution)
handshake headers are only accessible at the moment a websocket becomes connected (i.e. wic_get_state() == WIC_STATE_READY)
doesn't support extensions
there are a bewildering number of function pointers

The handshake field limitation is a consequence of storing header fields in the same buffer as used for receiving websocket frames. Applications that require header fields to persist beyond WIC_STATE_READY will need to copy the fields when they are available.

Integrations

mbed wrapper

Compiling

add include to the search path
compile sources in src

There are some macros you can define. These listed at the top of include/wic.h and in the API documentation.

The WIC_PORT_HEADER macro can be used to define a filename which will be included into wic.h. This might be the most convenient place to define/redefine other macros.

Usage

Below is an example of a client that:

connects
sends a "hello world" text
closes normally

#include "wic.h"

int main(int argc, char **argv)
{
    int s;
    static uint8_t rx[1000];
    struct wic_inst inst;
    struct wic_init_arg arg = {0};

    arg.rx = rx; arg.rx_max = sizeof(rx);    

    arg.on_send = on_send_handler;    
    arg.on_open = on_open_handler;        
    arg.on_message = on_message_handler;        
    arg.on_close_transport = on_close_transport_handler;        
    arg.on_buffer = on_buffer_handler;        

    arg.app = &s;
    arg.url = "ws://echo.websocket.org/";
    arg.role = WIC_ROLE_CLIENT;

    if(!wic_init(&inst, &arg)){

        exit(EXIT_FAILURE);
    };

    if(transport_open_client(wic_get_url_schema(&inst),
            wic_get_url_hostname(&inst), wic_get_url_port(&inst), &s)){

        if(wic_start(&inst) == WIC_STATUS_SUCCESS){

            while(transport_recv(s, &inst));
        }
        else{

            transport_close(&s);
        }
    }
    
    exit(EXIT_SUCCESS);
}

static void on_open_handler(struct wic_inst *inst)
{
    const char msg[] = "hello world";

    wic_send_text(inst, true, msg, strlen(msg));    
} 

static void on_close_transport_handler(struct wic_inst *inst)
{
    transport_close((int *)wic_get_app(inst));
}

static void on_send_handler(struct wic_inst *inst, const void *data,
        size_t size, enum wic_frame_type type)
{
    transport_write(*(int *)wic_get_app(inst), data, size);
}

static void *on_buffer_handler(struct wic_inst *inst, size_t min_size,
        enum wic_frame_type type, size_t *max_size)
{
    static uint8_t tx[1000U];

    *max_size = sizeof(tx);

    return (min_size <= sizeof(tx)) ? tx : NULL;
}

static bool on_message_handler(struct wic_inst *inst, enum wic_encoding encoding, bool fin, const char *data, uint16_t size)
{
    if(encoding == WIC_ENCODING_UTF8){

        printf("received text: %.*s\n", size, data);
    }

    wic_close(inst);

    return true;
}

Acknowledgements

WIC integrates code from the following projects:

Joyent/Node-JS http-parser
Bjoern Hoehrmann's UTF8 parser
MBED TLS SHA1 (modified to suit this project)

The Autobahn Test Suite has been used for verification.