WebSocket Class Library Documentation

🚀 WebSocket Class Library - A VB6 WebSocket implementation based on cWinsock wrapper, developed by woeoio@qq.com with claude ai based on VbAsyncSocket

📖 Table of Contents

• Overview
• Key Highlights
• Architecture Design
• Documentation Index

---

Overview

The WebSocket Class Library is a lightweight WebSocket communication library designed for VB6, fully compliant with RFC 6455. It is built on the cWinsock class, providing a simple, easy-to-use API and comprehensive feature support.

✨ Key Features

• 🔌 Pure Class Implementation - No controls needed, direct object programming
• 📦 Separated Design - Client and server as independent class libraries with clear responsibilities
• 🎯 Complete Protocol Support - Supports WebSocket text, binary, Ping/Pong, Close frame types
• 🌐 Efficient Buffering - Pre-allocated byte buffers to minimize memory allocation operations
• 🛡️ Automatic Handshake - Client and server automatically handle WebSocket handshake
• 🔄 Message Fragmentation - Supports fragmented transmission of large messages with automatic reassembly
• 📡 Broadcasting - Server supports broadcasting messages to all clients
• 🚀 Automatic Ping/Pong - Supports automatic heartbeat keepalive

---

Key Highlights

1️⃣ Clear Responsibility Separation 🎯

The library uses a modular design where each class handles a single responsibility:

' cWebSocketServer - Server management
Set m_Server = New cWebSocketServer
m_Server.Listen 8080

' cWebSocketClient - Client connection
Set m_Client = New cWebSocketClient
m_Client.Connect "ws://127.0.0.1:8080"

' cWebSocketFrame - Frame parsing and building (internal use)
' cByteBuffer - Efficient byte buffer (internal use)
' mWebSocketUtils - Common utility functions

---

2️⃣ Efficient Buffer Management 📊

The cByteBuffer class uses a pre-allocation strategy with on-demand growth to minimize ReDim Preserve operations:

' Pre-allocate 4KB, grow by 1.5x
Private Const INITIAL_CAPACITY As Long = 4096
Private Const GROWTH_FACTOR As Double = 1.5

---

3️⃣ Read-Only Frame Parsing 🔍

cWebSocketFrame.ParseHeader() does not modify input data, avoiding buffer confusion:

' 1. Parse header (read-only)
If oFrame.ParseHeader(RecvBuffer) Then
    ' 2. Check completeness
    If oFrame.IsCompleteFrame(RecvBuffer) Then
        ' 3. Extract and unmask (consume frame)
        baPayload = oFrame.ExtractPayload(RecvBuffer)
    End If
End If

---

4️⃣ Automatic Handshake Handling 🤝

Client Handshake

m_Client.Connect "ws://example.com:8080/chat"
' Automatically generates WebSocket Key
' Automatically sends handshake request
' Automatically verifies server response

Server Handshake

m_Server.Listen 8080
' Automatically detects HTTP Upgrade request
' Automatically calculates Accept Key
' Automatically sends 101 Switching Protocols response

---

5️⃣ Message Fragmentation Support 📦

Large messages are automatically fragmented during transmission, with automatic reassembly at the receiving end:

' Send large message (auto-fragmented)
m_Client.SendText LargeString

' Receiver automatically reassembles complete message
Private Sub m_Client_OnTextMessage(ByVal Message As String)
    ' Message is already the complete reassembled message
    ProcessMessage Message
End Sub

---

6️⃣ Server Broadcasting Feature 📢

' Broadcast to all clients
m_Server.BroadcastText "Hello everyone!"

' Broadcast excluding sender
m_Server.BroadcastText Message, ExcludeClientID

' Send to specific client
m_Server.SendText ClientID, "Private message"

' Broadcast binary data to all clients
m_Server.BroadcastBinary baData

---

7️⃣ Event-Driven Model ⚡

' Client events
Event OnOpen()
Event OnClose(ByVal Code As WsCloseCode, ByVal Reason As String)
Event OnTextMessage(ByVal Message As String)
Event OnBinaryMessage(Data() As Byte)
Event OnError(ByVal Description As String)
Event OnPong(Data() As Byte)

' Server events
Event OnStart(ByVal Port As Long)
Event OnStop()
Event OnClientConnect(ByVal ClientID As String, ByVal RemoteAddress As String, ByVal RemotePort As Long)
Event OnClientDisconnect(ByVal ClientID As String, ByVal Reason As String)
Event OnClientTextMessage(ByVal ClientID As String, ByVal Message As String)
Event OnClientBinaryMessage(ByVal ClientID As String, Data() As Byte)
Event OnError(ByVal Description As String)

