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

o	MS 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

o	Minnow Server instance.
len	is 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

o	Minnow Server instance.
len	is 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

o	the Minnow Server (MS) instance
sharkCon	the object returned by SharkSsl_createCon
socket	the 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

o	the Minnow Server (MS) instance
socket	the SOCKET instance created after accepting a new client
rec	a buffer the Minnow Server instance can use when receiving data
recSize	size of 'rec' buffer
send	a buffer the Minnow Server instance can use when writing data
sendSize	size 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

o	Minnow Server instance.
data	the data to send.
len	data 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

o	Minnow Server instance.
data	the data to send.
len	data 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

o	Minnow Server instance.
statusCode	is 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

o	Minnow Server instance.
extSize	is 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.
maxSize	is 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

o	Minnow Server instance.
buf	is a pointer set to the SharkSSL receive buffer, offset to the start of the WebSocket payload data.
timeout	in 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

o	Minnow Server.
dlen	destination buffer length.
contentLen	Content Lengt.
extHeader	optional 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

o	Minnow Server instance.
opCode	the WebSocket opcode.
data	the data to send.
len	data 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

o	MST instance
buf	create 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.
timeout	in 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

o	MST instance
buf	the data to send or NULL if data to send was saved to the return value from MST_getSendBufPtr.
len	'buf' length

Detailed Description

Modules

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ MS_constructor

◆ MS_sendBin

◆ MS_sendText

◆ MS_setSharkCon

◆ MS_setSocket

◆ MS_writeBin

◆ MS_writeText

Typedef Documentation

◆ MSFetchPage

Function Documentation

◆ MS_close()

◆ MS_prepSend()

◆ MS_read()

◆ MS_respCT()

◆ MS_webServer()

◆ MS_write()

◆ MST_read()

◆ MST_write()