Zen API
 All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
kWebSocket Class Reference

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)
{
{
//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));
}
{
kObject_Destroy(writer);
}
return kOK;
}
Inheritance diagram for kWebSocket:
Inheritance graph

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...
 
kAllocTrait kObject_AllocTraits (kObject object)
 Gets the bitset of allocator traits for any allocators used within this object, including aggregated child elements. More...
 
kStatus kObject_Clone (kObject *object, kObject source, kAlloc objectAllocator)
 Constructs a new object by copying an existing object, including any aggregated child elements. More...
 
kStatus kObject_Clone (kObject *object, kObject source, kAlloc objectAllocator, kAlloc valueAllocator, kObject context=kNULL)
 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...
 
kBool kObject_HasForeignData (kObject object)
 Reports whether the object, including aggregated child elements, contains any foreign memory references. More...
 
kSize kObject_HashCode (kObject object)
 Gets a hash code representing the state of this object. More...
 
kBool kObject_HasShared (kObject object)
 Reports whether an object or any of its aggregated child elements has a reference count greater than one. 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...
 
kAllocTrait kObject_VAllocTraits (kObject object)
 Protected virtual method that gets the bitset of allocator traits for any allocators used within this object, including aggregated child elements. More...
 
kStatus kObject_VClone (kObject object, kObject source, kAlloc valueAllocator, kObject context)
 Protected virtual method that clones (makes a deep copy of) the specified source object. 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...
 
kBool kObject_VHasShared (kObject object)
 Protected virtual method that reports whether an object or any of its aggregated child elements has a reference count greater than one. 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: