SharkSSL™ Embedded SSL/TLS Stack
Minnow Server

Detailed Description

Compact HTTPS and WebSocket Server.

The Minnow Server is a combined HTTPS and WebSocket server. The HTTPS server main focus is on upgrading HTTPS connections to WebSocket connections as specified in RFC 6455.

See the Minnow Server's home page for an introduction to this product.

See also
WebSocket Client Lib

The following example demonstrates initialization of the WssProtocolHandshake structure so the MS_webServer function can operate as an HTTPS server. In addition to operating as a WebSocket server, (se_accept) returns a new client connection, (SOCKET object) and then a (SharkSslCon) object is created prior to the Web Server function (MS_webServer) being called. The (MS_webServer) function returns an error code for anything that is not a WebSocket upgrade, including valid HTTPS GET requests. The error code signals that we should close the connection and wait for a new connection.

ZipFileSystem zfs;
WssProtocolHandshake wph={0};
wph.fetchPage = msInitZipFileSystem(&zfs, getLedZipReader());
wph.fetchPageHndl=&zfs;
while(se_accept(&listenSock, INFINITE_TMO, &sock) == 1)
{
WssReadState wss={0};
SharkSslCon* scon = SharkSsl_createCon(&sharkSsl);
if( ! MS_webServer(scon,&sock,&wph) )
{
// Successful upgrade: WebSocket code here
}
SharkSsl_terminateCon(&sharkSsl, scon);
se_close(&sock);
}

The MS_webServer function returns 0 when we have successfully upgraded the client HTTPS request to a secure WebSocket connection. At this point, you may either serve the WebSocket connection in the current thread/task or create a new thread/task to handle the new WebSocket connection. Creating a new task/thread is required if you require a WebSocket server that can manage more than one connection. Our included WebSocket examples are single threaded, and all new requests will be pending in our examples until the active WebSocket connection terminates.

Modules

 Minnow Server Error Codes
 Error codes returned by functions in the Minnow Server Lib.
 
 Minnow Server Helper Functions
 Minnow Server Helper Functions.
 
 Minnow Server ZIP File System Plugin
 The ZipFileSystem is an optional plugin that requires the Barracuda Web Server ZipFileIterator plugin.
 

Data Structures

struct  WssProtocolHandshake
 The WssProtocolHandshake structure keeps state information for the web server function MS_ebServer. More...
 
struct  WssReadState
 The WS protocol is frame based, and struct WssReadState keeps state information for the Minnow Server's MS_read function. More...
 
struct  MSTBuf
 The Minnow Server Transmission Buffer is used by the Minnow Server Transmission (MST) class when used in non secure mode. More...
 
struct  MST
 The Minnow Server Transmission Class defines a set of functions for reading and writing socket data either in secure mode using SharkSSL or non secure mode. More...
 
struct  MS
 MS: Minnow Server HTTP(S) and (secure) WebSocket Server. More...
 

Macros

#define MS_constructor(o)   memset(o,0,sizeof(MS))
 Minnow Server Constructor. More...
 
#define MS_setSharkCon(o, sharkCon, socket)
 Set the SharkSSL object and the socket connection after socket select accepts and creates a new server socket. More...
 
#define MS_setSocket(o, socket, rec, recSize, send, sendSize)
 Set the socket connection after socket select accepts and creates a new server socket. More...
 
#define MS_sendBin(o, len)   MS_send(o, WSOP_Binary, len)
 Send a WebSocket binary frame using the SharkSSL zero copy API. More...
 
#define MS_sendText(o, len)   MS_send(o, WSOP_Text, len)
 Send a WebSocket text frame using the SharkSSL zero copy API. More...
 
#define MS_writeBin(o, data, len)   MS_write(o,WSOP_Binary,data,len)
 Sends data as WebSocket text frame(s). More...
 
#define MS_writeText(o, data, len)   MS_write(o,WSOP_Text,data,len)
 Send data as WebSocket binary frame(s). More...
 

Typedefs

typedef int(* MSFetchPage) (void *hndl, struct MST *mst, U8 *path)
 A page fetch callback function used by function MS_ebServer is typically installed when the web application is stored on the device. More...
 
typedef struct MST MST
 The Minnow Server Transmission Class defines a set of functions for reading and writing socket data either in secure mode using SharkSSL or non secure mode.
 

Functions

U8 * MST_getSendBufPtr (MST *o)
 Get the send buffer pointer.
 
U16 MST_getSendBufSize (MST *o)
 Get the send buffer size.
 
int MST_read (MST *o, U8 **buf, U32 timeout)
 Write data to a secure layer or non secure (standard socket) layer. More...
 
int MST_write (MST *o, U8 *buf, int len)
 Write data to a secure layer or non secure (standard socket) layer. More...
 
U8 * MS_respCT (MS *o, int *dlen, int contentLen, const U8 *extHeader)
 Format a HTTP 200 OK response with Content Length. More...
 
int MS_webServer (MS *o, WssProtocolHandshake *wph)
 The Web Server function is responsible for parsing incoming HTTP requests and upgrading HTTP requests to WebSocket connections. More...
 
U8 * MS_prepSend (MS *o, int extSize, int *maxSize)
 Prepare sending a WebSocket frame using one of MS_sendBin or MS_sendText. More...
 
int MS_write (MS *o, U8 opCode, const void *data, int len)
 Function used by the two inline functions (macros) MS_writeBin and MS_writeText. More...
 
int MS_close (MS *o, int statusCode)
 Sends a WebSocket close frame command to the peer and close the socket. More...
 
int MS_read (MS *o, U8 **buf, U32 timeout)
 Waits for WebSocket frames sent by the peer side. More...
 

Macro Definition Documentation

◆ MS_constructor

#define MS_constructor (   o)    memset(o,0,sizeof(MS))

Minnow Server Constructor.

Parameters
oMS instance

◆ MS_sendBin

#define MS_sendBin (   o,
  len 
)    MS_send(o, WSOP_Binary, len)

Send a WebSocket binary frame using the SharkSSL zero copy API.

Parameters
oMinnow Server instance.
lenis the length of the buffer you copied into the pointer returned by MS_prepSend.
Returns
The data length 'len' on success or an Error Code on error.
See also
MS_writeBin

◆ MS_sendText

#define MS_sendText (   o,
  len 
)    MS_send(o, WSOP_Text, len)

Send a WebSocket text frame using the SharkSSL zero copy API.

Parameters
oMinnow Server instance.
lenis the length of the buffer you copied into the pointer returned by MS_prepSend.
Returns
The data length 'len' on success or an Error Code on error.
See also
MS_writeText

◆ MS_setSharkCon

#define MS_setSharkCon (   o,
  sharkCon,
  socket 
)
Value:
(o)->mst.u.sc=sharkCon, \
(o)->mst.sock=socket, \
(o)->mst.isSecure=TRUE

Set the SharkSSL object and the socket connection after socket select accepts and creates a new server socket.

The Minnow server instance will operate in secure (SSL) mode when this function is called.

Parameters
othe Minnow Server (MS) instance
sharkConthe object returned by SharkSsl_createCon
socketthe SOCKET instance created after accepting a new client
See also
MS_setSocket

◆ MS_setSocket

#define MS_setSocket (   o,
  socket,
  rec,
  recSize,
  send,
  sendSize 
)
Value:
(o)->mst.sock=socket, \
(o)->mst.b.recBuf=rec, \
(o)->mst.b.recBufSize=recSize, \
(o)->mst.b.sendBuf=send, \
(o)->mst.b.sendBufSize=sendSize, \
(o)->mst.isSecure=FALSE

Set the socket connection after socket select accepts and creates a new server socket.

The Minnow server instance will operate in non secure mode when this function is called.

Parameters
othe Minnow Server (MS) instance
socketthe SOCKET instance created after accepting a new client
reca buffer the Minnow Server instance can use when receiving data
recSizesize of 'rec' buffer
senda buffer the Minnow Server instance can use when writing data
sendSizesize of 'send' buffer
See also
MS_setSharkCon

◆ MS_writeBin

#define MS_writeBin (   o,
  data,
  len 
)    MS_write(o,WSOP_Binary,data,len)

Sends data as WebSocket text frame(s).

The data will be sent as multiple frames if len is longer than the SharkSSL send buffer size.

Parameters
oMinnow Server instance.
datathe data to send.
lendata length.
Returns
Zero on success or an Error Code on error.
See also
MS_sendBin

◆ MS_writeText

#define MS_writeText (   o,
  data,
  len 
)    MS_write(o,WSOP_Text,data,len)

Send data as WebSocket binary frame(s).

The data will be sent as multiple frames if len is longer than the SharkSSL send buffer size.

Parameters
oMinnow Server instance.
datathe data to send.
lendata length.
Returns
Zero on success or an Error Code on error.
See also
MS_sendText