---

Architecture Design

Class Hierarchy

WebSocket Class Library
├── cWebSocketServer (Server)
│   ├── m_ListenSocket: cWinsock (Listening Socket)
│   ├── m_Clients: Collection (Client collection)
│   └── m_FrameBuilder: cWebSocketFrame (Frame builder)
│
├── cWebSocketClient (Client)
│   ├── m_Socket: cWinsock (Connection Socket)
│   ├── m_RecvBuffer: cByteBuffer (Receive buffer)
│   └── m_FrameParser: cWebSocketFrame (Frame parser)
│
├── cWebSocketServerClient (Server Client)
│   ├── m_Socket: cWinsock
│   ├── m_RecvBuffer: cByteBuffer
│   └── m_FrameParser: cWebSocketFrame
│
├── cWebSocketFrame (Frame Parsing/Building)
│   └── Frame header parsing, unmasking, frame building
│
├── cByteBuffer (Byte Buffer)
│   └── Pre-allocation, auto-growth, Peek/Consume
│
└── mWebSocketUtils (Utility Module)
    ├── UTF-8 encoding/decoding
    ├── Base64 encoding
    ├── SHA1 hashing
    └── WebSocket Key generation/verification

Object Relationship Diagram

Server Object (cWebSocketServer)
├── Socket (Listening socket: cWinsock)
├── Clients Collection
│   ├── Client 1 (cWebSocketServerClient)
│   │   ├── Socket (Independent connection: cWinsock)
│   │   ├── RecvBuffer (cByteBuffer)
│   │   └── FrameParser (cWebSocketFrame)
│   ├── Client 2 (cWebSocketServerClient)
│   │   ├── Socket (Independent connection: cWinsock)
│   │   ├── RecvBuffer (cByteBuffer)
│   │   └── FrameParser (cWebSocketFrame)
│   └── ...
└── FrameBuilder (Shared frame builder: cWebSocketFrame)
    └── Used for building frames during broadcast (build once, send to multiple clients)

Connection Flow

Client Connection Flow

1. Connect(ws://host:port)
2. Parse URL (host, port, path)
3. Generate WebSocket Key
4. cWinsock.Connect()
5. TCP connection successful
6. Send handshake request (HTTP Upgrade)
7. Wait for 101 response
8. Verify Accept Key
9. Trigger OnOpen event
10. Start sending/receiving messages

Server Listening Flow

1. Listen(port)
2. cWinsock.Listen()
3. Wait for connection request
4. Accept connection, create cWebSocketServerClient
5. Wait for handshake request
6. Verify WebSocket Key
7. Calculate Accept Key
8. Send 101 response
9. Trigger OnClientConnect event
10. Start sending/receiving messages

---

Documentation Index

Document	Description
Library Overview	Overall introduction to the WebSocket library and design philosophy
Client Class	Detailed documentation of the cWebSocketClient class
Server Class	Detailed documentation of the cWebSocketServer class
Frame Parsing Class	Detailed documentation of the cWebSocketFrame class
Byte Buffer Class	Detailed documentation of the cByteBuffer class
Utility Module	Detailed documentation of the mWebSocketUtils module
Quick Start	Quick start examples
Advanced Usage	Advanced features and best practices

---

Dependencies

Component	Description
cWinsock.cls	Low-level Socket wrapper located in add/ directory, providing TCP connection functionality
cAsyncSocket.cls	Async Socket implementation located in src/ directory, the foundation of cWinsock
mWebSocketUtils.bas	WebSocket utility module
cByteBuffer.cls	Byte buffer class
cWebSocketFrame.cls	WebSocket frame parsing and building class
cWebSocketClient.cls	WebSocket client class
cWebSocketServer.cls	WebSocket server class
cWebSocketServerClient.cls	Server client connection class

---

Compatibility

• VB6/VBA - Fully compatible
• Windows - Windows XP and later
• WebSocket Protocol - RFC 6455 (fully compatible)
• SSL/TLS - Not supported yet (wss:// requires additional implementation)

---

License

Based on VbAsyncSocket (wqweto@gmail.com)

---

Authors

WebSocket Class Library: woeoio@qq.com
Base Socket Library: woeoio@qq.com
Original Socket Library: wqweto@gmail.com

---

Last Updated: 2026-01-10