oxFaceAndroid/DeviceUDPManager使用说明.md

DeviceUDPManager 使用说明

概述

DeviceUDPManager 是基于 KryoNet 库实现的 UDP 通信管理器，支持客户端和服务端两种模式，提供了完整的 UDP 数据收发功能。

特性

• ✅ 支持客户端和服务端模式
• ✅ 自动重连机制
• ✅ 线程安全的数据收发
• ✅ 支持多种数据类型（String、Integer、byte[]等）
• ✅ 完整的事件回调机制
• ✅ 单例模式，全局统一管理

快速开始

1. 依赖已添加

在 app/build.gradle 中已添加必要依赖：

// KryoNet UDP通信库
implementation 'com.esotericsoftware:kryonet:2.22.0-RC1'
implementation 'com.esotericsoftware:kryo:2.24.0'

2. 权限配置

在 AndroidManifest.xml 中已包含必要权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

3. 基本使用

客户端模式

// 获取管理器实例
DeviceUDPManager udpManager = DeviceUDPManager.getInstance();

// 设置监听器
udpManager.setMessageListener(new DeviceUDPManager.UDPMessageListener() {
    @Override
    public void onMessageReceived(Object message, Connection connection) {
        Log.i("UDP", "收到消息: " + message);
    }
    
    @Override
    public void onMessageSent(Object message) {
        Log.i("UDP", "发送成功: " + message);
    }
    
    @Override
    public void onMessageSendFailed(Object message, String error) {
        Log.e("UDP", "发送失败: " + error);
    }
});

udpManager.setConnectionStateListener(new DeviceUDPManager.ConnectionStateListener() {
    @Override
    public void onConnected() {
        Log.i("UDP", "连接成功");
        // 可以开始发送消息
        udpManager.sendUDPMessage("Hello Server!");
    }
    
    @Override
    public void onDisconnected() {
        Log.i("UDP", "连接断开");
    }
    
    @Override
    public void onConnectionFailed(String error) {
        Log.e("UDP", "连接失败: " + error);
    }
    
    @Override
    public void onReconnecting(int attempt) {
        Log.i("UDP", "重连中，第 " + attempt + " 次");
    }
});

// 初始化为客户端
udpManager.initializeAsClient(context, "192.168.1.100", 54555, 54777);

服务端模式

// 获取管理器实例
DeviceUDPManager udpManager = DeviceUDPManager.getInstance();

// 设置监听器（同客户端）
// ...

// 初始化为服务端
udpManager.initializeAsServer(context, 54555, 54777);

4. 发送消息

// 发送字符串消息
udpManager.sendUDPMessage("Hello UDP!");

// 发送数字消息
udpManager.sendUDPMessage(12345);

// 发送JSON格式消息
String jsonMsg = "{\"type\":\"status\",\"value\":\"online\"}";
udpManager.sendUDPMessage(jsonMsg);

// 服务端模式：发送消息给特定客户端
udpManager.sendUDPMessageToConnection(connection, "Hello Client!");

API 参考

主要方法

初始化方法

• initializeAsClient(Context, String, int, int) - 初始化为客户端
• initializeAsServer(Context, int, int) - 初始化为服务端

消息发送

• sendUDPMessage(Object) - 发送UDP消息
• sendUDPMessageToConnection(Connection, Object) - 发送消息给特定连接（服务端模式）

状态管理

• isConnected() - 获取连接状态
• isInitialized() - 获取初始化状态
• isClientMode() - 获取当前模式
• reconnect() - 手动重连（客户端模式）
• stop() - 停止UDP管理器
• release() - 释放所有资源

配置方法

• setMessageListener(UDPMessageListener) - 设置消息监听器
• setConnectionStateListener(ConnectionStateListener) - 设置连接状态监听器
• setAutoReconnect(boolean) - 设置自动重连

回调接口

UDPMessageListener

• onMessageReceived(Object, Connection) - 接收到消息
• onMessageSent(Object) - 消息发送成功
• onMessageSendFailed(Object, String) - 消息发送失败

ConnectionStateListener

• onConnected() - 连接成功
• onDisconnected() - 连接断开
• onConnectionFailed(String) - 连接失败
• onReconnecting(int) - 重连中

使用场景

1. 设备间通信

// 设备A作为服务端
udpManager.initializeAsServer(context, 54555, 54777);

// 设备B作为客户端
udpManager.initializeAsClient(context, "设备A的IP", 54555, 54777);

2. 命令控制

// 发送控制命令
udpManager.sendUDPMessage("command:restart");
udpManager.sendUDPMessage("command:get_status");

// 接收端处理
@Override
public void onMessageReceived(Object message, Connection connection) {
    if (message.toString().startsWith("command:")) {
        String command = message.toString().substring(8);
        handleCommand(command, connection);
    }
}

3. 状态同步

// 定期发送状态信息
String status = "{\"device_id\":\"" + Build.MODEL + 
               "\",\"status\":\"online\"," +
               "\"timestamp\":" + System.currentTimeMillis() + "}";
udpManager.sendUDPMessage(status);

注意事项

1. 线程安全: 所有方法都是线程安全的，可以在任意线程调用
2. 网络权限: 确保应用具有网络访问权限
3. 端口占用: 避免端口冲突，确保指定端口未被其他应用使用
4. 数据类型: 发送的对象需要是Kryo支持的类型或已注册的自定义类型
5. 资源释放: 在不需要时调用 stop() 或 release() 释放资源
6. 异常处理: 网络操作可能失败，注意处理回调中的错误信息

测试

可以使用提供的 UDPTestActivity 进行功能测试：

1. 在 AndroidManifest.xml 中注册Activity
2. 启动Activity进行测试
3. 可以在同一设备上启动服务端和客户端进行本地测试

扩展

自定义数据类型

// 注册自定义类型
public class CustomMessage {
    public String type;
    public String content;
    public long timestamp;
}

// 在初始化时注册
udpManager.getKryo().register(CustomMessage.class);

加密通信

可以在发送前加密消息，接收后解密：

// 发送加密消息
String encrypted = encrypt(originalMessage);
udpManager.sendUDPMessage(encrypted);

// 接收解密消息
String decrypted = decrypt(encryptedMessage);