Zen API

- Home
- Topics
- Types
- Files

All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
Public Member Functions
kWebSocket Class Reference
kApi/Io

## Description

Represents a WebSocket.

The kWebSocket class implements support for WebSocket protocol (RFC 6455). This protocol enables client software, typically running in a web browser, to communicate with servers more efficiently than would otherwise be possible over HTTP.

kWebSocket can be used in either a client or a server role. In a server context, a kWebSocket instance can be created from an HTTP request as follows:

kStatus App_HttpRequestHandler(App app, kHttpServer server, kHttpServerChannel channel)
{
kWebSocket webSocket = kNULL;
kStatus status;
if (kHttpServerRequest_IsWebSocketUpgrade(kHttpServerChannel_Request(channel)))
{
kCheck(kHttpServerChannel_ProcessWebSocketRequest(channel, kTRUE, &webSocket));
if (!kIsNull(webSocket))
{
//create a thread to handle the websocket connection
...
}
}
return kOK;
}

The WebSocket protocol is message-based. kWebSocket supports reading/writing complete messages using the kWebSocket_ReadMessage and kWebSocket_WriteMessage methods.

The WebSocket protocol also supports subdividing messages into multiple frames, enabling endpoints to stream messages of unknown length. Accordingly, kWebSocket inherits from the kStream base class and includes special methods that can be used in conjunction with kStream methods to support streaming reads/writes.

//Example: streaming read
kStatus ReadMessage(kWebSocket webSocket)
{
kByte buffer[256];
kSize bytesRead;
//wait for a new message to arrive (1s timeout)
kCheck(kWebSocket_Receive(webSocket, 1000000));
//read out the message; kStream_ReadSome will return kERROR_NOT_FOUND at the end of the message
while (kSuccess(kStream_ReadSome(webSocket, &buffer[0], 1, sizeof(buffer), &bytesRead)))
{
//process content
...
}
return kOK;
}
//Example: object serialization
kStatus WriteObject(kWebSocket webSocket, kObject object)
{
kDat6Serializer writer = kNULL;
kTry
{
//attach serializer to websocket stream
kTest(kDat6Serializer_Construct(&writer, webSocket, kNULL));
//serialize object; will write to websocket, generating frames as needed
kTest(kSerializer_WriteObject(writer, object));
//end the current websocket message (send final frame) and flush
kTest(kWebSocket_Send(webSocket));
}
kFinally
{
kObject_Destroy(writer);
kEndFinally();
}
return kOK;
}
Inheritance diagram for kWebSocket:

