xt_socket - 跨平台 Socket 抽象层

版本：0.2 | 日期：2026-06-11 | 路径： components/xt_socket/

---

一、概述

xt_socket 是跨平台 BSD Socket 统一接口。在 Windows（Winsock2）、Linux（POSIX）以及基于 lwip 的嵌入式平台上，让用户使用标准 BSD API 编写网络应用，无需关心平台差异。

标准 BSD 函数名（ socket 、 bind 、 connect 、 send 、 recv 等）在各平台直接可用。本层只处理平台无法统一的少数差异（初始化/清理、socket 类型、错误处理等）。

1.1 平台支持

平台	检测宏	说明
Windows	XT_SDK_PLATFORM_WINDOWS	Winsock2，需 WSAStartup
Linux	XT_SDK_PLATFORM_LINUX	POSIX，原生 BSD API
lwip 嵌入式	默认（else 分支）	lm620_internal、quectel 等

平台检测优先级：Windows > Linux > lwip。

1.2 依赖

无外部依赖。各平台使用各自的 Socket 实现（Winsock2 / POSIX / lwip）。

---

二、核心概念

2.1 统一类型与常量

能力	接口/宏	平台差异
Socket 类型	xt_socket_t	统一 int / SOCKET
无效句柄	XT_SOCKET_INVALID	统一 -1 / INVALID_SOCKET
错误句柄	XT_SOCKET_ERROR	统一 -1 / SOCKET_ERROR
错误码获取	xt_socket_errno	统一 errno / WSAGetLastError
错误描述	xt_socket_strerror	统一 strerror / 内置表
关闭函数	closesocket() 宏	Lin: close
关闭方向常量	SHUT_RD / SHUT_WR / SHUT_RDWR	Win: SD_* 映射
POSIX R/W	xt_socket_read / xt_socket_write	统一 read / recv

2.2 POSIX 读写封装

xt_socket_read 和 xt_socket_write 是 POSIX read/write 的跨平台封装，用于在不支持 read/write 的平台上用 recv/send 替代。

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_socket（跨平台 Socket） 。

3.1 生命周期

函数签名	说明
xt_err_t xt_socket_setup(void)	初始化 Socket 平台层（Windows 调 WSAStartup）
void xt_socket_cleanup(void)	反初始化 Socket 平台层（Windows 调 WSACleanup）

3.2 错误处理

函数签名	说明
int xt_socket_errno(void)	获取最近一次 Socket 操作的错误码
const char *xt_socket_strerror(int err)	将 Socket 错误码转为可读字符串

3.3 I/O 操作

函数签名	说明
xt_err_t xt_socket_set_nonblock(xt_socket_t s, int nonblock)	设置或清除 Socket 非阻塞模式
int xt_socket_read(xt_socket_t s, void *buf, size_t len)	从 Socket 读取数据（POSIX read 封装）
int xt_socket_write(xt_socket_t s, const void *buf, size_t len)	向 Socket 写入数据（POSIX write 封装）

---

四、常见模式

4.1 基本使用流程

#include "xt_socket.h"
 
// 1. 初始化
xt_socket_setup();
 
// 2. 直接使用标准 BSD API
xt_socket_t sock = socket(AF_INET, SOCK_STREAM, 0);
connect(sock, (struct sockaddr *)&addr, sizeof(addr));
send(sock, "hello", 5, 0);
 
// 3. 清理
closesocket(sock);
xt_socket_cleanup();

完整示例见： examples/network/socket_multi_platform/example_main.c

---

五、反模式

反模式	问题	正确做法
忘记调 xt_socket_setup()	Windows 上所有 Socket 操作失败	使用前必须初始化
忘记调 xt_socket_cleanup()	Windows 上资源泄漏	退出时清理
直接用 errno	跨平台不一致	用 xt_socket_errno()