GVSDS/TransPyC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrote the comments in the libraries under 'includes' in English (excluding those inside folders)

Browse Source
This commit is contained in:
TermiNexus
2026-07-29 23:34:36 +08:00
parent 3633be1995
commit a2cc28a6ab
54 changed files with 7091 additions and 899 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
includes/socket.py
View File

@@ -7,17 +7,17 @@ import w32.winsock2
# ============================================================
# socket.py — 跨平台 Socket 封装
# Python 风格 OOP API + 兼容旧版过程式函数
# socket.py — Cross-platform wrapper for Socket
# Python-style OOP API + Compatibility with legacy procedural functions
#
# 用法示例:
# Example:
# sock = socket.Socket(socket.AF_INET, socket.SOCK_STREAM)
# sock.connect("example.com", 80)
# sock.send(data, length)
# n = sock.recv(buf, bufsize)
# sock.close()
#
# 仅 3 处平台差异（通过 platmacro.IS_WINDOWS 分支）:
# Only 3 platform differences (via platmacro.IS_WINDOWS branch):
# 1. WSAStartup() / WSACleanup()
# 2. closesocket() vs close()
# 3. WSAGetLastError() vs errno
@@ -25,7 +25,7 @@ import w32.winsock2
# ============================================================
# 常量
# Constants
# ============================================================
AF_INET: t.CDefine = 2
AF_INET6: t.CDefine = 10
@@ -51,11 +51,11 @@ SOCKET_DEFAULT_TIMEOUT: t.CDefine = 0
# ============================================================
# 结构体
# Structures
# ============================================================
class SocketAddr:
"""sockaddr_in — IPv4 地址（16 字节，POSIX 布局）"""
"""sockaddr_in — IPv4 address (16 bytes layout)"""
family: u16
port: u16
addr: u32
@@ -63,7 +63,7 @@ class SocketAddr:
class HostEnt:
"""struct hostent — DNS 解析结果"""
"""struct hostent — DNS resolution result"""
h_name: CHARPTR
h_aliases: CHARPTR
h_addrtype: INT
@@ -72,14 +72,14 @@ class HostEnt:
class timeval:
"""struct timeval — 超时设置"""
"""struct timeval — Timeout setting"""
tv_sec: INT
tv_usec: INT
# ============================================================
# 外部 C 函数 — 使用 u64 句柄，跨平台兼容
# (Windows SOCKET=u64, POSIX fd=int → u64 零扩展兼容)
# External C Functions — Using u64 Handle, Cross-platform Compatibility
# (Windows SOCKET=u64, POSIX fd=int → u64 Zero-Extension Compatible)
# ============================================================
def socket(family: INT, type: INT, protocol: INT) -> u64 | t.CExtern | t.CExport: pass
@@ -97,18 +97,20 @@ def close(fd: u64) -> INT | t.CExtern | t.CExport: pass
# ============================================================
# 内部辅助函数
# Internal Auxiliary Functions
# ============================================================
def _CloseFd(fd: INT) -> INT:
"""平台差异：Windows 用 closesocket，POSIX 用 close。"""
"""Platform differences: Windows uses closesocket, POSIX uses close。"""
if platmacro.IS_WINDOWS:
return w32.winsock2.closesocket(u64(fd))
return close(fd)
def _MakeAddr(host: str, port: INT) -> SocketAddr:
"""构建 SocketAddr。先尝试点分十进制 IP，失败则 DNS 解析。"""
"""Build SocketAddr. First try decimal IP, then DNS resolution.
If decimal IP fails, try DNS resolution.
If DNS resolution fails, return INADDR_ANY."""
addr: SocketAddr
string.memset(c.Addr(addr), 0, 16)
addr.family = u16(AF_INET)
@@ -119,8 +121,8 @@ def _MakeAddr(host: str, port: INT) -> SocketAddr:
addr.addr = ip
return addr
# DNS 解析 — gethostbyname 返回 struct hostent*
# h_addr_list 是 char** → h_addr_list[0] 是 char* → *(uint32_t*)h_addr_list[0] 是 IP
# DNS resolution — gethostbyname returns struct hostent*
# h_addr_list is char** → h_addr_list[0] is char* → *(uint32_t*)h_addr_list[0] is IP
if platmacro.IS_WINDOWS:
he_raw: w32.winsock2.WSAHostEnt | t.CPtr = w32.winsock2.gethostbyname(host)
if he_raw is not None:
@@ -140,7 +142,7 @@ def _MakeAddr(host: str, port: INT) -> SocketAddr:
def _ParseIPv4(ip_str: str, out_addr: u32 | t.CPtr) -> bool:
"""解析点分十进制 IPv4 地址。"""
"""Parse IPv4 address."""
if ip_str is None or out_addr is None: return False
parts: t.CArray[INT, 4]
@@ -179,13 +181,13 @@ def _ParseIPv4(ip_str: str, out_addr: u32 | t.CPtr) -> bool:
# ============================================================
# Socket 类 — Python 风格 OOP API
# Socket class — Python OOP API
# ============================================================
class Socket:
"""跨平台 Socket 封装，贴近 Python socket.socket 用法。
"""Cross-platform Socket class, similar to Python socket.socket.
用法:
Usage:
sock = Socket(AF_INET, SOCK_STREAM)
sock.connect("example.com", 80)
sock.send(data, length)
@@ -198,12 +200,12 @@ class Socket:
protocol: INT
def __init__(self, family: INT, type: INT, protocol: INT = 0):
"""创建 Socket。
"""Create Socket.
Args:
family: 地址族 (AF_INET)
type: 套接字类型 (SOCK_STREAM)
protocol: 协议 (默认 0，自动匹配)
family: Address family (AF_INET)
type: Socket type (SOCK_STREAM)
protocol: Protocol (default 0, auto-match)
"""
self.family = family
self.type = type
@@ -215,13 +217,13 @@ class Socket:
self.fd = socket(family, type, protocol)
def connect(self, host: str, port: INT) -> INT:
"""连接到远程主机。
"""Connect to remote host.
Args:
host: 主机名或 IP
port: 端口号
host: Hostname or IP
port: Port number
Returns:
0 成功，非 0 失败
0 success, non 0 otherwise
"""
if self.fd == INVALID_SOCKET: return -1
addr: SocketAddr = _MakeAddr(host, port)
@@ -236,10 +238,10 @@ class Socket:
return result
def send(self, data: t.CVoid | t.CPtr, length: INT) -> INT:
"""发送数据。
"""Send data.
Returns:
已发送字节数，SOCKET_ERROR 失败
Sent bytes, SOCKET_ERROR on error
"""
if self.fd == INVALID_SOCKET: return SOCKET_ERROR
if data is None or length <= 0: return 0
@@ -249,10 +251,10 @@ class Socket:
return send(self.fd, data, length, 0)
def recv(self, buf: t.CVoid | t.CPtr, bufsize: INT) -> INT:
"""接收数据。
"""Receive data.
Returns:
已接收字节数，SOCKET_ERROR 失败，0 表示连接关闭
Received bytes, SOCKET_ERROR on error, 0 on connection close
"""
if self.fd == INVALID_SOCKET: return SOCKET_ERROR
if buf is None or bufsize <= 0: return 0
@@ -262,10 +264,10 @@ class Socket:
return recv(self.fd, buf, bufsize, 0)
def sendall(self, data: t.CVoid | t.CPtr, length: INT) -> INT:
"""发送全部数据（循环发送直到完成或出错）。
"""Send all data.
Returns:
0 成功，SOCKET_ERROR 失败
0 success, SOCKET_ERROR on error
"""
if self.fd == INVALID_SOCKET: return SOCKET_ERROR
if data is None or length <= 0: return 0
@@ -278,17 +280,17 @@ class Socket:
return 0
def close(self) -> INT:
"""关闭 Socket。"""
"""Close Socket."""
if self.fd == INVALID_SOCKET: return 0
result: INT = _CloseFd(self.fd)
self.fd = INVALID_SOCKET
return result
def bind(self, host: str, port: INT) -> INT:
"""绑定地址和端口（服务器端）。
"""Bind address and port (server-side).
Returns:
0 成功，非 0 失败
0 success, non 0 otherwise
"""
if self.fd == INVALID_SOCKET: return -1
addr: SocketAddr = _MakeAddr(host, port)
@@ -298,10 +300,10 @@ class Socket:
return bind(self.fd, c.Addr(addr), 16)
def listen(self, backlog: INT) -> INT:
"""开始监听连接（服务器端）。
"""Start for incoming connections (server-side).
Returns:
0 成功，非 0 失败
0 success, non 0 otherwise
"""
if self.fd == INVALID_SOCKET: return -1
@@ -310,12 +312,12 @@ class Socket:
return listen(self.fd, backlog)
def accept(self, out_client: 'Socket' | t.CPtr) -> INT:
"""接受一个客户端连接。
"""Accept a client connection.
Args:
out_client: 输出参数，接收客户端 Socket
out_client: Output parameter, receives client Socket
Returns:
客户端 fd（>= 0 成功），SOCKET_ERROR 失败
Client fd (>= 0 on success), SOCKET_ERROR on error
"""
if self.fd == INVALID_SOCKET: return SOCKET_ERROR
if out_client is None: return SOCKET_ERROR
@@ -344,10 +346,10 @@ class Socket:
return client_fd
def settimeout(self, timeout_ms: INT) -> INT:
"""设置接收和发送超时（毫秒）。0 表示无超时。
"""Set timeout for receive and send operations (milliseconds).
Returns:
0 成功，非 0 失败
0 success, non 0 otherwise
"""
if self.fd == INVALID_SOCKET: return -1
@@ -367,16 +369,16 @@ class Socket:
return r2
def fileno(self) -> INT:
"""返回底层文件描述符 / SOCKET 句柄。"""
"""Return underlying file descriptor / SOCKET handle."""
return self.fd
# ============================================================
# 平台初始化
# Platform initialization
# ============================================================
def SocketInit() -> INT:
"""初始化 Socket 库。Windows 下调用 WSAStartup，POSIX 无操作。"""
"""Initialize the Socket library. On Windows, call WSAStartup; on POSIX, do nothing."""
if platmacro.IS_WINDOWS:
wsa_data: t.CArray[BYTE, 400]
string.memset(c.Addr(wsa_data), 0, 400)
@@ -385,18 +387,18 @@ def SocketInit() -> INT:
def SocketCleanup() -> INT:
"""清理 Socket 库。"""
"""Cleanup the Socket library."""
if platmacro.IS_WINDOWS:
return w32.winsock2.WSACleanup()
return 0
# ============================================================
# 兼容旧版过程式 API（委托到 Socket 方法）
# Compatibility with old procedural API (delegates to Socket methods)
# ============================================================
def SocketCreate(family: INT, type: INT, protocol: INT, out_sock: Socket | t.CPtr) -> INT:
"""创建 Socket 句柄（兼容旧版 API）。建议使用 Socket(...) 构造。"""
"""Create a Socket handle (compatible with old API). It is recommended to use Socket(...) constructor."""
if out_sock is None: return -1
out_sock.family = family
out_sock.type = type
@@ -412,6 +414,7 @@ def SocketCreate(family: INT, type: INT, protocol: INT, out_sock: Socket | t.CPt
if fd == INVALID_SOCKET: return -1
return 0
# But maybe using OOP would be better, though that can be wrapped up later.
def SocketConnect(sock: Socket | t.CPtr, host: str, port: INT) -> INT:
return sock.connect(host, port)
@@ -446,6 +449,6 @@ def SocketSetTimeout(sock: Socket | t.CPtr, timeout_ms: INT) -> INT:
def SocketIsValid(sock: Socket | t.CPtr) -> bool:
"""检查 Socket 是否有效。"""
"""Check if a Socket is valid."""
if sock is None: return False
return sock.fd != INVALID_SOCKET