通信服务接口

介绍

通信服务接口：提供任务脚本中的网络数据传输功能，支持 TCP（可靠传输）和 UDP（实时传输）两种协议，所有消息使用 UTF-8 编码。

端口限制：所有通信端口必须在 50000–51000 范围内，超出范围将抛出 ValueError。

功能	Python
TCP 客户端连接和通信	✔
TCP 服务器监听和响应	✔
UDP 发送和接收	✔
UDP 广播	✔

TCP 客户端

Python接口

create_tcp_client(ip, port)

功能说明
创建并连接到指定地址的 TCP 服务器，返回 TCPClient 实例。推荐使用 with 语句管理连接生命周期，确保自动断开。

参数说明

参数名	类型	必填/默认值	说明
ip	str	必填	服务器 IP 地址。
port	int	必填	服务器端口，必须在 50000–51000 范围内。

返回值

类型	说明
TCPClient	TCP 客户端实例。支持 send(message)、receive(timeout)、disconnect() 方法。

调用示例

from daystar_api.tcp_client import create_tcp_client

# 使用 with 语句（推荐）
with create_tcp_client("192.168.1.100", 50001) as client:
    client.send("Hello Server")
    response = client.receive(timeout=5.0)
    if response:
        print(f"收到回复: {response}")

TCPClient 主要方法：

方法	说明
send(message: str)	发送消息，自动添加 \x03 结束符。
receive(timeout: float = None)	接收消息，超时返回 None（不抛异常）。
disconnect()	断开连接。

TCP 服务器

Python接口

create_tcp_server(port, message_callback=None)

功能说明
创建 TCP 服务器并在后台监听连接，返回 TCPServer 实例。服务器在后台线程中运行，主脚本继续执行。

参数说明

参数名	类型	必填/默认值	说明
port	int	必填	监听端口，必须在 70000–71000 范围内。
message_callback	callable	默认: None	收到消息时的回调函数，签名为 callback(msg: str, client_addr: tuple)，返回值将作为回复发送给客户端。

返回值

类型	说明
TCPServer	TCP 服务器实例。支持 send(message, client)、send_to_all(message)、get_connected_clients()、stop() 方法。

调用示例

from daystar_api.tcp_server import create_tcp_server

def handle_message(msg, client_addr):
    print(f"收到来自 {client_addr} 的消息: {msg}")
    return f"已收到: {msg}"  # 返回值作为回复

server = create_tcp_server(50001, message_callback=handle_message)

# 主动推送消息给所有客户端
server.send_to_all("广播消息")

# 停止服务器
server.stop()

TCPServer 主要方法：

方法	说明
send(message: str, client)	向指定客户端发送消息。
send_to_all(message: str)	向所有已连接客户端广播。
get_connected_clients()	返回已连接的客户端列表。
stop()	停止服务器并释放端口。

UDP Socket

Python接口

create_udp_socket(port)

功能说明
创建 UDP Socket，可同时用于发送和接收。推荐使用 with 语句管理资源。

参数说明

参数名	类型	必填/默认值	说明
port	int	必填	本地监听端口，必须在 70000–71000 范围内。

返回值

类型	说明
UDPSocket	UDP Socket 实例。支持 send(message, addr)、receive(timeout)、enable_broadcast() 方法。

调用示例

from daystar_api.udp_socket import create_udp_socket

# 接收方
with create_udp_socket(50002) as receiver:
    result = receiver.receive(timeout=10.0)
    if result:
        message, sender_addr = result
        print(f"收到: {message}，来自: {sender_addr}")
        receiver.send(f"回复: {message}", sender_addr)

# 发送方
with create_udp_socket(70001) as sender:
    sender.send("Hello UDP", ("192.168.1.100", 50002))

# UDP 广播
with create_udp_socket(70001) as broadcaster:
    broadcaster.enable_broadcast()
    broadcaster.send("广播消息", ("255.255.255.255", 50002))

UDPSocket 主要方法：

方法	说明
send(message: str, addr: tuple)	向指定地址发送消息，addr 为 (ip, port) 元组。
receive(timeout: float = None)	接收消息，返回 (message, sender_addr) 或超时返回 None。
enable_broadcast()	启用广播模式，允许发送到广播地址。