xt_socket（跨平台 Socket）

跨平台 Socket 抽象层 更多...

宏定义
#define	XT_SOCKET_INVALID   (-1)
#define	XT_SOCKET_ERROR   (-1)
#define	closesocket(s)
#define	XT_SELECT_NFDS(fd)

类型定义
typedef int	xt_socket_t

函数
xt_err_t	xt_socket_setup (void)
	初始化 Socket 平台层
void	xt_socket_cleanup (void)
	反初始化 Socket 平台层
int	xt_socket_errno (void)
	获取最近一次 Socket 操作的错误码
const char *	xt_socket_strerror (int err)
	将 Socket 错误码转为可读字符串
xt_err_t	xt_socket_set_nonblock (xt_socket_t s, int nonblock)
	设置或清除 Socket 非阻塞模式
static int	xt_socket_read (xt_socket_t s, void *buf, size_t len)
	从 Socket 读取数据（POSIX read 的跨平台封装）
static int	xt_socket_write (xt_socket_t s, const void *buf, size_t len)
	向 Socket 写入数据（POSIX write 的跨平台封装）

详细描述

跨平台 Socket 抽象层

宏定义说明

closesocket

#define closesocket

(

s

)

值:

lwip_close(s)

在文件 xt_socket.h 第 195 行定义.

XT_SELECT_NFDS

#define XT_SELECT_NFDS

(

fd

)

值:

((int)(fd) + 1)

在文件 xt_socket.h 第 211 行定义.

XT_SOCKET_ERROR

#define XT_SOCKET_ERROR   (-1)

在文件 xt_socket.h 第 192 行定义.

XT_SOCKET_INVALID

#define XT_SOCKET_INVALID   (-1)

在文件 xt_socket.h 第 191 行定义.

类型定义说明

xt_socket_t

typedef int xt_socket_t

在文件 xt_socket.h 第 190 行定义.

函数说明

xt_socket_cleanup()

void xt_socket_cleanup

(

void

)

反初始化 Socket 平台层

释放 Socket 子系统占用的平台资源。所有 Socket 操作完成后调用， 与 xt_socket_setup() 配对使用。

注解

Windows 平台调用 WSACleanup() 释放 Winsock2 DLL 资源。

Linux 和 lwip 平台为空操作。

调用前应确保所有 Socket 已关闭。

参见

xt_socket_setup

xt_socket_errno()

int xt_socket_errno

(

void

)

获取最近一次 Socket 操作的错误码

当 BSD Socket API（如 socket、bind、connect 等）返回 XT_SOCKET_ERROR 或 其他错误指示时，调用此函数获取具体的错误码。

返回

平台相关的错误码

返回值

>0	错误编号
0	无错误

注解

Linux/lwip 平台返回 errno 的值。

Windows 平台返回 WSAGetLastError() 的值，WSA 错误码不同于 POSIX errno。

应在 Socket API 返回错误后立即调用，否则后续 Socket 调用可能覆盖错误码。

参见

xt_socket_strerror

xt_socket_read()

int xt_socket_read ( xt_socket_t s, void * buf, size_t len )

inlinestatic

从 Socket 读取数据（POSIX read 的跨平台封装）

参数

s	Socket 句柄
buf	接收缓冲区
len	缓冲区大小

返回

>0 实际读取的字节数

0 连接已关闭

<0 错误，调用 xt_socket_errno() 获取错误码

注解

Linux/lwip 使用 read()，Windows 使用 recv()。

在文件 xt_socket.h 第 323 行定义.

xt_socket_set_nonblock()

xt_err_t xt_socket_set_nonblock	(	xt_socket_t	s,
		int	nonblock )

设置或清除 Socket 非阻塞模式

控制指定 Socket 的 I/O 模式为阻塞或非阻塞。非阻塞模式下，send、recv 等操作 立即返回而不等待，通过返回值判断操作完成状态。

参数

s	Socket 句柄
nonblock	非阻塞标志 1: 设为非阻塞模式 0: 设为阻塞模式

返回

XT_EOK 设置成功

XT_ERROR 设置失败

注解

Linux/lwip 平台通过 fcntl(F_SETFL, O_NONBLOCK) 实现，lwip 平台使用 lwip_fcntl()。

Windows 平台通过 ioctlsocket(FIONBIO) 实现，不兼容 fcntl。

非阻塞模式下，connect() 通常返回 -1 并设置错误码为 EINPROGRESS （Windows 为 WSAEWOULDBLOCK），需配合 select() 判断连接是否完成。

参见

xt_socket_errno

select

xt_socket_setup()

xt_err_t xt_socket_setup

(

void

)

初始化 Socket 平台层

在不同平台上执行 Socket 子系统初始化。必须在任何 Socket API 调用之前调用， 且只需调用一次。

返回

XT_EOK 初始化成功

XT_ERROR 初始化失败（仅 Windows 平台可能失败）

注解

Windows 平台调用 WSAStartup(2, 2) 初始化 Winsock2 DLL。

Linux 和 lwip 平台为空操作，始终返回 XT_EOK。

应与 xt_socket_cleanup() 配对使用。

参见

xt_socket_cleanup

examples/network/socket_multi_platform/example_main.c

xt_socket_strerror()

const char * xt_socket_strerror

(

int

err

)

将 Socket 错误码转为可读字符串

将 xt_socket_errno() 返回的错误码转换为人类可读的字符串描述，用于日志输出 和调试。

参数

err	错误码（由 xt_socket_errno() 返回）

返回

指向错误描述字符串的指针

注解

此函数返回的字符串为常量字面量或由标准库管理，可安全使用。

lwip/Linux 上 strerror() 的返回值在线程安全方面的行为取决于 libc 实现。

多次调用会覆盖之前的内容，如需保留请自行拷贝。

Linux/lwip 平台使用 strerror() 转换。

Windows 平台使用内置映射表，只覆盖常见 WSA 错误码，未知错误码返回 "Unknown WSA error"。

参见

xt_socket_errno

xt_socket_write()

int xt_socket_write ( xt_socket_t s, const void * buf, size_t len )

inlinestatic

向 Socket 写入数据（POSIX write 的跨平台封装）

参数

s	Socket 句柄
buf	数据缓冲区
len	写入大小

返回

>0 实际写入的字节数

<0 错误，调用 xt_socket_errno() 获取错误码

注解

Linux/lwip 使用 write()，Windows 使用 send()。

在文件 xt_socket.h 第 347 行定义.