Barracuda Application Server C/C++ Reference
 All Classes Functions Variables Typedefs Enumerations Enumerator Groups Pages
WebSockets

The Lua socket library (including WebSockets) provides three modes: blocking, asynchronous, and non blocking (cosockets). More...

Classes

struct  WSSCB
 WebSocket Server Connection Callback Interface: provides an interface between your application and the WebSocket server. More...
 
struct  WSS
 WebSocket Server (WSS) More...
 

Typedefs

typedef void(* WSSCB_Frame )(struct WSSCB *o, struct WSS *wss, void *data, int len, int text)
 WebSocket callback: a WebSocket frame is received. More...
 
typedef void(* WSSCB_Ping )(struct WSSCB *o, struct WSS *wss, void *data, int len)
 Optional webSocket callback: the function is called when the client sends a ping message. More...
 
typedef void(* WSSCB_Close )(struct WSSCB *o, struct WSS *wss, int status)
 WebSocket callback: the client closed the connection or the connection closed unexpectedly. More...
 
typedef struct WSSCB WSSCB
 WebSocket Server Connection Callback Interface: provides an interface between your application and the WebSocket server. More...
 
typedef struct WSS WSS
 WebSocket Server (WSS)
 

Functions

 WSSCB::WSSCB (WSSCB_Frame frameFp, WSSCB_Close closeFp, WSSCB_Ping pingFp=0)
 Provide your callback event functions. More...
 
 WSS::WSS (WSSCB *cb, SoDisp *disp, int startSize, int expandSize)
 Create and initialize a WebSocket Server instance. More...
 
 WSS::~WSS ()
 destructor.
 
int WSS::upgrade (HttpRequest *req)
 Upgrades an HTTP server request to a persistent WebSocket connection. More...
 
int WSS::connect (HttpConnection *con)
 Upgrades (morphs) an HTTP request to a persistent WebSocket connection. More...
 
int WSS::write (const void *data, int len, bool isTxt)
 Write/send a WebSocket frame. More...
 
int WSS::close (int statusCode=1000)
 Gracefully close the WebSocket connection by sending WebSocket status code N to the client prior to closing the active socket connection. More...
 
bool WSS::isValid ()
 Returns true if the WebSocket connection is valid.
 

Detailed Description

The Lua socket library (including WebSockets) provides three modes: blocking, asynchronous, and non blocking (cosockets).

The C WebSocket Server library provides one mode, the asynchronous mode. Asynchronous sockets means that receiving data is event driven and sending data is blocking (socket is in blocking mode). The concept of using asynchronous sockets is the same for Lua and C code thus consult the Lua documentation for an introduction to asynchronous sockets.

The library is limited to sending and receiving data less to or equal 0xFFFF.

Example: see examples/WebSocket-Chat/README.txt

Typedef Documentation

typedef struct WSSCB WSSCB

WebSocket Server Connection Callback Interface: provides an interface between your application and the WebSocket server.

The WebSocket Server connection calls the functions in this interface on "receive" events.

typedef void(* WSSCB_Close)(struct WSSCB *o, struct WSS *wss, int status)

WebSocket callback: the client closed the connection or the connection closed unexpectedly.

Parameters
othe WSSCB interface instance.
wssthe WebSocket server instance.
status.A positive value means that the client sent a graceful close message to the server. The value 1000 and 1001 indicates normal closure. Any other value sent by the client indicates an error condition. See RFC6455:7.4.1 for details. A negative error means the socket connection unexpectedly dropped.
typedef void(* WSSCB_Frame)(struct WSSCB *o, struct WSS *wss, void *data, int len, int text)

WebSocket callback: a WebSocket frame is received.

Parameters
othe WSSCB interface instance.
wssthe WebSocket server instance.
datathe data received. The data is conveniently zero terminated for strings.
lendata length.
texta boolean value set to TRUE for text frames and FALSE for binary frames.
typedef void(* WSSCB_Ping)(struct WSSCB *o, struct WSS *wss, void *data, int len)

Optional webSocket callback: the function is called when the client sends a ping message.

A Pong message is sent automatically.

Parameters
othe WSSCB interface instance.
wssthe WebSocket server instance.
dataa ping message may include payload data.
lendata length.

Function Documentation

int WSS::close ( int  statusCode = 1000)

Gracefully close the WebSocket connection by sending WebSocket status code N to the client prior to closing the active socket connection.

See https://tools.ietf.org/html/rfc6455#section-7.4

int WSS::connect ( HttpConnection con)

Upgrades (morphs) an HTTP request to a persistent WebSocket connection.

You must complete the WebSocket handshake by calling HttpRequest::wsUpgrade prior to calling this method.

Returns
0 on success and a negative value on error.
int WSS::upgrade ( HttpRequest req)

Upgrades an HTTP server request to a persistent WebSocket connection.

This method is typically called from within an HttpPage or HttpDir service function. The function performs a WebSocket handshake by calling HttpRequest::wsUpgrade. The function then calls WSS::connect if the WebSocket handshake was successful.

Parameters
reqmethod HttpRequest::getConnection returns the connection object used as a parameter for this method.
Returns
0 on success and a negative value on error.
int WSS::write ( const void *  data,
int  len,
bool  isTxt 
)

Write/send a WebSocket frame.

Parameters
datathe data to send
lendata length
isTxtset to true for text frames and false for binary frames.
WSS::WSS ( WSSCB cb,
SoDisp disp,
int  startSize,
int  expandSize 
)

Create and initialize a WebSocket Server instance.

Parameters
cbyour callback interface
dispthe server's socket dispatcher
startSizereceived data is buffered internally until a complete WebSocket frame is received. This data is buffered in a DynBuffer. The startSize and expandSize is used by the DynBuffer and enables a frame to dynamically grow from startSize and then at intervals of expandSize.
expandSizesee startSize for information.
WSSCB::WSSCB ( WSSCB_Frame  frameFp,
WSSCB_Close  closeFp,
WSSCB_Ping  pingFp = 0 
)

Provide your callback event functions.

Parameters
frameFpcalled when a complete frame has been received.
closeFpcalled when connection closes.
pingFpcalled when client sends a ping message (optional).