Typedef Documentation

◆ MSFetchPage

typedef int(* MSFetchPage) (void *hndl, struct MST *mst, U8 *path)

A page fetch callback function used by function MS_ebServer is typically installed when the web application is stored on the device.

See also
ZipFileSystem

Function Documentation

◆ MS_close()

int MS_close ( MS o,
int  statusCode 
)

Sends a WebSocket close frame command to the peer and close the socket.

Parameters
oMinnow Server instance.
statusCodeis a WebSocket status code.
Returns
The inverted statusCode on success or an Error Code if sending the close frame command to the peer failed.

◆ MS_prepSend()

U8* MS_prepSend ( MS o,
int  extSize,
int *  maxSize 
)

Prepare sending a WebSocket frame using one of MS_sendBin or MS_sendText.

This function returns a pointer to the SharkSSL send buffer, offset to the start of the WebSocket's payload data. The maximum payload data is returned in 'maxSize'.

Parameters
oMinnow Server instance.
extSizeis a Boolean value that should be set to FALSE if the payload will be less than or equal to 125 bytes. The parameter must be set to TRUE if the payload will be greater than 125 bytes.
maxSizeis an out value set to the SharkSSL buffer size minus the WebSocket frame size.
Returns
The SharkSSL send buffer, offset to the start of the WebSocket's payload data. This function cannot fail.

◆ MS_read()

int MS_read ( MS o,
U8 **  buf,
U32  timeout 
)

Waits for WebSocket frames sent by the peer side.

The function returns when data is available or on timeout. The function returns zero on timeout, but the peer can send zero length frames, so you must verify that it is a timeout by checking the status of WssReadState::isTimeout.

The WebSocket protocol is frame based, but the function can return a fragment before the complete WebSocket frame is received if the frame sent by the peer is larger than the SharkSSL receive buffer. The frame length is returned in WssReadState::frameLen, and the data consumed thus far is returned in WssReadState::bytesRead. The complete frame is consumed when frameLen == bytesRead.

Parameters
oMinnow Server instance.
bufis a pointer set to the SharkSSL receive buffer, offset to the start of the WebSocket payload data.
timeoutin milliseconds. The timeout can be set to INFINITE_TMO.
Returns
The payload data length or zero for zero length frames and timeout. The function returns one of the See Error Codes on error.

◆ MS_respCT()

U8* MS_respCT ( MS o,
int *  dlen,
int  contentLen,
const U8 *  extHeader 
)

Format a HTTP 200 OK response with Content Length.

Parameters
oMinnow Server.
dlendestination buffer length.
contentLenContent Lengt.
extHeaderoptional extra header values.
Returns
The input parameter 'dest' on success or NULL if the destination buffer is not sufficiently large for the response.

◆ MS_webServer()

int MS_webServer ( MS o,
WssProtocolHandshake wph 
)

The Web Server function is responsible for parsing incoming HTTP requests and upgrading HTTP requests to WebSocket connections.

It's main functionality is designed for upgrading an HTTPS request to a WebSocket connection; however, it also includes basic functionality for responding to HTTP static content requests such as fetching HTML files, JavaScript code, etc.

Note: WssProtocolHandshake::fetchPage must have been initialized for the function to respond to HTTP GET requests.

Returns
Zero on successful WebSocket connection upgrade. Returns an error code for all other operations, including fetching static content using the callback MSFetchPage – in this case, MS_ERR_NOT_WEBSOCKET is returned. See Error Codes for more information.

◆ MS_write()

int MS_write ( MS o,
U8  opCode,
const void *  data,
int  len 
)

Function used by the two inline functions (macros) MS_writeBin and MS_writeText.

Parameters
oMinnow Server instance.
opCodethe WebSocket opcode.
datathe data to send.
lendata length.
Returns
zero success or an Error Code on error.
See also
MS_writeText

◆ MST_read()

int MST_read ( MST o,
U8 **  buf,
U32  timeout 
)

Write data to a secure layer or non secure (standard socket) layer.

Parameters
oMST instance
bufcreate a pointer (U8* ptr) and pass in the pointer's address when calling this function. The pointer is set to the receive buffer when the functiion returns.
timeoutin milliseconds

◆ MST_write()

int MST_write ( MST o,
U8 *  buf,
int  len 
)

Write data to a secure layer or non secure (standard socket) layer.

Parameters
oMST instance
bufthe data to send or NULL if data to send was saved to the return value from MST_getSendBufPtr.
len'buf' length