# libwsc

**Repository Path**: schemerli/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**: 2
- **Created**: 2026-05-17
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocket Client Library for C

A lightweight WebSocket client library implemented in C, only dependent on OpenSSL library.

## Features

- **Minimal Dependencies**: Only depends on OpenSSL library
- **Full WebSocket Protocol Support**: Implements RFC 6455 specification
- **Secure Connections**: Supports wss:// protocol (encrypted WebSocket connections)
- **Callback-Based API**: Easy to use event-driven interface
- **Text and Binary Messages**: Support for both text and binary message types
- **Error Handling**: Comprehensive error reporting and handling

## Requirements

- **OpenSSL**: Version 1.1.0 or higher
- **C Compiler**: GCC, Clang, or any C99 compliant compiler
- **POSIX Compatibility**: For socket operations (works on Linux, macOS, and Windows with MinGW)

## Installation

### 1. Clone the repository

```bash
git clone <repository_url>
cd libws
```

### 2. Build the library

#### On Linux/macOS

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

#### On Windows (MinGW)

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

### 3. Build the example

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

## Usage

### Basic Example

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

// 回调函数实现
void on_open(ws_client_t *client) {
    printf("WebSocket connected!\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("Received: %s\n", message);
        free(message);
    }
}

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

void on_close(ws_client_t *client, uint16_t code, const char *reason) {
    printf("Closed: %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 Reference

### Core Functions

#### `ws_client_t *ws_client_create(void)`
Creates a new WebSocket client instance.

#### `int ws_client_connect(ws_client_t *client, const char *url, const char *origin)`
Connects to a WebSocket server.
- `url`: WebSocket URL (e.g., "wss://echo.websocket.org")
- `origin`: Optional origin header value

#### `int ws_client_send(ws_client_t *client, ws_opcode_t opcode, const uint8_t *data, size_t len)`
Sends a WebSocket message.
- `opcode`: Message type (WS_OPCODE_TEXT, WS_OPCODE_BINARY, etc.)
- `data`: Message data
- `len`: Data length

#### `int ws_client_send_text(ws_client_t *client, const char *text)`
Sends a text message.

#### `int ws_client_send_binary(ws_client_t *client, const uint8_t *data, size_t len)`
Sends a binary message.

#### `int ws_client_close(ws_client_t *client, uint16_t code, const char *reason)`
Closes the WebSocket connection.

#### `int ws_client_poll(ws_client_t *client, int timeout_ms)`
Processes WebSocket events (should be called in a loop).

#### `ws_state_t ws_client_get_state(ws_client_t *client)`
Gets the current connection state.

#### `const char *ws_client_get_error(ws_client_t *client)`
Gets the last error message.

#### `void ws_client_destroy(ws_client_t *client)`
Destroys the WebSocket client and frees resources.

### Callback Functions

#### `void (*ws_on_open_t)(ws_client_t *client)`
Called when the WebSocket connection is established.

#### `void (*ws_on_message_t)(ws_client_t *client, ws_opcode_t opcode, const uint8_t *data, size_t len)`
Called when a message is received.

#### `void (*ws_on_error_t)(ws_client_t *client, ws_error_t error, const char *message)`
Called when an error occurs.

#### `void (*ws_on_close_t)(ws_client_t *client, uint16_t code, const char *reason)`
Called when the WebSocket connection is closed.

## Connection States

- `WS_STATE_DISCONNECTED`: Not connected
- `WS_STATE_CONNECTING`: Connecting to server
- `WS_STATE_CONNECTED`: Connected and ready
- `WS_STATE_CLOSING`: Closing connection
- `WS_STATE_ERROR`: Error occurred

## Error Codes

- `WS_ERROR_NONE`: No error
- `WS_ERROR_CONNECT`: Connection error
- `WS_ERROR_HANDSHAKE`: Handshake error
- `WS_ERROR_SSL`: SSL error
- `WS_ERROR_SEND`: Send error
- `WS_ERROR_RECEIVE`: Receive error
- `WS_ERROR_FRAME`: Frame error
- `WS_ERROR_MEMORY`: Memory error

## Testing

Run the example program to test the WebSocket client:

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

This will connect to the WebSocket Echo Server, send a test message, and print the response.

## Limitations

- **No Automatic Reconnection**: The library doesn't handle automatic reconnection
- **No Thread Safety**: The library is not thread-safe
- **No Proxy Support**: Doesn't support connections through proxies

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.