WebSocket4D

仓库档案

创建时间：2026-10-20T00:36:13Z · 开始观察：2026-10-20T12:23:23.191Z

项目文档

<div align="center">
  <img src="Images/WebSocket4D-Banner.png" alt="WebSocket4D — Windows WebSocket library for Delphi and FreePascal" width="100%" />
</div>

# WebSocket4D

**A Windows WebSocket client and server library for Delphi and FreePascal.**

WebSocket4D provides a Pascal-oriented API for building real-time applications over WebSocket connections. It is designed for Windows and uses Windows WebSocket/HTTP facilities rather than requiring a separate cross-platform networking stack.

- **Created by:** Shaahin Ashayeri
- **Platform:** Windows 8 or later
- **Languages:** Delphi and FreePascal (FPC)
- **License:** MIT

> **Project status:** This repository contains implementation code and examples, but the current source package has not been verified here with a Delphi or FreePascal compiler. Please compile and test with your target compiler/version before using it in production.

## Features

- WebSocket client and server APIs in Pascal.
- Text and binary message support.
- Event-based notifications for connection, disconnection, incoming messages, and errors where exposed by the relevant class.
- Background/asynchronous receiving through `StartReceiving`.
- Configurable automatic reconnection options on the client.
- Receive-timeout configuration (in seconds) where supported by the client implementation.
- TLS/WSS example and server-side TLS configuration using certificate and private-key PEM files.
- Example projects demonstrating different library capabilities.

The exact available methods and events depend on the public declarations in `WebSocket4D.pas`. Consult the source and the example that matches your use case.

## Requirements

- Windows 8 or later.
- A compatible Delphi version or FreePascal compiler for Windows.
- For TLS examples, OpenSSL command-line tools to create a local test certificate and the Windows certificate store to trust that certificate for the WinHTTP-based client.
- Firewall permissions for the selected server port when connecting from another machine.

## Repository layout

```text
WebSocket4D/
├── README.md
├── Source/
│   ├── WebSocket4D.pas              # Main implementation unit
├── Images/
│   └── WebSocket4D-Banner.png
└── Examples/                        # Sample projects for exploring the library
```

## Getting started

1. Clone or download this repository.
2. Open an example project in the IDE appropriate to your compiler, or create a new Windows console project.
3. Add the folder containing `WebSocket4D.pas` to the project search path, or include the unit directly as shown by the example's `uses` clause.
4. Compile for Windows.
5. Start the server example first, then run the client and connect to the server URL/port shown by the example.

### Minimal client pattern

The following illustrates the general sequence; adapt event signatures and error handling to the exact unit version in your checkout:

```pascal
var
  Client: TWebSocket4DClient;
begin
  Client := TWebSocket4DClient.Create;
  try
    Client.Connect('ws://127.0.0.1:8080/');
    Client.StartReceiving;
    Client.SendText('Hello from WebSocket4D');
    Readln;
    Client.Close;
  finally
    Client.Free;
  end;
end.
```

For a long-running application, assign the relevant events before connecting and ensure the client/server is stopped before freeing it. Do not block a GUI thread with `Readln`; it is used only in console examples.

## Examples

Several example projects are included in the repository to help you explore the library's capabilities and understand how to use its API in practice. Review the examples that best match your needs and adapt them to your application.

If you have any questions or need help using WebSocket4D, please open an issue in the GitHub repository. I will be happy to guide you.

## TLS / WSS

`ws://` is an unencrypted WebSocket connection; `wss://` is WebSocket over TLS. The TLS server example uses `ConfigureTLS(CertFile, KeyFile)` with a PEM certificate and its matching private key. The client relies on Windows trust validation, so a locally self-signed certificate must be explicitly trusted for local testing and must include the correct Subject Alternative Name (SAN) for the hostname/IP used in the URL.

For certificate generation, Windows certificate-store setup, and troubleshooting, consult the README provided alongside the TLS example.

**Security warning:** the included certificate-generation script creates a self-signed certificate for local development only. Do not use its private key or certificate in production. For production, use a certificate issued by a trusted CA, protect the private key with appropriate filesystem permissions, renew certificates before expiry, and use the actual DNS name in the URL.

## Troubleshooting

- **Connection refused / timeout:** make sure the server is running, the URL and port match, and Windows Firewall permits the connection.
- **TLS certificate error:** ensure the certificate is trusted in the correct Windows certificate store and that its SAN matches `localhost` or the IP/DNS name in the URL. Restart the client after importing the certificate.
- **Client connects but no events arrive:** start receiving with `StartReceiving`, assign callbacks before connecting, and check whether the server sends messages.
- **Send fails after disconnect:** check connection state and error callbacks; if using auto-reconnect, only send after a successful connection event.
- **Compiler cannot find the unit:** add the correct source directory to the project search path and verify that the project is compiling the intended copy of `WebSocket4D.pas`.

## Threading and lifecycle notes

- Treat callbacks as potentially occurring on a worker/background thread unless the implementation explicitly documents otherwise. Synchronize access to UI controls and shared application state.
- Avoid freeing the client or server from inside a callback unless the implementation explicitly supports that lifecycle.
- Stop receiving/server activity and close connections before destroying objects.
- Automatic reconnection does not guarantee that an application-level operation is safe to repeat. Design message handling to tolerate reconnects and duplicate requests.

## Contributing and issues

Bug reports should include Windows version, Delphi/FPC version, the exact example used, reproduction steps, and the full compiler/runtime error. Please avoid including production private keys, credentials, or sensitive payloads in issue reports.

## Support WebSocket4D

If you find WebSocket4D useful, please consider supporting its continued development with a voluntary cryptocurrency donation.

Your support helps me maintain the library, improve its documentation and examples, fix bugs, and develop new features.

**BNB Donations**

Network: **BNB Smart Chain (BEP-20)**

Wallet address: `0xcB3324b1154CCdB9C497BbfeDd277Ed93407E519`

![BNB Donation QR Code](Images/BNB-Donation-QR.png)

Scan the QR code with your wallet app to donate.

Donations are entirely optional. WebSocket4D remains free and open-source.

Thank you for supporting WebSocket4D!

*Created by Shaahin Ashayeri*

---

**WebSocket4D** · Delphi + FreePascal · Windows ·