## Public Member Functions
kStatus | kWebSocket_Cancel (kWebSocket webSocket)
| Cancels any pending I/O operations. More...
kStatus | kWebSocket_Close (kWebSocket webSocket)
| Closes the WebSocket connection. More...
kStatus | kWebSocket_Connect (kWebSocket webSocket, kIpAddress address, k32u port, const kChar *host, const kChar *uri, k64u timeout)
| Connects a WebSocket to an HTTP server. More...
kStatus | kWebSocket_Construct (kWebSocket *webSocket, kAlloc allocator)
| Constructs a WebSocket that can be used to connect to a server. More...
k64u | kWebSocket_LastPong (kWebSocket webSocket)
| Reports the time at which the most recent pong message arrived. More...
kStatus | kWebSocket_ReadMessage (kWebSocket webSocket, kMemory memory, k64u timeout)
| Blocks until a whole message has been read (or until a timeout occurs). More...
kStatus | kWebSocket_Receive (kWebSocket webSocket, k64u timeout)
| Blocks until a new message is available for reading. More...
kWebSocketDataType | kWebSocket_ReceiveType (kWebSocket webSocket)
| Reports the data type of the most recently received data message. More...
kStatus | kWebSocket_Send (kWebSocket webSocket)
| Sends any buffered data and ends the current message. More...
kStatus | kWebSocket_SendPing (kWebSocket webSocket)
| Sends a ping message. More...
kWebSocketDataType | kWebSocket_SendType (kWebSocket webSocket)
| Reports the message data type currently used for sending. More...
kStatus | kWebSocket_SetReadBuffers (kWebSocket webSocket, kSSize socketSize, kSSize clientSize)
| Sets the size of the read buffers. More...
kStatus | kWebSocket_SetSendType (kWebSocket webSocket, kWebSocketDataType type)
| Sets the data transfer type used for send operations. More...
kStatus | kWebSocket_SetWriteBuffers (kWebSocket webSocket, kSSize socketSize, kSSize clientSize)
| Sets the size of write buffers. More...
kStatus | kWebSocket_WriteMessage (kWebSocket webSocket, const void *buffer, kSize size)
| Writes a complete WebSocket message. More...
Public Member Functions inherited from kStream
k64u | kStream_BytesRead (kStream stream)
| Reports the number of bytes read from this stream. More...
k64u | kStream_BytesWritten (kStream stream)
| Reports the number of bytes written to this stream. More...
kStatus | kStream_ClearStats (kStream stream)
| Clears stream statistics (e.g. More...
kStatus | kStream_Copy (kStream stream, kStream source, kSize size)
| Copies the specified number of bytes from one stream to another. More...
kStatus | kStream_CopyAll (kStream stream, kStream source)
| Copies all bytes from one stream to another. More...
kStatus | kStream_CopyEx (kStream stream, kStream source, kSize size, kCallbackFx progress, kPointer context)
| Copies the specified number of bytes from one stream to another, with progress feedback. More...
kStatus | kStream_Fill (kStream stream)
| Partially fills the read buffer with bytes from the underlying medium. More...
kStatus | kStream_Flush (kStream stream)
| Flushes buffered writes to the underlying medium. More...
kStatus | kStream_Read (kStream stream, void *buffer, kSize size)
| Reads the specified number of bytes from the stream. More...
kStatus | kStream_ReadSome (kStream stream, void *buffer, kSize minCount, kSize maxCount, kSize *bytesRead)
| Reads up to the specified number of bytes from the stream. More...
kStatus | kStream_Seek (kStream stream, k64s offset, kSeekOrigin origin)
| Moves the read/write pointer to the specified location, if supported by the underlying stream. More...
kStatus | kStream_Write (kStream stream, const void *buffer, kSize size)
| Writes the specified number of bytes to the stream. More...
Public Member Functions inherited from kObject
kAlloc | kObject_Alloc (kObject object)
| Gets the memory allocator associated with this object. More...
kStatus | kObject_Clone (kObject *object, kObject source, kAlloc allocator)
| Constructs a new object by copying an existing object, including any aggregated child elements. More...
kStatus | kObject_Destroy (kObject object)
| Destroys the object. More...
kStatus | kObject_Dispose (kObject object)
| Destroys the object and any aggregated child elements. More...
kBool | kObject_Equals (kObject object, kObject other)
| Determines whether the object is equal to another object. More...
kSize | kObject_HashCode (kObject object)
| Gets a hash code representing the state of this object. More...
kBool | kObject_Is (kObject object, kType type)
| Determines whether this object is an instance of the specified type. More...
kBool | kObject_IsShared (kObject object)
| Reports whether the object is currently shared (reference count greater than one). More...
kStatus | kObject_SetPool (kObject object, kObjectPool pool)
| Sets the object pool associated with this object. More...
kStatus | kObject_Share (kObject object)
| Increments the reference count associated with this object. More...
kSize | kObject_Size (kObject object)
| Estimates the memory consumed by this object, including any aggregated child elements. More...
kType | kObject_Type (kObject object)
| Returns the type of the object. More...

## Additional Inherited Members
Protected Member Functions inherited from kStream
kStatus | kStream_Init (kStream stream, kType type, kAlloc allocator)
| Protected method called by derived classes to initialize the kStream base class. More...
kStatus | kStream_VFill (kStream stream)
| Protected virtual method that partially fills the read buffer with bytes from the underlying medium. More...
kStatus | kStream_VFlush (kStream stream)
| Protected virtual method that flushes buffered writes to the underlying medium. More...
kStatus | kStream_VReadSomeImpl (kStream stream, void *buffer, kSize minCount, kSize maxCount, kSize *bytesRead)
| Protected virtual method that deallocates any resources owned by the object. More...
kStatus | kStream_VRelease (kStream stream)
| Protected virtual method that deallocates any resources owned by the object. More...
kStatus | kStream_VSeek (kStream stream, k64s offset, kSeekOrigin origin)
| Protected virtual method that moves the read/write pointer to the specified location. More...
kStatus | kStream_VWriteImpl (kStream stream, const void *buffer, kSize size)
| Protected virtual method that writes the specified number of bytes to the stream. More...
Protected Member Functions inherited from kObject
kStatus | kObject_FreeMem (kObject object, void *mem)
| Protected method called by derived classes to free memory using the object's allocator. More...
kStatus | kObject_FreeMemRef (kObject object, void *mem)
| Protected method called by derived classes to free memory (and reset the provided memory pointer to kNULL) using the object's allocator. More...
kStatus | kObject_GetMem (kObject object, kSize size, void *mem)
| Protected method called by derived classes to allocate memory using the object's allocator. More...
kStatus | kObject_GetMemZero (kObject object, kSize size, void *mem)
| Protected method called by derived classes to allocate and zero memory using the object's allocator. More...
kStatus | kObject_Init (kObject object, kType type, kAlloc alloc)
| Protected method called by derived classes to initialize the kObject base class. More...
kStatus | kObject_VDisposeItems (kObject object)
| Protected virtual method that destroys any aggregated child objects associated with a collection. More...
kBool | kObject_VEquals (kObject object, kObject other)
| Protected virtual method that compares two objects for equality. More...
kSize | kObject_VHashCode (kObject object)
| Protected virtual method that calculates a hash code representing the object instance. More...
kStatus | kObject_VInitClone (kObject object, kObject source, kAlloc allocator)
| Protected virtual method that clones (makes a deep copy of) the specified source object. More...
kStatus | kObject_VRelease (kObject object)
| Protected virtual method that deallocates any resources owned by the object. More...
kSize | kObject_VSize (kObject object)
| Protected virtual method that calculates the total size (in bytes) of the object instance. More...

The documentation for this class was generated from the following file:

- Io/kWebSocket.h