# libwsc

**Repository Path**: tinytaro/libwsc

## Basic Information

- **Project Name**: libwsc
- **Description**: C语言实现的WebSocket客户端函数库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# C语言WebSocket客户端库

一个轻量级的C语言实现的WebSocket客户端库，仅依赖于OpenSSL库。

## 特性

- **最小依赖**：仅依赖OpenSSL库
- **完整的WebSocket协议支持**：实现RFC 6455规范
- **安全连接**：支持wss://协议（加密的WebSocket连接）
- **基于回调的API**：易于使用的事件驱动接口
- **文本和二进制消息**：支持文本和二进制消息类型
- **错误处理**：全面的错误报告和处理

## 要求

- **OpenSSL**：版本1.1.0或更高
- **C编译器**：GCC、Clang或任何兼容C99的编译器
- **POSIX兼容性**：用于socket操作（适用于Linux、macOS和带MinGW的Windows）

## 安装

### 1. 克隆仓库

```bash
git clone <仓库地址>
cd libwsc
```

### 2. 构建库

#### 在Linux/macOS上

```bash
gcc -c websocket_client.c -o websocket_client.o -I/path/to/openssl/include
ar rcs libwsc.a websocket_client.o
```

#### 在Windows（MinGW）上

```bash
gcc -c websocket_client.c -o websocket_client.o -I/path/to/openssl/include
ar rcs libwsc.a websocket_client.o
```

### 3. 构建示例

```bash
gcc example.c -o example -L. -lwsc -L/path/to/openssl/lib -lssl -lcrypto -ldl
```

## 使用

### 基本示例

```c
#include "websocket_client.h"
#include <stdio.h>

// 回调函数实现
void on_open(ws_client_t *client) {
    printf("WebSocket连接成功！\n");
    ws_client_send_text(client, "Hello, WebSocket!");
}

void on_message(ws_client_t *client, ws_opcode_t opcode, const uint8_t *data, size_t len) {
    if (opcode == WS_OPCODE_TEXT) {
        char *message = (char *)malloc(len + 1);
        memcpy(message, data, len);
        message[len] = '\0';
        printf("接收到消息: %s\n", message);
        free(message);
    }
}

void on_error(ws_client_t *client, ws_error_t error, const char *message) {
    printf("错误: %s\n", message);
}

void on_close(ws_client_t *client, uint16_t code, const char *reason) {
    printf("连接关闭: %s\n", reason);
}

int main() {
    // 创建客户端
    ws_client_t *client = ws_client_create();
    
    // 设置回调
    ws_client_set_on_open(client, on_open);
    ws_client_set_on_message(client, on_message);
    ws_client_set_on_error(client, on_error);
    ws_client_set_on_close(client, on_close);
    
    // 连接服务器
    ws_client_connect(client, "wss://echo.websocket.org", NULL);
    
    // 事件循环
    while (ws_client_get_state(client) == WS_STATE_CONNECTED) {
        ws_client_poll(client, 1000);
    }
    
    // 清理资源
    ws_client_destroy(client);
    
    return 0;
}
```

## API参考

### 核心函数

#### `ws_client_t *ws_client_create(void)`
创建一个新的WebSocket客户端实例。

#### `int ws_client_connect(ws_client_t *client, const char *url, const char *origin)`
连接到WebSocket服务器。
- `url`：WebSocket URL（例如，"wss://echo.websocket.org"）
- `origin`：可选的origin头值

#### `int ws_client_send(ws_client_t *client, ws_opcode_t opcode, const uint8_t *data, size_t len)`
发送WebSocket消息。
- `opcode`：消息类型（WS_OPCODE_TEXT、WS_OPCODE_BINARY等）
- `data`：消息数据
- `len`：数据长度

#### `int ws_client_send_text(ws_client_t *client, const char *text)`
发送文本消息。

#### `int ws_client_send_binary(ws_client_t *client, const uint8_t *data, size_t len)`
发送二进制消息。

#### `int ws_client_close(ws_client_t *client, uint16_t code, const char *reason)`
关闭WebSocket连接。

#### `int ws_client_poll(ws_client_t *client, int timeout_ms)`
处理WebSocket事件（应在循环中调用）。

#### `ws_state_t ws_client_get_state(ws_client_t *client)`
获取当前连接状态。

#### `const char *ws_client_get_error(ws_client_t *client)`
获取最后一条错误消息。

#### `void ws_client_destroy(ws_client_t *client)`
销毁WebSocket客户端并释放资源。

### 回调函数

#### `void (*ws_on_open_t)(ws_client_t *client)`
当WebSocket连接建立时调用。

#### `void (*ws_on_message_t)(ws_client_t *client, ws_opcode_t opcode, const uint8_t *data, size_t len)`
当收到消息时调用。

#### `void (*ws_on_error_t)(ws_client_t *client, ws_error_t error, const char *message)`
当发生错误时调用。

#### `void (*ws_on_close_t)(ws_client_t *client, uint16_t code, const char *reason)`
当WebSocket连接关闭时调用。

## 连接状态

- `WS_STATE_DISCONNECTED`：未连接
- `WS_STATE_CONNECTING`：正在连接服务器
- `WS_STATE_CONNECTED`：已连接并就绪
- `WS_STATE_CLOSING`：正在关闭连接
- `WS_STATE_ERROR`：发生错误

## 错误代码

- `WS_ERROR_NONE`：无错误
- `WS_ERROR_CONNECT`：连接错误
- `WS_ERROR_HANDSHAKE`：握手错误
- `WS_ERROR_SSL`：SSL错误
- `WS_ERROR_SEND`：发送错误
- `WS_ERROR_RECEIVE`：接收错误
- `WS_ERROR_FRAME`：帧错误
- `WS_ERROR_MEMORY`：内存错误

## 测试

运行示例程序来测试WebSocket客户端：

```bash
./example wss://echo.websocket.org
```

这将连接到WebSocket回显服务器，发送测试消息并打印响应。

## 限制

- **无自动重连**：库不处理自动重连
- **无线程安全**：库不是线程安全的
- **无代理支持**：不支持通过代理连接

## 贡献

欢迎贡献！请随时提交Pull Request。

## 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。